@gala-chain/launchpad-sdk 6.0.0 → 7.0.0-beta.1

package/dist/src/types/stream-chat.dto.d.ts

@@ -1,810 +0,0 @@
-/**
- * Stream Chat API Data Transfer Objects and Types
- *
- * This module defines all types and interfaces for stream chat operations including
- * message sending/retrieval, chat status management, and WebSocket events.
- *
- * @since 5.1.0
- * @since 6.0.0 - Added reactions support to StreamChatMessage
- */
-import type { AddressFormat, HolderTierInfo, InternalApiResponse, PaginationParams, UserProfileInfo } from './common';
-import type { ReactionData } from './content-reactions.dto';
-/**
- * Consolidated chat constraints object combining message, pagination, and token name constraints
- */
-export declare const CHAT_CONSTRAINTS: {
-    readonly MESSAGE: {
-        readonly MIN_LENGTH: 1;
-        readonly MAX_LENGTH: 500;
-        readonly PATTERN: RegExp;
-    };
-    readonly PAGINATION: {
-        readonly DEFAULT_OFFSET: number | undefined;
-        readonly DEFAULT_LIMIT: number | undefined;
-        readonly MAX_LIMIT: number;
-    };
-    readonly TOKEN_NAME: {
-        readonly MIN_LENGTH: number;
-        readonly MAX_LENGTH: number;
-        readonly PATTERN: RegExp;
-    };
-};
-/**
- * Stream chat message
- *
- * Note: Messages have TWO IDs:
- * - `id`: MySQL auto-increment ID (may be undefined until flushed to DB)
- * - `messageId`: UUID-based string ID (always present, format: chat-{timestamp}-{uuid8})
- *
- * @since 5.1.0
- * @since 6.0.0 - Added reactions field
- */
-export interface StreamChatMessage {
-    /**
-     * MySQL database ID (auto-increment)
-     *
-     * May be undefined if the message hasn't been flushed to the database yet.
-     * Use `messageId` for reliable message identification.
-     */
-    id?: number;
-    /**
-     * Unique string identifier (always present)
-     *
-     * Format: `chat-{timestamp}-{uuid8}`
-     * Example: `chat-1702656000000-a1b2c3d4`
-     *
-     * This is the primary identifier for message deduplication and tracking.
-     */
-    messageId: string;
-    /** Message content (sanitized, max 500 chars) */
-    content: string;
-    /** Sender's wallet address in backend format */
-    userAddress: AddressFormat;
-    /** Token name this message belongs to */
-    tokenName: string;
-    /** Message creation timestamp (ISO 8601) */
-    createdAt: string;
-    /** Sender's profile information (may not be present in all responses) */
-    user?: UserProfileInfo;
-    /**
-     * Reaction data for this message (grouped by type with counts and user previews)
-     *
-     * @since 6.0.0
-     */
-    reactions?: ReactionData;
-    /**
-     * Holder tier badge for the message author (token-specific)
-     *
-     * Shows the author's token holding tier based on % of max supply held.
-     * Only present if the user holds tokens. Omitted for non-holders.
-     *
-     * @since 6.5.0
-     */
-    holderTier?: HolderTierInfo;
-}
-/**
- * Options for sending a chat message
- */
-export interface SendChatMessageOptions {
-    /** Token name for the chat room */
-    tokenName: string;
-    /** Message content (max 500 characters) */
-    content: string;
-}
-/**
- * Options for fetching chat messages
- */
-export interface FetchChatMessagesOptions extends Partial<PaginationParams> {
-    /** Token name for the chat room */
-    tokenName: string;
-    /** Cursor for pagination (messageId or timestamp) */
-    cursor?: string;
-    /** Sort order: 'asc' (oldest first) or 'desc' (newest first) */
-    sortOrder?: 'asc' | 'desc';
-}
-/**
- * Result from GET /live/:tokenName/chat
- */
-export interface ChatMessagesResult {
-    /** Array of chat messages */
-    messages: StreamChatMessage[];
-    /** Token name */
-    tokenName: string;
-    /** Current page number */
-    page: number;
-    /** Items per page */
-    limit: number;
-    /** Total number of messages */
-    total: number;
-    /** Whether there are more messages */
-    hasNext: boolean;
-    /** Cursor for next page (if available) */
-    nextCursor?: string;
-    /** Currently pinned message (if any) */
-    pinnedMessage: PinnedMessage | null;
-}
-/**
- * Result from POST /live/:tokenName/chat
- */
-export interface SendChatMessageResult {
-    /** Created message */
-    message: StreamChatMessage;
-    /** Token name */
-    tokenName: string;
-}
-/**
- * Options for deleting a chat message
- * @since 5.3.0
- */
-export interface DeleteChatMessageOptions {
-    /** Token name for the chat room */
-    tokenName: string;
-    /** Message ID to delete (UUID-based string ID) */
-    messageId: string;
-}
-/**
- * Result from DELETE /live/:tokenName/chat/:messageId
- * @since 5.3.0
- */
-export interface DeleteChatMessageResult {
-    /** Message ID that was deleted */
-    messageId: string;
-    /** Whether the message was successfully deleted */
-    deleted: boolean;
-    /** Token name */
-    tokenName: string;
-}
-/**
- * Feature status values for chat and stream control
- *
- * - 'ENABLED': Feature is on (default)
- * - 'DISABLED': Owner disabled (owner can re-enable)
- * - 'ADMIN_DISABLED': Admin disabled (owner locked out, only admin can change)
- *
- * @since 5.4.0
- */
-export declare const FEATURE_STATUS: {
-    readonly ENABLED: "ENABLED";
-    readonly DISABLED: "DISABLED";
-    readonly ADMIN_DISABLED: "ADMIN_DISABLED";
-};
-/**
- * Type for feature status values
- */
-export type FeatureStatusType = (typeof FEATURE_STATUS)[keyof typeof FEATURE_STATUS];
-/** Check if a value is a valid FeatureStatusType */
-export declare const isFeatureStatus: (value: unknown) => value is "DISABLED" | "ENABLED" | "ADMIN_DISABLED";
-/**
- * Reason why chat is disabled
- *
- * - 'global': Chat is disabled globally for all tokens
- * - 'token': Chat is disabled specifically for this token
- */
-export type ChatDisabledReason = 'global' | 'token';
-/**
- * Chat status response from GET /live/:tokenName/chat/status
- *
- * @since 5.1.0 - Added `reason` field based on backend review
- * @since 5.4.0 - Added `status` field for detailed feature status
- */
-export interface ChatStatusResponse {
-    /** Whether chat is enabled (computed from status) */
-    enabled: boolean;
-    /**
-     * Detailed feature status (v5.4.0+)
-     *
-     * - 'ENABLED': Chat is on
-     * - 'DISABLED': Owner disabled (owner can re-enable)
-     * - 'ADMIN_DISABLED': Admin disabled (owner locked out)
-     */
-    status?: FeatureStatusType;
-    /**
-     * Reason why chat is disabled (only present when enabled=false)
-     *
-     * - 'global': Chat is disabled globally for all tokens
-     * - 'token': Chat is disabled specifically for this token
-     */
-    reason?: ChatDisabledReason;
-}
-/**
- * Global chat status response from GET /live/chat/global/status
- */
-export interface GlobalChatStatus {
-    /** Whether chat is globally enabled */
-    enabled: boolean;
-    /** Last status change timestamp (ISO 8601) */
-    updatedAt?: string;
-}
-/**
- * Pinned message data
- *
- * Only one message can be pinned per stream at a time.
- * Pinning a new message automatically unpins any existing one.
- *
- * @since 5.5.0
- */
-export interface PinnedMessage {
-    /** Message ID of the pinned message (UUID-based string) */
-    messageId: string;
-    /** Message content */
-    content: string;
-    /** Wallet address of the message author */
-    userAddress: AddressFormat;
-    /** Wallet address of who pinned the message */
-    pinnedBy: AddressFormat;
-    /** Timestamp when message was pinned (ISO 8601) */
-    pinnedAt: string;
-    /** Author's profile information */
-    user?: UserProfileInfo;
-    /**
-     * Holder tier badge for the message author (token-specific)
-     *
-     * @since 6.5.0
-     */
-    holderTier?: HolderTierInfo;
-}
-/**
- * Options for pinning a chat message
- *
- * Admin API key required.
- *
- * @since 5.5.0
- */
-export interface PinMessageOptions {
-    /** Token name for the chat room */
-    tokenName: string;
-    /** Message ID to pin (UUID-based string ID) */
-    messageId: string;
-}
-/**
- * Result from POST /live/:tokenName/chat/pin
- *
- * @since 5.5.0
- */
-export interface PinMessageResult {
-    /** Token name */
-    tokenName: string;
-    /** The pinned message data */
-    pinnedMessage: PinnedMessage;
-}
-/**
- * Result from DELETE /live/:tokenName/chat/pin
- *
- * @since 5.5.0
- */
-export interface UnpinMessageResult {
-    /** Token name */
-    tokenName: string;
-    /** Whether a message was unpinned */
-    unpinned: boolean;
-    /** Message ID that was unpinned (if any) */
-    unpinnedMessageId?: string;
-}
-/**
- * Result from GET /live/:tokenName/chat/pinned
- *
- * @since 5.5.0
- */
-export interface GetPinnedMessageResult {
-    /** Token name */
-    tokenName: string;
-    /** The pinned message data, or null if no message is pinned */
-    pinnedMessage: PinnedMessage | null;
-}
-/**
- * WebSocket event: stream_chat_message
- *
- * Emitted when a new chat message is sent in a stream room
- */
-export type StreamChatMessageEvent = StreamChatMessage;
-/**
- * WebSocket event: stream_chat_sent
- *
- * Acknowledgment sent to the sender after successful message send
- */
-export interface StreamChatSentEvent {
-    /** Token name */
-    tokenName: string;
-    /** ID of the sent message */
-    messageId: string;
-}
-/**
- * WebSocket event: stream_chat_error
- *
- * Emitted when a chat operation fails
- */
-export interface StreamChatErrorEvent {
-    /** Token name */
-    tokenName: string;
-    /** Error message */
-    message: string;
-}
-/**
- * WebSocket event: stream_chat_status
- *
- * Emitted when chat status changes for a token
- */
-export interface StreamChatStatusEvent {
-    /** Token name */
-    tokenName: string;
-    /** Whether chat is now enabled */
-    enabled: boolean;
-    /** Reason for status (if disabled) */
-    reason?: ChatDisabledReason;
-}
-/**
- * WebSocket event: stream_chat_deleted
- *
- * Emitted when a chat message is deleted. Clients should show [deleted] placeholder.
- *
- * @since 5.3.0
- */
-export interface StreamChatDeletedEvent {
-    /** Token name (lowercase) */
-    tokenName: string;
-    /** ID of the deleted message (UUID-based string) */
-    messageId: string;
-    /** Timestamp when message was deleted (ISO 8601) */
-    deletedAt: string;
-}
-/**
- * WebSocket event: stream_chat_pinned
- *
- * Emitted when a message is pinned to the top of the chat.
- *
- * @since 5.5.0
- */
-export interface StreamChatPinnedEvent {
-    /** Token name (lowercase) */
-    tokenName: string;
-    /** The pinned message data */
-    pinnedMessage: PinnedMessage;
-}
-/**
- * WebSocket event: stream_chat_unpinned
- *
- * Emitted when a pinned message is unpinned (manually or via message deletion).
- *
- * @since 5.5.0
- */
-export interface StreamChatUnpinnedEvent {
-    /** Token name (lowercase) */
-    tokenName: string;
-    /** Message ID that was unpinned */
-    unpinnedMessageId: string;
-}
-/**
- * WebSocket event: stream_chat_global_status
- *
- * Emitted when global chat status changes
- */
-export interface StreamChatGlobalStatusEvent {
-    /** Whether chat is globally enabled */
-    enabled: boolean;
-    /** Timestamp of change (ISO 8601) */
-    updatedAt: string;
-}
-/**
- * WebSocket authentication result
- */
-export interface StreamChatAuthenticatedEvent {
-    /** Authenticated wallet address */
-    address: AddressFormat;
-}
-/**
- * WebSocket authentication error
- */
-export interface StreamChatAuthErrorEvent {
-    /** Error message */
-    message: string;
-}
-/**
- * Preset reaction emojis available in the quick-bar
- * @since 5.2.0
- */
-export declare const PRESET_REACTIONS: readonly ["❤️", "🔥", "🚀", "💎", "🌟"];
-/**
- * Type for preset reaction emojis
- */
-export type PresetReaction = (typeof PRESET_REACTIONS)[number];
-/**
- * WebSocket event: stream_reaction
- *
- * Broadcast to all viewers when a user sends an emoji reaction.
- * Reactions are ephemeral - not persisted to database.
- *
- * @since 5.2.0
- */
-export interface StreamReactionEvent {
-    /** Token name (lowercase) */
-    tokenName: string;
-    /** Emoji reaction (single emoji or short sequence) */
-    emoji: string;
-    /** Sender's wallet address (optional for privacy) */
-    userAddress?: string;
-    /** Server timestamp when reaction was sent (ms since epoch) */
-    timestamp: number;
-    /** Stream timecode when reaction was sent (seconds from stream start) */
-    streamTime: number;
-}
-/**
- * Error codes for reaction failures
- * @since 5.2.0
- */
-export declare const REACTION_ERROR_CODES: {
-    /** User has exceeded reaction rate limit */
-    readonly RATE_LIMITED: "RATE_LIMITED";
-    /** Emoji validation failed (too long, invalid format, etc.) */
-    readonly INVALID_EMOJI: "INVALID_EMOJI";
-    /** User is not authenticated */
-    readonly NOT_AUTHENTICATED: "NOT_AUTHENTICATED";
-    /** Stream is not currently live */
-    readonly STREAM_NOT_LIVE: "STREAM_NOT_LIVE";
-};
-export type ReactionErrorCode = (typeof REACTION_ERROR_CODES)[keyof typeof REACTION_ERROR_CODES];
-/**
- * WebSocket event: stream_reaction_error
- *
- * Emitted to sender when a reaction fails to send.
- *
- * @since 5.2.0
- */
-export interface StreamReactionErrorEvent {
-    /** Token name */
-    tokenName: string;
-    /** Error message */
-    message: string;
-    /** Error code for programmatic handling */
-    code?: ReactionErrorCode;
-}
-/**
- * Data for send_stream_reaction WebSocket event
- * @since 5.2.0
- */
-export interface SendStreamReactionData {
-    /** Token name for the stream */
-    tokenName: string;
-    /** Emoji reaction to send */
-    emoji: string;
-    /** Current stream timecode in seconds (for viewer sync) */
-    streamTime?: number;
-}
-/**
- * Data for authenticate WebSocket event
- */
-export interface AuthenticateData {
-    /** JWT token for authentication */
-    token: string;
-}
-/**
- * Data for send_stream_chat WebSocket event
- */
-export interface SendStreamChatData {
-    /** Token name for the chat room */
-    tokenName: string;
-    /** Message content */
-    content: string;
-}
-/**
- * Data for subscribe_stream WebSocket event
- */
-export interface SubscribeStreamData {
-    /** Token name to subscribe to */
-    tokenName: string;
-}
-/**
- * Data for unsubscribe_stream WebSocket event
- */
-export interface UnsubscribeStreamData {
-    /** Token name to unsubscribe from */
-    tokenName: string;
-}
-/**
- * Standard backend response wrapper for chat endpoints
- * @internal
- * @see InternalApiResponse in common.ts for the shared type
- * @deprecated Use InternalApiResponse from common.ts directly
- */
-export type InternalChatResponse<T = unknown> = InternalApiResponse<T>;
-/**
- * Internal response from get messages endpoint
- * @internal
- */
-export interface InternalGetMessagesResponse extends InternalChatResponse<{
-    messages: StreamChatMessage[];
-    total: number;
-    page: number;
-    limit: number;
-    nextCursor?: string;
-    pinnedMessage?: PinnedMessage | null;
-}> {
-}
-/**
- * Internal response from send message endpoint
- * @internal
- */
-export interface InternalSendMessageResponse extends InternalChatResponse<StreamChatMessage> {
-}
-/**
- * Internal response from chat status endpoint
- * @internal
- */
-export interface InternalChatStatusResponse extends InternalChatResponse<ChatStatusResponse> {
-}
-/**
- * Internal response from global chat status endpoint
- * @internal
- */
-export interface InternalGlobalChatStatusResponse extends InternalChatResponse<GlobalChatStatus> {
-}
-/**
- * Internal response from chat toggle endpoints
- * @internal
- * @since 5.4.0 - Added status field for dual-auth support
- */
-export interface InternalChatToggleResponse extends InternalChatResponse<{
-    enabled: boolean;
-    tokenName?: string;
-    status?: FeatureStatusType;
-}> {
-}
-/**
- * Internal response from delete message endpoint
- * @internal
- * @since 5.3.0
- */
-export interface InternalDeleteMessageResponse extends InternalChatResponse<{
-    messageId: string;
-    deleted: boolean;
-}> {
-}
-/**
- * Internal response from pin message endpoint
- * @internal
- * @since 5.5.0
- */
-export interface InternalPinMessageResponse extends InternalChatResponse<{
-    pinnedMessage: PinnedMessage;
-    tokenName: string;
-}> {
-}
-/**
- * Internal response from unpin message endpoint
- * @internal
- * @since 5.5.0
- */
-export interface InternalUnpinMessageResponse extends InternalChatResponse<{
-    unpinned: boolean;
-    unpinnedMessageId?: string;
-    tokenName: string;
-}> {
-}
-/**
- * Internal response from get pinned message endpoint
- * @internal
- * @since 5.5.0
- */
-export interface InternalGetPinnedMessageResponse extends InternalChatResponse<{
-    pinnedMessage: PinnedMessage | null;
-    tokenName: string;
-}> {
-}
-/**
- * Chat engagement statistics (scoped to stream session)
- * @since 5.10.0
- */
-export interface ChatStats {
-    /** Total number of chat messages in the current/last stream session */
-    readonly messageCount: number;
-    /** Number of unique users who sent chat messages */
-    readonly uniqueChatters: number;
-    /** ISO 8601 timestamp indicating the start of the counting period (streamStartedAt) */
-    readonly since: string | null;
-}
-/**
- * Comment engagement statistics (all-time for token)
- * @since 5.10.0
- */
-export interface CommentStats {
-    /** Total number of token page comments */
-    readonly count: number;
-    /** Number of unique users who left comments */
-    readonly uniqueCommenters: number;
-}
-/**
- * Combined engagement statistics for a token
- *
- * Used by the Studio analytics dashboard.
- * - Chat stats: scoped to current/last stream session
- * - Comment stats: all-time for the token
- *
- * @since 5.10.0
- */
-export interface EngagementStats {
-    /** Chat statistics (live stream messages) */
-    readonly chat: ChatStats;
-    /** Comment statistics (token page comments - all-time) */
-    readonly comments: CommentStats;
-}
-/**
- * Options for fetching engagement stats
- * @since 5.10.0
- */
-export interface GetEngagementStatsOptions {
-    /** Token name to fetch stats for */
-    tokenName: string;
-}
-/**
- * Result from GET /live/:tokenName/engagement/stats
- * @since 5.10.0
- */
-export interface EngagementStatsResult extends EngagementStats {
-    /** Token name */
-    readonly tokenName: string;
-}
-/**
- * Internal response from engagement stats endpoint
- * @internal
- * @since 5.10.0
- */
-export interface InternalEngagementStatsResponse extends InternalChatResponse<EngagementStats> {
-}
-/**
- * Type guard for ChatDisabledReason
- */
-export declare function isChatDisabledReason(value: unknown): value is ChatDisabledReason;
-/**
- * Type guard for StreamChatMessage
- */
-export declare function isStreamChatMessage(obj: unknown): obj is StreamChatMessage;
-/**
- * Type guard for StreamChatMessageEvent
- */
-export declare function isStreamChatMessageEvent(obj: unknown): obj is StreamChatMessageEvent;
-/**
- * Type guard for StreamChatErrorEvent
- */
-export declare function isStreamChatErrorEvent(obj: unknown): obj is StreamChatErrorEvent;
-/**
- * Type guard for StreamChatDeletedEvent
- * @since 5.3.0
- */
-export declare function isStreamChatDeletedEvent(obj: unknown): obj is StreamChatDeletedEvent;
-/**
- * Type guard for PinnedMessage
- * @since 5.5.0
- */
-export declare function isPinnedMessage(obj: unknown): obj is PinnedMessage;
-/**
- * Type guard for StreamChatPinnedEvent
- * @since 5.5.0
- */
-export declare function isStreamChatPinnedEvent(obj: unknown): obj is StreamChatPinnedEvent;
-/**
- * Type guard for StreamChatUnpinnedEvent
- * @since 5.5.0
- */
-export declare function isStreamChatUnpinnedEvent(obj: unknown): obj is StreamChatUnpinnedEvent;
-/**
- * Type guard for ChatStatusResponse
- */
-export declare function isChatStatusResponse(obj: unknown): obj is ChatStatusResponse;
-/**
- * Validates chat message content
- */
-export declare function isValidChatContent(content: string): boolean;
-/**
- * Validates token name format for chat operations
- */
-export declare function isValidChatTokenName(tokenName: string): boolean;
-/**
- * Type guard for StreamReactionEvent
- * @since 5.2.0
- */
-export declare function isStreamReactionEvent(obj: unknown): obj is StreamReactionEvent;
-/**
- * Type guard for StreamReactionErrorEvent
- * @since 5.2.0
- */
-export declare function isStreamReactionErrorEvent(obj: unknown): obj is StreamReactionErrorEvent;
-/**
- * Check if a value is a valid ReactionErrorCode
- * @since 5.2.0
- */
-export declare const isReactionErrorCode: (value: unknown) => value is "RATE_LIMITED" | "INVALID_EMOJI" | "NOT_AUTHENTICATED" | "STREAM_NOT_LIVE";
-/**
- * User information for typing indicators
- *
- * Minimal user info broadcast when showing typing status.
- *
- * @since 5.11.0
- */
-export interface TypingUser {
-    /** User's wallet address */
-    userAddress: string;
-    /** User's display name */
-    fullName: string;
-    /** User's profile image URL (optional) */
-    profileImage?: string;
-}
-/**
- * WebSocket event: user_typing
- *
- * Broadcast to all viewers when users are actively typing in chat.
- * Typing indicators are ephemeral - not persisted to database.
- *
- * Auto-expires after 5 seconds of no typing activity.
- *
- * @since 5.11.0
- */
-export interface TypingIndicatorEvent {
-    /** Token name (lowercase) */
-    tokenName: string;
-    /** Array of currently typing users (aggregated list) */
-    typingUsers: TypingUser[];
-}
-/**
- * Data for typing_start WebSocket event (client → server)
- * @since 5.11.0
- */
-export interface TypingStartData {
-    /** Token name for the chat room */
-    tokenName: string;
-}
-/**
- * Data for typing_stop WebSocket event (client → server)
- * @since 5.11.0
- */
-export interface TypingStopData {
-    /** Token name for the chat room */
-    tokenName: string;
-}
-/**
- * Type guard for TypingUser
- * @since 5.11.0
- */
-export declare function isTypingUser(obj: unknown): obj is TypingUser;
-/**
- * Type guard for TypingIndicatorEvent
- * @since 5.11.0
- */
-export declare function isTypingIndicatorEvent(obj: unknown): obj is TypingIndicatorEvent;
-/**
- * Validates SendChatMessageOptions
- *
- * @param options - Options to validate
- * @throws {ValidationError} If options are invalid
- */
-export declare function validateSendChatMessageOptions(options: SendChatMessageOptions): void;
-/**
- * Validates FetchChatMessagesOptions
- *
- * @param options - Options to validate
- * @throws {ValidationError} If options are invalid
- */
-export declare function validateFetchChatMessagesOptions(options: FetchChatMessagesOptions): void;
-/**
- * Validates DeleteChatMessageOptions
- *
- * @param options - Options to validate
- * @throws {ValidationError} If options are invalid
- * @since 5.3.0
- */
-export declare function validateDeleteChatMessageOptions(options: DeleteChatMessageOptions): void;
-/**
- * Validates PinMessageOptions
- *
- * @param options - Options to validate
- * @throws {ValidationError} If options are invalid
- * @since 5.5.0
- */
-export declare function validatePinMessageOptions(options: PinMessageOptions): void;
-/**
- * Validates GetEngagementStatsOptions
- *
- * @param options - Options to validate
- * @throws {ValidationError} If options are invalid
- * @since 5.10.0
- */
-export declare function validateGetEngagementStatsOptions(options: GetEngagementStatsOptions): void;
-//# sourceMappingURL=stream-chat.dto.d.ts.map