@dialtribe/react-sdk 0.1.0-alpha.5

package/dist/broadcast-player.d.mts

@@ -0,0 +1,517 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React$1, { Component, ReactNode, ErrorInfo } from 'react';
+
+/**
+ * DialTribe SDK Context
+ * Manages session token and auto-refresh across all SDK components
+ */
+interface DialTribeContextValue {
+    /** Current session token */
+    sessionToken: string | null;
+    /** Update the session token (called automatically on refresh) */
+    setSessionToken: (token: string, expiresAt?: string) => void;
+    /** Whether the session token is expired/invalid */
+    isExpired: boolean;
+    /** Mark token as expired */
+    markExpired: () => void;
+}
+interface DialTribeProviderProps {
+    /** Session token from your backend (required) */
+    sessionToken: string;
+    /** Called when the API returns a refreshed token via X-Session-Token header */
+    onTokenRefresh?: (newToken: string, expiresAt: string) => void;
+    /** Called when the session token expires or becomes invalid */
+    onTokenExpired?: () => void;
+    /** Your React app */
+    children: React$1.ReactNode;
+}
+/**
+ * DialTribe Provider
+ *
+ * Wraps your app to provide session token authentication to all SDK components.
+ *
+ * @example
+ * ```tsx
+ * <DialTribeProvider
+ *   sessionToken="sess_xxx..."
+ *   onTokenRefresh={(newToken) => {
+ *     // Save to state/localStorage
+ *     setToken(newToken);
+ *   }}
+ *   onTokenExpired={() => {
+ *     // Redirect to login or refresh
+ *     router.push('/login');
+ *   }}
+ * >
+ *   <App />
+ * </DialTribeProvider>
+ * ```
+ */
+declare function DialTribeProvider({ sessionToken: initialToken, onTokenRefresh, onTokenExpired, children, }: DialTribeProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access DialTribe context
+ *
+ * @throws Error if used outside DialTribeProvider
+ *
+ * @example
+ * ```tsx
+ * const { sessionToken, setSessionToken } = useDialTribe();
+ * ```
+ */
+declare function useDialTribe(): DialTribeContextValue;
+
+/**
+ * DialTribe API Client
+ *
+ * Handles all API communication with fixed DialTribe endpoints.
+ * Automatically manages session token refresh via X-Session-Token headers.
+ */
+/** DialTribe API base URL (production only) */
+declare const DIALTRIBE_API_BASE = "https://dialtribe.com/api/public/v1";
+/** API endpoints (fixed, not configurable) */
+declare const ENDPOINTS: {
+    readonly broadcasts: "https://dialtribe.com/api/public/v1/broadcasts";
+    readonly broadcast: (id: number) => string;
+    readonly contentPlay: "https://dialtribe.com/api/public/v1/content/play";
+    readonly presignedUrl: "https://dialtribe.com/api/public/v1/media/presigned-url";
+    readonly sessionStart: "https://dialtribe.com/api/public/v1/session/start";
+    readonly sessionPing: "https://dialtribe.com/api/public/v1/session/ping";
+};
+interface ApiClientConfig {
+    /** Session token for authentication */
+    sessionToken: string;
+    /** Called when API returns a refreshed token */
+    onTokenRefresh?: (newToken: string, expiresAt: string) => void;
+    /** Called when token expires or becomes invalid */
+    onTokenExpired?: () => void;
+}
+/**
+ * DialTribe API Client
+ *
+ * Low-level client for making authenticated requests to DialTribe API.
+ * Handles session token auto-refresh automatically.
+ */
+declare class DialTribeClient {
+    private config;
+    constructor(config: ApiClientConfig);
+    /**
+     * Make an authenticated request to DialTribe API
+     *
+     * Automatically:
+     * - Adds Authorization header with session token
+     * - Checks for X-Session-Token header in response (token refresh)
+     * - Calls onTokenRefresh if new token is provided
+     * - Calls onTokenExpired on 401 errors
+     */
+    fetch(url: string, options?: RequestInit): Promise<Response>;
+    /**
+     * Update the session token
+     * Called automatically when token is refreshed, or manually by user
+     */
+    setSessionToken(token: string): void;
+    /**
+     * Get list of broadcasts for the authenticated app
+     */
+    getBroadcasts(params?: {
+        page?: number;
+        limit?: number;
+        broadcastStatus?: 1 | 2;
+        search?: string;
+        includeDeleted?: boolean;
+    }): Promise<any>;
+    /**
+     * Get a single broadcast by ID
+     */
+    getBroadcast(id: number): Promise<any>;
+    /**
+     * Get presigned URL for media playback
+     *
+     * @param broadcastId - Broadcast ID
+     * @param hash - Broadcast hash (optional if using session token)
+     * @param action - 'download' to force download, otherwise streams
+     */
+    getPlaybackUrl(params: {
+        broadcastId: number;
+        hash?: string;
+        action?: 'download';
+    }): Promise<string>;
+    /**
+     * Refresh a presigned URL before it expires
+     *
+     * @param broadcastId - Broadcast ID
+     * @param hash - Broadcast hash
+     * @param fileType - Type of media file
+     */
+    refreshPresignedUrl(params: {
+        broadcastId: number;
+        hash: string;
+        fileType: 'mp4' | 'mp3' | 'hls';
+    }): Promise<{
+        url: string;
+        expiresAt: string;
+        expiresIn: number;
+    }>;
+    /**
+     * Start a new audience tracking session
+     *
+     * @returns audienceId and optional resumePosition
+     */
+    startSession(params: {
+        contentId: number;
+        broadcastId: number;
+        appId: string;
+        foreignId?: string | null;
+        foreignTier?: string;
+        sessionId: string;
+        fileType: string;
+        platform: string;
+        userAgent: string | null;
+        origin: string | null;
+        country?: string | null;
+        region?: string | null;
+    }): Promise<{
+        audienceId: string;
+        resumePosition?: number;
+    }>;
+    /**
+     * Send a session ping event
+     *
+     * Event types:
+     * - 0: PAUSE/STOP
+     * - 1: PLAY/START
+     * - 2: HEARTBEAT
+     * - 3: UNMOUNT
+     */
+    sendSessionPing(params: {
+        audienceId: string;
+        sessionId: string;
+        eventType: 0 | 1 | 2 | 3;
+        currentTime: number;
+        duration: number;
+    }): Promise<any>;
+}
+
+/**
+ * Broadcast data structure
+ * Matches the response from /api/public/v1/broadcasts
+ */
+interface Broadcast {
+    id: number;
+    hash: string | null;
+    platformBroadcastId: string | null;
+    streamKey: string;
+    broadcastStatus: number;
+    recordingStatus: number;
+    isVideo: boolean;
+    saveRecordings: boolean;
+    startedAt: string;
+    endedAt: string | null;
+    durationSeconds: number | null;
+    s3FolderUrl: string | null;
+    hlsPlaylistUrl: string | null;
+    recordingMp4Url: string | null;
+    recordingMp3Url: string | null;
+    mp4Size: string;
+    mp3Size: string;
+    terminatedBy: string | null;
+    terminationReason: string | null;
+    transcriptStatus?: number;
+    transcriptUrl?: string | null;
+    transcriptPreview?: string | null;
+    transcriptDuration?: number | null;
+    transcriptLanguage?: string | null;
+    transcriptError?: string | null;
+    transcriptSize?: string;
+    app?: {
+        s3Hash: string | null;
+    };
+    content?: {
+        id: number;
+        hash: string;
+    } | null;
+    streamKeyRecord?: {
+        foreignId: string;
+        foreignName: string | null;
+    } | null;
+}
+/**
+ * Transcript word interface (from OpenAI Whisper API)
+ */
+interface TranscriptWord {
+    word: string;
+    start: number;
+    end: number;
+}
+/**
+ * Transcript segment interface
+ */
+interface TranscriptSegment {
+    id: number;
+    start: number;
+    end: number;
+    text: string;
+    words: TranscriptWord[];
+}
+/**
+ * Full transcript data structure
+ */
+interface TranscriptData {
+    text: string;
+    segments?: TranscriptSegment[];
+    words?: TranscriptWord[];
+}
+
+interface BroadcastPlayerProps {
+    /** Broadcast data from DialTribe API */
+    broadcast: Broadcast;
+    /** Optional: App ID for tracking */
+    appId?: string;
+    /** Optional: Content ID for tracking */
+    contentId?: number;
+    /** Foreign user ID from partner system (any tier) */
+    foreignId?: string;
+    /** Tier name from partner system (e.g., 'guest', 'member', 'subscriber_gold') */
+    foreignTier?: string;
+    /**
+     * Optional render prop for clip creator
+     * If provided, the "Create Clip" button will be shown and this will be called when clicked
+     */
+    renderClipCreator?: (props: {
+        isOpen: boolean;
+        onClose: () => void;
+        sourceVideoUrl?: string;
+        sourceAudioUrl?: string;
+        sourceDuration: number;
+        onPauseParent: () => void;
+    }) => React.ReactNode;
+    /** Optional: Called when player encounters error */
+    onError?: (error: Error) => void;
+    /** Optional: Custom CSS classes */
+    className?: string;
+    /** Optional: Enable keyboard shortcuts (Space, arrows, M, F, etc.). Default: false */
+    enableKeyboardShortcuts?: boolean;
+}
+/**
+ * BroadcastPlayer - Core media player component (no modal wrapper)
+ *
+ * Plays video/audio broadcasts with transcript, waveform visualization, and clip creation.
+ * Uses DialTribeClient for authenticated API calls.
+ *
+ * @example
+ * ```tsx
+ * <BroadcastPlayer
+ *   broadcast={broadcast}
+ *   appId="app_123"
+ *   contentId={456}
+ * />
+ * ```
+ */
+declare function BroadcastPlayer({ broadcast, appId, contentId, foreignId, foreignTier, renderClipCreator, onError, className, enableKeyboardShortcuts, }: BroadcastPlayerProps): react_jsx_runtime.JSX.Element;
+
+interface BroadcastPlayerModalProps {
+    /** Broadcast data from DialTribe API */
+    broadcast: Broadcast;
+    /** Whether modal is open */
+    isOpen: boolean;
+    /** Called when modal should close */
+    onClose: () => void;
+    /** Optional: App ID for tracking */
+    appId?: string;
+    /** Optional: Content ID for tracking */
+    contentId?: number;
+    /** Foreign user ID from partner system (any tier) */
+    foreignId?: string;
+    /** Tier name from partner system (e.g., 'guest', 'member', 'subscriber_gold') */
+    foreignTier?: string;
+    /**
+     * Optional render prop for clip creator
+     * If provided, the "Create Clip" button will be shown and this will be called when clicked
+     */
+    renderClipCreator?: (props: {
+        isOpen: boolean;
+        onClose: () => void;
+        sourceVideoUrl?: string;
+        sourceAudioUrl?: string;
+        sourceDuration: number;
+        onPauseParent: () => void;
+    }) => React.ReactNode;
+    /** Optional: Custom CSS classes for the player */
+    className?: string;
+    /** Optional: Enable keyboard shortcuts (Space, arrows, M, F, etc.). Default: false */
+    enableKeyboardShortcuts?: boolean;
+}
+/**
+ * BroadcastPlayerModal - Modal wrapper for BroadcastPlayer
+ *
+ * Provides a modal overlay with ESC key handling and backdrop click to close.
+ * Uses the new BroadcastPlayer component for all player functionality.
+ *
+ * @example
+ * ```tsx
+ * <BroadcastPlayerModal
+ *   broadcast={broadcast}
+ *   isOpen={showModal}
+ *   onClose={() => setShowModal(false)}
+ *   appId="app_123"
+ *   contentId={456}
+ * />
+ * ```
+ */
+declare function BroadcastPlayerModal({ broadcast, isOpen, onClose, appId, contentId, foreignId, foreignTier, renderClipCreator, className, enableKeyboardShortcuts, }: BroadcastPlayerModalProps): react_jsx_runtime.JSX.Element | null;
+
+interface Props {
+    children: ReactNode;
+    /** Callback when modal needs to be closed */
+    onClose?: () => void;
+    /** Broadcast ID for logging purposes */
+    broadcastId?: number;
+}
+interface State {
+    hasError: boolean;
+    error: Error | null;
+    errorInfo: ErrorInfo | null;
+}
+/**
+ * Error Boundary for Broadcast Player Modal
+ *
+ * Catches and handles React errors that occur during:
+ * - Rendering
+ * - Lifecycle methods
+ * - Constructors of the whole tree below them
+ *
+ * Does NOT catch errors in:
+ * - Event handlers (use try-catch)
+ * - Asynchronous code (use try-catch)
+ * - Server-side rendering
+ * - Errors thrown in the error boundary itself
+ *
+ * Benefits:
+ * - Prevents white screen of death
+ * - Provides user-friendly error UI
+ * - Logs errors for debugging
+ * - Allows graceful recovery
+ */
+declare class BroadcastPlayerErrorBoundary extends Component<Props, State> {
+    constructor(props: Props);
+    static getDerivedStateFromError(error: Error): Partial<State>;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    handleReset: () => void;
+    handleClose: () => void;
+    render(): string | number | boolean | Iterable<ReactNode> | react_jsx_runtime.JSX.Element | null | undefined;
+}
+
+interface AudioWaveformProps {
+    /** Audio/video element for playback visualization */
+    audioElement?: HTMLMediaElement | null;
+    /** Media stream for live streaming visualization */
+    mediaStream?: MediaStream | null;
+    /** Whether the audio is currently playing (for playback mode) */
+    isPlaying?: boolean;
+    /** Whether this is currently a live stream (for HLS streams) */
+    isLive?: boolean;
+}
+/**
+ * Shared audio waveform visualization component
+ * Can be used for both live streaming (MediaStream) and playback (HTMLVideoElement)
+ */
+declare function AudioWaveform({ audioElement, mediaStream, isPlaying, isLive, }: AudioWaveformProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Shared Loading Spinner Component
+ */
+interface LoadingSpinnerProps {
+    /**
+     * Optional text to display below the spinner
+     */
+    text?: string;
+    /**
+     * Size variant of the spinner
+     * @default "md"
+     */
+    size?: "sm" | "md" | "lg";
+    /**
+     * Color scheme
+     * @default "default"
+     */
+    variant?: "default" | "primary" | "white";
+}
+/**
+ * Loading spinner component with optional text
+ *
+ * @example
+ * <LoadingSpinner />
+ * <LoadingSpinner text="Loading broadcasts..." size="lg" />
+ * <LoadingSpinner variant="white" />
+ */
+declare function LoadingSpinner({ text, size, variant, }: LoadingSpinnerProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Format seconds to time string (HH:MM:SS or MM:SS)
+ *
+ * @param seconds - Number of seconds
+ * @param includeHours - Whether to always include hours (default: auto-detect)
+ * @returns Formatted time string
+ *
+ * Examples:
+ * - formatTime(45) → "0:45"
+ * - formatTime(125) → "2:05"
+ * - formatTime(3665) → "1:01:05"
+ */
+declare function formatTime(seconds: number, includeHours?: boolean): string;
+
+/**
+ * CDN domain for broadcast content
+ * Can be overridden via environment variable CONTENT_CDN_DOMAIN
+ */
+declare const CDN_DOMAIN: string;
+/**
+ * Build S3 key prefix for broadcast files
+ *
+ * @param appHash - App S3 hash
+ * @param broadcastHash - Broadcast hash
+ * @returns S3 key prefix with trailing slash
+ */
+declare function buildBroadcastS3KeyPrefix(appHash: string, broadcastHash: string): string;
+/**
+ * Build CDN URL for a broadcast file (HLS)
+ *
+ * @param appHash - App S3 hash
+ * @param broadcastHash - Broadcast hash
+ * @param filename - File name (e.g., "index.m3u8", "seg-0-000001.ts")
+ * @returns CDN URL
+ */
+declare function buildBroadcastCdnUrl(appHash: string, broadcastHash: string, filename: string): string;
+
+declare const HTTP_STATUS: {
+    readonly OK: 200;
+    readonly CREATED: 201;
+    readonly ACCEPTED: 202;
+    readonly NO_CONTENT: 204;
+    readonly MOVED_PERMANENTLY: 301;
+    readonly FOUND: 302;
+    readonly SEE_OTHER: 303;
+    readonly NOT_MODIFIED: 304;
+    readonly TEMPORARY_REDIRECT: 307;
+    readonly PERMANENT_REDIRECT: 308;
+    readonly BAD_REQUEST: 400;
+    readonly UNAUTHORIZED: 401;
+    readonly PAYMENT_REQUIRED: 402;
+    readonly FORBIDDEN: 403;
+    readonly NOT_FOUND: 404;
+    readonly METHOD_NOT_ALLOWED: 405;
+    readonly NOT_ACCEPTABLE: 406;
+    readonly CONFLICT: 409;
+    readonly GONE: 410;
+    readonly PAYLOAD_TOO_LARGE: 413;
+    readonly UNSUPPORTED_MEDIA_TYPE: 415;
+    readonly UNPROCESSABLE_ENTITY: 422;
+    readonly TOO_MANY_REQUESTS: 429;
+    readonly INTERNAL_SERVER_ERROR: 500;
+    readonly NOT_IMPLEMENTED: 501;
+    readonly BAD_GATEWAY: 502;
+    readonly SERVICE_UNAVAILABLE: 503;
+    readonly GATEWAY_TIMEOUT: 504;
+};
+type HttpStatusCode = typeof HTTP_STATUS[keyof typeof HTTP_STATUS];
+
+export { type ApiClientConfig, AudioWaveform, type Broadcast, BroadcastPlayer, BroadcastPlayerErrorBoundary, BroadcastPlayerModal, type BroadcastPlayerModalProps, type BroadcastPlayerProps, CDN_DOMAIN, DIALTRIBE_API_BASE, DialTribeClient, type DialTribeContextValue, DialTribeProvider, type DialTribeProviderProps, ENDPOINTS, HTTP_STATUS, type HttpStatusCode, LoadingSpinner, type TranscriptData, type TranscriptSegment, type TranscriptWord, buildBroadcastCdnUrl, buildBroadcastS3KeyPrefix, formatTime, useDialTribe };