@birdie-so/snippet/src/index.d.ts

Helper for integrating the Birdie screen recording snippet into modern JavaScript apps. Requires a Birdie account.

export interface BirdieMetadata {
    [key: string]: any;
}

export interface BirdieContact {
    id?: string | number;
    name?: string;
    email?: string | null;
    phone?: string;
    [key: string]: any;
}

export type BirdieEvent =
    | 'start' | 'stop' | 'captureStarted' | 'captureStopped'
    | 'pause' | 'restart' | 'resume'
    | 'recorderClose' | 'recorderOpen'
    | 'recordingSent' | 'error';

export interface BirdieSettings {
    /**
     * Unique Birdie client ID.
     */
    clientId: string;

    /**
     * Optional metadata to pass to Birdie before recording starts.
     */
    metadata?: BirdieMetadata;

    /**
     * Optional contact details to identify the customer.
     */
    contact?: BirdieContact;

    /**
     * Callback when Birdie is fully loaded and available as `window.birdie`.
     */
    onReady?: (birdie: BirdieAPI) => void;

    /**
     * If true (default), guarantees at most one active handler per event.
     * Re-registering the same event replaces the previous handler (prevents double fires on remount/HMR).
     */
    singleHandlerPerEvent?: boolean;

    settings?: {
        privacy?: {
            mask_response_body?: boolean;
        };
        [key: string]: any;
    };

    /** Legacy direct-embed aliases still accepted for bootstrap compatibility. */
    contact_id?: string | number;
    contact_name?: string;
    contact_email?: string | null;
    contact_phone?: string;

    [key: string]: any;
}

// export interface BirdieAPI {
//     metadata: BirdieMetadata;
//     on(event: 'start' | 'stop' | 'captureStarted' | 'captureStopped' | 'pause' | 'restart' | 'resume' | 'recorderClose' | 'recorderOpen' | 'recordingSent' | 'error', callback: (data: any) => void): void;
// }

export interface BirdieAPI {
    contact: BirdieContact;
    metadata: BirdieMetadata;

    // on(
    //     event:
    //         | 'start' | 'stop' | 'captureStarted' | 'captureStopped'
    //         | 'pause' | 'restart' | 'resume'
    //         | 'recorderClose' | 'recorderOpen'
    //         | 'recordingSent' | 'error',
    //     callback: (data: any) => void
    // ): void;

    // off(
    //     event:
    //         | 'start' | 'stop' | 'captureStarted' | 'captureStopped'
    //         | 'pause' | 'restart' | 'resume'
    //         | 'recorderClose' | 'recorderOpen'
    //         | 'recordingSent' | 'error',
    //     callback: (data: any) => void
    // ): void;

    // /** Auto-unsubscribes after the first event emission. */
    // onOnce(
    //     event:
    //         | 'start' | 'stop' | 'captureStarted' | 'captureStopped'
    //         | 'pause' | 'restart' | 'resume'
    //         | 'recorderClose' | 'recorderOpen'
    //         | 'recordingSent' | 'error',
    //     callback: (data: any) => void
    // ): void;

    on(event: BirdieEvent, callback: (data: any) => void): void;
    off(event: BirdieEvent, callback: (data: any) => void): void;

    /** Auto-unsubscribes after the first event emission. */
    onOnce(event: BirdieEvent, callback: (data: any) => void): void;

    setContact(contact: BirdieContact): void;
    setMetadata(metadata: BirdieMetadata): void;
    update(data: { contact?: BirdieContact; metadata?: BirdieMetadata }): void;
}

/**
 * Initializes the Birdie widget by injecting the CDN script with your client ID.
 * Automatically configures window.birdieSettings and registers optional metadata or event listeners.
 */
export function initBirdie(settings: BirdieSettings): void;

/**
 * Returns the current `window.birdie` instance if available, or null.
 * You can also pass a callback to run once Birdie becomes available.
 */
export function getBirdieInstance(callback?: (birdie: BirdieAPI) => void): BirdieAPI | null;

/** Updates Birdie metadata after initialization. */
export function setBirdieMetadata(metadata: BirdieMetadata): void;

/** Updates Birdie contact after initialization. */
export function setBirdieContact(contact: BirdieContact): void;

/** Updates Birdie runtime data after initialization. */
export function updateBirdie(data: { contact?: BirdieContact; metadata?: BirdieMetadata }): void;