@encatch/web-sdk 1.3.0 → 1.4.0

package/dist/{src/types.d.ts → index.d.ts}

@@ -1,474 +1,629 @@
-/**
- * Encatch Web SDK Type Definitions
- */
-/**
- * User traits for identifying users
- * Supports nested operations: $set, $setOnce, $increment, $decrement, $unset
- */
-export interface UserTraits {
-    /** Set user attributes (overwrites existing values) */
-    $set?: Record<string, any>;
-    /** Set user attributes only if they don't already exist */
-    $setOnce?: Record<string, any>;
-    /** Increment numeric user attributes */
-    $increment?: Record<string, number>;
-    /** Decrement numeric user attributes */
-    $decrement?: Record<string, number>;
-    /** Remove user attributes */
-    $unset?: string[];
-}
-/**
- * Secure options for user identification
- */
-export interface SecureOptions {
-    /** User signature (required when secure is set) */
-    signature: string;
-    /** Optional datetime in UTC when the signature was generated */
-    generatedDateTimeinUTC?: string;
-}
-/**
- * Options for the identifyUser method
- */
-export interface IdentifyOptions {
-    /** User's preferred locale (ISO 639-1 codes, comma-separated) */
-    locale?: string;
-    /** User's country (ISO 3166 country code) */
-    country?: string;
-    /** Secure identification options with signature */
-    secure?: SecureOptions;
-}
-/**
- * Options for the startSession method
- */
-export interface StartSessionOptions {
-    /** When true, do not call the immediate ping (30s ping interval still runs) */
-    skipImmediatePing?: boolean;
-    /**
-     * When true, do not send the initial trackScreen for the current URL
-     * (URL change listeners still run). Defaults to true.
-     */
-    skipImmediateTrackScreen?: boolean;
-}
-/**
- * Theme options
- */
-export type Theme = 'light' | 'dark' | 'system';
-/**
- * Configuration options for the SDK
- */
-export interface EncatchConfig {
-    /** Override the default web host for loading the SDK script */
-    webHost?: string;
-    /** Theme setting - defaults to 'system' */
-    theme?: Theme;
-    /** API base URL - defaults to 'https://app.encatch.com' */
-    apiBaseUrl?: string;
-    /** When true, displays the form inline at full height without modal overlay */
-    isFullScreen?: boolean;
-    /**
-     * Optional interceptor called before any form is shown (manual or automatic).
-     * Receives the form configuration payload. If it returns false (or Promise<false>),
-     * the SDK will not display its built-in iframe form; the app can instead render a
-     * custom UI and use submitForm / emitEvent / refineText to complete the flow.
-     * Pending responses from addToResponse() are cleared when false is returned.
-     */
-    onBeforeShowForm?: (payload: ShowFormInterceptorPayload) => boolean | Promise<boolean>;
-}
-/**
- * Payload passed to the onBeforeShowForm interceptor.
- * Contains the full form configuration returned by the server along with
- * context values the SDK resolved at call time.
- */
-export interface ShowFormInterceptorPayload {
-    /** The form slug or ID that was requested */
-    formId: string;
-    /** Raw form configuration returned by the show-form API */
-    formConfig: Record<string, unknown>;
-    /** Reset mode in effect for this show call */
-    resetMode: ResetMode;
-    /** Whether the form was triggered automatically (server-side) or manually (developer call) */
-    triggerType: 'automatic' | 'manual';
-    /** Pre-filled responses staged via addToResponse() */
-    prefillResponses: Record<string, unknown>;
-    /** Active locale, if set */
-    locale?: string;
-    /** Active theme */
-    theme?: Theme;
-    /** Serialized context values (Dates already converted to ISO strings) */
-    context?: Record<string, string | number | boolean>;
-}
-/**
- * An individual question answer within a form submission
- */
-export interface QuestionAnswer {
-    nps?: number;
-    csat?: number;
-    /** Star-rating / rating scale answer (schema field: `rating`) */
-    rating?: number;
-    singleChoice?: string;
-    singleChoiceOther?: string;
-    multipleChoiceMultiple?: string[];
-    /** Free-text "Other" answer for multiple-choice-multiple questions (schema field: `multipleChoiceOther`) */
-    multipleChoiceOther?: string;
-    nestedSelection?: string[];
-    shortAnswer?: string;
-    longText?: string;
-}
-/**
- * A single question response within a form submission
- */
-export interface QuestionResponse {
-    questionId: string;
-    type?: string;
-    answer?: QuestionAnswer;
-    /** Present on engine-built submits: whether this question was on the respondent's path */
-    isOnPath?: boolean;
-}
-/**
- * Form details for a manual form submission
- */
-export interface FormDetails {
-    /** The server-issued configuration ID for this form */
-    formConfigurationId: string;
-    /** When true, marks this as a partial (mid-journey) submission */
-    isPartialSubmit?: boolean;
-    feedbackIdentifier?: string;
-    responseLanguageCode?: string;
-    response?: {
-        questions?: QuestionResponse[];
-    };
-    completionTimeInSeconds?: number;
-    /** Caller-provided metadata attached to this submission (Dates already serialized to ISO strings) */
-    context?: Record<string, string | number | boolean>;
-    /** IDs of questions the user actually visited, in order */
-    visitedQuestionIds?: string[];
-}
-/**
- * Parameters for manually submitting a form (used with onBeforeShowForm interceptor)
- */
-export interface SubmitFormRequest {
-    triggerType?: 'automatic' | 'manual';
-    formDetails: FormDetails;
-}
-/**
- * Parameters for the refineText AI enhancement endpoint
- */
-export interface RefineTextRequest {
-    questionId: string;
-    feedbackConfigurationId: string;
-    userText: string;
-}
-/**
- * Response from the refineText endpoint
- */
-export interface RefineTextResponse {
-    message?: string;
-    refinedText?: string;
-    status?: number;
-    error?: string;
-    code?: string;
-}
-/**
- * A single turn in a Q&A with AI conversation
- */
-export interface QnaWithAiConversationTurn {
-    /** The question asked by the respondent */
-    question: string;
-    /** The AI's answer; empty string for the current unanswered turn */
-    answer: string;
-}
-/**
- * Parameters for the qnaWithAi endpoint
- */
-export interface QnaWithAiRequest {
-    feedbackConfigurationId: string;
-    questionId: string;
-    /** Full conversation including the current unanswered turn as the last entry */
-    conversation: QnaWithAiConversationTurn[];
-}
-/**
- * Response from the qnaWithAi endpoint
- */
-export interface QnaWithAiResponse {
-    answer: string;
-}
-/**
- * Parameters for the uploadFile method
- */
-export interface UploadFileRequest {
-    /** The form's server-issued configuration ID */
-    feedbackConfigurationId: string;
-    /** The question ID the file belongs to */
-    questionId: string;
-    /** The file or blob to upload */
-    file: File | Blob;
-    /**
-     * File name to send to the server (e.g. "signature.png").
-     * Defaults to "upload" when omitted.
-     */
-    fileName?: string;
-    /**
-     * Optional progress callback — receives upload percentage (0–100).
-     * Useful for driving a progress bar in custom UIs.
-     */
-    onProgress?: (percent: number) => void;
-}
-/**
- * Response from the uploadFile endpoint
- */
-export interface UploadFileResponse {
-    /** Permanent URL of the uploaded file */
-    fileUrl: string;
-}
-/**
- * Reset mode for form data when showing a form
- * - 'always': Clear form data every time showForm is called (default)
- * - 'on-complete': Clear form data only if form was previously completed
- * - 'never': Never clear form data (preserve user's previous answers)
- */
-export type ResetMode = 'always' | 'on-complete' | 'never';
-/**
- * Context values that can be attached to a form submission.
- * Date values are automatically serialized to ISO strings before being sent.
- */
-export type ContextValue = string | number | Date | boolean;
-/**
- * Options for the showForm method
- */
-export interface ShowFormOptions {
-    /**
-     * Controls when form data should be cleared
-     * @default 'always'
-     */
-    reset?: ResetMode;
-    /**
-     * Arbitrary key-value pairs attached to the form submission.
-     * Useful for passing caller-side metadata (e.g. plan tier, feature flag states).
-     * Date values are automatically serialized to ISO 8601 strings.
-     */
-    context?: Record<string, ContextValue>;
-}
-/**
- * Event types that can be subscribed to
- */
-export type EventType = 'form:show' | 'form:started' | 'form:submit'
-/**
- * For `exit_form` with `autoTriggerDelayMs`, the SDK may close the form on this event
- * and fire `form:ctaTriggered` after the delay from the parent window (not the iframe).
- * Host apps do not schedule timers — this is SDK-internal.
- */
- | 'form:complete' | 'form:close' | 'form:dismissed' | 'form:error' | 'form:section:change' | 'form:answered' | 'form:remindmelater'
-/**
- * Fired when a completionCta action fires on a thank_you or exit_form screen.
- * payload.data: { action, route?, url?, surface, trigger }
- *
- * - action "app_navigate": host navigates to data.route in _encatch.on(); the SDK
- *   closes the form iframe automatically after emitting this event.
- * - action "redirect_internal": the SDK navigates the parent page to data.url (same tab);
- *   the form is already closing.
- * - action "redirect_external": the SDK opens data.url in a new tab; the form is already closing.
- */
- | 'form:ctaTriggered';
-/**
- * Event callback function type
- * Receives all form events with the event type and payload
- */
-export type EventCallback = (eventType: EventType, payload: EventPayload) => void;
-/**
- * Event payload structure
- */
-export interface EventPayload {
-    /** The form ID related to the event */
-    formId?: string;
-    /** Timestamp of the event */
-    timestamp: number;
-    /** Additional event-specific data */
-    data?: Record<string, unknown>;
-}
-/**
- * Internal command tuple type for the queue
- */
-export type Command = [string, ...unknown[]];
-/**
- * The Encatch SDK interface
- */
-export interface EncatchSDK {
-    /**
-     * Initialize the SDK with an API key
-     * This triggers the loading of the remote implementation script
-     * @param apiKey - Your Encatch API key
-     * @param config - Optional configuration options
-     */
-    init(apiKey: string, config?: EncatchConfig): void;
-    /**
-     * Identify the current user
-     * @param userName - User name or unique identifier (e.g. username, email) (required)
-     * @param traits - Optional user traits with nested operations ($set, $setOnce, $increment, $decrement, $unset)
-     * @param options - Optional settings like locale, country, and secure signature
-     */
-    identifyUser(userName: string, traits?: UserTraits, options?: IdentifyOptions): void;
-    /**
-     * Set the user's preferred locale
-     * @param locale - Comma-separated ISO 639-1 language codes (e.g., 'fr,en,es')
-     */
-    setLocale(locale: string): void;
-    /**
-     * Set the user's country
-     * @param country - ISO 3166 country code (e.g., 'US', 'FR')
-     */
-    setCountry(country: string): void;
-    /**
-     * Set the theme
-     * @param theme - Theme value ('light', 'dark', or 'system')
-     */
-    setTheme(theme: Theme): void;
-    /**
-     * Track a custom event
-     * @param eventName - Name of the event to track
-     */
-    trackEvent(eventName: string): void;
-    /**
-     * Track a screen view
-     * @param screenName - Name of the screen to track
-     */
-    trackScreen(screenName: string): void;
-    /**
-     * Manually start a new session
-     * Useful after user login to reset session timing
-     * @param options - Optional flags to skip immediate ping and/or immediate trackScreen
-     */
-    startSession(options?: StartSessionOptions): void;
-    /**
-     * Temporarily stops the automatic background ping without affecting open forms,
-     * URL change listeners, or user identity. Reversed by resumeSession().
-     * Not persisted — clears automatically on page reload.
-     */
-    pauseSession(): void;
-    /**
-     * Restarts the background ping interval after a pauseSession() call.
-     * No-op if the session was not paused.
-     */
-    resumeSession(): void;
-    /**
-     * Fully suspends all SDK activity — stops the ping interval, URL change
-     * tracking, and closes any open forms. User identity is preserved.
-     * Persists across page reloads via localStorage. Re-enable with startSession().
-     */
-    stopSession(): void;
-    /**
-     * Reset the current user (logout)
-     * Reverts the SDK to anonymous mode
-     */
-    resetUser(): void;
-    /**
-     * Show a specific form by ID
-     * @param formId - The ID of the form to display
-     * @param options - Optional settings for form display behavior
-     */
-    showForm(formId: string, options?: ShowFormOptions): void;
-    /**
-     * Dismiss a form and report to the server
-     * Closes the iframe if open and calls the dismiss-form endpoint
-     * @param formConfigurationId - The form configuration ID to dismiss (required for API call)
-     */
-    dismissForm(formConfigurationId?: string): void;
-    /**
-     * Prepopulate a form response.
-     * @param questionId - The ID or slug of the question to prepopulate. When a slug
-     *   is provided the form engine resolves it to the matching question ID automatically.
-     * @param value - The value to set
-     */
-    addToResponse(questionId: string, value: unknown): void;
-    /**
-     * Manually submit a form to the Encatch API.
-     * Use this when onBeforeShowForm returns false and you render a custom UI —
-     * call submitForm once the user completes your custom form.
-     * @param params - Submission details including formConfigurationId and question responses
-     */
-    submitForm(params: SubmitFormRequest): void;
-    /**
-     * Emit a form lifecycle event to all on() subscribers.
-     * Use this when onBeforeShowForm returns false to mirror the events that the
-     * built-in iframe form would normally fire (e.g. form:show, form:started,
-     * form:answered, form:submit, form:complete, form:close).
-     * @param eventType - The event type to emit
-     * @param payload - Event payload (timestamp is added automatically)
-     */
-    emitEvent(eventType: EventType, payload: Omit<EventPayload, 'timestamp'>): void;
-    /**
-     * Request AI text refinement for a long-text answer.
-     * Use this when onBeforeShowForm returns false and your custom UI includes
-     * an AI-enhance feature.
-     * @param params - The question ID, form configuration ID, and user text to refine
-     * @returns Promise resolving to the refined text response
-     */
-    refineText(params: RefineTextRequest): Promise<RefineTextResponse>;
-    /**
-     * Call the Q&A with AI endpoint for a qna_with_ai question.
-     * Sends the full conversation history (including the current unanswered turn) and
-     * returns the AI-generated answer.
-     * @param params - feedbackConfigurationId, questionId, and full conversation array
-     * @returns Promise resolving to { answer: string }
-     */
-    qnaWithAi(params: QnaWithAiRequest): Promise<QnaWithAiResponse>;
-    /**
-     * Streaming variant of qnaWithAi.
-     * Calls onChunk for each partial delta as the AI generates the answer,
-     * and onDone with the final authoritative answer when complete.
-     * @param params - feedbackConfigurationId, questionId, and full conversation array
-     * @param callbacks.onChunk - Called for each partial text delta
-     * @param callbacks.onDone - Called once with the complete final answer
-     * @returns Promise that resolves when the stream is complete
-     */
-    streamQnaWithAi(params: QnaWithAiRequest, callbacks: {
-        onChunk: (delta: string) => void;
-        onDone: (answer: string) => void;
-    }): Promise<void>;
-    /**
-     * Upload a file to the Encatch file storage.
-     * Use this when onBeforeShowForm returns false and your custom UI contains a
-     * file, image, signature, or media question — call uploadFile for each selected
-     * file and store the returned fileUrl in your answer payload.
-     * @param params - feedbackConfigurationId, questionId, file, optional fileName and onProgress
-     * @returns Promise resolving to { fileUrl: string }
-     */
-    uploadFile(params: UploadFileRequest): Promise<UploadFileResponse>;
-    /**
-     * Subscribe to all form events
-     * The callback receives all form events (show, submit, close, complete, error)
-     * @param callback - Function to call when any form event occurs
-     * @returns Unsubscribe function
-     */
-    on(callback: EventCallback): () => void;
-    /**
-     * Clear all SDK state and stored data, reverting to a brand-new visitor state.
-     * Stops the ping interval and URL change listeners, clears all localStorage and
-     * IndexedDB data written by the SDK, and resets all in-memory identity state.
-     * showForm() and submitForm() continue to work after this call (with NIL UUIDs),
-     * but no tracking fires until startSession() or identifyUser() is called again.
-     * Use this to implement a "forget me" / consent withdrawal flow.
-     */
-    clearAll(): void;
-    /**
-     * Merge additional source tracking key-value pairs into the SDK's in-memory
-     * source tracking store. These values are combined with auto-parsed URL params
-     * whenever showForm() is called. Values set here take precedence over URL params
-     * on key collision. Persists in memory for the lifetime of the page session.
-     * Supported on the web SDK only.
-     * @param values - Key-value pairs to merge into the source tracking store
-     */
-    addSourceTracking(values: Record<string, string>): void;
-    /** Internal: Command queue for calls made before script loads */
-    _q: Command[];
-    /** Internal: Event callbacks */
-    _eventCallbacks: EventCallback[];
-    /** Internal: Whether the SDK has been initialized */
-    _initialized: boolean;
-    /** Internal: The API key */
-    _apiKey: string | null;
-    /** Internal: Configuration */
-    _config: EncatchConfig;
-}
+/** Answer for an address question. */
+declare interface AddressAnswer {
+    addressLine1?: string;
+    addressLine2?: string;
+    city?: string;
+    stateProvince?: string;
+    postalCode?: string;
+    country?: string;
+}
+
+/** Annotation answer containing file metadata and markers. */
+declare interface Annotation {
+    fileType: string;
+    fileName: string;
+    markers: AnnotationMarker[];
+}
+
+/** A single annotation marker placed on a file. */
+declare interface AnnotationMarker {
+    markerNo: string;
+    timeline: string;
+    comment: string;
+}
+
+/** Flexible answer item supporting every question type. */
+declare interface AnswerItem {
+    nps?: number;
+    nestedSelection?: string[];
+    longText?: string;
+    shortAnswer?: string;
+    singleChoice?: string;
+    rating?: number;
+    yesNo?: boolean;
+    consent?: boolean;
+    multipleChoiceMultiple?: string[];
+    singleChoiceOther?: string;
+    multipleChoiceOther?: string;
+    annotation?: Annotation;
+    ratingMatrix?: Record<string, number | string>;
+    matrixSingleChoice?: Record<string, string>;
+    matrixMultipleChoice?: Record<string, string[]>;
+    others?: string;
+    date?: string;
+    csat?: number;
+    opinionScale?: number;
+    ranking?: string[];
+    pictureChoice?: string[];
+    pictureChoiceOther?: string;
+    signature?: SignatureAnswer;
+    fileUpload?: FileUploadAnswer;
+    email?: string;
+    number?: string;
+    website?: string;
+    phoneNumber?: PhoneNumberAnswer;
+    address?: AddressAnswer;
+    videoAudio?: VideoAudioAnswer;
+    scheduler?: SchedulerAnswer;
+    qnaWithAi?: QnaWithAiAnswer;
+    paymentsUpi?: PaymentsUpiAnswer;
+}
+
+/**
+ * Internal command tuple type for the queue
+ */
+declare type Command = [string, ...unknown[]];
+
+/**
+ * Context values that can be attached to a form submission.
+ * Date values are automatically serialized to ISO strings before being sent.
+ */
+declare type ContextValue = string | number | Date | boolean;
+
+declare const _encatch: EncatchSDK;
+export { _encatch }
+export default _encatch;
+
+/**
+ * Configuration options for the SDK
+ */
+export declare interface EncatchConfig {
+    /** Override the default web host for loading the SDK script */
+    webHost?: string;
+    /** Theme setting - defaults to 'system' */
+    theme?: Theme;
+    /** API base URL - defaults to 'https://app.encatch.com' */
+    apiBaseUrl?: string;
+    /** When true, displays the form inline at full height without modal overlay */
+    isFullScreen?: boolean;
+    /**
+     * Optional interceptor called before any form is shown (manual or automatic).
+     * Receives the form configuration payload. If it returns false (or Promise<false>),
+     * the SDK will not display its built-in iframe form; the app can instead render a
+     * custom UI and use submitForm / emitEvent / refineText to complete the flow.
+     * Pending responses from addToResponse() are cleared when false is returned.
+     */
+    onBeforeShowForm?: (payload: ShowFormInterceptorPayload) => boolean | Promise<boolean>;
+}
+
+/**
+ * The Encatch SDK interface
+ */
+export declare interface EncatchSDK {
+    /**
+     * Initialize the SDK with an API key
+     * This triggers the loading of the remote implementation script
+     * @param apiKey - Your Encatch API key
+     * @param config - Optional configuration options
+     */
+    init(apiKey: string, config?: EncatchConfig): void;
+    /**
+     * Identify the current user
+     * @param userName - User name or unique identifier (e.g. username, email) (required)
+     * @param traits - Optional user traits with nested operations ($set, $setOnce, $increment, $decrement, $unset)
+     * @param options - Optional settings like locale, country, and secure signature
+     */
+    identifyUser(userName: string, traits?: UserTraits, options?: IdentifyOptions): void;
+    /**
+     * Set the user's preferred locale
+     * @param locale - Comma-separated ISO 639-1 language codes (e.g., 'fr,en,es')
+     */
+    setLocale(locale: string): void;
+    /**
+     * Set the user's country
+     * @param country - ISO 3166 country code (e.g., 'US', 'FR')
+     */
+    setCountry(country: string): void;
+    /**
+     * Set the theme
+     * @param theme - Theme value ('light', 'dark', or 'system')
+     */
+    setTheme(theme: Theme): void;
+    /**
+     * Track a custom event
+     * @param eventName - Name of the event to track
+     */
+    trackEvent(eventName: string): void;
+    /**
+     * Track a screen view
+     * @param screenName - Name of the screen to track
+     */
+    trackScreen(screenName: string): void;
+    /**
+     * Manually start a new session
+     * Useful after user login to reset session timing
+     * @param options - Optional flags to skip immediate ping and/or immediate trackScreen
+     */
+    startSession(options?: StartSessionOptions): void;
+    /**
+     * Temporarily stops the automatic background ping without affecting open forms,
+     * URL change listeners, or user identity. Reversed by resumeSession().
+     * Not persisted — clears automatically on page reload.
+     */
+    pauseSession(): void;
+    /**
+     * Restarts the background ping interval after a pauseSession() call.
+     * No-op if the session was not paused.
+     */
+    resumeSession(): void;
+    /**
+     * Fully suspends all SDK activity — stops the ping interval, URL change
+     * tracking, and closes any open forms. User identity is preserved.
+     * Persists across page reloads via localStorage. Re-enable with startSession().
+     */
+    stopSession(): void;
+    /**
+     * Reset the current user (logout)
+     * Reverts the SDK to anonymous mode
+     */
+    resetUser(): void;
+    /**
+     * Show a specific form by ID
+     * @param formId - The ID of the form to display
+     * @param options - Optional settings for form display behavior
+     */
+    showForm(formId: string, options?: ShowFormOptions): void;
+    /**
+     * Dismiss a form and report to the server
+     * Closes the iframe if open and calls the dismiss-form endpoint
+     * @param formConfigurationId - The form configuration ID to dismiss (required for API call)
+     */
+    dismissForm(formConfigurationId?: string): void;
+    /**
+     * Prepopulate a form response.
+     * @param questionId - The ID or slug of the question to prepopulate. When a slug
+     *   is provided the form engine resolves it to the matching question ID automatically.
+     * @param value - The value to set
+     */
+    addToResponse(questionId: string, value: unknown): void;
+    /**
+     * Manually submit a form to the Encatch API.
+     * Use this when onBeforeShowForm returns false and you render a custom UI —
+     * call submitForm once the user completes your custom form.
+     * @param params - Submission details including formConfigurationId and question responses
+     */
+    submitForm(params: SubmitFormRequest): void;
+    /**
+     * Emit a form lifecycle event to all on() subscribers.
+     * Use this when onBeforeShowForm returns false to mirror the events that the
+     * built-in iframe form would normally fire (e.g. form:show, form:started,
+     * form:answered, form:submit, form:complete, form:close).
+     * @param eventType - The event type to emit
+     * @param payload - Event payload (timestamp is added automatically)
+     */
+    emitEvent(eventType: EventType, payload: Omit<EventPayload, 'timestamp'>): void;
+    /**
+     * Request AI text refinement for a long-text answer.
+     * Use this when onBeforeShowForm returns false and your custom UI includes
+     * an AI-enhance feature.
+     * @param params - The question ID, form configuration ID, and user text to refine
+     * @returns Promise resolving to the refined text response
+     */
+    refineText(params: RefineTextRequest): Promise<RefineTextResponse>;
+    /**
+     * Call the Q&A with AI endpoint for a qna_with_ai question.
+     * Sends the full conversation history (including the current unanswered turn) and
+     * returns the AI-generated answer.
+     * @param params - feedbackConfigurationId, questionId, and full conversation array
+     * @returns Promise resolving to { answer: string }
+     */
+    qnaWithAi(params: QnaWithAiRequest): Promise<QnaWithAiResponse>;
+    /**
+     * Streaming variant of qnaWithAi.
+     * Calls onChunk for each partial delta as the AI generates the answer,
+     * and onDone with the final authoritative answer when complete.
+     * @param params - feedbackConfigurationId, questionId, and full conversation array
+     * @param callbacks.onChunk - Called for each partial text delta
+     * @param callbacks.onDone - Called once with the complete final answer
+     * @returns Promise that resolves when the stream is complete
+     */
+    streamQnaWithAi(params: QnaWithAiRequest, callbacks: {
+        onChunk: (delta: string) => void;
+        onDone: (answer: string) => void;
+    }): Promise<void>;
+    /**
+     * Upload a file to the Encatch file storage.
+     * Use this when onBeforeShowForm returns false and your custom UI contains a
+     * file, image, signature, or media question — call uploadFile for each selected
+     * file and store the returned fileUrl in your answer payload.
+     * @param params - feedbackConfigurationId, questionId, file, optional fileName and onProgress
+     * @returns Promise resolving to { fileUrl: string }
+     */
+    uploadFile(params: UploadFileRequest): Promise<UploadFileResponse>;
+    /**
+     * Subscribe to all form events
+     * The callback receives all form events (show, submit, close, complete, error)
+     * @param callback - Function to call when any form event occurs
+     * @returns Unsubscribe function
+     */
+    on(callback: EventCallback): () => void;
+    /**
+     * Clear all SDK state and stored data, reverting to a brand-new visitor state.
+     * Stops the ping interval and URL change listeners, clears all localStorage and
+     * IndexedDB data written by the SDK, and resets all in-memory identity state.
+     * showForm() and submitForm() continue to work after this call (with NIL UUIDs),
+     * but no tracking fires until startSession() or identifyUser() is called again.
+     * Use this to implement a "forget me" / consent withdrawal flow.
+     */
+    clearAll(): void;
+    /**
+     * Merge additional source tracking key-value pairs into the SDK's in-memory
+     * source tracking store. These values are combined with auto-parsed URL params
+     * whenever showForm() is called. Values set here take precedence over URL params
+     * on key collision. Persists in memory for the lifetime of the page session.
+     * Supported on the web SDK only.
+     * @param values - Key-value pairs to merge into the source tracking store
+     */
+    addSourceTracking(values: Record<string, string>): void;
+    /** Internal: Command queue for calls made before script loads */
+    _q: Command[];
+    /** Internal: Event callbacks */
+    _eventCallbacks: EventCallback[];
+    /** Internal: Whether the SDK has been initialized */
+    _initialized: boolean;
+    /** Internal: The API key */
+    _apiKey: string | null;
+    /** Internal: Configuration */
+    _config: EncatchConfig;
+}
+
+/**
+ * Event callback function type
+ * Receives all form events with the event type and payload
+ */
+export declare type EventCallback = (eventType: EventType, payload: EventPayload) => void;
+
+/**
+ * Event payload structure
+ */
+export declare interface EventPayload {
+    /** The form ID related to the event */
+    formId?: string;
+    /** Timestamp of the event */
+    timestamp: number;
+    /** Additional event-specific data */
+    data?: Record<string, unknown>;
+}
+
+/**
+ * Event types that can be subscribed to
+ */
+export declare type EventType = 'form:show' | 'form:started' | 'form:submit'
+/**
+* For `exit_form` with `autoTriggerDelayMs`, the SDK may close the form on this event
+* and fire `form:ctaTriggered` after the delay from the parent window (not the iframe).
+* Host apps do not schedule timers — this is SDK-internal.
+*/
+| 'form:complete' | 'form:close' | 'form:dismissed' | 'form:error' | 'form:section:change' | 'form:answered' | 'form:remindmelater'
+/**
+* Fired when a completionCta action fires on a thank_you or exit_form screen.
+* payload.data: { action, route?, url?, surface, trigger }
+*
+* - action "app_navigate": host navigates to data.route in _encatch.on(); the SDK
+*   closes the form iframe automatically after emitting this event.
+* - action "redirect_internal": the SDK navigates the parent page to data.url (same tab);
+*   the form is already closing.
+* - action "redirect_external": the SDK opens data.url in a new tab; the form is already closing.
+*/
+| 'form:ctaTriggered';
+
+/** Answer for a file upload question; array supports single and multiple uploads. */
+declare type FileUploadAnswer = FileUploadAnswerItem[];
+
+/** Metadata for a single uploaded file. */
+declare interface FileUploadAnswerItem {
+    fileUrl: string;
+    fileName: string;
+    fileSizeMb: number;
+    mimeType?: string;
+}
+
+/** Form details for an SDK-style submit-form request. */
+export declare interface FormDetails {
+    formConfigurationId: string;
+    feedbackIdentifier?: string;
+    responseLanguageCode?: string;
+    isPartialSubmit?: boolean;
+    completionTimeInSeconds?: number;
+    response?: FormDetailsResponse;
+    visitedQuestionIds?: string[];
+    context?: Record<string, string | number | boolean>;
+}
+
+/** User responses nested inside an SDK-style submit-form request. */
+declare interface FormDetailsResponse {
+    questions?: QuestionResponse[];
+    context?: Record<string, unknown>;
+    contact?: Record<string, unknown>;
+    sourceTrackingFieldValues?: Record<string, string>;
+}
+
+/**
+ * Options for the identifyUser method
+ */
+export declare interface IdentifyOptions {
+    /** User's preferred locale (ISO 639-1 codes, comma-separated) */
+    locale?: string;
+    /** User's country (ISO 3166 country code) */
+    country?: string;
+    /** Secure identification options with signature */
+    secure?: SecureOptions;
+}
+
+/** Answer for a payments_upi question; self-reported UPI transaction reference. */
+declare interface PaymentsUpiAnswer {
+    transactionId: string;
+    encatchPaymentReference: string;
+    amount: string;
+    currency: "INR";
+    payeeVpa: string;
+    payeeName?: string;
+    sourceEmail?: string;
+    upiIntentUri?: string;
+    selfReported: true;
+}
+
+/** Answer for a phone number question. */
+declare interface PhoneNumberAnswer {
+    countryCode: string;
+    number: string;
+    e164?: string;
+}
+
+/** Answer for a qna_with_ai question; ordered transcript of Q&A pairs. */
+declare type QnaWithAiAnswer = QnaWithAiPair[];
+
+/**
+ * A single turn in a Q&A with AI conversation
+ */
+export declare interface QnaWithAiConversationTurn {
+    /** The question asked by the respondent */
+    question: string;
+    /** The AI's answer; empty string for the current unanswered turn */
+    answer: string;
+}
+
+/** A single Q&A exchange between the respondent and the AI. */
+declare interface QnaWithAiPair {
+    question: string;
+    answer: string;
+}
+
+/**
+ * Parameters for the qnaWithAi endpoint
+ */
+export declare interface QnaWithAiRequest {
+    feedbackConfigurationId: string;
+    questionId: string;
+    /** Full conversation including the current unanswered turn as the last entry */
+    conversation: QnaWithAiConversationTurn[];
+}
+
+/**
+ * Response from the qnaWithAi endpoint
+ */
+export declare interface QnaWithAiResponse {
+    answer: string;
+}
+
+/** All supported question answer shapes. */
+export declare type QuestionAnswer = AnswerItem;
+
+/** Response to a specific question in the feedback form. */
+export declare interface QuestionResponse {
+    questionId: string;
+    /**
+     * The answer provided for this question; null for display-only types
+     * (thank_you, welcome, exit_form) or unanswered questions on the path.
+     */
+    answer?: QuestionAnswer | null;
+    type?: string;
+    error?: string;
+    isOnPath?: boolean;
+    timeSpentMs?: number;
+    isPathTraversed?: boolean;
+}
+
+/**
+ * Parameters for the refineText AI enhancement endpoint
+ */
+export declare interface RefineTextRequest {
+    questionId: string;
+    feedbackConfigurationId: string;
+    userText: string;
+}
+
+/**
+ * Response from the refineText endpoint
+ */
+export declare interface RefineTextResponse {
+    message?: string;
+    refinedText?: string;
+    status?: number;
+    error?: string;
+    code?: string;
+}
+
+/**
+ * Reset mode for form data when showing a form
+ * - 'always': Clear form data every time showForm is called (default)
+ * - 'on-complete': Clear form data only if form was previously completed
+ * - 'never': Never clear form data (preserve user's previous answers)
+ */
+export declare type ResetMode = 'always' | 'on-complete' | 'never';
+
+/** Answer for a scheduler question; shape depends on the calendar provider. */
+declare type SchedulerAnswer = {
+    provider: "google_calendar";
+    bookedAt: string;
+} | {
+    provider: "calendly";
+    slotStart: string;
+    slotEnd: string;
+    eventId?: string;
+    bookedAt: string;
+};
+
+/**
+ * Secure options for user identification
+ */
+declare interface SecureOptions {
+    /** User signature (required when secure is set) */
+    signature: string;
+    /** Optional datetime in UTC when the signature was generated */
+    generatedDateTimeinUTC?: string;
+}
+
+/**
+ * Payload passed to the onBeforeShowForm interceptor.
+ * Contains the full form configuration returned by the server along with
+ * context values the SDK resolved at call time.
+ */
+export declare interface ShowFormInterceptorPayload {
+    /** The form slug or ID that was requested */
+    formId: string;
+    /** Raw form configuration returned by the show-form API */
+    formConfig: Record<string, unknown>;
+    /** Reset mode in effect for this show call */
+    resetMode: ResetMode;
+    /** Whether the form was triggered automatically (server-side) or manually (developer call) */
+    triggerType: 'automatic' | 'manual';
+    /** Pre-filled responses staged via addToResponse() */
+    prefillResponses: Record<string, unknown>;
+    /** Active locale, if set */
+    locale?: string;
+    /** Active theme */
+    theme?: Theme;
+    /** Serialized context values (Dates already converted to ISO strings) */
+    context?: Record<string, string | number | boolean>;
+}
+
+/**
+ * Options for the showForm method
+ */
+export declare interface ShowFormOptions {
+    /**
+     * Controls when form data should be cleared
+     * @default 'always'
+     */
+    reset?: ResetMode;
+    /**
+     * Arbitrary key-value pairs attached to the form submission.
+     * Useful for passing caller-side metadata (e.g. plan tier, feature flag states).
+     * Date values are automatically serialized to ISO 8601 strings.
+     */
+    context?: Record<string, ContextValue>;
+    /**
+     * CSS selector for a host element to render the form inline into (highest-priority
+     * placement). If the selector matches an element, the form mounts there; if it
+     * doesn't match (or is invalid), placement falls back to the `#encatch` rules
+     * (a `<div id="encatch">`, optionally bound to a form via `data-encatch-form-id`)
+     * and then to the default modal. Example: `showForm('id', { selector: '#feedback-slot' })`.
+     */
+    selector?: string;
+}
+
+/** Answer for a signature question. */
+declare interface SignatureAnswer {
+    mode: "type" | "draw" | "upload";
+    fileUrl?: string;
+    typedName?: string;
+}
+
+/**
+ * Options for the startSession method
+ */
+export declare interface StartSessionOptions {
+    /** When true, do not call the immediate ping (30s ping interval still runs) */
+    skipImmediatePing?: boolean;
+    /**
+     * When true, do not send the initial trackScreen for the current URL
+     * (URL change listeners still run). Defaults to true.
+     */
+    skipImmediateTrackScreen?: boolean;
+}
+
+/** Complete submit-form request envelope (SDK-facing contract). */
+export declare interface SubmitFormRequest {
+    triggerType?: "automatic" | "manual";
+    formDetails: FormDetails;
+    $deviceInfo?: Record<string, unknown>;
+}
+
+/**
+ * Theme options
+ */
+export declare type Theme = 'light' | 'dark' | 'system';
+
+/**
+ * Parameters for the uploadFile method
+ */
+export declare interface UploadFileRequest {
+    /** The form's server-issued configuration ID */
+    feedbackConfigurationId: string;
+    /** The question ID the file belongs to */
+    questionId: string;
+    /** The file or blob to upload */
+    file: File | Blob;
+    /**
+     * File name to send to the server (e.g. "signature.png").
+     * Defaults to "upload" when omitted.
+     */
+    fileName?: string;
+    /**
+     * Optional progress callback — receives upload percentage (0–100).
+     * Useful for driving a progress bar in custom UIs.
+     */
+    onProgress?: (percent: number) => void;
+}
+
+/**
+ * Response from the uploadFile endpoint
+ */
+export declare interface UploadFileResponse {
+    /** Permanent URL of the uploaded file */
+    fileUrl: string;
+}
+
+/**
+ * User traits for identifying users
+ * Supports nested operations: $set, $setOnce, $increment, $decrement, $unset
+ */
+export declare interface UserTraits {
+    /** Set user attributes (overwrites existing values) */
+    $set?: Record<string, any>;
+    /** Set user attributes only if they don't already exist */
+    $setOnce?: Record<string, any>;
+    /** Increment numeric user attributes */
+    $increment?: Record<string, number>;
+    /** Decrement numeric user attributes */
+    $decrement?: Record<string, number>;
+    /** Remove user attributes */
+    $unset?: string[];
+}
+
+/** Answer for a video / audio / photo / text question. */
+declare interface VideoAudioAnswer {
+    mode: "video" | "audio" | "photo" | "text";
+    fileUrl?: string;
+    text?: string;
+    durationSeconds?: number;
+    transcriptText?: string;
+}
+
+export { }
+
+
 /**
  * Global window augmentation for TypeScript
  */
@@ -477,4 +632,3 @@ declare global {
         _encatch: EncatchSDK;
     }
 }
-//# sourceMappingURL=types.d.ts.map