@active-reach/web-sdk 1.12.0 → 1.14.0

package/dist/{analytics-6PR9ERDS.mjs → analytics-DGt-CSgi.mjs}

@@ -1764,6 +1764,24 @@ class EcommerceTracker {
       variant_id: wishlist.product.variant_id
     });
   }
+  // -- Back-in-stock waitlist --
+  //
+  // Server-side substrate: contact_events row keyed on
+  // (organization_id, contact_id, event_name='product_waitlisted',
+  //  event_properties['product_id']). Resolved by
+  // product_event_trigger_service._get_waitlisted_contacts and fanned out via
+  // catalog.back_in_stock journey trigger when stock_event_handler_worker
+  // detects the SKU flipping back into stock.
+  productWaitlisted(waitlist) {
+    this.aegis.track("product_waitlisted", {
+      product_id: waitlist.product.product_id,
+      sku: waitlist.product.sku ?? waitlist.product.product_id,
+      variant_id: waitlist.product.variant_id,
+      name: waitlist.product.name,
+      price: waitlist.product.price,
+      channels: waitlist.channels
+    });
+  }
   // -- Promotions --
   promotionViewed(promo) {
     this.aegis.track("promotion_viewed", { ...promo });
@@ -2215,6 +2233,134 @@ const _TraitGovernor = class _TraitGovernor {
 };
 _TraitGovernor.WARN_CAP = 3;
 let TraitGovernor = _TraitGovernor;
+const VALID_CHANNELS = /* @__PURE__ */ new Set([
+  "email",
+  "sms",
+  "push",
+  "webpush",
+  "whatsapp",
+  "rcs",
+  "inapp"
+]);
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const PHONE_RE = /^\+[1-9]\d{7,14}$/;
+const SHA256_HEX_RE = /^[a-f0-9]{64}$/i;
+const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+class UserNamespace {
+  constructor(aegis) {
+    this.pendingTraits = {};
+    this.aegis = aegis;
+  }
+  /**
+   * Authoritative identity write. Flushes any pending pre-login traits
+   * along with the supplied `traits` argument as a single identify call.
+   */
+  login(userId, traits) {
+    if (typeof userId !== "string" || userId.length === 0) {
+      logger.warn("[user.login] userId must be a non-empty string");
+      return;
+    }
+    const merged = { ...this.pendingTraits, ...traits || {} };
+    this.pendingTraits = {};
+    this.aegis.identify(userId, merged);
+  }
+  /**
+   * Drops the current userId and any pending pre-login traits. Does NOT
+   * fire a server-side logout event — that's a separate explicit `track`.
+   */
+  logout() {
+    this.pendingTraits = {};
+    this.aegis.reset();
+  }
+  setAttribute(key, value) {
+    if (typeof key !== "string" || key.length === 0) {
+      logger.warn("[user.setAttribute] key must be a non-empty string");
+      return;
+    }
+    this.writeTraits({ [key]: value });
+  }
+  setAttributes(map) {
+    if (!map || typeof map !== "object") {
+      logger.warn("[user.setAttributes] map must be an object");
+      return;
+    }
+    this.writeTraits(map);
+  }
+  setEmail(email) {
+    if (!EMAIL_RE.test(email)) {
+      logger.warn("[user.setEmail] invalid email format");
+      return;
+    }
+    this.writeTraits({ email: email.toLowerCase() });
+  }
+  setPhone(phone) {
+    if (!PHONE_RE.test(phone)) {
+      logger.warn("[user.setPhone] phone must be E.164 (e.g. +15551234567)");
+      return;
+    }
+    this.writeTraits({ phone });
+  }
+  setHashedEmail(sha256Hex) {
+    if (!SHA256_HEX_RE.test(sha256Hex)) {
+      logger.warn("[user.setHashedEmail] expected 64-char hex SHA-256");
+      return;
+    }
+    this.writeTraits({ email_sha256: sha256Hex.toLowerCase() });
+  }
+  setHashedPhone(sha256Hex) {
+    if (!SHA256_HEX_RE.test(sha256Hex)) {
+      logger.warn("[user.setHashedPhone] expected 64-char hex SHA-256");
+      return;
+    }
+    this.writeTraits({ phone_sha256: sha256Hex.toLowerCase() });
+  }
+  setBirthDate(iso) {
+    if (!ISO_DATE_RE.test(iso)) {
+      logger.warn("[user.setBirthDate] expected YYYY-MM-DD");
+      return;
+    }
+    this.writeTraits({ birth_date: iso });
+  }
+  setOptIn(channel, granted) {
+    if (!VALID_CHANNELS.has(channel)) {
+      logger.warn(`[user.setOptIn] unknown channel: ${channel}`);
+      return;
+    }
+    if (typeof granted !== "boolean") {
+      logger.warn("[user.setOptIn] granted must be a boolean");
+      return;
+    }
+    this.writeTraits({ [`opt_in_${channel}`]: granted });
+  }
+  /**
+   * HMAC-signed identity token. Ingress-side verification not yet wired —
+   * the trait is forwarded as-is and persisted on the contact record
+   * until that lands.
+   */
+  setSecureToken(token) {
+    if (typeof token !== "string" || token.length === 0) {
+      logger.warn("[user.setSecureToken] token must be a non-empty string");
+      return;
+    }
+    this.writeTraits({ _secure_token: token });
+  }
+  /**
+   * Test/inspection hook — returns a copy of the pending traits buffer.
+   * Used by the e2e smoke test to assert pre-login accumulation.
+   */
+  _getPendingTraits() {
+    return { ...this.pendingTraits };
+  }
+  // ---------------------------------------------------------------------------
+  writeTraits(traits) {
+    const userId = this.aegis.getUserId();
+    if (userId) {
+      this.aegis.identify(userId, traits);
+      return;
+    }
+    Object.assign(this.pendingTraits, traits);
+  }
+}
 class Aegis {
   constructor() {
     this.config = null;
@@ -2225,6 +2371,7 @@ class Aegis {
     this.initPromise = null;
     this.consent = null;
     this._ecommerce = null;
+    this._user = null;
     this.rateLimiter = null;
     this.nameGovernor = new NameGovernor();
     this.traitGovernor = new TraitGovernor();
@@ -2233,6 +2380,8 @@ class Aegis {
     this._originalPushState = null;
     this._originalReplaceState = null;
     this._lastEventIds = /* @__PURE__ */ new Map();
+    this._workspaceCodes = /* @__PURE__ */ new Set();
+    this._runtimeWorkspace = null;
   }
   async init(writeKey, config) {
     if (this.initPromise) {
@@ -2400,6 +2549,151 @@ class Aegis {
       });
     }
   }
+  /**
+   * Symmetric counterpart to `use(plugin)`. Calls the plugin's `destroy()`
+   * hook (if defined) and removes it from the registry so its hooks no
+   * longer fire on subsequent events. Safe to call with a name that
+   * isn't registered — logs a warning and returns.
+   *
+   * Primary use case: React components that register a plugin in
+   * `useEffect` and need to unregister in the cleanup function so HMR /
+   * provider remount doesn't leak listeners. See cashier-portal's
+   * MetaPixelInjector for an example.
+   */
+  removePlugin(name) {
+    this.plugins.unregister(name);
+  }
+  /**
+   * Plugin-handshake P1 — ingest the workspace_code allowlist from the
+   * bootstrap response. Pass `result.workspaceCodes` from `bootstrap()`
+   * here so the SDK can do path-segment workspace detection on
+   * customer-facing pages like `/south/rewards`, `/ghatkopar/feedback`.
+   *
+   * Empty array is the right answer for single-outlet tenants — SDK
+   * will skip the path cascade and fall through to query param /
+   * setWorkspace() / gateway origin lookup.
+   *
+   * Safe to call before init() — the set is consulted at event-fire time.
+   */
+  ingestWorkspaceCodes(codes) {
+    this._workspaceCodes = new Set(
+      (codes ?? []).filter((c) => typeof c === "string" && c.length > 0)
+    );
+    logger.debug("Workspace codes ingested", { count: this._workspaceCodes.size });
+  }
+  /**
+   * Plugin-handshake P1 (Track E) — explicitly set the workspace for
+   * subsequent events. Used by:
+   *   - SPAs where workspace context changes via in-app routing
+   *   - Mobile / RN apps that have no URL
+   *   - Custom integrations that resolve workspace from their own state
+   *
+   * Pass null to clear (or call clearWorkspace()).
+   *
+   * Persisted to sessionStorage so SPA reloads / page transitions on the
+   * same outlet inherit it without re-calling.
+   */
+  setWorkspace(codeOrId) {
+    this._runtimeWorkspace = codeOrId;
+    if (typeof window !== "undefined" && window.sessionStorage) {
+      try {
+        if (codeOrId) {
+          window.sessionStorage.setItem("aegis_runtime_ws", codeOrId);
+        } else {
+          window.sessionStorage.removeItem("aegis_runtime_ws");
+        }
+      } catch {
+      }
+    }
+    logger.debug("Runtime workspace set", { value: codeOrId });
+  }
+  /** Symmetric helper to clear the runtime workspace. */
+  clearWorkspace() {
+    this.setWorkspace(null);
+  }
+  /**
+   * Inspect the URL's first path segment and return it if it's in the
+   * org's workspace_code allowlist. Skips well-known non-workspace prefixes
+   * (e.g. `b` for bill short codes; `s` is the storefront app slug).
+   *
+   * Returns undefined when:
+   *   - window is undefined (SSR / Node)
+   *   - path is empty / root
+   *   - first segment isn't in `_workspaceCodes` (e.g. /products, /cart)
+   *
+   * The returned value is a workspace CODE (slug like "south"), not a
+   * UUID. The gateway normalizes code → UUID server-side via
+   * workspace_subaccounts lookup with Redis cache.
+   */
+  getPathWorkspaceCode() {
+    if (typeof window === "undefined") return void 0;
+    if (this._workspaceCodes.size === 0) return void 0;
+    try {
+      const segments = window.location.pathname.split("/").filter(Boolean);
+      if (segments.length === 0) return void 0;
+      const first = segments[0].toLowerCase();
+      return this._workspaceCodes.has(first) ? first : void 0;
+    } catch {
+      return void 0;
+    }
+  }
+  /**
+   * Resolve the effective `workspace_id` for the next event.
+   *
+   * Cascade (highest precedence first):
+   *   1. `this.config.workspace_id` — explicit operator config (headless
+   *      SDK usage, server-rendered apps, native shells).
+   *   2. `?ws=` query param on the current URL — the P3 storefront URL
+   *      contract. The outlet picker writes this via `router.replace`.
+   *   3. URL path segment (P1 Track A) — `/south/rewards` → "south" when
+   *      "south" is in the org's workspace_code allowlist.
+   *   4. `aegis.setWorkspace()` runtime override (P1 Track E) — SPAs +
+   *      mobile + custom integrations.
+   *   5. sessionStorage `aegis_runtime_ws` — persists setWorkspace across
+   *      reloads/SPA route changes.
+   *   6. `undefined` — gateway falls back to `resolveByOrigin` lookup
+   *      against the property's allowed_origins.
+   *
+   * The returned value can be EITHER a UUID (from config / ?ws=) or a
+   * workspace CODE slug (from path / setWorkspace). The gateway
+   * normalizes slug → UUID server-side; analytics layer never needs to
+   * worry about the difference.
+   *
+   * See docs/architecture/MULTI_OUTLET_URL_STRATEGY.md §2.3 and
+   * docs/architecture/PLUGIN_HANDSHAKE_AUTOMATION.md §2.
+   */
+  /**
+   * Public so peer SDK surfaces (AegisMessageRuntime / AegisInAppManager /
+   * AegisPlacementManager / AegisWidgetManager) can plumb the same
+   * resolved workspace into their own gateway POSTs. Each manager calls
+   * the gateway on its own endpoint (`/v1/in_app/events`,
+   * `/v1/placements/track`, `/v1/widgets/track-event`); without this,
+   * those events arrive at event-ingress with no workspace_id stamped
+   * → impressions/clicks fall back to the org's primary workspace and
+   * cross-outlet attribution breaks.
+   */
+  getEffectiveWorkspaceId() {
+    var _a;
+    const configured = (_a = this.config) == null ? void 0 : _a.workspace_id;
+    if (configured) return configured;
+    if (typeof window === "undefined") return void 0;
+    try {
+      const ws = new URLSearchParams(window.location.search).get("ws");
+      if (ws && ws.length > 0) return ws;
+    } catch {
+    }
+    const pathWs = this.getPathWorkspaceCode();
+    if (pathWs) return pathWs;
+    if (this._runtimeWorkspace) return this._runtimeWorkspace;
+    try {
+      if (window.sessionStorage) {
+        const cached = window.sessionStorage.getItem("aegis_runtime_ws");
+        if (cached && cached.length > 0) return cached;
+      }
+    } catch {
+    }
+    return void 0;
+  }
   track(eventName, properties) {
     if (!this.assertInitialized()) return;
     const messageId = generateMessageId();
@@ -2412,7 +2706,7 @@ class Aegis {
       anonymousId: this.identity.getAnonymousId(),
       userId: this.identity.getUserId() || void 0,
       sessionId: this.session.getSessionId(),
-      workspace_id: this.config.workspace_id || void 0,
+      workspace_id: this.getEffectiveWorkspaceId(),
       context: buildContext(this.config, this.session)
     };
     this._lastEventIds.set(eventName, messageId);
@@ -2420,7 +2714,7 @@ class Aegis {
   }
   identify(userId, traits) {
     if (!this.assertInitialized()) return;
-    const wsForGovernor = this.config.workspace_id || null;
+    const wsForGovernor = this.getEffectiveWorkspaceId() || null;
     const { sanitized: governedTraits } = this.traitGovernor.process(traits, wsForGovernor);
     this.identity.setUserId(userId, governedTraits);
     const event = {
@@ -2431,7 +2725,7 @@ class Aegis {
       anonymousId: this.identity.getAnonymousId(),
       userId,
       sessionId: this.session.getSessionId(),
-      workspace_id: this.config.workspace_id || void 0,
+      workspace_id: this.getEffectiveWorkspaceId(),
       context: buildContext(this.config, this.session)
     };
     this.captureEvent(event);
@@ -2447,14 +2741,14 @@ class Aegis {
       anonymousId: this.identity.getAnonymousId(),
       userId: this.identity.getUserId() || void 0,
       sessionId: this.session.getSessionId(),
-      workspace_id: this.config.workspace_id || void 0,
+      workspace_id: this.getEffectiveWorkspaceId(),
       context: buildContext(this.config, this.session)
     };
     this.captureEvent(event);
   }
   group(groupId, traits) {
     if (!this.assertInitialized()) return;
-    const wsForGovernor = this.config.workspace_id || null;
+    const wsForGovernor = this.getEffectiveWorkspaceId() || null;
     const { sanitized: governedTraits } = this.traitGovernor.process(traits, wsForGovernor);
     const event = {
       type: "group",
@@ -2484,6 +2778,31 @@ class Aegis {
     };
     this.captureEvent(event);
   }
+  /**
+   * SPA-logical screen view. Distinct from `page()` (URL-bound) — fires
+   * when the user enters a logical surface like cart / checkout / drawer
+   * without a URL change. Gateway maps `screen` → `engagement.screen_view`.
+   */
+  screen(name, properties) {
+    if (!this.assertInitialized()) return;
+    if (typeof name !== "string" || name.length === 0) {
+      logger.warn("aegis.screen: name must be a non-empty string");
+      return;
+    }
+    const event = {
+      type: "screen",
+      name,
+      properties: properties || {},
+      messageId: generateMessageId(),
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      anonymousId: this.identity.getAnonymousId(),
+      userId: this.identity.getUserId() || void 0,
+      sessionId: this.session.getSessionId(),
+      workspace_id: this.getEffectiveWorkspaceId(),
+      context: buildContext(this.config, this.session)
+    };
+    this.captureEvent(event);
+  }
   async captureEvent(event) {
     var _a;
     if (((_a = this.config) == null ? void 0 : _a.enable_consent_mode) && this.consent) {
@@ -2570,6 +2889,7 @@ class Aegis {
   reset() {
     if (!this.assertInitialized()) return;
     this.identity.reset();
+    this._user = null;
     logger.info("User identity reset");
   }
   /**
@@ -2754,6 +3074,12 @@ class Aegis {
     }
     return this._ecommerce;
   }
+  get user() {
+    if (!this._user) {
+      this._user = new UserNamespace(this);
+    }
+    return this._user;
+  }
   destroy() {
     this.stopSPATracking();
     if (this.queue) {
@@ -2780,7 +3106,8 @@ export {
   NameGovernor as N,
   RateLimiter as R,
   Storage as S,
+  UserNamespace as U,
   logger as l,
   murmurhash3_x86_32 as m
 };
-//# sourceMappingURL=analytics-6PR9ERDS.mjs.map
+//# sourceMappingURL=analytics-DGt-CSgi.mjs.map