@gala-chain/launchpad-sdk 5.0.3 → 5.0.4-beta.1

package/dist/src/services/StreamChatService.d.ts

@@ -0,0 +1,378 @@
+/**
+ * Stream Chat Service
+ *
+ * Handles all stream chat operations including message retrieval,
+ * sending messages, and chat status management.
+ *
+ * @category Services
+ * @since 5.1.0
+ */
+import { HttpClient } from '../utils/http';
+import { StreamTokenServiceBase } from './StreamTokenServiceBase';
+import type { JwtAuth } from '../auth/JwtAuth';
+import { SendChatMessageOptions, FetchChatMessagesOptions, ChatMessagesResult, SendChatMessageResult, DeleteChatMessageOptions, DeleteChatMessageResult, ChatStatusResponse, GlobalChatStatus, PinMessageOptions, PinMessageResult, UnpinMessageResult, GetPinnedMessageResult, GetEngagementStatsOptions, EngagementStatsResult } from '../types/stream-chat.dto';
+/**
+ * Stream Chat Service Class
+ *
+ * Provides methods for:
+ * - Message retrieval (paginated with cursor support)
+ * - Sending messages (authenticated)
+ * - Chat status management (per-token and global)
+ *
+ * @example
+ * ```typescript
+ * const chatService = new StreamChatService(httpClient, 'admin-api-key', true);
+ *
+ * // Get chat messages
+ * const messages = await chatService.getMessages({ tokenName: 'mytoken', limit: 50 });
+ *
+ * // Send a message
+ * const result = await chatService.sendMessage({
+ *   tokenName: 'mytoken',
+ *   content: 'Hello world!'
+ * });
+ * ```
+ */
+export declare class StreamChatService extends StreamTokenServiceBase {
+    constructor(http: HttpClient, adminApiKey?: string, jwtAuth?: JwtAuth, debugMode?: boolean);
+    /**
+     * Get chat messages for a token
+     *
+     * Public endpoint - no authentication required.
+     * Supports pagination with page/limit and cursor-based navigation.
+     *
+     * @param options Fetch options including tokenName and pagination
+     * @returns Paginated list of chat messages
+     * @throws ValidationError if token name is invalid
+     *
+     * @example
+     * ```typescript
+     * // Basic usage
+     * const messages = await chatService.getMessages({ tokenName: 'mytoken' });
+     *
+     * // With pagination
+     * const page2 = await chatService.getMessages({
+     *   tokenName: 'mytoken',
+     *   page: 2,
+     *   limit: 25,
+     *   sortOrder: 'desc'
+     * });
+     *
+     * // Cursor-based pagination
+     * const next = await chatService.getMessages({
+     *   tokenName: 'mytoken',
+     *   cursor: messages.nextCursor
+     * });
+     * ```
+     */
+    getMessages(options: FetchChatMessagesOptions): Promise<ChatMessagesResult>;
+    /**
+     * Send a chat message
+     *
+     * Requires JWT authentication.
+     *
+     * **Rate Limits:**
+     * - Messages are subject to backend rate limiting
+     * - Excessive requests may result in temporary throttling
+     * - For real-time chat, consider using WebSocket via StreamWebSocketService
+     *
+     * @param options Message options including tokenName and content
+     * @returns Created message with server-assigned IDs
+     * @throws ValidationError if token name or content is invalid
+     * @throws Error if user is not authenticated
+     * @throws Error if rate limit exceeded (HTTP 429)
+     *
+     * @example
+     * ```typescript
+     * const result = await chatService.sendMessage({
+     *   tokenName: 'mytoken',
+     *   content: 'Hello everyone!'
+     * });
+     * console.log('Message ID:', result.message.messageId);
+     * console.log('Created at:', result.message.createdAt);
+     * ```
+     */
+    sendMessage(options: SendChatMessageOptions): Promise<SendChatMessageResult>;
+    /**
+     * Delete a chat message
+     *
+     * Supports three authorization methods:
+     * 1. **Message Author**: User who sent the message (JWT auth)
+     * 2. **Stream Owner**: Owner of the token/stream (JWT auth)
+     * 3. **Admin**: Platform administrator (admin API key)
+     *
+     * Deleted messages:
+     * - Immediately notify viewers via WebSocket (`stream_chat_deleted` event)
+     * - Excluded from GET /chat responses on refresh
+     *
+     * @param options Delete options including tokenName and messageId
+     * @returns Deletion result confirming the message was deleted
+     * @throws ValidationError if token name or messageId is invalid
+     * @throws Error if user is not authenticated (JWT required unless admin)
+     * @throws Error if user is not authorized to delete the message
+     * @throws Error if message not found (404)
+     *
+     * @since 5.3.0
+     *
+     * @example
+     * ```typescript
+     * // Delete as message author or stream owner (JWT auth)
+     * const result = await chatService.deleteMessage({
+     *   tokenName: 'mytoken',
+     *   messageId: 'chat-1702656000000-a1b2c3d4'
+     * });
+     * console.log('Deleted:', result.deleted);
+     *
+     * // Delete as admin (requires admin API key set in constructor)
+     * const adminResult = await adminChatService.deleteMessage({
+     *   tokenName: 'mytoken',
+     *   messageId: 'chat-1702656000000-a1b2c3d4'
+     * });
+     * ```
+     */
+    deleteMessage(options: DeleteChatMessageOptions): Promise<DeleteChatMessageResult>;
+    /**
+     * Get chat status for a token
+     *
+     * Public endpoint - no authentication required.
+     *
+     * @param tokenName Token name (lowercase)
+     * @returns Chat enabled status, detailed status, and reason if disabled
+     * @throws ValidationError if token name is invalid
+     *
+     * @example
+     * ```typescript
+     * const status = await chatService.getChatStatus('mytoken');
+     * console.log('Chat enabled:', status.enabled);
+     * console.log('Status:', status.status); // 'ENABLED' | 'DISABLED' | 'ADMIN_DISABLED'
+     * if (!status.enabled) {
+     *   console.log('Reason:', status.reason); // 'global' or 'token'
+     * }
+     * ```
+     */
+    getChatStatus(tokenName: string): Promise<ChatStatusResponse>;
+    /**
+     * Disable chat for a token
+     *
+     * Dual-auth endpoint - supports both Admin API key and JWT (owner) auth.
+     *
+     * Authorization behavior:
+     * - **Admin (API key)**: Sets ADMIN_DISABLED - owner is locked out
+     * - **Owner (JWT)**: Sets DISABLED - owner can re-enable later
+     *
+     * When ADMIN_DISABLED, the owner cannot enable chat until an admin enables it again.
+     *
+     * @param tokenName Token name (lowercase)
+     * @returns Updated enabled status with detailed status
+     * @throws ConfigurationError if neither admin API key nor JWT is configured
+     * @throws ValidationError if token name is invalid
+     * @throws Error if owner tries to disable when ADMIN_DISABLED (403)
+     *
+     * @since 5.4.0 - Added dual-auth support (API key OR JWT)
+     *
+     * @example
+     * ```typescript
+     * // As admin (using API key)
+     * await adminChatService.disableChat('mytoken');
+     * // Sets ADMIN_DISABLED - owner locked out
+     *
+     * // As owner (using JWT)
+     * await ownerChatService.disableChat('mytoken');
+     * // Sets DISABLED - owner can re-enable
+     * ```
+     */
+    disableChat(tokenName: string): Promise<{
+        enabled: boolean;
+        tokenName: string;
+        status?: string;
+    }>;
+    /**
+     * Enable chat for a token
+     *
+     * Dual-auth endpoint - supports both Admin API key and JWT (owner) auth.
+     *
+     * Authorization behavior:
+     * - **Admin (API key)**: Sets ENABLED - clears any lock, owner regains control
+     * - **Owner (JWT)**: Sets ENABLED - only works if not ADMIN_DISABLED
+     *
+     * When ADMIN_DISABLED, only an admin can enable chat.
+     * Owners attempting to enable when ADMIN_DISABLED will get a 403 error.
+     *
+     * @param tokenName Token name (lowercase)
+     * @returns Updated enabled status with detailed status
+     * @throws ConfigurationError if neither admin API key nor JWT is configured
+     * @throws ValidationError if token name is invalid
+     * @throws Error if owner tries to enable when ADMIN_DISABLED (403)
+     *
+     * @since 5.4.0 - Added dual-auth support (API key OR JWT)
+     *
+     * @example
+     * ```typescript
+     * // As admin (using API key) - clears admin lock
+     * await adminChatService.enableChat('mytoken');
+     * // Sets ENABLED - owner can now manage chat
+     *
+     * // As owner (using JWT)
+     * await ownerChatService.enableChat('mytoken');
+     * // Sets ENABLED (fails with 403 if ADMIN_DISABLED)
+     * ```
+     */
+    enableChat(tokenName: string): Promise<{
+        enabled: boolean;
+        tokenName: string;
+        status?: string;
+    }>;
+    /**
+     * Get global chat status
+     *
+     * Public endpoint - no authentication required.
+     *
+     * @returns Global chat enabled status
+     *
+     * @example
+     * ```typescript
+     * const status = await chatService.getGlobalChatStatus();
+     * console.log('Chat enabled globally:', status.enabled);
+     * ```
+     */
+    getGlobalChatStatus(): Promise<GlobalChatStatus>;
+    /**
+     * Disable chat globally
+     *
+     * Admin endpoint - requires admin API key.
+     *
+     * @returns Updated global chat status
+     * @throws ConfigurationError if admin API key is not set
+     *
+     * @example
+     * ```typescript
+     * await chatService.disableGlobalChat();
+     * console.log('Chat disabled globally');
+     * ```
+     */
+    disableGlobalChat(): Promise<GlobalChatStatus>;
+    /**
+     * Enable chat globally
+     *
+     * Admin endpoint - requires admin API key.
+     *
+     * @returns Updated global chat status
+     * @throws ConfigurationError if admin API key is not set
+     *
+     * @example
+     * ```typescript
+     * await chatService.enableGlobalChat();
+     * console.log('Chat enabled globally');
+     * ```
+     */
+    enableGlobalChat(): Promise<GlobalChatStatus>;
+    /**
+     * Get the currently pinned message for a token
+     *
+     * Public endpoint - no authentication required.
+     *
+     * @param tokenName Token name (lowercase)
+     * @returns Pinned message data, or null if no message is pinned
+     * @throws ValidationError if token name is invalid
+     *
+     * @since 5.5.0
+     *
+     * @example
+     * ```typescript
+     * const result = await chatService.getPinnedMessage('mytoken');
+     * if (result.pinnedMessage) {
+     *   console.log('Pinned:', result.pinnedMessage.content);
+     *   console.log('Pinned by:', result.pinnedMessage.pinnedBy);
+     * } else {
+     *   console.log('No message is currently pinned');
+     * }
+     * ```
+     */
+    getPinnedMessage(tokenName: string): Promise<GetPinnedMessageResult>;
+    /**
+     * Pin a message to the top of the chat
+     *
+     * Admin endpoint - requires admin API key.
+     *
+     * **Behavior:**
+     * - Only one message can be pinned at a time per stream
+     * - Pinning a new message automatically unpins any existing pinned message
+     * - The pinned message remains visible at the top of the chat
+     * - Pinned message is cached in Redis for fast retrieval
+     *
+     * @param options Pin options including tokenName and messageId
+     * @returns The pinned message data
+     * @throws ConfigurationError if admin API key is not set
+     * @throws ValidationError if token name or messageId is invalid
+     * @throws Error if message not found (404)
+     * @throws Error if message is already deleted
+     *
+     * @since 5.5.0
+     *
+     * @example
+     * ```typescript
+     * const result = await chatService.pinMessage({
+     *   tokenName: 'mytoken',
+     *   messageId: 'chat-1702656000000-a1b2c3d4'
+     * });
+     * console.log('Pinned message:', result.pinnedMessage.content);
+     * ```
+     */
+    pinMessage(options: PinMessageOptions): Promise<PinMessageResult>;
+    /**
+     * Unpin the currently pinned message
+     *
+     * Admin endpoint - requires admin API key.
+     *
+     * If no message is currently pinned, this operation succeeds silently.
+     *
+     * @param tokenName Token name (lowercase)
+     * @returns Result indicating whether a message was unpinned
+     * @throws ConfigurationError if admin API key is not set
+     * @throws ValidationError if token name is invalid
+     *
+     * @since 5.5.0
+     *
+     * @example
+     * ```typescript
+     * const result = await chatService.unpinMessage('mytoken');
+     * if (result.unpinned) {
+     *   console.log('Unpinned message:', result.unpinnedMessageId);
+     * } else {
+     *   console.log('No message was pinned');
+     * }
+     * ```
+     */
+    unpinMessage(tokenName: string): Promise<UnpinMessageResult>;
+    /**
+     * Get engagement statistics for a token
+     *
+     * Dual-auth endpoint - supports both Admin API key and JWT auth.
+     * Requires MANAGE_CHAT permission when using JWT auth.
+     *
+     * Returns combined statistics for:
+     * - **Chat**: Message count and unique chatters (scoped to current/last stream session)
+     * - **Comments**: Total count and unique commenters (all-time)
+     *
+     * Used by the Studio analytics dashboard.
+     *
+     * @param options Options including tokenName
+     * @returns Engagement statistics for chat and comments
+     * @throws ValidationError if token name is invalid
+     * @throws Error if user lacks MANAGE_CHAT permission (403)
+     *
+     * @since 5.10.0
+     *
+     * @example
+     * ```typescript
+     * const stats = await chatService.getEngagementStats({ tokenName: 'mytoken' });
+     * console.log('Chat messages:', stats.chat.messageCount);
+     * console.log('Unique chatters:', stats.chat.uniqueChatters);
+     * console.log('Chat since:', stats.chat.since);
+     * console.log('Total comments:', stats.comments.count);
+     * console.log('Unique commenters:', stats.comments.uniqueCommenters);
+     * ```
+     */
+    getEngagementStats(options: GetEngagementStatsOptions): Promise<EngagementStatsResult>;
+}
+//# sourceMappingURL=StreamChatService.d.ts.map

package/dist/src/services/StreamChatService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StreamChatService.d.ts","sourceRoot":"","sources":["../../../src/services/StreamChatService.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAI3C,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAI/C,OAAO,EACL,sBAAsB,EACtB,wBAAwB,EACxB,kBAAkB,EAClB,qBAAqB,EACrB,wBAAwB,EACxB,uBAAuB,EACvB,kBAAkB,EAClB,gBAAgB,EAQhB,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EAClB,sBAAsB,EAKtB,yBAAyB,EACzB,qBAAqB,EAQtB,MAAM,0BAA0B,CAAC;AAElC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,iBAAkB,SAAQ,sBAAsB;gBAEzD,IAAI,EAAE,UAAU,EAChB,WAAW,CAAC,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,OAAO,EACjB,SAAS,GAAE,OAAe;IAS5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACG,WAAW,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA2CjF;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACG,WAAW,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IA6BlF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;IACG,aAAa,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAuCxF;;;;;;;;;;;;;;;;;;OAkBG;IACG,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAiBnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACG,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IA6BvG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAiCtG;;;;;;;;;;;;OAYG;IACG,mBAAmB,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAQtD;;;;;;;;;;;;;OAaG;IACG,iBAAiB,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAUpD;;;;;;;;;;;;;OAaG;IACG,gBAAgB,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAcnD;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAc1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACG,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAqBvE;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA0BlE;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACG,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,OAAO,CAAC,qBAAqB,CAAC;CA6B7F"}