@encatch/react-native-sdk 1.0.0-beta.0

package/dist/index.d.ts

@@ -0,0 +1,409 @@
+import React, { ReactNode } from 'react';
+
+/**
+ * All shared TypeScript interfaces and types for the Encatch React Native SDK.
+ */
+interface EncatchConfig {
+    /**
+     * Base URL used for all API calls.
+     * Defaults to 'https://app.encatch.com'.
+     */
+    apiBaseUrl?: string;
+    /**
+     * Base URL used to load the react-native-sdk-form WebView page.
+     * Defaults to the same value as apiBaseUrl.
+     * Override this only if your web host differs from your API host.
+     */
+    webHost?: string;
+    /** Default theme for forms. Defaults to 'system'. */
+    theme?: Theme;
+    /** When true, the form overlay is displayed full-screen. */
+    isFullScreen?: boolean;
+    /** Enable verbose SDK logging to the console. */
+    debugMode?: boolean;
+    /** Override app version (default: auto-detected from native app) */
+    appVersion?: string;
+    /**
+     * Optional interceptor called before any form is shown (manual or automatic).
+     * If it returns false (or Promise<false>), the SDK form will not open; the app
+     * can show a custom widget using the payload. Prefills are cleared when false.
+     */
+    onBeforeShowForm?: (payload: ShowFormInterceptorPayload) => boolean | Promise<boolean>;
+}
+interface ShowFormInterceptorPayload {
+    formId: string;
+    formConfig: ShowFormResponse;
+    resetMode: ResetMode;
+    triggerType: 'automatic' | 'manual';
+    /** Pre-filled responses from addToResponse() */
+    prefillResponses: Record<string, unknown>;
+    locale?: string;
+    theme?: Theme;
+}
+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 screen (screen listeners still run) */
+    skipImmediateTrackScreen?: boolean;
+}
+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[];
+}
+interface SecureOptions {
+    signature: string;
+    generatedDateTimeinUTC?: string;
+}
+interface IdentifyOptions {
+    locale?: string;
+    country?: string;
+    secure?: SecureOptions;
+}
+type Theme = 'light' | 'dark' | 'system';
+/**
+ * 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)
+ */
+type ResetMode = 'always' | 'on-complete' | 'never';
+interface ShowFormOptions {
+    /**
+     * Controls when form data should be cleared.
+     * @default 'always'
+     */
+    reset?: ResetMode;
+}
+type EventType = 'form:show' | 'form:started' | 'form:submit' | 'form:complete' | 'form:close' | 'form:dismissed' | 'form:error' | 'form:section:change' | 'form:answered';
+interface EventPayload {
+    formId?: string;
+    timestamp: number;
+    data?: Record<string, unknown>;
+}
+type EventCallback = (eventType: EventType, payload: EventPayload) => void;
+interface ApiDeviceInfo {
+    $deviceOs?: string;
+    $deviceVersion?: string;
+    $deviceOsVersion?: string;
+    $deviceType?: string;
+    $deviceSize?: 'mobile' | 'tablet' | 'desktop';
+    $sdkVersion?: string;
+    $appVersion?: string;
+    $app?: string;
+    $deviceLanguage?: string;
+    $userLanguage?: string;
+    $countryCode?: string;
+    $preferredTheme?: string;
+    $timezone?: string;
+    $urlOrScreenName?: string;
+}
+interface ShowFormResponse {
+    feedbackConfigurationId: string;
+    feedbackIdentifier?: string;
+    triggerType?: 'automatic' | 'manual';
+    formConfiguration?: Record<string, unknown>;
+    questionnaireFields?: any;
+    otherConfigurationProperties?: any;
+    welcomeScreenProperties?: any;
+    endScreenProperties?: any;
+    appearanceProperties?: any;
+    partialResponseEnabled?: boolean;
+    pingAgainIn?: number;
+    pingOnNextPageVisit?: boolean;
+    $feedbackTransactions?: string;
+}
+interface RefineTextRequest {
+    questionId: string;
+    feedbackConfigurationId: string;
+    userText: string;
+    $deviceInfo?: ApiDeviceInfo;
+    $feedbackTransactions?: string;
+}
+interface RefineTextResponse {
+    message?: string;
+    refinedText?: string;
+    status?: number;
+    error?: string;
+    pingAgainIn?: number;
+    pingOnNextPageVisit?: boolean;
+    $feedbackTransactions?: string;
+}
+interface QuestionAnswer {
+    nps?: number;
+    rating?: number;
+    singleChoice?: string;
+    singleChoiceOther?: string;
+    multipleChoiceMultiple?: string[];
+    multipleChoiceMultipleOther?: string;
+    nestedSelection?: string[];
+    shortAnswer?: string;
+    longText?: string;
+    annotation?: {
+        fileType?: string;
+        fileData?: string;
+        fileName?: string;
+    };
+}
+interface QuestionResponse {
+    questionId: string;
+    type?: string;
+    answer?: QuestionAnswer;
+}
+interface FormDetails {
+    formConfigurationId: string;
+    isPartialSubmit?: boolean;
+    feedbackIdentifier?: string;
+    responseLanguageCode?: string;
+    response?: {
+        questions?: QuestionResponse[];
+    };
+    completionTimeInSeconds?: number;
+}
+interface SubmitFormRequest {
+    triggerType?: 'automatic' | 'manual';
+    formDetails: FormDetails;
+    $deviceInfo?: ApiDeviceInfo;
+    $feedbackTransactions?: string;
+}
+
+/**
+ * Encatch React Native SDK — Core
+ *
+ * The main singleton class. Mirrors the web SDK's encatch.ts + api-client.ts
+ * but uses React Native APIs (AsyncStorage, fetch, Platform) instead of
+ * browser APIs (localStorage, ky, window).
+ *
+ * Architecture:
+ *  - All public methods are static on the Encatch class.
+ *  - An internal EventEmitter connects Encatch to EncatchWebView for form display.
+ *  - A 30-second ping interval mirrors the web SDK behaviour.
+ *  - A retry queue wraps identifyUser / trackEvent / trackScreen calls.
+ */
+
+declare class EncatchSDK {
+    private _initialized;
+    private _debugMode;
+    private _apiKey;
+    private _apiBaseUrl;
+    private _webHost;
+    private _isFullScreen;
+    private _userName;
+    private _userId;
+    private _userSignature;
+    private _locale;
+    private _country;
+    private _theme;
+    private _currentScreen;
+    private _deviceId;
+    private _sessionId;
+    private _feedbackTransactions;
+    private _pingIntervalId;
+    private _pingTimeoutId;
+    private _pingIntervalMs;
+    private _isPingActive;
+    private _isFormVisible;
+    private _appVersion;
+    private _appPackageName;
+    private _eventCallbacks;
+    private _onBeforeShowForm;
+    private _logger;
+    init(apiKey: string, config?: EncatchConfig): Promise<void>;
+    identifyUser(userName: string, traits?: UserTraits, options?: IdentifyOptions): Promise<void>;
+    setLocale(locale: string): void;
+    setCountry(country: string): void;
+    setTheme(theme: Theme): void;
+    trackEvent(eventName: string): Promise<void>;
+    /**
+     * Best-effort server call for form lifecycle events (form:show, form:started, etc.).
+     * Not enqueued — matches web SDK behaviour where form events are fire-and-forget.
+     */
+    _trackFormEvent(eventName: string, feedbackConfigurationId?: string): Promise<void>;
+    trackScreen(screenName: string): Promise<void>;
+    showForm(formId: string, options?: ShowFormOptions): Promise<void>;
+    private _showFormInternal;
+    /** Used internally when server returns a formConfigurationId auto-trigger */
+    private _showFormById;
+    dismissForm(formConfigurationId?: string): Promise<void>;
+    private _pendingResponses;
+    addToResponse(questionId: string, value: unknown): void;
+    getPendingResponses(): Record<string, unknown>;
+    clearPendingResponses(): void;
+    submitForm(params: SubmitFormRequest): Promise<void>;
+    refineText(params: RefineTextRequest): Promise<RefineTextResponse>;
+    startSession(options?: StartSessionOptions): Promise<void>;
+    resetUser(): Promise<void>;
+    private _startPingInterval;
+    private _stopPingInterval;
+    private _scheduleNextPing;
+    private _doPing;
+    setFormVisible(visible: boolean): void;
+    private _handleResponseMeta;
+    on(callback: EventCallback): () => void;
+    off(callback: EventCallback): void;
+    emitEvent(eventType: EventType, payload: Omit<EventPayload, 'timestamp'>): void;
+    private _buildDeviceInfo;
+    private _post;
+    get isInitialized(): boolean;
+    get apiKey(): string | null;
+    get baseUrl(): string;
+    get webHost(): string;
+    get isFullScreen(): boolean;
+    get theme(): Theme;
+    get locale(): string | null;
+    get deviceId(): string | null;
+    get sessionId(): string | null;
+    get userName(): string | null;
+    get userId(): string | null;
+    get debugMode(): boolean;
+    stop(): void;
+}
+declare const Encatch: EncatchSDK;
+
+/**
+ * EncatchProvider
+ *
+ * React context provider that:
+ *  1. Calls Encatch.init() on mount (safe to call multiple times)
+ *  2. Auto-tracks screen changes via Expo Router or React Navigation
+ *  3. Exposes useEncatch() hook with the full SDK API surface
+ *
+ * Usage:
+ *   <EncatchProvider apiKey="..." navigationType="expo-router">
+ *     <App />
+ *   </EncatchProvider>
+ */
+
+interface EncatchContextValue {
+    isInitialized: boolean;
+    /**
+     * True when the SDK has a confirmed server-issued identity (both userName and
+     * userId are present). Useful for gating auth-dependent UI without a separate
+     * auth store. Automatically restored from storage on cold start (option 3) and
+     * updated reactively when identifyUser succeeds or resetUser is called (option 1).
+     */
+    isIdentified: boolean;
+    /** The identified user's userName, or null if not identified. */
+    userName: string | null;
+    /** Call Encatch.identifyUser */
+    identifyUser: (userName: string, traits?: UserTraits, options?: IdentifyOptions) => void;
+    /** Call Encatch.setLocale */
+    setLocale: (locale: string) => void;
+    /** Call Encatch.setCountry */
+    setCountry: (country: string) => void;
+    /** Call Encatch.setTheme */
+    setTheme: (theme: Theme) => void;
+    /** Call Encatch.trackEvent */
+    trackEvent: (eventName: string) => void;
+    /** Call Encatch.trackScreen */
+    trackScreen: (screenName: string) => void;
+    /** Call Encatch.showForm */
+    showForm: (formId: string, options?: ShowFormOptions) => void;
+    /** Call Encatch.dismissForm */
+    dismissForm: (formConfigurationId?: string) => void;
+    /** Call Encatch.addToResponse */
+    addToResponse: (questionId: string, value: unknown) => void;
+    /** Call Encatch.resetUser */
+    resetUser: () => void;
+    /** Subscribe to SDK events */
+    on: (callback: EventCallback) => () => void;
+    /** Unsubscribe from SDK events */
+    off: (callback: EventCallback) => void;
+    /**
+     * Submit form (for custom native forms when using onBeforeShowForm interceptor).
+     * Sends responses to the Encatch API.
+     */
+    submitForm: (params: SubmitFormRequest) => void;
+    /**
+     * Emit a form event (for custom native forms when using onBeforeShowForm interceptor).
+     * Use to mirror WebView form events: form:show, form:started, form:answered, form:submit, form:complete, form:close, etc.
+     */
+    emitEvent: (eventType: EventType, payload: Omit<EventPayload, 'timestamp'>) => void;
+    /**
+     * Refine text via AI (for custom native forms with AI enhance feature).
+     */
+    refineText: (params: RefineTextRequest) => Promise<RefineTextResponse>;
+}
+interface EncatchProviderProps {
+    children: ReactNode;
+    /** Your Encatch API key */
+    apiKey: string;
+    /** SDK configuration (apiBaseUrl, webHost, theme, isFullScreen, debugMode) */
+    config?: EncatchConfig;
+    /**
+     * Navigation library used for automatic screen tracking.
+     * - 'expo-router': uses useSegments/usePathname from expo-router
+     * - 'react-navigation': uses useNavigationState from @react-navigation/native
+     * - null: no automatic tracking (call Encatch.trackScreen manually)
+     * @default null
+     */
+    navigationType?: 'expo-router' | 'react-navigation' | null;
+    /** Screen names that should be skipped for tracking */
+    skippedRoutes?: string[];
+}
+declare const EncatchProvider: React.FC<EncatchProviderProps>;
+declare function useEncatch(): EncatchContextValue;
+
+/**
+ * EncatchWebView
+ *
+ * Drop-in component that renders the Encatch form inside a WebView overlay.
+ * Place once anywhere in your app's root layout — no props required.
+ *
+ * Responsibilities:
+ *  - Subscribes to the internal Encatch event emitter (showForm / dismissForm)
+ *  - Loads the remote react-native-sdk-form URL in a react-native-webview
+ *  - Bridges postMessages bidirectionally:
+ *      WebView → Native:  onMessage  (form:ready, form:submit, form:close, etc.)
+ *      Native → WebView:  injectJavaScript  (sdk:formConfig, sdk:theme, etc.)
+ *  - Animated entrance/exit (slide from position or scale from center)
+ *  - Responsive width: phone 100%, tablet 600px max, handles orientation changes
+ */
+
+declare const EncatchWebView: React.FC;
+
+/**
+ * Helpers for custom native forms (when using onBeforeShowForm interceptor).
+ * Use these to build SubmitFormRequest from your native form responses.
+ */
+
+interface NativeFormResponse {
+    questionId: string;
+    type: string;
+    value: string | number | string[];
+}
+interface BuildSubmitRequestOptions {
+    triggerType?: 'automatic' | 'manual';
+    formConfigurationId: string;
+    responseLanguageCode?: string;
+    completionTimeInSeconds?: number;
+    isPartialSubmit?: boolean;
+    feedbackIdentifier?: string;
+}
+/**
+ * Builds a SubmitFormRequest from native form responses.
+ * Use when you have a custom native form and need to submit to the Encatch API.
+ *
+ * @example
+ * ```ts
+ * const responses = [
+ *   { questionId: 'q1', type: 'rating', value: 5 },
+ *   { questionId: 'q2', type: 'short_answer', value: 'Great product!' },
+ * ];
+ * const req = buildSubmitRequest(
+ *   { formConfigurationId: formConfig.feedbackConfigurationId },
+ *   responses
+ * );
+ * Encatch.submitForm(req);
+ * ```
+ */
+declare function buildSubmitRequest(options: BuildSubmitRequestOptions, responses: NativeFormResponse[]): SubmitFormRequest;
+
+export { type ApiDeviceInfo, type BuildSubmitRequestOptions, Encatch, type EncatchConfig, type EncatchContextValue, EncatchProvider, type EncatchProviderProps, EncatchWebView, type EventCallback, type EventPayload, type EventType, type FormDetails, type IdentifyOptions, type NativeFormResponse, type QuestionAnswer, type QuestionResponse, type RefineTextRequest, type RefineTextResponse, type ResetMode, type SecureOptions, type ShowFormInterceptorPayload, type ShowFormOptions, type ShowFormResponse, type StartSessionOptions, type SubmitFormRequest, type Theme, type UserTraits, buildSubmitRequest, useEncatch };