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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Phyder Mobile Solutions Pvt. Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,204 @@
+# Ensight React Native SDK Documentation
+
+## Overview
+
+Ensight SDK provides a seamless way to integrate user feedback collection into your React Native applications. This SDK allows you to display customized feedback forms, collect user responses, and submit them to the Ensight backend.
+
+## Installation
+
+```bash
+# Using npm
+npm install ensight-react-native
+
+# Using yarn
+yarn add ensight-react-native
+```
+
+## Quick Start
+
+```javascript
+import Ensight, { EnsightConfig, EnsightTheme } from "ensight-react-native";
+
+// Initialize the SDK
+const config = new EnsightConfig({
+  host: "https://app.dev.en-gage.in",
+  themeMode: "light",
+  language: "en",
+});
+
+Ensight.instance.ensightApp.initialize({
+  apiKey: "YOUR_API_KEY_HERE",
+  config: config,
+});
+
+// Open feedback form
+Ensight.instance.ensightApp.openFeedback();
+```
+
+## Core Features
+
+- In-app feedback collection
+- Customizable feedback forms
+- Theme support (light/dark)
+- Multilingual support
+- User identification
+- Session management
+- Event analytics
+
+## SDK Initialization
+
+Initialize the SDK early in your application lifecycle:
+
+```javascript
+const userInfo = {
+  user_name: "user@example.com",
+  properties: {
+    email: "user@example.com",
+    user_age: 30,
+  },
+};
+
+const config = new EnsightConfig({
+  host: "https://app.dev.en-gage.in",
+  identity: userInfo,
+  processAfterIdentitySet: false,
+  isAutoCaptureEnabled: true,
+  themeMode: "light",
+  language: "en",
+});
+
+Ensight.instance.ensightApp.initialize({
+  apiKey: "YOUR_API_KEY_HERE",
+  config: config,
+});
+```
+
+## Displaying Feedback Forms
+
+### Open Default Feedback
+
+```javascript
+await Ensight.instance.ensightApp.openFeedback();
+```
+
+### Open Feedback by ID
+
+```javascript
+await Ensight.instance.ensightApp.openFeedbackById("FEEDBACK_CONFIGURATION_ID");
+```
+
+### Open Feedback by Name
+
+```javascript
+await Ensight.instance.ensightApp.openFeedbackByName("Feedback Form Title");
+```
+
+## User Identification
+
+Identify users to personalize feedback forms:
+
+```javascript
+Ensight.instance.ensightApp.identify("user@example.com", {
+  email: "user@example.com",
+  user_age: 30,
+});
+```
+
+## Session Management
+
+Control and manage user sessions:
+
+```javascript
+// Stop the current session and generate a new session ID
+await Ensight.instance.ensightApp.stopSession();
+
+// Reset the session, clear user data, and reinitialize
+await Ensight.instance.ensightApp.resetSession();
+```
+
+## Theming
+
+Customize the appearance of feedback forms:
+
+```javascript
+// Set theme to dark mode
+Ensight.instance.ensightApp.setTheme(EnsightTheme.dark);
+
+// Set theme to light mode
+Ensight.instance.ensightApp.setTheme(EnsightTheme.light);
+```
+
+## Language Support
+
+Change the language for feedback forms:
+
+```javascript
+// Set language to English
+Ensight.instance.ensightApp.setLanguage("en");
+
+// Set language to Spanish
+Ensight.instance.ensightApp.setLanguage("es");
+```
+
+## Event Tracking
+
+Track user events for analytics:
+
+```javascript
+const eventInfo = {
+  event_name: "button_click",
+  properties: {
+    button_id: "submit_form",
+    page: "checkout",
+  },
+};
+
+Ensight.instance.ensightApp.queueEvent(eventInfo);
+```
+
+## Path Observation
+
+Track user navigation within your app:
+
+```javascript
+// Set the current path
+Ensight.instance.ensightApp.setCurrentPath("/home/products");
+
+// Add path change observer
+const pathObserver = Ensight.instance.ensightApp.pathObserver;
+pathObserver.addObserver((oldPath, newPath) => {
+  console.log(`Navigation changed from ${oldPath} to ${newPath}`);
+});
+```
+
+## Troubleshooting
+
+If you encounter issues with the SDK:
+
+1. Check initialization parameters
+2. Verify API key and host URL
+3. Ensure network connectivity
+4. Check console logs for error messages
+
+## API Reference
+
+| Method/Property         | Description                             | Parameters                                                     | Return          |
+| ----------------------- | --------------------------------------- | -------------------------------------------------------------- | --------------- |
+| `initialize`            | Initializes the SDK                     | `apiKey: string, config?: EnsightConfig`                       | `void`          |
+| `openFeedback`          | Opens the default feedback form         | None                                                           | `Promise<void>` |
+| `openFeedbackById`      | Opens a feedback form by ID             | `id: string`                                                   | `Promise<void>` |
+| `openFeedbackByName`    | Opens a feedback form by name           | `name: string`                                                 | `Promise<void>` |
+| `identify`              | Identifies a user                       | `userId: string, traits?: Record<string, any>`                 | `void`          |
+| `submitFeedback`        | Submits feedback data                   | `feedback?: Record<string, any>`                               | `Promise<void>` |
+| `stopSession`           | Stops the current session               | None                                                           | `Promise<void>` |
+| `resetSession`          | Resets the session and clears user data | None                                                           | `Promise<void>` |
+| `setTheme`              | Sets the theme                          | `theme: EnsightTheme`                                          | `void`          |
+| `setLanguage`           | Sets the language                       | `language: string`                                             | `void`          |
+| `queueEvent`            | Adds an event to the analytics queue    | `event: EventInfo`                                             | `void`          |
+| `setCurrentPath`        | Sets the current path for analytics     | `path: string`                                                 | `void`          |
+| `addPopupStateListener` | Adds a listener for popup state changes | `listener: (isVisible: boolean, props?: PopupUIProps) => void` | `() => void`    |
+| `pathObserver`          | Gets the path observer instance         | None                                                           | `PathObserver`  |
+
+## Support
+
+For additional support, please contact support@ensight.com or visit our documentation at https://docs.ensight.com

package/dist/index.d.mts

@@ -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 };