@encatch/react-native-sdk 1.0.0-beta.1 → 1.0.0-beta.3

package/README.md

@@ -21,3 +21,4 @@ For the full API reference, configuration options, and usage examples, visit the
 ## License
 
 MIT
+ 

package/dist/index.d.mts

@@ -39,6 +39,8 @@ interface ShowFormInterceptorPayload {
     prefillResponses: Record<string, unknown>;
     locale?: string;
     theme?: Theme;
+    /** Serialized caller context (Dates already converted to ISO strings) */
+    context?: Record<string, string | number | boolean>;
 }
 interface StartSessionOptions {
     /** When true, do not call the immediate ping (30s ping interval still runs) */
@@ -75,12 +77,23 @@ type Theme = 'light' | 'dark' | 'system';
  * - 'never': Never clear form data (preserve user's previous answers)
  */
 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.
+ */
+type ContextValue = string | number | Date | boolean;
 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>;
 }
 type EventType = 'form:show' | 'form:started' | 'form:submit' | 'form:complete' | 'form:close' | 'form:dismissed' | 'form:error' | 'form:section:change' | 'form:answered';
 interface EventPayload {
@@ -112,8 +125,6 @@ interface ShowFormResponse {
     formConfiguration?: Record<string, unknown>;
     questionnaireFields?: any;
     otherConfigurationProperties?: any;
-    welcomeScreenProperties?: any;
-    endScreenProperties?: any;
     appearanceProperties?: any;
     partialResponseEnabled?: boolean;
     pingAgainIn?: number;
@@ -136,6 +147,7 @@ interface RefineTextResponse {
     pingOnNextPageVisit?: boolean;
     $feedbackTransactions?: string;
 }
+type QuestionType = 'rating' | 'single_choice' | 'nps' | 'nested_selection' | 'multiple_choice_multiple' | 'short_answer' | 'long_text' | 'annotation' | 'welcome' | 'thank_you' | 'message_panel' | 'yes_no' | 'rating_matrix' | 'matrix_single_choice' | 'matrix_multiple_choice' | 'exit_form';
 interface QuestionAnswer {
     nps?: number;
     rating?: number;
@@ -151,10 +163,14 @@ interface QuestionAnswer {
         fileData?: string;
         fileName?: string;
     };
+    yesNo?: boolean;
+    ratingMatrix?: Record<string, number | string>;
+    matrixSingleChoice?: Record<string, string>;
+    matrixMultipleChoice?: Record<string, string[]>;
 }
 interface QuestionResponse {
     questionId: string;
-    type?: string;
+    type?: QuestionType;
     answer?: QuestionAnswer;
 }
 interface FormDetails {
@@ -166,6 +182,10 @@ interface FormDetails {
         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 navigated to, in order. Used for drop-off analysis. */
+    visitedQuestionIds?: string[];
 }
 interface SubmitFormRequest {
     triggerType?: 'automatic' | 'manual';
@@ -233,6 +253,12 @@ declare class EncatchSDK {
     private _showFormById;
     dismissForm(formConfigurationId?: string): Promise<void>;
     private _pendingResponses;
+    /**
+     * Pre-fills a response before showing a form.
+     * @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;
     getPendingResponses(): Record<string, unknown>;
     clearPendingResponses(): void;
@@ -308,7 +334,7 @@ interface EncatchContextValue {
     showForm: (formId: string, options?: ShowFormOptions) => void;
     /** Call Encatch.dismissForm */
     dismissForm: (formConfigurationId?: string) => void;
-    /** Call Encatch.addToResponse */
+    /** Call Encatch.addToResponse. Accepts a question ID or slug. */
     addToResponse: (questionId: string, value: unknown) => void;
     /** Call Encatch.resetUser */
     resetUser: () => void;

package/dist/index.d.ts

@@ -39,6 +39,8 @@ interface ShowFormInterceptorPayload {
     prefillResponses: Record<string, unknown>;
     locale?: string;
     theme?: Theme;
+    /** Serialized caller context (Dates already converted to ISO strings) */
+    context?: Record<string, string | number | boolean>;
 }
 interface StartSessionOptions {
     /** When true, do not call the immediate ping (30s ping interval still runs) */
@@ -75,12 +77,23 @@ type Theme = 'light' | 'dark' | 'system';
  * - 'never': Never clear form data (preserve user's previous answers)
  */
 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.
+ */
+type ContextValue = string | number | Date | boolean;
 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>;
 }
 type EventType = 'form:show' | 'form:started' | 'form:submit' | 'form:complete' | 'form:close' | 'form:dismissed' | 'form:error' | 'form:section:change' | 'form:answered';
 interface EventPayload {
@@ -112,8 +125,6 @@ interface ShowFormResponse {
     formConfiguration?: Record<string, unknown>;
     questionnaireFields?: any;
     otherConfigurationProperties?: any;
-    welcomeScreenProperties?: any;
-    endScreenProperties?: any;
     appearanceProperties?: any;
     partialResponseEnabled?: boolean;
     pingAgainIn?: number;
@@ -136,6 +147,7 @@ interface RefineTextResponse {
     pingOnNextPageVisit?: boolean;
     $feedbackTransactions?: string;
 }
+type QuestionType = 'rating' | 'single_choice' | 'nps' | 'nested_selection' | 'multiple_choice_multiple' | 'short_answer' | 'long_text' | 'annotation' | 'welcome' | 'thank_you' | 'message_panel' | 'yes_no' | 'rating_matrix' | 'matrix_single_choice' | 'matrix_multiple_choice' | 'exit_form';
 interface QuestionAnswer {
     nps?: number;
     rating?: number;
@@ -151,10 +163,14 @@ interface QuestionAnswer {
         fileData?: string;
         fileName?: string;
     };
+    yesNo?: boolean;
+    ratingMatrix?: Record<string, number | string>;
+    matrixSingleChoice?: Record<string, string>;
+    matrixMultipleChoice?: Record<string, string[]>;
 }
 interface QuestionResponse {
     questionId: string;
-    type?: string;
+    type?: QuestionType;
     answer?: QuestionAnswer;
 }
 interface FormDetails {
@@ -166,6 +182,10 @@ interface FormDetails {
         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 navigated to, in order. Used for drop-off analysis. */
+    visitedQuestionIds?: string[];
 }
 interface SubmitFormRequest {
     triggerType?: 'automatic' | 'manual';
@@ -233,6 +253,12 @@ declare class EncatchSDK {
     private _showFormById;
     dismissForm(formConfigurationId?: string): Promise<void>;
     private _pendingResponses;
+    /**
+     * Pre-fills a response before showing a form.
+     * @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;
     getPendingResponses(): Record<string, unknown>;
     clearPendingResponses(): void;
@@ -308,7 +334,7 @@ interface EncatchContextValue {
     showForm: (formId: string, options?: ShowFormOptions) => void;
     /** Call Encatch.dismissForm */
     dismissForm: (formConfigurationId?: string) => void;
-    /** Call Encatch.addToResponse */
+    /** Call Encatch.addToResponse. Accepts a question ID or slug. */
     addToResponse: (questionId: string, value: unknown) => void;
     /** Call Encatch.resetUser */
     resetUser: () => void;

package/dist/index.js

@@ -553,7 +553,8 @@ var EncatchSDK = class {
     // ============================================================================
     // Form response helpers
     // ============================================================================
-    // Pre-filled responses stored by addToResponse, sent with sdk:prefillResponses
+    // Pre-filled responses stored by addToResponse, sent with sdk:prefillResponses.
+    // Keys may be question IDs or slugs; the form engine resolves slugs to IDs.
     this._pendingResponses = {};
   }
   // ============================================================================
@@ -787,6 +788,13 @@ var EncatchSDK = class {
     var _a, _b, _c, _d, _e, _f, _g;
     const resetMode = (_a = options == null ? void 0 : options.reset) != null ? _a : "always";
     const triggerType = (_b = options == null ? void 0 : options.triggerType) != null ? _b : "manual";
+    const serializedContext = (options == null ? void 0 : options.context) ? Object.entries(options.context).reduce(
+      (acc, [key, value]) => {
+        acc[key] = value instanceof Date ? value.toISOString() : value;
+        return acc;
+      },
+      {}
+    ) : void 0;
     const deviceInfo = await this._buildDeviceInfo();
     const req = {
       formSlugOrId: formId,
@@ -811,7 +819,8 @@ var EncatchSDK = class {
         triggerType,
         prefillResponses,
         locale: (_f = this._locale) != null ? _f : void 0,
-        theme: this._theme
+        theme: this._theme,
+        context: serializedContext
       };
       if (this._onBeforeShowForm) {
         const allow = await Promise.resolve(this._onBeforeShowForm(payload));
@@ -827,7 +836,8 @@ var EncatchSDK = class {
         triggerType,
         prefillResponses: Object.keys(prefillResponses).length > 0 ? prefillResponses : void 0,
         locale: (_g = this._locale) != null ? _g : void 0,
-        theme: this._theme
+        theme: this._theme,
+        context: serializedContext
       });
       this._isFormVisible = true;
     } catch (err) {
@@ -864,6 +874,12 @@ var EncatchSDK = class {
     }
     this.emitEvent("form:dismissed", { formId: formConfigurationId != null ? formConfigurationId : "" });
   }
+  /**
+   * Pre-fills a response before showing a form.
+   * @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, value) {
     this._pendingResponses[questionId] = value;
   }
@@ -1626,11 +1642,12 @@ var EncatchWebView = () => {
       switch (type) {
         case "form:ready": {
           if (!formPayload) return;
-          const { formConfig, resetMode, triggerType, prefillResponses, locale, theme } = formPayload;
+          const { formConfig, resetMode, triggerType, prefillResponses, locale, theme, context } = formPayload;
           injectSDKMessage({
             type: "sdk:formConfig",
             data: __spreadProps(__spreadValues({}, formConfig), {
-              triggerType
+              triggerType,
+              context
             })
           });
           if (resetMode === "always") {
@@ -1681,7 +1698,9 @@ var EncatchWebView = () => {
               feedbackIdentifier: data.feedbackIdentifier,
               responseLanguageCode: data.responseLanguageCode,
               response: data.response,
-              completionTimeInSeconds: data.completionTimeInSeconds
+              completionTimeInSeconds: data.completionTimeInSeconds,
+              context: data.context,
+              visitedQuestionIds: data.visitedQuestionIds
             },
             $feedbackTransactions: void 0
           };

package/dist/index.mjs

@@ -522,7 +522,8 @@ var EncatchSDK = class {
     // ============================================================================
     // Form response helpers
     // ============================================================================
-    // Pre-filled responses stored by addToResponse, sent with sdk:prefillResponses
+    // Pre-filled responses stored by addToResponse, sent with sdk:prefillResponses.
+    // Keys may be question IDs or slugs; the form engine resolves slugs to IDs.
     this._pendingResponses = {};
   }
   // ============================================================================
@@ -756,6 +757,13 @@ var EncatchSDK = class {
     var _a, _b, _c, _d, _e, _f, _g;
     const resetMode = (_a = options == null ? void 0 : options.reset) != null ? _a : "always";
     const triggerType = (_b = options == null ? void 0 : options.triggerType) != null ? _b : "manual";
+    const serializedContext = (options == null ? void 0 : options.context) ? Object.entries(options.context).reduce(
+      (acc, [key, value]) => {
+        acc[key] = value instanceof Date ? value.toISOString() : value;
+        return acc;
+      },
+      {}
+    ) : void 0;
     const deviceInfo = await this._buildDeviceInfo();
     const req = {
       formSlugOrId: formId,
@@ -780,7 +788,8 @@ var EncatchSDK = class {
         triggerType,
         prefillResponses,
         locale: (_f = this._locale) != null ? _f : void 0,
-        theme: this._theme
+        theme: this._theme,
+        context: serializedContext
       };
       if (this._onBeforeShowForm) {
         const allow = await Promise.resolve(this._onBeforeShowForm(payload));
@@ -796,7 +805,8 @@ var EncatchSDK = class {
         triggerType,
         prefillResponses: Object.keys(prefillResponses).length > 0 ? prefillResponses : void 0,
         locale: (_g = this._locale) != null ? _g : void 0,
-        theme: this._theme
+        theme: this._theme,
+        context: serializedContext
       });
       this._isFormVisible = true;
     } catch (err) {
@@ -833,6 +843,12 @@ var EncatchSDK = class {
     }
     this.emitEvent("form:dismissed", { formId: formConfigurationId != null ? formConfigurationId : "" });
   }
+  /**
+   * Pre-fills a response before showing a form.
+   * @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, value) {
     this._pendingResponses[questionId] = value;
   }
@@ -1615,11 +1631,12 @@ var EncatchWebView = () => {
       switch (type) {
         case "form:ready": {
           if (!formPayload) return;
-          const { formConfig, resetMode, triggerType, prefillResponses, locale, theme } = formPayload;
+          const { formConfig, resetMode, triggerType, prefillResponses, locale, theme, context } = formPayload;
           injectSDKMessage({
             type: "sdk:formConfig",
             data: __spreadProps(__spreadValues({}, formConfig), {
-              triggerType
+              triggerType,
+              context
             })
           });
           if (resetMode === "always") {
@@ -1670,7 +1687,9 @@ var EncatchWebView = () => {
               feedbackIdentifier: data.feedbackIdentifier,
               responseLanguageCode: data.responseLanguageCode,
               response: data.response,
-              completionTimeInSeconds: data.completionTimeInSeconds
+              completionTimeInSeconds: data.completionTimeInSeconds,
+              context: data.context,
+              visitedQuestionIds: data.visitedQuestionIds
             },
             $feedbackTransactions: void 0
           };

package/package.json

@@ -12,15 +12,10 @@
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.3",
   "files": [
     "dist"
   ],
-  "scripts": {
-    "build": "tsup",
-    "build:watch": "tsup --watch",
-    "clean": "rm -rf dist"
-  },
   "peerDependencies": {
     "react": ">=18.0.0",
     "react-native": ">=0.73.0",
@@ -67,5 +62,10 @@
     "react-native": "0.84.1",
     "typescript": "~5.9.3",
     "tsup": "^8.5.1"
+  },
+  "scripts": {
+    "build": "tsup",
+    "build:watch": "tsup --watch",
+    "clean": "rm -rf dist"
   }
-}
+}