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

package/README.md

@@ -87,11 +87,11 @@ 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 saves self-reported details on a new lead and adopts its signed session. Earlier events retain their original credentials and resolve to the lead through the browser link. When email verification is enabled, the SDK adopts a customer session after a successful challenge. Phone numbers remain unverified. Form values and verification codes stay on the identity endpoints. Popup lifecycle observations obey collection permission.
 
 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.
 

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,24 @@ 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 lead 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 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.");
+      const { session, ...acknowledgement } = result;
+      if (session != null) {
+        if (result.status !== "recorded" || prior?.customer_id !== null) throw new Error("Invalid popup lead 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 +267,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 +289,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 +326,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 +394,7 @@ function createSagepilotInstallationClient(options) {
 
 // package.json
 var name = "@sagepilot-ai/web-events-addon";
-var version = "0.2.4";
+var version = "0.2.5";
 
 // 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 +2396,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 +2693,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 +2717,7 @@ function createSagepilotWebEvents(options) {
     detach(true);
     client.cancelPending();
     try {
-      await operation();
+      return await operation();
     } finally {
       identityChanging = false;
       if (!destroyed) {
@@ -2916,17 +2946,21 @@ function createSagepilotWebEvents(options) {
       }
     },
     flush,
-    /** Submits contact-only data through the explicit identity endpoint, never through autocapture. */
+    /** Keeps contact data on the identity endpoint and fences capture while a new lead session is adopted. */
     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") {
+        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));
+      emitPopup("popup_submitted");
       await completeVisitor(anonymousId);
     },
     /** Applies an explicit logout boundary without relabeling earlier observations. */