@xapp/stentor-handler-contact-capture 1.80.3

package/lib/ContactCaptureHandler.d.ts

@@ -0,0 +1,34 @@
+import { ContactCaptureHandlerConfig } from "./models";
+/**
+ * ContactCaptureHandler manages lead collection from form submissions.
+ *
+ * When a FORM_SUBMIT action arrives from the chat widget, the result object
+ * contains all form field values as key-value pairs in `formSlots`. This handler:
+ *
+ *  1. Separates configured lead data fields (matched against `leadDataList`) from
+ *     tracking/extra fields (UTM params, TrustedForm cert URLs, etc.).
+ *  2. Calls `sendLead()` to forward the lead and extras to the configured CRM service.
+ */
+export declare class ContactCaptureHandler {
+    private config;
+    constructor(config?: ContactCaptureHandlerConfig);
+    /**
+     * Sends a lead to the configured CRM service.
+     *
+     * TrustedForm fields (`xxTrustedFormCertUrl`, `xxTrustedFormPingUrl`) are
+     * passed through in `extras` so downstream integrations (e.g., Boberdoo)
+     * can forward them to lead buyers. They do not appear in `ExternalLead.fields`
+     * because they are not configured in `leadDataList`.
+     *
+     * UTM params, click IDs, and `xxTrustedForm*` fields follow the same "extras"
+     * pattern used for attribution tracking.
+     *
+     * @param formSlots - All key-value pairs from the FORM_SUBMIT payload result
+     * @param requestAttributes - Top-level request attributes (may also carry UTM/TrustedForm data)
+     * @param transcript - Conversation transcript
+     */
+    sendLead(formSlots: Record<string, string>, requestAttributes?: Record<string, string>, transcript?: unknown[]): Promise<{
+        status: string;
+        message?: string;
+    }>;
+}

package/lib/ContactCaptureHandler.js

@@ -0,0 +1,101 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContactCaptureHandler = void 0;
+/*! Copyright (c) 2026, XAPP AI */
+const stentor_logger_1 = require("stentor-logger");
+/**
+ * Tracks known "extra" field names that flow through to downstream integrations
+ * as `extras` rather than as lead data fields.
+ */
+const EXTRA_FIELD_NAMES = new Set([
+    "utm_source",
+    "utm_campaign",
+    "utm_medium",
+    "utm_content",
+    "utm_term",
+    "gclid",
+    "fbclid",
+    "rwg_token",
+    "xxTrustedFormCertUrl",
+    "xxTrustedFormPingUrl"
+]);
+/**
+ * ContactCaptureHandler manages lead collection from form submissions.
+ *
+ * When a FORM_SUBMIT action arrives from the chat widget, the result object
+ * contains all form field values as key-value pairs in `formSlots`. This handler:
+ *
+ *  1. Separates configured lead data fields (matched against `leadDataList`) from
+ *     tracking/extra fields (UTM params, TrustedForm cert URLs, etc.).
+ *  2. Calls `sendLead()` to forward the lead and extras to the configured CRM service.
+ */
+class ContactCaptureHandler {
+    constructor(config = {}) {
+        this.config = config;
+    }
+    /**
+     * Sends a lead to the configured CRM service.
+     *
+     * TrustedForm fields (`xxTrustedFormCertUrl`, `xxTrustedFormPingUrl`) are
+     * passed through in `extras` so downstream integrations (e.g., Boberdoo)
+     * can forward them to lead buyers. They do not appear in `ExternalLead.fields`
+     * because they are not configured in `leadDataList`.
+     *
+     * UTM params, click IDs, and `xxTrustedForm*` fields follow the same "extras"
+     * pattern used for attribution tracking.
+     *
+     * @param formSlots - All key-value pairs from the FORM_SUBMIT payload result
+     * @param requestAttributes - Top-level request attributes (may also carry UTM/TrustedForm data)
+     * @param transcript - Conversation transcript
+     */
+    sendLead(formSlots_1) {
+        return __awaiter(this, arguments, void 0, function* (formSlots, requestAttributes = {}, transcript = []) {
+            const leadDataList = this.config.leadDataList || [];
+            const leadDataNames = new Set(leadDataList.map((s) => s.name));
+            const fields = [];
+            const extras = {};
+            // Iterate all form slot keys and route to either `fields` or `extras`
+            for (const [key, value] of Object.entries(formSlots)) {
+                if (!value)
+                    continue;
+                if (EXTRA_FIELD_NAMES.has(key)) {
+                    // Known extra field — pass through as an extra, not a lead field
+                    extras[key] = value;
+                }
+                else if (leadDataNames.has(key) || leadDataList.length === 0) {
+                    fields.push({ name: key, value });
+                }
+            }
+            // Also pick up TrustedForm and UTM data from top-level request attributes
+            // when they are not already present in formSlots (belt-and-suspenders)
+            for (const key of EXTRA_FIELD_NAMES) {
+                if (requestAttributes[key] && !extras[key]) {
+                    extras[key] = requestAttributes[key];
+                }
+            }
+            if (!this.config.crmService) {
+                (0, stentor_logger_1.log)().warn("ContactCaptureHandler: no CRM service configured, lead not sent");
+                return { status: "Failure", message: "No CRM service configured" };
+            }
+            try {
+                const result = yield this.config.crmService.send({ fields, transcript }, extras);
+                return result;
+            }
+            catch (err) {
+                (0, stentor_logger_1.log)().error(`ContactCaptureHandler sendLead() error: ${err instanceof Error ? err.message : String(err)}`);
+                return { status: "Failure", message: err instanceof Error ? err.message : String(err) };
+            }
+        });
+    }
+}
+exports.ContactCaptureHandler = ContactCaptureHandler;
+//# sourceMappingURL=ContactCaptureHandler.js.map

package/lib/ContactCaptureHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContactCaptureHandler.js","sourceRoot":"","sources":["../src/ContactCaptureHandler.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,kCAAkC;AAClC,mDAAqC;AAIrC;;;GAGG;AACH,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAC;IAC9B,YAAY;IACZ,cAAc;IACd,YAAY;IACZ,aAAa;IACb,UAAU;IACV,OAAO;IACP,QAAQ;IACR,WAAW;IACX,sBAAsB;IACtB,sBAAsB;CACzB,CAAC,CAAC;AAEH;;;;;;;;;GASG;AACH,MAAa,qBAAqB;IAG9B,YAAY,SAAsC,EAAE;QAChD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACzB,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACU,QAAQ;6DACjB,SAAiC,EACjC,oBAA4C,EAAE,EAC9C,aAAwB,EAAE;YAE1B,MAAM,YAAY,GAAG,IAAI,CAAC,MAAM,CAAC,YAAY,IAAI,EAAE,CAAC;YACpD,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;YAE/D,MAAM,MAAM,GAAe,EAAE,CAAC;YAC9B,MAAM,MAAM,GAAe,EAAE,CAAC;YAE9B,sEAAsE;YACtE,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;gBACnD,IAAI,CAAC,KAAK;oBAAE,SAAS;gBAErB,IAAI,iBAAiB,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;oBAC7B,iEAAiE;oBACjE,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;gBACxB,CAAC;qBAAM,IAAI,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;oBAC7D,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC;gBACtC,CAAC;YACL,CAAC;YAED,0EAA0E;YAC1E,uEAAuE;YACvE,KAAK,MAAM,GAAG,IAAI,iBAAiB,EAAE,CAAC;gBAClC,IAAI,iBAAiB,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;oBACzC,MAAM,CAAC,GAAG,CAAC,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC;gBACzC,CAAC;YACL,CAAC;YAED,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;gBAC1B,IAAA,oBAAG,GAAE,CAAC,IAAI,CAAC,iEAAiE,CAAC,CAAC;gBAC9E,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,2BAA2B,EAAE,CAAC;YACvE,CAAC;YAED,IAAI,CAAC;gBACD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,EAAE,MAAM,CAAC,CAAC;gBACjF,OAAO,MAAM,CAAC;YAClB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACX,IAAA,oBAAG,GAAE,CAAC,KAAK,CAAC,2CAA2C,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;gBAC3G,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;YAC5F,CAAC;QACL,CAAC;KAAA;CACJ;AAlED,sDAkEC"}

package/lib/index.d.ts

@@ -0,0 +1,3 @@
+/*! Copyright (c) 2026, XAPP AI */
+export { ContactCaptureHandler } from "./ContactCaptureHandler";
+export * from "./models";

package/lib/index.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContactCaptureHandler = void 0;
+/*! Copyright (c) 2026, XAPP AI */
+var ContactCaptureHandler_1 = require("./ContactCaptureHandler");
+Object.defineProperty(exports, "ContactCaptureHandler", { enumerable: true, get: function () { return ContactCaptureHandler_1.ContactCaptureHandler; } });
+__exportStar(require("./models"), exports);
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,kCAAkC;AAClC,iEAAgE;AAAvD,8HAAA,qBAAqB,OAAA;AAC9B,2CAAyB"}

package/lib/models.d.ts

@@ -0,0 +1,87 @@
+/*! Copyright (c) 2026, XAPP AI */
+/**
+ * A single form field from the FORM_SUBMIT payload.
+ */
+export interface FormSlot {
+    name: string;
+    value: string;
+}
+/**
+ * Extra data passed to the CRM service alongside the lead fields.
+ * Includes tracking params (UTM, click IDs) and TrustedForm cert URLs.
+ */
+export interface LeadExtras {
+    /**
+     * UTM source tracking parameter (e.g., "google", "facebook")
+     */
+    utm_source?: string;
+    /**
+     * UTM campaign tracking parameter
+     */
+    utm_campaign?: string;
+    /**
+     * UTM medium tracking parameter
+     */
+    utm_medium?: string;
+    /**
+     * UTM content tracking parameter
+     */
+    utm_content?: string;
+    /**
+     * UTM term tracking parameter
+     */
+    utm_term?: string;
+    /**
+     * Google click ID
+     */
+    gclid?: string;
+    /**
+     * Facebook click ID
+     */
+    fbclid?: string;
+    /**
+     * Reserve-with-Google token — indicates the lead originated from a Google Business Profile
+     */
+    rwg_token?: string;
+    /**
+     * TrustedForm certificate URL.
+     * Set when the form-widget has TrustedForm enabled.
+     * Lead buyers on Boberdoo (and other platforms) use this to claim the certificate.
+     */
+    xxTrustedFormCertUrl?: string;
+    /**
+     * TrustedForm ping URL used to extend certificate retention windows.
+     */
+    xxTrustedFormPingUrl?: string;
+    [key: string]: string | undefined;
+}
+/**
+ * Configuration for a contact capture lead data field.
+ */
+export interface LeadDataSlot {
+    /** The form slot name (e.g., "FIRST_NAME", "PHONE") */
+    name: string;
+    /** Human-readable label */
+    label?: string;
+    /** Whether this field is required before sending the lead */
+    required?: boolean;
+}
+export interface ContactCaptureHandlerConfig {
+    /**
+     * The list of lead data fields to collect from form slots.
+     * Only slots with matching names end up in the ExternalLead.fields array.
+     */
+    leadDataList?: LeadDataSlot[];
+    /**
+     * Optional CRM service to send leads to.
+     */
+    crmService?: {
+        send(lead: {
+            fields: FormSlot[];
+            transcript: unknown[];
+        }, extras?: LeadExtras): Promise<{
+            status: string;
+            message?: string;
+        }>;
+    };
+}

package/lib/models.js

@@ -0,0 +1,4 @@
+"use strict";
+/*! Copyright (c) 2026, XAPP AI */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=models.js.map

package/lib/models.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.js","sourceRoot":"","sources":["../src/models.ts"],"names":[],"mappings":";AAAA,kCAAkC"}

package/package.json

@@ -0,0 +1,37 @@
+{
+    "name": "@xapp/stentor-handler-contact-capture",
+    "license": "Apache-2.0",
+    "publishConfig": {
+        "access": "public"
+    },
+    "version": "1.80.3",
+    "description": "Contact capture handler that routes form submissions to CRM services",
+    "types": "lib/index",
+    "main": "lib/index",
+    "files": [
+        "lib"
+    ],
+    "engines": {
+        "node": "^20 || ^22 || ^24"
+    },
+    "devDependencies": {
+        "@types/chai": "5.2.3",
+        "@types/sinon": "4.3.3",
+        "@xapp/config": "0.3.0",
+        "chai": "4.5.0",
+        "mocha": "11.7.5",
+        "sinon": "21.0.0",
+        "stentor-logger": "1.72.3",
+        "ts-node": "10.9.2",
+        "typescript": "5.9.3"
+    },
+    "peerDependencies": {
+        "stentor-logger": "1.x"
+    },
+    "scripts": {
+        "build": "tsc -d true -p .",
+        "clean": "rm -rf ./lib/*",
+        "test": "mocha --recursive --timeout 9000 -r ts-node/register \"./src/**/__test__/*.test.ts\""
+    },
+    "gitHead": "06fa3fc79deca527eab7f75696fae30afa5e1587"
+}