saltfish/dist/index.d.ts

An interactive video-guided tour system for web applications

import type { SaltfishConfig, PlaylistOptions, playlistManifest } from './types';
import { SaltfishEventName, EventHandler } from './managers/EventManager';
import type { DeviceInfo } from './utils/deviceDetection';
/**
 * Global Saltfish playlist Player API
 */
export interface SaltfishAPI {
    /**
     * Initializes the Saltfish playlist Player
     * @param token - Saltfish API token or configuration object
     * @returns Promise that resolves when initialization is complete
     * @note You don't need to use await with this method - it can be called synchronously.
     *       You can also listen for the 'initialized' event instead of awaiting the promise.
     * @example
     * // Using with just a token:
     * saltfish.init('YOUR_API_TOKEN');
     * saltfish.startPlaylist('your_playlist_id');
     *
     * // Using with configuration object:
     * saltfish.init({
     *   token: 'YOUR_API_TOKEN',
     *   enableAnalytics: false // Disable analytics for development
     * });
     *
     * // Using with events:
     * saltfish.on('initialized', () => {
     *   saltfish.startPlaylist('your_playlist_id');
     * });
     * saltfish.init('YOUR_API_TOKEN');
     */
    init: (token: string | SaltfishConfig) => Promise<void>;
    /**
     * Identifies the current user
     * @param userId - User ID
     * @param userData - Additional user data
     */
    identify: (userId: string, userData?: Record<string, any>) => void;
    /**
     * Identifies the current user anonymously (localStorage only, no backend communication)
     * This method provides the same functionality as identify() but stores user data in localStorage
     * instead of communicating with the backend. It automatically generates and persists an anonymous
     * user ID. It still supports autoStart functionality by using localStorage-based user data for
     * playlist triggers and watched playlist tracking.
     * @param userData - Optional additional user data
     * @example
     * // Identify user anonymously (generates persistent anonymous user ID automatically)
     * saltfish.identifyAnonymous({ name: 'John Doe', preferences: { theme: 'dark' } });
     *
     * // Or with no additional data
     * saltfish.identifyAnonymous();
     *
     * // Still supports autoStart with once conditions
     * // AutoStart playlists will work using localStorage watched playlist data
     */
    identifyAnonymous: (userData?: Record<string, any>) => void;
    /**
     * Starts a playlist
     * @param playlistId - playlist ID to start
     * @param options - Optional configuration for position, drag behavior, and starting step
     * @param options.position - Position of the player on screen
     * @param options.allowDrag - Whether the player can be dragged
     * @param options.startNodeId - Optional step ID to start from instead of the manifest's default startStep
     * @returns Promise that resolves when playlist is started
     * @note You don't need to use await with this method - it can be called synchronously.
     *       You can also listen for the 'playlistStarted' event instead of awaiting the promise.
     * @note If a list of playlists was provided by the backend during initialization, the `playlistId` parameter
     *       may be ignored, and the player will attempt to load the first playlist from that list.
     * @note If a playlist is already running, this will automatically reset the store state and start the new playlist with a clean state.
     * @example
     * // Using without await:
     * saltfish.startPlaylist('your_playlist_id');
     *
     * // Starting from a specific step:
     * saltfish.startPlaylist('your_playlist_id', { startNodeId: 'step2' });
     *
     * // Starting a new playlist while another is running:
     * saltfish.startPlaylist('new_playlist_id'); // Automatically resets state
     *
     * // Using with events:
     * saltfish.on('playlistStarted', (event) => {
     *   console.log('Playlist started:', event.playlist.id);
     * });
     * saltfish.startPlaylist('your_playlist_id');
     */
    startPlaylist: (playlistId: string, options?: PlaylistOptions) => Promise<void>;
    /**
     * Gets the current session ID
     * @returns The unique session ID generated during initialization
     */
    getSessionId: () => string;
    /**
     * Gets the current run ID
     * @returns The unique run ID for the current playlist execution, or null if no playlist is running
     */
    getRunId: () => string | null;
    /**
     * Registers an event listener to be called when the given eventName is triggered
     * @param eventName - Name of event to listen for. See list of supported events.
     * @param listener - Function to call when the event is triggered
     */
    on: <T extends SaltfishEventName>(eventName: T, listener: EventHandler<T>) => void;
    /**
     * Removes an event listener for the given eventName
     * @param eventName - Name of event to stop listening for
     * @param listener - Function to remove
     * @returns true if the listener was removed, false if it wasn't found
     */
    off: <T extends SaltfishEventName>(eventName: T, listener: EventHandler<T>) => boolean;
    /**
     * Resets the current playlist
     */
    resetPlaylist: () => void;
    /**
     * Destroys the Saltfish playlist Player
     */
    destroy: () => void;
    /**
     * Testing utilities for development mode only
     * These will be removed in production builds
     */
    __dev__?: {
        /**
         * Sets a custom mock manifest for testing
         * @param manifest - The manifest to use for testing
         */
        setMockManifest: (manifest: playlistManifest) => void;
        /**
         * Creates a custom mock manifest based on provided overrides
         * @param overrides - Partial playlistManifest to override default values
         */
        createMockManifest: (overrides: Partial<playlistManifest>) => playlistManifest;
        /**
         * The default mock manifest
         */
        defaultMockManifest: playlistManifest;
        /**
         * Gets current device detection information
         * @returns DeviceInfo object with all device details
         */
        getDeviceInfo: () => DeviceInfo;
    };
}
declare const saltfish: SaltfishAPI;
export default saltfish;
//# sourceMappingURL=index.d.ts.map