tentacle-sdk 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Tentacle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,169 @@
+# 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
+
+```bash
+# Install the latest alpha release
+npm install tentacle-sdk@alpha
+
+# Or with a specific version
+npm install tentacle-sdk@0.1.0-alpha.1
+```
+
+The SDK works with both ESM and CommonJS projects, and includes full TypeScript type definitions.
+
+## Quick Start
+
+```typescript
+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
+
+```typescript
+// 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
+
+```typescript
+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
+
+```bash
+cd packages/sdk
+pnpm install
+pnpm build
+```
+
+The built SDK will be in `dist/`.