saltfish/dist/index.d.ts

An interactive video-guided tour system for web applications

import type { SaltfishConfig, PlaylistOptions } from './types';
import type { 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.
     * @note Language configuration has been moved to identify() and identifyAnonymous() methods.
     *       The 'language' field in config is deprecated.
     * @example
     * // Using with just a token:
     * saltfish.init('YOUR_API_TOKEN');
     * saltfish.identify('user123', { language: 'sv' });
     * 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 (can include 'language' property: e.g., 'sv', 'en', 'de', or 'auto' for browser detection)
     * @example
     * // Identify user with language preference
     * saltfish.identify('user123', {
     *   name: 'John Doe',
     *   email: 'john@example.com',
     *   language: 'sv' // Swedish playlists
     * });
     *
     * // Use automatic language detection
     * saltfish.identify('user123', { language: 'auto' });
     */
    identify: (userId: string, userData?: Record<string, unknown>) => 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 triggered playlists functionality by using localStorage-based user data for
     * playlist triggers and watched playlist tracking.
     * @param userData - Optional additional user data (can include 'language' property: e.g., 'sv', 'en', 'de', or 'auto' for browser detection)
     * @example
     * // Identify user anonymously with language preference
     * saltfish.identifyAnonymous({
     *   name: 'John Doe',
     *   preferences: { theme: 'dark' },
     *   language: 'sv' // Swedish playlists
     * });
     *
     * // Or with just language (auto-detect from browser)
     * saltfish.identifyAnonymous({ language: 'auto' });
     *
     * // Or with no additional data
     * saltfish.identifyAnonymous();
     *
     * // Still supports triggered playlists with once conditions
     * // Triggered playlists will work using localStorage watched playlist data
     */
    identifyAnonymous: (userData?: Record<string, unknown>) => void;
    /**
     * Starts a playlist
     * @param playlistId - playlist ID to start
     * @param options - Optional configuration for position and starting step
     * @param options.position - Position of the player on screen
     * @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;
    /**
     * Gets the current version of the Saltfish player
     * @returns The version string from package.json
     */
    version: () => string;
    /**
     * Development utilities for debugging and testing
     */
    __dev__?: {
        /**
         * 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