Tentacle SDK

TypeScript SDK for the Tentacle streaming platform API. Provides type-safe access to Twitch and Kick events in real-time.

Note: This SDK is currently in alpha. The API may change between versions.

Installation

# Install the latest alpha release
npm install tentacle-sdk@alpha

# Or with a specific version
npm install [email protected]

The SDK works with both ESM and CommonJS projects, and includes full TypeScript type definitions.

Quick Start

import { TentacleClient } from 'tentacle-sdk'

const client = new TentacleClient({
  baseUrl: 'https://api.tentacle.live',
  accessToken: 'your-access-token',
})

// Subscribe to realtime Twitch/Kick events
const unsubscribe = client.realtime.subscribe({
  onEvent: (event) => {
    switch (event.kind) {
      case 'StreamChatMessage':
        // Chat message from Twitch or Kick
        const msg = event.payload
        console.log(`[${msg.$platform}] ${msg.$text}`)
        console.log(`Viewer ID: ${msg.$viewerId}`)
        break

      case 'StreamEvent':
        // Stream event (follow, sub, raid, cheer, etc.)
        const evt = event.payload
        if (evt.$platform === 'twitch') {
          switch (evt.$type) {
            case 'channel.follow':
              console.log(`New Twitch follower: ${evt.userDisplayName}`)
              break
            case 'channel.subscribe':
              console.log(`New Twitch sub: ${evt.userDisplayName}`)
              break
            case 'channel.raid':
              console.log(`Raid from ${evt.fromBroadcasterUserDisplayName} with ${evt.viewers} viewers`)
              break
            case 'channel.cheer':
              console.log(`Cheer: ${evt.bits} bits from ${evt.userDisplayName}`)
              break
          }
        } else if (evt.$platform === 'kick') {
          switch (evt.$type) {
            case 'channel.followed':
              console.log(`New Kick follower: ${evt.username}`)
              break
            case 'channel.subscription.new':
              console.log(`New Kick sub: ${evt.username}`)
              break
          }
        }
        break

      case 'StreamViewerActivity':
        console.log(`Viewer activity: ${event.payload.viewerId}`)
        break
    }
  },
  onError: (error) => console.error('Connection error:', error),
  onOpen: () => console.log('Connected to realtime events!'),
  onClose: () => console.log('Disconnected'),
})

// When done, unsubscribe:
unsubscribe()

API Overview

The SDK provides access to the following APIs:

• realtime - Subscribe to live Twitch and Kick events via SSE
• apps - Manage apps and viewer properties
• stream - Access chat messages and events history
• subathon - Access subathon statistics
• viewer - Access viewer data

REST API Examples

// Get recent chat messages
const messages = await client.stream.getChatMessages({ take: 50 })

// Get recent stream events
const events = await client.stream.getEvents({ take: 20 })

// List apps
const { apps } = await client.apps.list()

// Get subathon stats
const subs = await client.subathon.getSubs()
const donations = await client.subathon.getDonations()

// Get viewer data
const viewer = await client.viewer.get({ viewerId: 'v1' })

Event Types

Twitch Events

• channel.follow - New follower
• channel.subscribe - New subscription
• channel.subscription.gift - Gift subscription
• channel.cheer - Bits cheer
• channel.raid - Incoming raid
• channel.channel_points_custom_reward_redemption.add - Channel point redemption
• stream.online - Stream started
• stream.offline - Stream ended

Kick Events

• channel.followed - New follower
• channel.subscription.new - New subscription
• channel.subscription.renewal - Subscription renewal
• channel.subscription.gifts - Gift subscriptions
• livestream.status.updated - Stream status change

Type Imports

import type {
  // Realtime events
  RealtimeEvent,

  // Chat messages
  StreamChatMessageJson,
  TwitchChatMessageJson,
  KickChatMessageJson,

  // Stream events
  StreamEventJson,
  TwitchEventJson,
  KickEventJson,
  TwitchEventJson_Follow,
  TwitchEventJson_Subscription,
  TwitchEventJson_Cheer,
  TwitchEventJson_Raid,

  // App and viewer types
  AppJson,
  ViewerJson,
  ViewerMiniJson,
} from 'tentacle-sdk'

Building from Source

cd packages/sdk
pnpm install
pnpm build

The built SDK will be in dist/.