tentacle-sdk 0.0.1

package/dist/index.d.cts

@@ -0,0 +1,1562 @@
+/**
+ * HTTP utilities for the Tentacle SDK.
+ * Uses tRPC HTTP protocol to communicate with the Tentacle API.
+ *
+ * @module http
+ */
+/**
+ * Error thrown by the Tentacle SDK when an API request fails.
+ */
+declare class TentacleError extends Error {
+    /**
+     * HTTP status code of the failed request.
+     */
+    readonly status: number;
+    /**
+     * Error code from the server, if available.
+     */
+    readonly code?: string;
+    constructor(message: string, status: number, code?: string);
+}
+/**
+ * Configuration for the HTTP client.
+ */
+interface HttpClientConfig {
+    /**
+     * Base URL of the Tentacle API.
+     * @example "https://api.tentacle.live"
+     */
+    baseUrl: string;
+    /**
+     * Access token for authentication.
+     * Obtain this from the Tentacle dashboard or via the auth API.
+     */
+    accessToken?: string;
+}
+/**
+ * HTTP client for making tRPC requests to the Tentacle API.
+ */
+declare class HttpClient {
+    private readonly baseUrl;
+    private readonly accessToken?;
+    constructor(config: HttpClientConfig);
+    /**
+     * Get the headers for a request.
+     */
+    private getHeaders;
+    /**
+     * Build the tRPC URL for a procedure call.
+     *
+     * @param procedure - Full procedure path (e.g., "apps.list")
+     * @param input - Optional input for queries (will be URL encoded)
+     */
+    private buildTrpcUrl;
+    /**
+     * Handle the tRPC response.
+     */
+    private handleResponse;
+    /**
+     * Make a tRPC query (GET request).
+     *
+     * @param procedure - Full procedure path (e.g., "apps.list")
+     * @param input - Optional input data
+     * @returns The response data
+     * @throws {TentacleError} If the request fails
+     */
+    query<T>(procedure: string, input?: unknown): Promise<T>;
+    /**
+     * Make a tRPC mutation (POST request).
+     *
+     * @param procedure - Full procedure path (e.g., "apps.create")
+     * @param input - Input data for the mutation
+     * @returns The response data
+     * @throws {TentacleError} If the request fails
+     */
+    mutate<T>(procedure: string, input?: unknown): Promise<T>;
+    /**
+     * Get the base URL for SSE connections.
+     */
+    getBaseUrl(): string;
+    /**
+     * Get the access token for SSE connections.
+     */
+    getAccessToken(): string | undefined;
+}
+
+/**
+ * Type definitions for the Tentacle SDK.
+ *
+ * These types mirror the server's Zod schemas to ensure type safety.
+ * All types are defined inline to make the SDK self-contained.
+ *
+ * @module types
+ */
+/**
+ * ISO 8601 date string.
+ */
+type DateIsoString = string;
+/**
+ * Stream platform.
+ */
+type StreamPlatform = "twitch" | "kick";
+/**
+ * Position of an emote or emoji in a chat message.
+ */
+interface ChatMessagePosition {
+    start: number;
+    end: number;
+}
+/**
+ * Emoji in a chat message.
+ */
+interface ChatMessageEmoji {
+    code: string;
+    name: string;
+    count: number;
+    positions: ChatMessagePosition[];
+}
+/**
+ * Emote in a chat message.
+ */
+interface ChatMessageEmote {
+    id: string;
+    name: string;
+    count: number;
+    positions: ChatMessagePosition[];
+}
+/**
+ * Base fields for all chat messages.
+ */
+interface CommonChatMessage {
+    $command: string | null;
+    $commandArgs: string[];
+    $createdAt: DateIsoString;
+    $emojis: Record<string, ChatMessageEmoji>;
+    $emotes: Record<string, ChatMessageEmote>;
+    $html: string;
+    $id: string;
+    $kind: "ChatMessageJson";
+    $text: string;
+    $viewerId: string;
+}
+/**
+ * Twitch chat message.
+ */
+interface TwitchChatMessageJson extends CommonChatMessage {
+    $platform: "twitch";
+    $type: "chat.message";
+    bits: number;
+    channelId: string;
+    color: string | null;
+    emoteOnly: boolean;
+    id: string;
+    isCheer: boolean;
+    isFirst: boolean;
+    isHighlight: boolean;
+    isRedemption: boolean;
+    isReply: boolean;
+    isReturningChatter: boolean;
+    message: string;
+    userInfo: TwitchUserInfo | null;
+}
+/**
+ * Twitch user info.
+ */
+interface TwitchUserInfo {
+    badgeInfo: Record<string, string>;
+    badges: Record<string, string>;
+    color: string | null;
+    displayName: string;
+    id: string;
+    isBroadcaster: boolean;
+    isFounder: boolean;
+    isMod: boolean;
+    isSubscriber: boolean;
+    isVip: boolean;
+    name: string;
+    userType: string | null;
+}
+/**
+ * Kick chat message.
+ */
+interface KickChatMessageJson extends CommonChatMessage {
+    $platform: "kick";
+    $type: "chat.message";
+    chatroomId: number;
+    content: string;
+    createdAt: string;
+    id: string;
+    senderId: number;
+    type: string;
+    username: string;
+}
+/**
+ * Chat message from Twitch or Kick.
+ */
+type StreamChatMessageJson = TwitchChatMessageJson | KickChatMessageJson;
+/**
+ * Base fields for all stream events.
+ */
+interface CommonEventJson {
+    $createdAt: DateIsoString;
+    $id: string;
+    $kind: "EventJson";
+    $userId: string;
+    $viewerId: string | null;
+}
+/**
+ * Twitch event types.
+ */
+type TwitchEventType = "channel.ban" | "channel.cheer" | "channel.follow" | "channel.raid" | "channel.channel_points_custom_reward_redemption.add" | "channel.shield_mode.begin" | "channel.shield_mode.end" | "channel.shoutout.receive" | "channel.subscribe" | "channel.subscription.gift" | "channel.subscription.message" | "stream.online" | "stream.offline";
+/**
+ * Twitch follow event.
+ */
+interface TwitchEventJson_Follow extends CommonEventJson {
+    $platform: "twitch";
+    $type: "channel.follow";
+    followedAt: string;
+    userId: string;
+    userDisplayName: string;
+    userName: string;
+}
+/**
+ * Twitch subscription event.
+ */
+interface TwitchEventJson_Subscription extends CommonEventJson {
+    $platform: "twitch";
+    $type: "channel.subscribe";
+    isGift: boolean;
+    tier: string;
+    userId: string;
+    userDisplayName: string;
+    userName: string;
+}
+/**
+ * Twitch subscription gift event.
+ */
+interface TwitchEventJson_SubscriptionGift extends CommonEventJson {
+    $platform: "twitch";
+    $type: "channel.subscription.gift";
+    cumulativeTotal: number | null;
+    isAnonymous: boolean;
+    tier: string;
+    total: number;
+    userId: string | null;
+    userDisplayName: string | null;
+    userName: string | null;
+}
+/**
+ * Twitch cheer event.
+ */
+interface TwitchEventJson_Cheer extends CommonEventJson {
+    $platform: "twitch";
+    $type: "channel.cheer";
+    bits: number;
+    isAnonymous: boolean;
+    message: string;
+    userId: string | null;
+    userDisplayName: string | null;
+    userName: string | null;
+}
+/**
+ * Twitch raid event.
+ */
+interface TwitchEventJson_Raid extends CommonEventJson {
+    $platform: "twitch";
+    $type: "channel.raid";
+    fromBroadcasterUserId: string;
+    fromBroadcasterUserName: string;
+    fromBroadcasterUserDisplayName: string;
+    viewers: number;
+}
+/**
+ * Twitch channel point redemption event.
+ */
+interface TwitchEventJson_RedemptionAdd extends CommonEventJson {
+    $platform: "twitch";
+    $type: "channel.channel_points_custom_reward_redemption.add";
+    id: string;
+    rewardId: string;
+    rewardTitle: string;
+    rewardCost: number;
+    rewardPrompt: string;
+    userId: string;
+    userDisplayName: string;
+    userName: string;
+    userInput: string;
+    status: string;
+    redeemedAt: string;
+}
+/**
+ * Twitch stream online event.
+ */
+interface TwitchEventJson_StreamOnline extends CommonEventJson {
+    $platform: "twitch";
+    $type: "stream.online";
+    id: string;
+    type: string;
+    startedAt: string;
+}
+/**
+ * All Twitch event types.
+ */
+type TwitchEventJson = TwitchEventJson_Follow | TwitchEventJson_Subscription | TwitchEventJson_SubscriptionGift | TwitchEventJson_Cheer | TwitchEventJson_Raid | TwitchEventJson_RedemptionAdd | TwitchEventJson_StreamOnline;
+/**
+ * Kick follow event.
+ */
+interface KickEventJson_ChannelFollow extends CommonEventJson {
+    $platform: "kick";
+    $type: "channel.followed";
+    followersCount: number;
+    username: string;
+}
+/**
+ * Kick subscription new event.
+ */
+interface KickEventJson_ChannelSubscriptionNew extends CommonEventJson {
+    $platform: "kick";
+    $type: "channel.subscription.new";
+    months: number;
+    username: string;
+}
+/**
+ * Kick subscription renewal event.
+ */
+interface KickEventJson_ChannelSubscriptionRenewal extends CommonEventJson {
+    $platform: "kick";
+    $type: "channel.subscription.renewal";
+    months: number;
+    username: string;
+}
+/**
+ * Kick subscription gifts event.
+ */
+interface KickEventJson_ChannelSubscriptionGifts extends CommonEventJson {
+    $platform: "kick";
+    $type: "channel.subscription.gifts";
+    giftedUsernames: string[];
+    gifterUsername: string;
+}
+/**
+ * Kick livestream status updated event.
+ */
+interface KickEventJson_LivestreamStatusUpdated extends CommonEventJson {
+    $platform: "kick";
+    $type: "livestream.status.updated";
+    isLive: boolean;
+}
+/**
+ * All Kick event types.
+ */
+type KickEventJson = KickEventJson_ChannelFollow | KickEventJson_ChannelSubscriptionNew | KickEventJson_ChannelSubscriptionRenewal | KickEventJson_ChannelSubscriptionGifts | KickEventJson_LivestreamStatusUpdated;
+/**
+ * Stream event from Twitch or Kick.
+ */
+type StreamEventJson = TwitchEventJson | KickEventJson;
+/**
+ * Viewer activity event.
+ */
+interface StreamViewerActivityJson {
+    id: string;
+    userId: string;
+    viewerId: string;
+    createdAt: DateIsoString;
+}
+/**
+ * Realtime chat message event.
+ */
+interface RealtimeEvent_StreamChatMessage {
+    kind: "StreamChatMessage";
+    payload: StreamChatMessageJson;
+}
+/**
+ * Realtime stream event.
+ */
+interface RealtimeEvent_StreamEvent {
+    kind: "StreamEvent";
+    payload: StreamEventJson;
+}
+/**
+ * Realtime viewer activity event.
+ */
+interface RealtimeEvent_StreamViewerActivity {
+    kind: "StreamViewerActivity";
+    payload: StreamViewerActivityJson;
+}
+/**
+ * Realtime event from the Tentacle server.
+ *
+ * This is a discriminated union - use `event.kind` to determine the event type:
+ * - `StreamChatMessage`: Chat message from Twitch or Kick
+ * - `StreamEvent`: Stream event (follow, sub, raid, cheer, etc.)
+ * - `StreamViewerActivity`: Viewer activity update
+ *
+ * @example
+ * ```typescript
+ * client.realtime.subscribe({
+ *   onEvent: (event) => {
+ *     switch (event.kind) {
+ *       case 'StreamChatMessage':
+ *         console.log(`[${event.payload.$platform}] ${event.payload.$text}`)
+ *         break
+ *       case 'StreamEvent':
+ *         if (event.payload.$platform === 'twitch' && event.payload.$type === 'channel.follow') {
+ *           console.log(`New follower: ${event.payload.userDisplayName}`)
+ *         }
+ *         break
+ *       case 'StreamViewerActivity':
+ *         console.log(`Viewer ${event.payload.viewerId} active`)
+ *         break
+ *     }
+ *   }
+ * })
+ * ```
+ */
+type RealtimeEvent = RealtimeEvent_StreamChatMessage | RealtimeEvent_StreamEvent | RealtimeEvent_StreamViewerActivity;
+/**
+ * App.
+ */
+interface AppJson {
+    createdAt: DateIsoString;
+    id: string;
+    isActive: boolean;
+    isDefault: boolean;
+    name: string;
+    state: unknown;
+    updatedAt: DateIsoString;
+    userId: string;
+}
+/**
+ * Viewer property type.
+ */
+type ViewerPropertyType = "number" | "bool" | "string";
+/**
+ * Base viewer property fields.
+ */
+interface ViewerPropertyJsonBase {
+    id: string;
+    appId: string;
+    name: string;
+    viewerId: string;
+}
+/**
+ * Number viewer property.
+ */
+interface ViewerPropertyJson_Number extends ViewerPropertyJsonBase {
+    type: "number";
+    value: number;
+}
+/**
+ * Boolean viewer property.
+ */
+interface ViewerPropertyJson_Bool extends ViewerPropertyJsonBase {
+    type: "bool";
+    value: boolean;
+}
+/**
+ * String viewer property.
+ */
+interface ViewerPropertyJson_String extends ViewerPropertyJsonBase {
+    type: "string";
+    value: string;
+}
+/**
+ * Viewer property.
+ */
+type ViewerPropertyJson = ViewerPropertyJson_Number | ViewerPropertyJson_Bool | ViewerPropertyJson_String;
+/**
+ * Kick badge.
+ */
+interface KickBadge {
+    type: string;
+    text: string;
+    count?: number;
+}
+/**
+ * Viewer Kick data.
+ */
+interface ViewerKickJson {
+    createdAt: DateIsoString;
+    updatedAt: DateIsoString;
+    viewerId: string;
+    id: number;
+    username: string;
+    badges?: KickBadge[] | null;
+    isBroadcaster: boolean;
+    isModerator: boolean;
+    isOwner: boolean;
+    isStaff: boolean;
+    isSubscriber: boolean;
+    isVerified: boolean;
+    isVip: boolean;
+}
+/**
+ * Viewer Twitch data.
+ */
+interface ViewerTwitchJson {
+    createdAt: DateIsoString;
+    updatedAt: DateIsoString;
+    viewerId: string;
+    id: string;
+    username: string;
+    displayName: string;
+    profileImageUrl?: string | null;
+    isBroadcaster: boolean;
+    isFounder: boolean;
+    isMod: boolean;
+    isSubscriber: boolean;
+    isVip: boolean;
+}
+/**
+ * Viewer (mini).
+ */
+interface ViewerMiniJson {
+    id: string;
+    createdAt: DateIsoString;
+    updatedAt: DateIsoString;
+    kick?: ViewerKickJson | null;
+    twitch?: ViewerTwitchJson | null;
+}
+/**
+ * Viewer (full).
+ */
+interface ViewerJson extends ViewerMiniJson {
+    isMock?: boolean;
+    properties?: Record<string, ViewerPropertyJson> | null;
+}
+/**
+ * Viewer action.
+ */
+interface ViewerActionJson {
+    id: string;
+    name: string;
+    data: unknown;
+    appId: string;
+    viewerId: string;
+    createdAt: DateIsoString;
+}
+/**
+ * Subscription unlock.
+ */
+interface SubUnlock {
+    subs: number;
+    title: string;
+    reached: boolean;
+}
+/**
+ * Subscription stats.
+ */
+interface SubathonStats_Subscriptions {
+    count: number;
+    goal: number;
+    goalProgress: number;
+    newestSubViewers: ViewerJson[];
+    unlocks: SubUnlock[];
+    nextUnlock: {
+        subs: number;
+        title: string;
+    };
+}
+/**
+ * Gifted subscription unlock.
+ */
+interface GiftedSubUnlock {
+    giftedSubs: number;
+    title: string;
+    reached: boolean;
+}
+/**
+ * Gifted subscription stats.
+ */
+interface SubathonStats_GiftedSubscriptions {
+    count: number;
+    goal: number;
+    goalProgress: number;
+    latestGiftedSub: unknown;
+    topGifterViewers: ViewerJson[];
+    viewerIdToTotal: Record<string, number>;
+    unlocks: GiftedSubUnlock[];
+    nextUnlock: {
+        giftedSubs: number;
+        title: string;
+    };
+}
+/**
+ * Donation unlock.
+ */
+interface DonationUnlock {
+    dollars: number;
+    dollarsText: string;
+    title: string;
+    reached: boolean;
+}
+/**
+ * Donation stats.
+ */
+interface SubathonStats_Donations {
+    dollars: number;
+    goal: number;
+    goalProgress: number;
+    latestCheer: unknown;
+    topDonorViewers: ViewerJson[];
+    viewerIdToTotalBits: Record<string, number>;
+    unlocks: DonationUnlock[];
+    nextUnlock: {
+        dollars: number;
+        dollarsText: string;
+        title: string;
+    };
+}
+/**
+ * Order direction for pagination.
+ */
+type OrderDirection = "asc" | "desc";
+/**
+ * Viewers by property response.
+ */
+interface ViewersByPropertyOutput {
+    property: {
+        name: string;
+        type: ViewerPropertyType;
+        appId: string;
+    };
+    viewers: Array<ViewerMiniJson & {
+        properties: Record<string, ViewerPropertyJson>;
+    }>;
+}
+
+/**
+ * Realtime subscription utilities for the Tentacle SDK.
+ * Uses Server-Sent Events (SSE) via tRPC to receive live updates from Twitch and Kick.
+ *
+ * @module realtime
+ */
+
+/**
+ * Options for subscribing to realtime events.
+ */
+interface RealtimeSubscribeOptions {
+    /**
+     * Callback invoked when a realtime event is received.
+     * Events include chat messages, stream events (follows, subs, raids, etc.),
+     * and viewer activity.
+     *
+     * @param event - The realtime event with `kind` discriminator and `payload`.
+     *
+     * @example
+     * ```typescript
+     * onEvent: (event) => {
+     *   switch (event.kind) {
+     *     case 'StreamChatMessage':
+     *       console.log(`${event.payload.userInfo?.displayName}: ${event.payload.$text}`)
+     *       break
+     *     case 'StreamEvent':
+     *       if (event.payload.$platform === 'twitch' && event.payload.$type === 'channel.follow') {
+     *         console.log(`New follower: ${event.payload.userDisplayName}`)
+     *       }
+     *       break
+     *   }
+     * }
+     * ```
+     */
+    onEvent: (event: RealtimeEvent) => void;
+    /**
+     * Callback invoked when an error occurs.
+     * The subscription will automatically attempt to reconnect.
+     *
+     * @param error - The error that occurred.
+     */
+    onError?: (error: Error) => void;
+    /**
+     * Callback invoked when the connection is established.
+     */
+    onOpen?: () => void;
+    /**
+     * Callback invoked when the connection is closed.
+     */
+    onClose?: () => void;
+}
+/**
+ * Function to unsubscribe from realtime events.
+ * Call this to close the SSE connection and stop receiving events.
+ *
+ * @example
+ * ```typescript
+ * const unsubscribe = client.realtime.subscribe({ onEvent: ... })
+ * // Later, when done:
+ * unsubscribe()
+ * ```
+ */
+type UnsubscribeFunction = () => void;
+/**
+ * Realtime API for subscribing to Twitch and Kick events.
+ */
+declare class RealtimeApi {
+    private readonly baseUrl;
+    private readonly accessToken?;
+    constructor(baseUrl: string, accessToken?: string);
+    /**
+     * Subscribe to realtime events from Twitch and Kick.
+     *
+     * This establishes a Server-Sent Events (SSE) connection to receive live updates:
+     * - **StreamChatMessage**: Chat messages from Twitch or Kick
+     * - **StreamEvent**: Events like follows, subscriptions, raids, cheers
+     * - **StreamViewerActivity**: Viewer activity updates
+     *
+     * Each event includes viewer data (when available) via the `$viewerId` field
+     * and platform-specific user info.
+     *
+     * @param options - Subscription options with event callbacks
+     * @returns Function to unsubscribe and close the connection
+     *
+     * @example
+     * ```typescript
+     * 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, 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.fromBroadcasterUserName} with ${evt.viewers} viewers`)
+     *               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!'),
+     *   onClose: () => console.log('Disconnected'),
+     * })
+     *
+     * // When done, unsubscribe:
+     * unsubscribe()
+     * ```
+     *
+     * @throws {Error} If no access token is configured
+     */
+    subscribe(options: RealtimeSubscribeOptions): UnsubscribeFunction;
+}
+
+/**
+ * Credential store interface for persisting access tokens.
+ *
+ * Implement this interface to provide custom credential storage.
+ * The SDK includes a FileCredentialStore for Node.js environments.
+ *
+ * @example
+ * ```typescript
+ * // Custom credential store for Unreal Engine (PuerTS)
+ * class UnrealCredentialStore implements CredentialStore {
+ *   async getAccessToken(): Promise<string | null> {
+ *     return UE.SaveGame.LoadString("TentacleAccessToken")
+ *   }
+ *
+ *   async setAccessToken(token: string): Promise<void> {
+ *     UE.SaveGame.SaveString("TentacleAccessToken", token)
+ *   }
+ *
+ *   async clearAccessToken(): Promise<void> {
+ *     UE.SaveGame.Delete("TentacleAccessToken")
+ *   }
+ * }
+ * ```
+ *
+ * @module auth/credential-store
+ */
+/**
+ * Interface for persisting access tokens.
+ *
+ * Implementations should securely store tokens in a platform-appropriate way.
+ * For Node.js, use FileCredentialStore. For other platforms (Unity, Unreal),
+ * implement this interface using the platform's native storage APIs.
+ */
+interface CredentialStore {
+    /**
+     * Retrieves the stored access token.
+     *
+     * @returns The access token, or null if none is stored.
+     */
+    getAccessToken(): Promise<string | null>;
+    /**
+     * Stores an access token.
+     *
+     * @param token - The access token to store.
+     */
+    setAccessToken(token: string): Promise<void>;
+    /**
+     * Removes the stored access token.
+     */
+    clearAccessToken(): Promise<void>;
+}
+
+/**
+ * Device authorization flow for the Tentacle SDK.
+ *
+ * Implements OAuth 2.0 Device Authorization Grant (RFC 8628) for
+ * authenticating devices that cannot easily display a web browser.
+ *
+ * @module auth/device-auth
+ */
+
+/**
+ * Result of initiating device authorization.
+ */
+interface DeviceAuthInitResult {
+    /** Code used by SDK to poll for authorization status. */
+    deviceCode: string;
+    /** User-friendly code displayed to the user (e.g., "ABCD-1234"). */
+    userCode: string;
+    /** URL where user should navigate to enter the code. */
+    verificationUrl: string;
+    /** Seconds until this authorization request expires. */
+    expiresIn: number;
+    /** Recommended polling interval in seconds. */
+    interval: number;
+}
+/**
+ * Result of polling device authorization status.
+ */
+interface DeviceAuthPollResult {
+    /** Current status of the authorization request. */
+    status: "pending" | "approved" | "denied" | "expired";
+    /** Access token (only present when status is "approved"). */
+    accessToken?: string;
+}
+/**
+ * Options for the device authorization flow.
+ */
+interface DeviceAuthOptions {
+    /** Optional client information displayed to the user during approval. */
+    clientInfo?: string;
+    /**
+     * Callback invoked when user authorization is required.
+     * Display the verification URL and code to the user.
+     */
+    onAuthRequired: (params: {
+        verificationUrl: string;
+        userCode: string;
+    }) => void;
+    /**
+     * Optional callback invoked when authorization is approved.
+     */
+    onAuthApproved?: () => void;
+    /**
+     * Optional callback invoked when authorization is denied.
+     */
+    onAuthDenied?: () => void;
+    /**
+     * Optional callback invoked when authorization times out.
+     */
+    onAuthTimeout?: () => void;
+    /**
+     * Timeout in milliseconds for the polling loop.
+     * Defaults to 600000 (10 minutes).
+     */
+    pollTimeout?: number;
+}
+/**
+ * Device authorization flow implementation.
+ *
+ * @example
+ * ```typescript
+ * const flow = new DeviceAuthFlow("https://api.tentacle.live")
+ *
+ * // Initiate the flow
+ * const { deviceCode, userCode, verificationUrl } = await flow.initiate({
+ *   clientInfo: "My Game v1.0",
+ * })
+ *
+ * // Display to user
+ * console.log(`Visit ${verificationUrl}`)
+ * console.log(`Enter code: ${userCode}`)
+ *
+ * // Poll until approved
+ * const result = await flow.pollUntilComplete(deviceCode, 5000)
+ * if (result.status === "approved") {
+ *   console.log(`Authenticated! Token: ${result.accessToken}`)
+ * }
+ * ```
+ */
+declare class DeviceAuthFlow {
+    private readonly baseUrl;
+    constructor(baseUrl: string);
+    /**
+     * Initiates a device authorization request.
+     *
+     * @param options - Options for the request.
+     * @returns Device and user codes for authorization.
+     */
+    initiate(options?: {
+        clientInfo?: string;
+    }): Promise<DeviceAuthInitResult>;
+    /**
+     * Polls for the current authorization status.
+     *
+     * @param deviceCode - The device code from initiate().
+     * @returns Current authorization status.
+     */
+    poll(deviceCode: string): Promise<DeviceAuthPollResult>;
+    /**
+     * Polls until authorization is complete (approved, denied, or expired).
+     *
+     * @param deviceCode - The device code from initiate().
+     * @param intervalMs - Polling interval in milliseconds.
+     * @param timeoutMs - Maximum time to wait in milliseconds.
+     * @returns Final authorization result.
+     */
+    pollUntilComplete(deviceCode: string, intervalMs?: number, timeoutMs?: number): Promise<DeviceAuthPollResult>;
+}
+
+/**
+ * Main Tentacle SDK client.
+ *
+ * @module client
+ */
+
+/**
+ * Configuration options for the TentacleClient.
+ */
+interface TentacleClientConfig {
+    /**
+     * Base URL of the Tentacle API.
+     *
+     * @example "https://api.tentacle.live"
+     */
+    baseUrl: string;
+    /**
+     * Access token for authentication.
+     * Required for most API operations.
+     *
+     * You can obtain an access token from the Tentacle dashboard.
+     *
+     * @example "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+     */
+    accessToken?: string;
+}
+/**
+ * Options for creating a TentacleClient with automatic authentication.
+ */
+interface TentacleClientCreateOptions {
+    /**
+     * Base URL of the Tentacle API.
+     *
+     * @example "https://api.tentacle.live"
+     */
+    baseUrl: string;
+    /**
+     * Credential store for persisting access tokens.
+     * The SDK will check for a cached token and use it if valid.
+     */
+    credentialStore: CredentialStore;
+    /**
+     * Options for the device authorization flow.
+     * Used when no valid cached token is available.
+     */
+    deviceAuthOptions: DeviceAuthOptions;
+}
+/**
+ * Apps API for managing apps and viewer properties.
+ */
+declare class AppsApi {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Create a new app.
+     *
+     * @param options - App creation options
+     * @param options.name - Name of the app
+     * @returns The created app
+     *
+     * @example
+     * ```typescript
+     * const { app } = await client.apps.create({ name: "My Game" })
+     * console.log(`Created app: ${app.id}`)
+     * ```
+     */
+    create(options: {
+        name: string;
+    }): Promise<{
+        app: AppJson;
+    }>;
+    /**
+     * List all apps for the current user.
+     *
+     * @returns Array of apps
+     *
+     * @example
+     * ```typescript
+     * const { apps } = await client.apps.list()
+     * for (const app of apps) {
+     *   console.log(`${app.name}: ${app.id}`)
+     * }
+     * ```
+     */
+    list(): Promise<{
+        apps: AppJson[];
+    }>;
+    /**
+     * Get an app by name.
+     *
+     * @param options - Query options
+     * @param options.name - Name of the app
+     * @returns The app
+     *
+     * @example
+     * ```typescript
+     * const { app } = await client.apps.getByName({ name: "My Game" })
+     * console.log(`App ID: ${app.id}`)
+     * ```
+     */
+    getByName(options: {
+        name: string;
+    }): Promise<{
+        app: AppJson;
+    }>;
+    /**
+     * List apps for a viewer.
+     * Requires viewer authentication.
+     *
+     * @param options - Query options
+     * @param options.where - Filter options
+     * @param options.where.isActive - Filter by active status
+     * @returns Array of apps
+     *
+     * @example
+     * ```typescript
+     * const { apps } = await client.apps.listForViewer({ where: { isActive: true } })
+     * ```
+     */
+    listForViewer(options?: {
+        where?: {
+            isActive?: boolean;
+        };
+    }): Promise<{
+        apps: AppJson[];
+    }>;
+    /**
+     * Create or update viewer properties.
+     *
+     * @param properties - Array of viewer properties to create/update
+     * @returns Success status
+     *
+     * @example
+     * ```typescript
+     * await client.apps.createViewerProperties([
+     *   { id: "prop1", appId: "app1", viewerId: "v1", name: "score", type: "number", value: 100 },
+     * ])
+     * ```
+     */
+    createViewerProperties(properties: ViewerPropertyJson[]): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Update viewer properties.
+     *
+     * @param properties - Array of viewer properties to update
+     * @returns Success status
+     *
+     * @example
+     * ```typescript
+     * await client.apps.updateViewerProperties([
+     *   { id: "prop1", appId: "app1", viewerId: "v1", name: "score", type: "number", value: 150 },
+     * ])
+     * ```
+     */
+    updateViewerProperties(properties: ViewerPropertyJson[]): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Get viewers by property.
+     *
+     * @param options - Query options
+     * @param options.appId - App ID
+     * @param options.propertyName - Property name to query
+     * @param options.propertyType - Property type
+     * @param options.orderDirection - Order direction (asc/desc)
+     * @param options.take - Number of results (1-1000, default 20)
+     * @returns Viewers with the specified property
+     *
+     * @example
+     * ```typescript
+     * const result = await client.apps.getViewersByProperty({
+     *   appId: "app1",
+     *   propertyName: "score",
+     *   propertyType: "number",
+     *   orderDirection: "desc",
+     *   take: 10,
+     * })
+     * for (const viewer of result.viewers) {
+     *   console.log(`${viewer.twitch?.displayName}: ${viewer.properties.score.value}`)
+     * }
+     * ```
+     */
+    getViewersByProperty(options: {
+        appId: string;
+        propertyName: string;
+        propertyType: ViewerPropertyType;
+        orderDirection?: OrderDirection;
+        take?: number;
+    }): Promise<ViewersByPropertyOutput>;
+}
+/**
+ * Stream API for accessing chat messages and events.
+ */
+declare class StreamApi {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Get the latest chat messages from Twitch and Kick.
+     *
+     * @param options - Query options
+     * @param options.take - Maximum number of messages to return (default: 50)
+     * @param options.isCommand - Filter to only command messages (starting with !)
+     * @returns Array of chat messages from both platforms
+     *
+     * @example
+     * ```typescript
+     * // Get latest 50 chat messages
+     * const messages = await client.stream.getChatMessages()
+     *
+     * // Get latest 10 command messages
+     * const commands = await client.stream.getChatMessages({
+     *   take: 10,
+     *   isCommand: true,
+     * })
+     *
+     * for (const msg of messages) {
+     *   console.log(`[${msg.$platform}] ${msg.$text}`)
+     * }
+     * ```
+     */
+    getChatMessages(options?: {
+        take?: number;
+        isCommand?: boolean;
+    }): Promise<StreamChatMessageJson[]>;
+    /**
+     * Get the latest stream events from Twitch and Kick.
+     *
+     * Events include follows, subscriptions, raids, cheers, and more.
+     *
+     * @param options - Query options
+     * @param options.take - Maximum number of events to return (default: 50)
+     * @returns Array of stream events from both platforms
+     *
+     * @example
+     * ```typescript
+     * const events = await client.stream.getEvents({ take: 20 })
+     *
+     * for (const event of events) {
+     *   if (event.$platform === 'twitch') {
+     *     switch (event.$type) {
+     *       case 'channel.follow':
+     *         console.log(`New follower: ${event.userDisplayName}`)
+     *         break
+     *       case 'channel.subscribe':
+     *         console.log(`New subscriber: ${event.userDisplayName}`)
+     *         break
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    getEvents(options?: {
+        take?: number;
+    }): Promise<StreamEventJson[]>;
+}
+/**
+ * Subathon API for accessing subathon statistics.
+ */
+declare class SubathonApi {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Get subscription stats.
+     *
+     * @returns Subscription statistics
+     *
+     * @example
+     * ```typescript
+     * const stats = await client.subathonStats.getSubs()
+     * console.log(`Subs: ${stats.count}/${stats.goal}`)
+     * ```
+     */
+    getSubs(): Promise<SubathonStats_Subscriptions>;
+    /**
+     * Get gifted subscription stats.
+     *
+     * @returns Gifted subscription statistics
+     *
+     * @example
+     * ```typescript
+     * const stats = await client.subathonStats.getGiftedSubs()
+     * console.log(`Gifted subs: ${stats.count}`)
+     * ```
+     */
+    getGiftedSubs(): Promise<SubathonStats_GiftedSubscriptions>;
+    /**
+     * Get donation stats.
+     *
+     * @returns Donation statistics
+     *
+     * @example
+     * ```typescript
+     * const stats = await client.subathonStats.getDonations()
+     * console.log(`Donations: $${stats.dollars}`)
+     * ```
+     */
+    getDonations(): Promise<SubathonStats_Donations>;
+    /**
+     * Get subscription stats for overlay.
+     * Public endpoint - no authentication required.
+     *
+     * @param options - Query options
+     * @param options.email - User email
+     * @returns Subscription statistics or null if user not found
+     *
+     * @example
+     * ```typescript
+     * const stats = await client.subathonStats.getOverlaySubs({ email: "user@example.com" })
+     * if (stats) {
+     *   console.log(`Subs: ${stats.count}`)
+     * }
+     * ```
+     */
+    getOverlaySubs(options: {
+        email: string;
+    }): Promise<SubathonStats_Subscriptions | null>;
+    /**
+     * Get gifted subscription stats for overlay.
+     * Public endpoint - no authentication required.
+     *
+     * @param options - Query options
+     * @param options.email - User email
+     * @returns Gifted subscription statistics or null if user not found
+     *
+     * @example
+     * ```typescript
+     * const stats = await client.subathonStats.getOverlayGiftedSubs({ email: "user@example.com" })
+     * ```
+     */
+    getOverlayGiftedSubs(options: {
+        email: string;
+    }): Promise<SubathonStats_GiftedSubscriptions | null>;
+    /**
+     * Get donation stats for overlay.
+     * Public endpoint - no authentication required.
+     *
+     * @param options - Query options
+     * @param options.email - User email
+     * @returns Donation statistics or null if user not found
+     *
+     * @example
+     * ```typescript
+     * const stats = await client.subathonStats.getOverlayDonations({ email: "user@example.com" })
+     * ```
+     */
+    getOverlayDonations(options: {
+        email: string;
+    }): Promise<SubathonStats_Donations | null>;
+}
+/**
+ * Viewer API for accessing viewer data.
+ */
+declare class ViewerApi {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Create a viewer action.
+     * Requires viewer authentication.
+     *
+     * @param options - Action options
+     * @param options.name - Action name
+     * @param options.data - Action data
+     * @param options.appId - App ID
+     * @returns Success status
+     *
+     * @example
+     * ```typescript
+     * await client.viewer.createAction({
+     *   name: "button_click",
+     *   data: { buttonId: "play" },
+     *   appId: "app1",
+     * })
+     * ```
+     */
+    createAction(options: {
+        name: string;
+        data: unknown;
+        appId: string;
+    }): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Get mini viewer data.
+     *
+     * @param options - Query options
+     * @param options.viewerId - Viewer ID
+     * @returns Viewer mini data
+     *
+     * @example
+     * ```typescript
+     * const viewer = await client.viewer.getMini({ viewerId: "v1" })
+     * console.log(`Twitch: ${viewer.twitch?.displayName}`)
+     * ```
+     */
+    getMini(options: {
+        viewerId: string;
+    }): Promise<ViewerMiniJson>;
+    /**
+     * Get full viewer data including properties.
+     *
+     * @param options - Query options
+     * @param options.viewerId - Viewer ID
+     * @returns Full viewer data
+     *
+     * @example
+     * ```typescript
+     * const viewer = await client.viewer.get({ viewerId: "v1" })
+     * console.log(`Twitch: ${viewer.twitch?.displayName}`)
+     * if (viewer.properties) {
+     *   for (const [name, prop] of Object.entries(viewer.properties)) {
+     *     console.log(`${name}: ${prop.value}`)
+     *   }
+     * }
+     * ```
+     */
+    get(options: {
+        viewerId: string;
+    }): Promise<ViewerJson>;
+}
+/**
+ * Main client for the Tentacle API.
+ *
+ * Provides access to Tentacle API endpoints including:
+ * - **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
+ *
+ * @example
+ * ```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 })
+ * ```
+ */
+declare class TentacleClient {
+    private readonly http;
+    /**
+     * Creates a TentacleClient with automatic authentication.
+     *
+     * This factory method handles the device authorization flow:
+     * 1. Checks for a cached token in the credential store
+     * 2. Validates the cached token with the API
+     * 3. If invalid or missing, initiates device authorization
+     * 4. Caches the new token after successful authorization
+     *
+     * @param options - Creation options
+     * @returns A configured TentacleClient
+     *
+     * @example
+     * ```typescript
+     * const client = await TentacleClient.create({
+     *   baseUrl: "https://api.tentacle.live",
+     *   credentialStore: new FileCredentialStore(),
+     *   deviceAuthOptions: {
+     *     clientInfo: "My Unreal Game",
+     *     onAuthRequired: ({ verificationUrl, userCode }) => {
+     *       console.log(`Visit: ${verificationUrl}`)
+     *       console.log(`Enter code: ${userCode}`)
+     *     },
+     *   },
+     * })
+     * ```
+     */
+    static create(options: TentacleClientCreateOptions): Promise<TentacleClient>;
+    /**
+     * Apps API for managing apps and viewer properties.
+     *
+     * @example
+     * ```typescript
+     * const { apps } = await client.apps.list()
+     * const { app } = await client.apps.create({ name: "My Game" })
+     * ```
+     */
+    readonly apps: AppsApi;
+    /**
+     * Realtime API for subscribing to live Twitch and Kick events.
+     *
+     * Use this to receive:
+     * - Chat messages from Twitch and Kick
+     * - Stream events (follows, subs, raids, cheers, etc.)
+     * - Viewer activity updates
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = client.realtime.subscribe({
+     *   onEvent: (event) => {
+     *     switch (event.kind) {
+     *       case 'StreamChatMessage':
+     *         console.log(event.payload.$text)
+     *         break
+     *       case 'StreamEvent':
+     *         console.log(event.payload.$type)
+     *         break
+     *     }
+     *   },
+     * })
+     * ```
+     */
+    readonly realtime: RealtimeApi;
+    /**
+     * Stream API for accessing chat messages and events history.
+     *
+     * @example
+     * ```typescript
+     * const messages = await client.stream.getChatMessages({ take: 50 })
+     * const events = await client.stream.getEvents({ take: 20 })
+     * ```
+     */
+    readonly stream: StreamApi;
+    /**
+     * Subathon API for accessing subathon statistics.
+     *
+     * @example
+     * ```typescript
+     * const subs = await client.subathon.getSubs()
+     * const donations = await client.subathon.getDonations()
+     * ```
+     */
+    readonly subathon: SubathonApi;
+    /**
+     * Viewer API for accessing viewer data.
+     *
+     * @example
+     * ```typescript
+     * const viewer = await client.viewer.get({ viewerId: "v1" })
+     * ```
+     */
+    readonly viewer: ViewerApi;
+    /**
+     * Create a new Tentacle client.
+     *
+     * @param config - Client configuration
+     * @param config.baseUrl - Base URL of the Tentacle API
+     * @param config.accessToken - Access token for authentication
+     *
+     * @example
+     * ```typescript
+     * const client = new TentacleClient({
+     *   baseUrl: 'https://api.tentacle.live',
+     *   accessToken: 'your-access-token',
+     * })
+     * ```
+     */
+    constructor(config: TentacleClientConfig);
+}
+
+/**
+ * File-based credential store for Node.js environments.
+ *
+ * Stores access tokens in a JSON file on the local filesystem.
+ * Default location: ~/.tentacle/credentials.json
+ *
+ * @module auth/file-credential-store
+ */
+
+/**
+ * Options for configuring the FileCredentialStore.
+ */
+interface FileCredentialStoreOptions {
+    /**
+     * Path to the credentials file.
+     * Defaults to ~/.tentacle/credentials.json
+     */
+    path?: string;
+}
+/**
+ * File-based credential store implementation.
+ *
+ * Stores access tokens in a JSON file with restricted permissions (0o600).
+ * Uses dynamic imports for Node.js fs module to support non-Node environments.
+ *
+ * @example
+ * ```typescript
+ * const store = new FileCredentialStore()
+ * await store.setAccessToken("my-token")
+ * const token = await store.getAccessToken()
+ * ```
+ */
+declare class FileCredentialStore implements CredentialStore {
+    private readonly path;
+    constructor(options?: FileCredentialStoreOptions);
+    /**
+     * Gets the default credentials file path.
+     */
+    private getDefaultPath;
+    /**
+     * Retrieves the stored access token.
+     */
+    getAccessToken(): Promise<string | null>;
+    /**
+     * Stores an access token.
+     *
+     * Creates the directory if it doesn't exist.
+     * Sets file permissions to 0o600 (user read/write only).
+     */
+    setAccessToken(token: string): Promise<void>;
+    /**
+     * Removes the stored access token.
+     */
+    clearAccessToken(): Promise<void>;
+}
+
+export { type AppJson, type ChatMessageEmoji, type ChatMessageEmote, type ChatMessagePosition, type CommonChatMessage, type CommonEventJson, type CredentialStore, type DateIsoString, DeviceAuthFlow, type DeviceAuthInitResult, type DeviceAuthOptions, type DeviceAuthPollResult, type DonationUnlock, FileCredentialStore, type FileCredentialStoreOptions, type GiftedSubUnlock, type KickBadge, type KickChatMessageJson, type KickEventJson, type KickEventJson_ChannelFollow, type KickEventJson_ChannelSubscriptionGifts, type KickEventJson_ChannelSubscriptionNew, type KickEventJson_ChannelSubscriptionRenewal, type KickEventJson_LivestreamStatusUpdated, type OrderDirection, type RealtimeEvent, type RealtimeEvent_StreamChatMessage, type RealtimeEvent_StreamEvent, type RealtimeEvent_StreamViewerActivity, type RealtimeSubscribeOptions, type StreamChatMessageJson, type StreamEventJson, type StreamPlatform, type StreamViewerActivityJson, type SubUnlock, type SubathonStats_Donations, type SubathonStats_GiftedSubscriptions, type SubathonStats_Subscriptions, TentacleClient, type TentacleClientConfig, type TentacleClientCreateOptions, TentacleError, type TwitchChatMessageJson, type TwitchEventJson, type TwitchEventJson_Cheer, type TwitchEventJson_Follow, type TwitchEventJson_Raid, type TwitchEventJson_RedemptionAdd, type TwitchEventJson_StreamOnline, type TwitchEventJson_Subscription, type TwitchEventJson_SubscriptionGift, type TwitchEventType, type TwitchUserInfo, type UnsubscribeFunction, type ViewerActionJson, type ViewerJson, type ViewerKickJson, type ViewerMiniJson, type ViewerPropertyJson, type ViewerPropertyJsonBase, type ViewerPropertyJson_Bool, type ViewerPropertyJson_Number, type ViewerPropertyJson_String, type ViewerPropertyType, type ViewerTwitchJson, type ViewersByPropertyOutput };