@jam.dev/recording-links/lib/sdk.d.ts

Capture bug reports from your users with the Jam recording links SDK

import * as refs from "./utils/refs";
/**
 * The name of a Jam script that can be loaded dynamically.
 */
export type ScriptName = "capture" | "recorder";
type Events = {
    loaded: {
        type: "script";
    } & ({
        name: "recorder";
        Recorder: RecorderSingleton;
    } | {
        name: Exclude<ScriptName, "recorder">;
    });
};
/**
 * The Jam recorder singleton interface.
 * Provides methods for opening and controlling recording sessions.
 */
type RecorderSingleton = {
    /**
     * Opens a recorder for the specified recording ID.
     * @param recordingId - The ID of the recording to open
     * @param params - Optional parameters for opening the recorder
     * @param params.jamTitle - Optional title for the recording
     * @param params.removeOnEscape - Whether to remove the opened recorder on Escape presses. Default: true
     * @param params.applyJamData - Custom function to apply recording data to URL
     * @returns Unknown - TODO: expose a public API for opened recorders
     */
    open(recordingId: string, params?: Pick<InitializeOptions, "applyJamData"> & {
        jamTitle?: string | null;
        /** Whether to remove the opened recorder on Escape presses. Default: true */
        removeOnEscape?: boolean;
    }): unknown;
};
type InitializeOptions = {
    /**
     * A reference counter to manage the number of active `Recorder` instances.
     * This should be a shared reference counter, so that multiple instances of the
     * SDK (e.g. in different browser tabs) can coordinate loading capture scripts
     * on all tabs once any tab has an active recorder.
     */
    recorderRefCounter?: refs.RefCounter;
    /**
     * Comma-separated list of team IDs to validate recording IDs against.
     * If not provided, will read from `<meta name="jam:team" content="...">` tags.
     */
    teamId?: string;
    /**
     * Whether to open the JamRecorder immediately on initialization.
     * May be provided a recording ID as a string, in which case we will open it.
     * If the value resolves to `undefined` or `null`, we will default to `true`.
     * Default: `true`
     */
    openImmediately?: boolean | string | undefined | null;
    /**
     * Extract a `recordingId` and `jamTitle` from the provided string.
     * Defaults to reading the `jam-recording` and `jam-title` QSPs off the URL.
     */
    parseJamData?(input: string): SerializableJamData | null;
    /**
     * Applies a `recordingId` and `jamTitle` when the JamRecorder is opened or closes.
     * Defaults to setting (or rm'ing) the `jam-recording` and `jam-title` QSPs.
     * Setting a custom `parseJamData` disables this default.
     */
    applyJamData?(data: SerializableJamData): string;
};
/**
 * Data structure representing Jam recording metadata that can be serialized to/from URLs.
 */
export type SerializableJamData = {
    /** The unique identifier of the recording, or null if not present */
    recordingId: string | null;
    /** The human-readable title of the recording, or null if not present */
    jamTitle: string | null;
};
/**
 * Add an event listener for SDK events.
 * @param type - The event type to listen for
 * @param listener - The event handler function
 * @param options - Optional event listener configuration
 */
export declare const addEventListener: <K extends "loaded">(type: K, listener: (event: CustomEvent<Events[K]>) => void, options?: boolean | AddEventListenerOptions) => void;
/**
 * Remove an event listener for SDK events.
 * @param type - The event type to stop listening for
 * @param listener - The event handler function to remove
 * @param options - Optional event listener configuration
 */
export declare const removeEventListener: <K extends "loaded">(type: K, listener: (event: CustomEvent<Events[K]>) => void, options?: boolean | AddEventListenerOptions) => void;
/** Whether the SDK has been initialized. */
export declare const isInitialized: () => false;
/**
 * The loaded Recorder singleton instance. Will be null until loadRecorder() is called successfully.
 */
export declare let Recorder: RecorderSingleton | null;
/**
 * Initializes the Jam Recording Links SDK.
 *
 * This function sets up the SDK for managing recording sessions across browser tabs.
 * It configures reference counting for coordinating capture scripts and can automatically
 * load recordings based on URL parameters.
 *
 * @param options - Configuration options for the SDK
 * @param options.recorderRefCounter - Custom reference counter for managing recorder instances across tabs
 * @param options.teamId - Team ID for validating recording IDs
 * @param options.openImmediately - Whether to automatically open recorder from URL parameters (default: true)
 *                                  Can be set to a specific recording ID as a string to open that recording.
 * @param options.parseJamData - Custom function to extract recording data from URLs
 * @param options.applyJamData - Custom function to apply recording data to URLs
 *
 * @throws {Error} If the SDK has already been initialized
 *
 * @example
 * ```typescript
 * // Basic initialization
 * jam.initialize();
 *
 * // Custom configuration
 * jam.initialize({
 *   teamId: "team-123",
 *   openImmediately: false // or "abc-123" to open a specific recording
 * });
 * ```
 */
export declare function initialize({ recorderRefCounter, ...config }?: InitializeOptions): void;
/**
 * Loads the Jam recorder module and returns the recorder singleton.
 *
 * This function dynamically imports the recorder script from the Jam CDN,
 * initializes it with the provided configuration, and sets up reference counting
 * for cross-tab coordination.
 *
 * @param options - Configuration options for loading the recorder
 * @param options.teamId - Team ID for validating recording IDs
 * @param options.openImmediately - Whether to automatically open the recorder (default: true)
 *                                  Can be set to a specific recording ID as a string to open that recording.
 * @param options.parseJamData - Custom function to extract recording data from URLs
 * @param options.applyJamData - Custom function to apply recording data to URLs
 *
 * @returns Promise that resolves to the RecorderSingleton instance
 *
 * @throws {Error} If the SDK has not been initialized
 * @throws {Error} If the recorder script fails to load
 *
 * @example
 * ```typescript
 * // Load recorder without opening anything
 * const recorder = await jam.loadRecorder();
 *
 * // Load recorder and open a specific recording
 * const recorder = await jam.loadRecorder({
 *   openImmediately: false, // or "recording-abc123"
 * });
 *
 * // Use the recorder
 * recorder.open("recording-xyz789", { jamTitle: "Bug Report" });
 * ```
 */
export declare function loadRecorder({ ...config }?: Omit<InitializeOptions, "recorderRefCounter">): Promise<RecorderSingleton>;
export {};
//# sourceMappingURL=sdk.d.ts.map