tentacle-sdk 0.0.1

package/docs/api/type-aliases/UnsubscribeFunction.md

@@ -0,0 +1,22 @@
+[**tentacle-sdk**](../index.md)
+
+***
+
+# Type Alias: UnsubscribeFunction()
+
+> **UnsubscribeFunction** = () => `void`
+
+Function to unsubscribe from realtime events.
+Call this to close the SSE connection and stop receiving events.
+
+## Returns
+
+`void`
+
+## Example
+
+```typescript
+const unsubscribe = client.realtime.subscribe({ onEvent: ... })
+// Later, when done:
+unsubscribe()
+```

package/docs/api/type-aliases/ViewerPropertyJson.md

@@ -0,0 +1,9 @@
+[**tentacle-sdk**](../index.md)
+
+***
+
+# Type Alias: ViewerPropertyJson
+
+> **ViewerPropertyJson** = [`ViewerPropertyJson_Number`](../interfaces/ViewerPropertyJson_Number.md) \| [`ViewerPropertyJson_Bool`](../interfaces/ViewerPropertyJson_Bool.md) \| [`ViewerPropertyJson_String`](../interfaces/ViewerPropertyJson_String.md)
+
+Viewer property.

package/docs/api/type-aliases/ViewerPropertyType.md

@@ -0,0 +1,9 @@
+[**tentacle-sdk**](../index.md)
+
+***
+
+# Type Alias: ViewerPropertyType
+
+> **ViewerPropertyType** = `"number"` \| `"bool"` \| `"string"`
+
+Viewer property type.

package/docs/overview.md

@@ -0,0 +1,160 @@
+# Tentacle SDK Documentation
+
+TypeScript SDK for the Tentacle streaming platform API. Provides type-safe access to REST endpoints and realtime events from Twitch and Kick.
+
+## Installation
+
+```bash
+npm install tentacle-sdk
+# or
+pnpm add tentacle-sdk
+```
+
+## Quick Start
+
+```typescript
+import { TentacleClient } from "tentacle-sdk"
+
+const client = new TentacleClient({
+  baseUrl: "https://api.tentacle.live",
+  accessToken: "your-access-token",
+})
+
+// Subscribe to realtime events (Twitch + Kick)
+const unsubscribe = client.realtime.subscribe({
+  onEvent: (event) => {
+    if (event.kind === "StreamChatMessage") {
+      console.log(`Chat: ${event.payload.$text}`)
+    } else if (event.kind === "StreamEvent") {
+      console.log(`Event: ${event.payload.$type}`)
+    }
+  },
+})
+
+// Get recent chat messages
+const messages = await client.stream.getChatMessages({ take: 10 })
+
+// When done, unsubscribe
+unsubscribe()
+```
+
+## API Reference
+
+Full API documentation is auto-generated from JSDoc comments in the source code.
+
+- [API Reference Index](./api/index.md) - Complete API documentation
+- [TentacleClient](./api/classes/TentacleClient.md) - Main client class
+- [TentacleError](./api/classes/TentacleError.md) - Error handling
+- [RealtimeEvent](./api/type-aliases/RealtimeEvent.md) - Realtime event types
+
+## SDK Structure
+
+### TentacleClient
+
+The main entry point. Provides access to all API namespaces:
+
+| Namespace | Description |
+|-----------|-------------|
+| `client.realtime` | Subscribe to live Twitch/Kick events via SSE |
+| `client.account` | Manage user accounts |
+| `client.apps` | Manage apps and viewer properties |
+| `client.auth` | Authentication and access tokens |
+| `client.customEvents` | Manage custom event triggers |
+| `client.dashboard` | Manage dashboards |
+| `client.settings` | Manage user settings |
+| `client.stream` | Access chat messages and events history |
+| `client.subathonStats` | Access subathon statistics |
+| `client.viewer` | Access viewer data |
+
+### Realtime Events
+
+The SDK uses Server-Sent Events (SSE) for realtime updates. Three event types are supported:
+
+| Event Kind | Description |
+|------------|-------------|
+| `StreamChatMessage` | Chat messages from Twitch or Kick |
+| `StreamEvent` | Stream events (follows, subs, raids, cheers, etc.) |
+| `StreamViewerActivity` | Viewer activity updates |
+
+```typescript
+client.realtime.subscribe({
+  onEvent: (event) => {
+    switch (event.kind) {
+      case "StreamChatMessage":
+        // event.payload is TwitchChatMessageJson | KickChatMessageJson
+        console.log(`[${event.payload.$platform}] ${event.payload.$text}`)
+        break
+
+      case "StreamEvent":
+        // event.payload is TwitchEventJson | KickEventJson
+        if (event.payload.$platform === "twitch") {
+          switch (event.payload.$type) {
+            case "channel.follow":
+              console.log(`New follower: ${event.payload.userDisplayName}`)
+              break
+            case "channel.subscribe":
+              console.log(`New sub: ${event.payload.userDisplayName}`)
+              break
+            case "channel.raid":
+              console.log(`Raid from ${event.payload.fromBroadcasterUserName}`)
+              break
+          }
+        }
+        break
+
+      case "StreamViewerActivity":
+        console.log(`Viewer ${event.payload.viewerId} active`)
+        break
+    }
+  },
+  onError: (error) => console.error("Connection error:", error),
+  onOpen: () => console.log("Connected!"),
+  onClose: () => console.log("Disconnected"),
+})
+```
+
+### Error Handling
+
+API errors throw `TentacleError` with HTTP status and optional error code:
+
+```typescript
+import { TentacleError } from "tentacle-sdk"
+
+try {
+  await client.settings.get()
+} catch (error) {
+  if (error instanceof TentacleError) {
+    console.error(`Error ${error.status}: ${error.message}`)
+    if (error.code) {
+      console.error(`Code: ${error.code}`)
+    }
+  }
+}
+```
+
+## Authentication
+
+Most endpoints require an access token. You can obtain one from:
+
+1. **Tentacle Dashboard** - For user tokens
+2. **Auth API** - For programmatic access
+
+```typescript
+// Get or create an access token
+const token = await client.auth.getOrCreateAccessToken()
+console.log(`Token: ${token.jwt}`)
+
+// Check token validity
+const { isValid } = await client.auth.getAccessTokenStatus({ jwt: token.jwt })
+```
+
+## Platform Support
+
+The SDK normalizes data from both Twitch and Kick. All messages and events include:
+
+- `$platform`: `"twitch"` or `"kick"`
+- `$type`: Platform-specific event type
+- `$viewerId`: Unified viewer ID (when available)
+- `$createdAt`: ISO 8601 timestamp
+
+This allows you to handle both platforms with unified logic while still accessing platform-specific fields when needed.

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "tentacle-sdk",
+  "version": "0.0.1",
+  "license": "MIT",
+  "description": "SDK for the Tentacle platform",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "LICENSE"
+  ],
+  "keywords": [
+    "tentacle",
+    "streaming",
+    "twitch",
+    "kick",
+    "api",
+    "sdk",
+    "typescript",
+    "realtime",
+    "sse"
+  ],
+  "homepage": "https://www.tentacle.live",
+  "scripts": {
+    "prepublishOnly": "just build"
+  },
+  "devDependencies": {
+    "@tentacle/common": "workspace:*",
+    "@types/node": "catalog:",
+    "dotenv-cli": "catalog:",
+    "tsup": "~8.5.1",
+    "tsx": "catalog:",
+    "typedoc": "catalog:",
+    "typedoc-plugin-markdown": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  },
+  "packageManager": "pnpm@10.12.1"
+}