@sagepilot-ai/web-events-addon 0.2.4 → 0.2.6

package/README.md

@@ -87,13 +87,15 @@ In Settings → SDK, select a web installation, turn on **First-party visitor co
 
 Records retain event ID, occurrence time, workspace/registered installation, original signed session owner and local identity epoch. A separate credential cache retains at most four owner generations across verification/reload so anonymous backlog stays anonymous. Records whose authority is unavailable or explicitly revoked are dropped with diagnostics; they never block newer owners or get relabeled.
 
-## Popup and verified identity
+## Popup and visitor identity
 
 Settings → SDK publishes a text-only popup template independently from mapping versions. The installed runtime renders the published revision inside a shadow DOM, with exact page paths, delay/scroll conditions, frequency limits, required fields and keyboard dismissal/focus management. Submitting the form sets the existing contact endpoint's `marketing_consent` field to `true`. The renderer and dashboard preview have no consent checkbox or label. Drafts never render. Disabled publication removes an open popup after refresh. Native app registrations do not render website popups.
 
-Email verification happens through the explicit contact endpoint. Contact-only forms save self-reported details and keep anonymous authority. Only a completed server challenge creates an identified session; phone numbers remain unverified. Form values and verification codes never enter ordinary observations. Shown/submitted/dismissed lifecycle observations obey collection permission.
+A contact-only form requires a phone number and can collect an optional email. Platform API resolves a compatible phone match first, then tries a unique email match. It creates a customer when neither matches and saves the form contact as unverified. Earlier events retain their original capture owner and resolve through the browser link. When email verification is enabled, the email field is required and the link is made after the code succeeds.
 
-The popup handles submission/verification itself. Host-owned forms can use `submitContact({submission_id,popup_revision,name?,email?,phone?,marketing_consent})` and `verifyContact(challengeId,code)`. `logout()` immediately pauses capture and cancels pending uploads before revoking the API grant and establishing a fresh anonymous owner. Queued events retain their original ownership. The collector discards any records whose credentials the logout revoked. Existing signed ingress credentials expire within 15 minutes.
+With a compatible Platform API, a successful form submission sends one `popup_submitted` event through Event Handler even when storefront analytics is off. Popup impressions, dismissals and automatic events still follow collection permission. Form values and codes stay off browser observations. FJE adds the selected customer's contact details and verification flags to attributed event history.
+
+The popup handles submission/verification itself. Host-owned forms can use `submitContact({submission_id,popup_revision,phone,name?,email?,marketing_consent})` and `verifyContact(challengeId,code)`. `logout()` immediately pauses capture and cancels pending uploads before revoking the API grant and establishing a fresh anonymous owner. Queued events retain their original ownership. The collector discards any records whose credentials the logout revoked. Existing signed ingress credentials expire within 15 minutes.
 
 - At most 128 pending route/click/network emissions per collector, and 128 capture writes / 512 KiB of serialized handoff evidence.
 - The journal holds up to 8,192 records or 8 MiB, whichever comes first. It evicts oldest records at capacity. The 24-hour local expiry fits the server's existing offline renewal window.

package/dist/index.cjs

@@ -142,27 +142,40 @@ var SagepilotInstallationClient = class {
     this.startup = startup;
     return startup;
   }
-  /** Renews the owner or, when allowed for web capture, starts fresh after an expired browser session. */
+  /** Renews capture, using separate browser proof to recover a linked web visitor after expiry. */
   async refresh(recoverAnonymous = false) {
     if (this.pending) return this.pending;
     if (!this.anonymousId) throw new Error("Start the installation client before renewing it.");
     const generation = this.generation, prior = this.current;
     const pending = (async () => {
       let renewing = prior;
+      let resumed = false;
       let value;
       try {
         value = await this.requestSession(prior?.session_token);
       } catch (error) {
         if (!recoverAnonymous || !prior || this.options.platform !== "web" || generation !== this.generation || !(error instanceof SagepilotInstallationError) || error.status !== 401) throw error;
         renewing = null;
-        value = await this.requestSession();
+        if (prior.browser_resume_token) {
+          try {
+            value = await this.requestSession(prior.browser_resume_token, true);
+            resumed = true;
+          } catch (resumeError) {
+            if (generation !== this.generation || !(resumeError instanceof SagepilotInstallationError) || ![401, 403, 422].includes(resumeError.status ?? 0)) throw resumeError;
+          }
+        }
+        if (!resumed) value = await this.requestSession();
       }
       const next = this.validateSession(value);
       if (generation !== this.generation) throw new Error("SDK session startup was cancelled.");
-      if (renewing && (next.session_id !== renewing.session_id || next.customer_id !== renewing.customer_id) || !renewing && (next.customer_id !== null || next.session_id === prior?.session_id)) {
+      if (renewing && (next.session_id !== renewing.session_id || next.customer_id !== renewing.customer_id) || !renewing && (next.customer_id !== null || !resumed && next.session_id === prior?.session_id)) {
         throw new Error("SDK session renewal changed capture ownership.");
       }
-      if (prior && !renewing) this.owners.delete(prior.session_id);
+      if (resumed && next.browser_resume_token !== prior?.browser_resume_token) {
+        throw new Error("SDK browser recovery returned invalid proof.");
+      }
+      if (renewing && !next.browser_resume_token) next.browser_resume_token = renewing.browser_resume_token;
+      if (prior && next.session_id !== prior.session_id) this.owners.delete(prior.session_id);
       this.current = next;
       this.remember(next);
       try {
@@ -176,8 +189,8 @@ var SagepilotInstallationClient = class {
     this.pending = pending;
     return pending;
   }
-  /** Requests policy for this browser or device with the original token when renewing. */
-  requestSession(token) {
+  /** Sends only the capture token for renewal or the distinct credential for browser recovery. */
+  requestSession(token, resumeBrowser = false) {
     return this.request(`${this.apiHost}/platform-api/v1/sdk/sessions`, {
       method: "POST",
       headers: token ? { Authorization: `Bearer ${token}` } : {},
@@ -185,7 +198,8 @@ var SagepilotInstallationClient = class {
         key: `${this.workspaceId}:${this.installationId}`,
         anonymous_id: this.anonymousId,
         platform: this.options.platform,
-        ...this.options.appId ? { app_id: this.options.appId } : {}
+        ...this.options.appId ? { app_id: this.options.appId } : {},
+        ...resumeBrowser ? { resume_browser: true } : {}
       })
     });
   }
@@ -223,12 +237,25 @@ var SagepilotInstallationClient = class {
     if (new TextEncoder().encode(body).byteLength > 128 * 1024) throw new Error("SDK batch exceeds the upload limit.");
     return validateSagepilotInstallationReceipt(await this.request(auth.url, { method: "POST", headers: auth.headers, body }), observations.map((item) => item.event_id));
   }
-  /** Submits explicit popup contacts independently from ordinary observation payloads. */
+  /** Submits contact and adopts only a scoped customer session returned by the server. */
   async submitContact(input) {
     if (!UUID.test(input.submission_id) || !Number.isSafeInteger(input.popup_revision) || input.popup_revision < 1 || typeof input.marketing_consent !== "boolean") throw new Error("Invalid popup submission.");
-    const result = await this.authenticated("/contact", input);
-    if (!result || !["recorded", "verification_required"].includes(result.status) || result.status === "verification_required" && (!result.challenge_id || !UUID.test(result.challenge_id) || !Number.isFinite(Date.parse(result.expires_at ?? "")))) throw new Error("Invalid popup submission response.");
-    return result;
+    if (this.transitioning) throw new Error("An SDK identity operation is already running.");
+    this.transitioning = true;
+    const generation = this.generation, prior = this.current;
+    try {
+      const body = prior?.popup_submission_events === true ? { ...input, server_submission_event: true } : input;
+      const result = await this.authenticated("/contact", body);
+      if (!result || !["recorded", "verification_required"].includes(result.status) || result.status === "verification_required" && (!result.challenge_id || !UUID.test(result.challenge_id) || !Number.isFinite(Date.parse(result.expires_at ?? "")))) throw new Error("Invalid popup submission response.");
+      const { session, ...acknowledgement } = result;
+      if (session != null) {
+        if (result.status !== "recorded" || prior?.customer_id !== null) throw new Error("Invalid popup customer session.");
+        await this.adoptTransition(session, prior, generation, true);
+      }
+      return acknowledgement;
+    } finally {
+      this.transitioning = false;
+    }
   }
   /** Adopts customer authority only from the server's completed verification operation. */
   async verifyContact(challengeId, code) {
@@ -241,7 +268,7 @@ var SagepilotInstallationClient = class {
   }
   /** Keeps a bounded credential cache separate from observations so old anonymous batches retain their owner. */
   remember(session) {
-    this.owners.set(session.session_id, { ...session });
+    this.owners.set(session.session_id, { ...session, browser_resume_token: void 0 });
     while (this.owners.size > 4) this.owners.delete(this.owners.keys().next().value);
     try {
       void Promise.resolve(this.options.storage?.setItem(this.storageKey + ":owners", JSON.stringify([...this.owners.values()]))).catch(() => {
@@ -263,24 +290,28 @@ var SagepilotInstallationClient = class {
     this.transitioning = true;
     const generation = this.generation, prior = this.current;
     try {
-      const next = this.validateSession(await this.authenticated(path, body));
-      if (generation !== this.generation || !prior || next.session_id === prior.session_id || (identified ? next.customer_id === null : next.customer_id !== null)) throw new Error("Invalid SDK identity transition.");
-      this.generation++;
-      this.cancelPending();
-      this.pending = null;
-      if (path === "/logout") this.owners.delete(prior.session_id);
-      else this.remember(prior);
-      this.current = next;
-      this.remember(next);
-      try {
-        await this.options.storage?.setItem(this.storageKey, JSON.stringify(next));
-      } catch {
-      }
-      return { ...next };
+      return await this.adoptTransition(await this.authenticated(path, body), prior, generation, identified);
     } finally {
       this.transitioning = false;
     }
   }
+  /** Installs one new server owner and retains earlier credentials unless the owner logged out. */
+  async adoptTransition(value, prior, generation, identified) {
+    const next = this.validateSession(value);
+    if (generation !== this.generation || !prior || next.session_id === prior.session_id || (identified ? next.customer_id === null : next.customer_id !== null)) throw new Error("Invalid SDK identity transition.");
+    this.generation++;
+    this.cancelPending();
+    this.pending = null;
+    if (identified) this.remember(prior);
+    else this.owners.delete(prior.session_id);
+    this.current = next;
+    this.remember(next);
+    try {
+      await this.options.storage?.setItem(this.storageKey, JSON.stringify(next));
+    } catch {
+    }
+    return { ...next };
+  }
   /** Cancels requests on permission/ownership boundaries while preserving the current session for safe renewal. */
   cancelPending() {
     this.uploadRevision++;
@@ -296,10 +327,10 @@ var SagepilotInstallationClient = class {
     this.startup = null;
     this.owners.clear();
   }
-  /** Rejects foreign, identified or malformed session responses before credentials are used. */
+  /** Rejects foreign or malformed session responses before credentials are used. */
   validateSession(value) {
     const session = value;
-    if (!session || session.workspace_id !== this.workspaceId || session.installation_id !== this.installationId || session.platform !== this.options.platform || session.anonymous_id !== this.anonymousId || session.customer_id !== null && (typeof session.customer_id !== "string" || !UUID.test(session.customer_id)) || !UUID.test(session.session_id) || typeof session.session_token !== "string" || session.session_token.length > 16384 || !session.session_token || !Number.isFinite(Date.parse(session.expires_at)) || typeof session.collection_enabled !== "boolean" || session.visitor_cookie_enabled !== void 0 && typeof session.visitor_cookie_enabled !== "boolean" || !Number.isSafeInteger(session.revision)) {
+    if (!session || session.workspace_id !== this.workspaceId || session.installation_id !== this.installationId || session.platform !== this.options.platform || session.anonymous_id !== this.anonymousId || session.customer_id !== null && (typeof session.customer_id !== "string" || !UUID.test(session.customer_id)) || !UUID.test(session.session_id) || typeof session.session_token !== "string" || session.session_token.length > 16384 || !session.session_token || session.browser_resume_token != null && (session.platform !== "web" || typeof session.browser_resume_token !== "string" || !session.browser_resume_token || session.browser_resume_token.length > 8192) || !Number.isFinite(Date.parse(session.expires_at)) || typeof session.collection_enabled !== "boolean" || session.visitor_cookie_enabled !== void 0 && typeof session.visitor_cookie_enabled !== "boolean" || !Number.isSafeInteger(session.revision)) {
       throw new Error("SDK session response has invalid scope or ownership.");
     }
     const url = safeURL(session.ingestion_url);
@@ -364,7 +395,7 @@ function createSagepilotInstallationClient(options) {
 
 // package.json
 var name = "@sagepilot-ai/web-events-addon";
-var version = "0.2.4";
+var version = "0.2.6";
 
 // src/projection.ts
 var sensitive = /password|passwd|secret|token|authorization|cookie|session|email|phone|contact|address|card|payment|cvv|ssn|dob|birth|customer|user|account|person|profile|name|description|message|content|text|search|query/i;
@@ -2366,7 +2397,6 @@ function createPopup(options) {
           }
           const result = await options.submit(contact);
           if (revision !== generation) return;
-          options.emit("popup_submitted");
           for (const input of inputs.values()) input.value = "";
           if (result.status === "verification_required") {
             let restartForm2 = function() {
@@ -2664,13 +2694,14 @@ function createSagepilotWebEvents(options) {
       captureBytes -= bytes;
     });
   };
+  function emitPopup(action) {
+    if (enabled()) capture("lifecycle", { action }, epoch, Date.now());
+  }
   const popup = createPopup({
     client,
     storage,
     report,
-    emit(action) {
-      if (enabled()) capture("lifecycle", { action }, epoch, Date.now());
-    },
+    emit: emitPopup,
     submit(input) {
       return addon.submitContact(input);
     },
@@ -2687,7 +2718,7 @@ function createSagepilotWebEvents(options) {
     detach(true);
     client.cancelPending();
     try {
-      await operation();
+      return await operation();
     } finally {
       identityChanging = false;
       if (!destroyed) {
@@ -2916,17 +2947,21 @@ function createSagepilotWebEvents(options) {
       }
     },
     flush,
-    /** Submits contact-only data through the explicit identity endpoint, never through autocapture. */
+    /** Keeps contact on the identity endpoint and fences capture while adopting the customer. */
     async submitContact(input) {
-      const anonymousId = client.session()?.anonymous_id;
-      const result = await client.submitContact(input);
-      if (result.status === "recorded") await completeVisitor(anonymousId);
+      const session = client.session();
+      const result = session?.popup?.verification === "none" && session.customer_id === null ? await changeIdentity(() => client.submitContact(input)) : await client.submitContact(input);
+      if (result.status === "recorded") {
+        if (result.popup_submission_recorded !== true) emitPopup("popup_submitted");
+        await completeVisitor(session?.anonymous_id);
+      }
       return result;
     },
     /** Verifies proof behind a capture fence; buffered anonymous observations remain anonymous. */
     async verifyContact(challengeId, code) {
       const anonymousId = client.session()?.anonymous_id;
-      await changeIdentity(() => client.verifyContact(challengeId, code));
+      const session = await changeIdentity(() => client.verifyContact(challengeId, code));
+      if (session.popup_submission_recorded !== true) emitPopup("popup_submitted");
       await completeVisitor(anonymousId);
     },
     /** Applies an explicit logout boundary without relabeling earlier observations. */