@cross-deck/web 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 All notable changes to `@cross-deck/web` will be documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.0] — 2026-05-10
+
+Bank-grade analytics enrichment. Two additive changes that close the gap between Crossdeck's analytics surface and Google Analytics 4 / Google Ads dashboards: identity continuity that survives cleared storage, and first-touch acquisition attribution attached to every event of a session. No public API changes — `Crossdeck.init({...})` callsites do not need to change.
+
+### Added
+
+- **Identity continuity — dual-store redundancy.** The SDK now writes `anonymousId` and `crossdeckCustomerId` to BOTH `localStorage` (primary) and a 1st-party `document.cookie` (secondary). On boot it reads both and prefers primary; if primary is empty, it recovers from the cookie and resyncs primary. This protects against ITP localStorage purges, "clear site data" actions, and aggressive privacy extensions — a returning user keeps the same Crossdeck identity instead of becoming a phantom new visitor on dashboards. See `sdks/SDK_TRUTH.md` § "Identity continuity — bank-grade redundancy" for the full contract.
+- **`CookieStorage` adapter** in `storage.ts`. Sets `Path=/`, `Max-Age=63072000` (2y), `SameSite=Lax`, `Secure` (when over HTTPS — omitted on `http://localhost` so dev works without a TLS cert). Encodes/decodes cookie names + values defensively so embedded `;` and `=` survive round-trip.
+- **First-touch acquisition capture in `AutoTracker`.** On every `session.started` the SDK reads `window.location.search` and `document.referrer` and captures `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`, plus `referrer`. Non-empty values are auto-attached to every subsequent event of that session — matching GA4's session-pinned attribution semantics. SPA route changes mid-session do NOT re-read the URL; a new session (>30 min idle, or explicit `resetSession()`) re-captures off the current URL.
+- **`AutoTracker.currentAcquisition`** getter. Returns the captured-once-per-session acquisition context for inspection / tests / framework bindings. Returns empty strings (not undefined) when there's no active session so callers can spread without conditional logic.
+- **`captureAcquisition()` exported** from `auto-track.ts` for unit testing acquisition extraction in isolation.
+- **18 new tests** (138 total, up from 120):
+    - `storage.test.ts` — 6 cases covering `CookieStorage` round-trip, URL-encoding survival, attribute emission (Path / SameSite / Max-Age / Secure on HTTPS, Secure-omitted on HTTP), null on broken cookies, no-op in Node (no `document`).
+    - `identity.test.ts` — 6 cases covering the redundancy contract: writes-to-both, recovery from secondary when primary cleared, recovery from primary when secondary cleared, primary-wins-on-conflict, set/reset both, defence-in-depth against a throwing secondary.
+    - `auto-track.test.ts` — 5 cases: `captureAcquisition` reads utm_*, returns empty for clean URLs, `currentAcquisition` is session-pinned (SPA navigation does NOT change it mid-session), `resetSession` re-captures off the current URL, returns empty when no session exists.
+
+### Server-side enrichment (lands without an SDK upgrade)
+
+The 0.6.0 SDK pairs with these backend changes that started populating ClickHouse columns ahead of this release — every existing 0.5.0 install starts seeing them in dashboards immediately:
+
+- **Geography** — `events.country` populated from the Cloudflare `CF-IPCountry` header at `/v1/events`. Server-decided, not client-trusted.
+- **New vs returning** — `events.is_new` populated by a Firestore-transactional `visitors/{anonymousId}` upsert in the ClickHouse projector. First event for a new anonymousId wins the race; concurrent inserts converge.
+- **Device hoist** — `events.browser`, `events.os`, `events.device_class` hoisted out of `properties_json` to first-class LowCardinality columns for fast slicing.
+- **Acquisition columns** — `events.utm_source`, `events.utm_medium`, `events.utm_campaign`, `events.utm_content`, `events.utm_term`, `events.referrer_host` populated from event properties (which the 0.6.0 SDK now sends; pre-0.6.0 events get empty strings).
+- **Sessions** — `sessions` table aggregates the same enrichment columns via `any` / `max` (for `is_new`) so per-session breakdowns don't have to fan out across raw events.
+- ClickHouse migration `006_analytics_columns.sql` is idempotent and additive — old rows already in `events` keep working with empty / 0 defaults.
+
+### Privacy posture
+
+Privacy posture is unchanged from single-store identity. The cookie holds only the same `anonymousId` already in `localStorage` — no fingerprintable data, no PII. Anything that can read `localStorage` on the same origin can read this cookie; the security model is identical to Stripe, Segment, and PostHog's 1st-party identity cookies. `persistIdentity: false` continues to disable all persistence (in-memory only) for customers running strict consent flows.
+
+### Compatibility
+
+Source-compatible with 0.5.0. No public API changes. No deprecated symbols. Existing snippets do not need to change.
+
 ## [0.4.0] — 2026-05-09
 
 Reactive entitlements. Pre-0.4.0, calling `Crossdeck.isEntitled("pro")` directly inside a React render path showed the empty-cache result forever — React had no way to know the cache had populated asynchronously after `init()`. This release closes that gap with a first-class subscribe API on the SDK and a React subpackage that uses it.

package/README.md

@@ -92,6 +92,8 @@ That's the full happy path.
 
 Every event — auto-tracked and developer-emitted — is enriched with the device-info payload below. Quick tab switches (Cmd-Tab, switching browser tabs) don't end the session — only real closes do, matching GA4's session-window convention.
 
+**Per-session acquisition (v0.6.0+):** when a session starts the SDK reads `window.location.search` and `document.referrer` and captures `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`, plus `referrer`. Non-empty values are auto-attached to every subsequent event of that session — first-touch attribution stays pinned to the entry URL even after SPA route changes strip the params away. A new session (>30 min idle) re-reads the URL.
+
 ## Auto-attached device info
 
 Every event's `properties` is enriched with whatever the SDK can detect:
@@ -195,11 +197,14 @@ In `debug: true` mode the SDK warns (one signal per call) when property keys loo
 Forward purchase evidence (Apple StoreKit 2) directly to Crossdeck for verification — closes the purchase-to-entitled latency from seconds to milliseconds (faster than waiting for the App Store webhook). (`purchaseApple()` is kept as a deprecated alias.)
 
 ```ts
-await Crossdeck.syncPurchases({
-  signedTransactionInfo: transaction.jsonRepresentation,  // from StoreKit 2
-  signedRenewalInfo: subscription.signedRenewalInfo,      // optional
-  appAccountToken: "uuid-…",                              // optional
-});
+// Inside an async transaction handler — wrap top-level awaits.
+async function forwardTransaction(transaction) {
+  await Crossdeck.syncPurchases({
+    signedTransactionInfo: transaction.jsonRepresentation, // from StoreKit 2
+    signedRenewalInfo: subscription.signedRenewalInfo,     // optional
+    appAccountToken: "uuid-…",                             // optional
+  });
+}
 ```
 
 Stripe and Google purchases are verified via webhooks (Stripe Connect platform endpoint, Google Play RTDN) — there's no SDK-side push for those.
@@ -293,6 +298,23 @@ Publishable keys aren't secrets — they're identifiers, safe to ship in client
 - **Env partition** — a `cd_pub_live_…` key cannot read `cd_pub_test_…` data and vice versa.
 - **No raw payment credentials** ever pass through this SDK or sit in a Crossdeck database. Apple `.p8`s, Stripe secret keys, Google service-account JSON — all in Google Cloud Secret Manager, runtime-only access from the Crossdeck backend.
 
+## Identity & cookies (v0.6.0+)
+
+The SDK persists `anonymousId` and `crossdeckCustomerId` so a returning user keeps the same Crossdeck identity across page loads. By default in browsers it writes to BOTH `localStorage` (primary) and a 1st-party `document.cookie` (secondary, `Path=/`, `Max-Age=2y`, `SameSite=Lax`, `Secure` over HTTPS). The redundancy keeps "10k unique visitors" actually meaning 10k humans even when one store is wiped by ITP, private browsing, or "clear site data."
+
+The cookie holds only the same `anonymousId` already in `localStorage` — no fingerprintable data, no PII. Same security posture as Stripe, Segment, and PostHog's 1st-party identity cookies.
+
+**Disabling persistence.** Customers running strict consent flows (e.g. cookies disabled until the visitor opts in via a consent banner) should pass `persistIdentity: false` to `Crossdeck.init`. That switches the SDK to in-memory only — no `localStorage`, no cookie, identity is recreated on every page load. Re-`init` with `persistIdentity: true` once consent lands.
+
+```ts
+Crossdeck.init({
+  appId, publicKey, environment,
+  persistIdentity: false,  // strict consent — opt in later
+});
+```
+
+**Cookie disclosure.** If your privacy policy enumerates cookies, list this one as a "1st-party functional / analytics cookie used to keep the same visitor identity across page loads." The Crossdeck cookie name uses the configured `storagePrefix` (default `crossdeck:`) followed by `anon_id` (and `cdcust_id` once a user signs in).
+
 ## Versioning
 
 This package follows [semver](https://semver.org). The wire-format types (`PublicEntitlement`, `AliasResult`, etc.) are duplicated from the backend's `v1-types.ts` — they're the stable contract, not a shared module. Breaking changes to those types only ship in major versions.

package/dist/index.cjs

@@ -78,7 +78,7 @@ function typeMapForStatus(status) {
 
 // src/http.ts
 var SDK_NAME = "@cross-deck/web";
-var SDK_VERSION = "0.3.0";
+var SDK_VERSION = "0.6.0";
 var DEFAULT_BASE_URL = "https://api.cross-deck.com/v1";
 var HttpClient = class {
   constructor(config) {
@@ -110,7 +110,8 @@ var HttpClient = class {
       response = await fetch(url, {
         method,
         headers,
-        body: bodyInit
+        body: bodyInit,
+        keepalive: options.keepalive === true
       });
     } catch (err) {
       throw new CrossdeckError({
@@ -155,19 +156,25 @@ var HttpClient = class {
 var KEY_ANON = "anon_id";
 var KEY_CDCUST = "cdcust_id";
 var IdentityStore = class {
-  constructor(storage, prefix) {
-    this.storage = storage;
+  constructor(primary, prefix, secondary) {
+    this.primary = primary;
     this.prefix = prefix;
-    const stored = {
-      anon: storage.getItem(prefix + KEY_ANON),
-      cdcust: storage.getItem(prefix + KEY_CDCUST)
-    };
+    this.secondary = secondary ?? null;
+    const anonFromPrimary = primary.getItem(prefix + KEY_ANON);
+    const cdcustFromPrimary = primary.getItem(prefix + KEY_CDCUST);
+    const anonFromSecondary = this.secondary?.getItem(prefix + KEY_ANON) ?? null;
+    const cdcustFromSecondary = this.secondary?.getItem(prefix + KEY_CDCUST) ?? null;
+    const anon = anonFromPrimary ?? anonFromSecondary;
+    const cdcust = cdcustFromPrimary ?? cdcustFromSecondary;
     this.state = {
-      anonymousId: stored.anon ?? this.mintAnonymousId(),
-      crossdeckCustomerId: stored.cdcust
+      anonymousId: anon ?? this.mintAnonymousId(),
+      crossdeckCustomerId: cdcust
     };
-    if (!stored.anon) {
-      storage.setItem(prefix + KEY_ANON, this.state.anonymousId);
+    if (!anonFromPrimary || !anonFromSecondary) {
+      this.writeBoth(prefix + KEY_ANON, this.state.anonymousId);
+    }
+    if (cdcust && (!cdcustFromPrimary || !cdcustFromSecondary)) {
+      this.writeBoth(prefix + KEY_CDCUST, cdcust);
     }
   }
   /** Return the persisted anonymous device ID (always set). */
@@ -181,7 +188,7 @@ var IdentityStore = class {
   /** Persist a newly-resolved Crossdeck customer ID. */
   setCrossdeckCustomerId(value) {
     this.state.crossdeckCustomerId = value;
-    this.storage.setItem(this.prefix + KEY_CDCUST, value);
+    this.writeBoth(this.prefix + KEY_CDCUST, value);
   }
   /**
    * Wipe persisted identity. Called by reset() — used when an end-user
@@ -189,13 +196,13 @@ var IdentityStore = class {
    * pre-login session is a fresh customer in the identity graph.
    */
   reset() {
-    this.storage.removeItem(this.prefix + KEY_ANON);
-    this.storage.removeItem(this.prefix + KEY_CDCUST);
+    this.deleteBoth(this.prefix + KEY_ANON);
+    this.deleteBoth(this.prefix + KEY_CDCUST);
     this.state = {
       anonymousId: this.mintAnonymousId(),
       crossdeckCustomerId: null
     };
-    this.storage.setItem(this.prefix + KEY_ANON, this.state.anonymousId);
+    this.writeBoth(this.prefix + KEY_ANON, this.state.anonymousId);
   }
   /**
    * Generate an anonymousId. Crockford-ish base32 timestamp + random
@@ -207,6 +214,30 @@ var IdentityStore = class {
     const rand = randomChars(10);
     return `anon_${ts}${rand}`;
   }
+  writeBoth(key, value) {
+    try {
+      this.primary.setItem(key, value);
+    } catch {
+    }
+    if (this.secondary) {
+      try {
+        this.secondary.setItem(key, value);
+      } catch {
+      }
+    }
+  }
+  deleteBoth(key) {
+    try {
+      this.primary.removeItem(key);
+    } catch {
+    }
+    if (this.secondary) {
+      try {
+        this.secondary.removeItem(key);
+      } catch {
+      }
+    }
+  }
 };
 function randomChars(count) {
   const alphabet = "0123456789abcdefghijklmnopqrstuvwxyz";
@@ -335,8 +366,12 @@ var EventQueue = class {
    * Flush the buffer to /v1/events. Resolves when the network call
    * completes (success or failure). On failure, events stay in the
    * buffer for the next flush attempt.
+   *
+   * `options.keepalive` marks the underlying fetch as keepalive so the
+   * browser keeps the request alive past page unload. Use this for
+   * terminal flushes (pagehide / visibilitychange→hidden / beforeunload).
    */
-  async flush() {
+  async flush(options = {}) {
     if (this.buffer.length === 0) return null;
     this.cancelTimerIfSet();
     const batch = this.buffer.splice(0);
@@ -352,7 +387,8 @@ var EventQueue = class {
           environment: env.environment,
           sdk: env.sdk,
           events: batch
-        }
+        },
+        keepalive: options.keepalive === true
       });
       this.lastFlushAt = Date.now();
       this.lastError = null;
@@ -427,6 +463,59 @@ var MemoryStorage = class {
     this.store.delete(key);
   }
 };
+var CookieStorage = class {
+  constructor(options) {
+    this.maxAgeSec = options?.maxAgeSec ?? 63072e3;
+    this.secure = options?.secure ?? defaultSecure();
+    this.sameSite = options?.sameSite ?? "Lax";
+  }
+  getItem(key) {
+    if (!hasDocument()) return null;
+    const doc = globalThis.document;
+    const cookies = doc.cookie ? doc.cookie.split(/;\s*/) : [];
+    const prefix = encodeURIComponent(key) + "=";
+    for (const c of cookies) {
+      if (c.startsWith(prefix)) {
+        try {
+          return decodeURIComponent(c.slice(prefix.length));
+        } catch {
+          return null;
+        }
+      }
+    }
+    return null;
+  }
+  setItem(key, value) {
+    if (!hasDocument()) return;
+    const doc = globalThis.document;
+    const parts = [
+      `${encodeURIComponent(key)}=${encodeURIComponent(value)}`,
+      "Path=/",
+      `Max-Age=${this.maxAgeSec}`,
+      `SameSite=${this.sameSite}`
+    ];
+    if (this.secure) parts.push("Secure");
+    try {
+      doc.cookie = parts.join("; ");
+    } catch {
+    }
+  }
+  removeItem(key) {
+    if (!hasDocument()) return;
+    const doc = globalThis.document;
+    const parts = [
+      `${encodeURIComponent(key)}=`,
+      "Path=/",
+      "Max-Age=0",
+      `SameSite=${this.sameSite}`
+    ];
+    if (this.secure) parts.push("Secure");
+    try {
+      doc.cookie = parts.join("; ");
+    } catch {
+    }
+  }
+};
 function detectDefaultStorage() {
   try {
     const ls = globalThis.localStorage;
@@ -440,6 +529,17 @@ function detectDefaultStorage() {
   }
   return new MemoryStorage();
 }
+function defaultSecure() {
+  try {
+    const loc = globalThis.location;
+    return loc?.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+function hasDocument() {
+  return typeof globalThis.document !== "undefined";
+}
 
 // src/device-info.ts
 function isBrowser() {
@@ -540,6 +640,14 @@ var DEFAULT_AUTO_TRACK = {
   deviceInfo: true
 };
 var SESSION_RESUME_THRESHOLD_MS = 30 * 60 * 1e3;
+var EMPTY_ACQUISITION = {
+  utm_source: "",
+  utm_medium: "",
+  utm_campaign: "",
+  utm_content: "",
+  utm_term: "",
+  referrer: ""
+};
 var AutoTracker = class {
   constructor(cfg, track) {
     this.cfg = cfg;
@@ -575,6 +683,18 @@ var AutoTracker = class {
   get currentSessionId() {
     return this.session?.sessionId ?? null;
   }
+  /**
+   * Per-session acquisition context — utm_* + referrer, captured once
+   * at session start. Returns empty strings when there's no session
+   * (Node, before init, after uninstall) so callers can spread without
+   * conditional logic. Bank-grade rule: capture once, attach to every
+   * event of the session, don't re-read on every track() (the URL
+   * changes via SPA pushState; the source-of-record is the URL we
+   * landed on).
+   */
+  get currentAcquisition() {
+    return this.session?.acquisition ?? EMPTY_ACQUISITION;
+  }
   // ---------- sessions ----------
   installSessionTracking() {
     this.session = this.startNewSession();
@@ -612,7 +732,8 @@ var AutoTracker = class {
       sessionId: mintSessionId(),
       startedAt: Date.now(),
       hiddenAt: null,
-      endedSent: false
+      endedSent: false,
+      acquisition: captureAcquisition()
     };
   }
   emitSessionStart() {
@@ -678,6 +799,26 @@ function mintSessionId() {
   const ts = Date.now().toString(36);
   return `sess_${ts}${randomChars(10)}`;
 }
+function captureAcquisition() {
+  if (!isBrowserSafe()) return { ...EMPTY_ACQUISITION };
+  const result = { ...EMPTY_ACQUISITION };
+  try {
+    const w = globalThis.window;
+    const params = new URLSearchParams(w.location.search ?? "");
+    result.utm_source = params.get("utm_source") ?? "";
+    result.utm_medium = params.get("utm_medium") ?? "";
+    result.utm_campaign = params.get("utm_campaign") ?? "";
+    result.utm_content = params.get("utm_content") ?? "";
+    result.utm_term = params.get("utm_term") ?? "";
+  } catch {
+  }
+  try {
+    const doc = globalThis.document;
+    if (typeof doc.referrer === "string") result.referrer = doc.referrer;
+  } catch {
+  }
+  return result;
+}
 
 // src/debug.ts
 var SENSITIVE_KEY_PATTERNS = [
@@ -782,7 +923,11 @@ var CrossdeckClient = class {
       storagePrefix: options.storagePrefix ?? "crossdeck:",
       autoHeartbeat: options.autoHeartbeat ?? true,
       eventFlushBatchSize: options.eventFlushBatchSize ?? 20,
-      eventFlushIntervalMs: options.eventFlushIntervalMs ?? 5e3,
+      // 1500ms idle window. Short enough that an event queued on page
+      // load still flushes if the user leaves quickly (the keepalive
+      // pagehide handler picks up anything that doesn't); long enough
+      // that bursts of clicks coalesce into one network round-trip.
+      eventFlushIntervalMs: options.eventFlushIntervalMs ?? 1500,
       sdkVersion: options.sdkVersion ?? SDK_VERSION,
       autoTrack,
       appVersion: options.appVersion ?? null
@@ -795,7 +940,10 @@ var CrossdeckClient = class {
       sdkVersion: opts.sdkVersion
     });
     const effectiveStorage = persistIdentity ? storage : new MemoryStorage();
-    const identity = new IdentityStore(effectiveStorage, opts.storagePrefix);
+    const useCookieRedundancy = persistIdentity && !options.storage && // honour caller's adapter choice
+    typeof globalThis.document !== "undefined";
+    const cookieStore = useCookieRedundancy ? new CookieStorage() : void 0;
+    const identity = new IdentityStore(effectiveStorage, opts.storagePrefix, cookieStore);
     const entitlements = new EntitlementCache();
     const events = new EventQueue({
       http,
@@ -824,7 +972,8 @@ var CrossdeckClient = class {
       deviceInfo,
       options: opts,
       debug,
-      developerUserId: null
+      developerUserId: null,
+      uninstallUnloadFlush: null
     };
     debug.emit("sdk.configured", `Crossdeck connected to ${opts.appId} in ${opts.environment} mode.`, {
       appId: opts.appId,
@@ -839,6 +988,9 @@ var CrossdeckClient = class {
       this.state.autoTracker = tracker;
       tracker.install();
     }
+    this.state.uninstallUnloadFlush = installUnloadFlush(() => {
+      void this.flush({ keepalive: true }).catch(() => void 0);
+    });
     if (opts.autoHeartbeat) {
       void this.heartbeat().catch(() => void 0);
     }
@@ -972,6 +1124,15 @@ var CrossdeckClient = class {
     const enriched = { ...s.deviceInfo };
     const sessionId = s.autoTracker?.currentSessionId;
     if (sessionId) enriched.sessionId = sessionId;
+    const acquisition = s.autoTracker?.currentAcquisition;
+    if (acquisition) {
+      if (acquisition.utm_source) enriched.utm_source = acquisition.utm_source;
+      if (acquisition.utm_medium) enriched.utm_medium = acquisition.utm_medium;
+      if (acquisition.utm_campaign) enriched.utm_campaign = acquisition.utm_campaign;
+      if (acquisition.utm_content) enriched.utm_content = acquisition.utm_content;
+      if (acquisition.utm_term) enriched.utm_term = acquisition.utm_term;
+      if (acquisition.referrer) enriched.referrer = acquisition.referrer;
+    }
     if (properties) Object.assign(enriched, properties);
     const event = {
       eventId: this.mintEventId(),
@@ -985,11 +1146,16 @@ var CrossdeckClient = class {
   /**
    * Force-flush queued events. Useful to call from page-unload handlers.
    *
+   * Pass `{ keepalive: true }` from terminal handlers (pagehide /
+   * visibilitychange→hidden / beforeunload). The browser keeps the
+   * request alive after the page tears down, so the final batch
+   * actually lands instead of being cancelled with the unload.
+   *
    * NorthStar §4: standard method name across all Crossdeck SDKs.
    */
-  async flush() {
+  async flush(options = {}) {
     const s = this.requireStarted();
-    await s.events.flush();
+    await s.events.flush(options);
   }
   /** @deprecated Use `flush()` instead. NorthStar §4 standardised the name. */
   async flushEvents() {
@@ -1172,6 +1338,23 @@ function resolveAutoTrack(input) {
     deviceInfo: input.deviceInfo ?? DEFAULT_AUTO_TRACK.deviceInfo
   };
 }
+function installUnloadFlush(onUnload) {
+  const w = globalThis.window;
+  const doc = globalThis.document;
+  if (!w || !doc) return () => void 0;
+  const onVisChange = () => {
+    if (doc.visibilityState === "hidden") onUnload();
+  };
+  const onTerminal = () => onUnload();
+  doc.addEventListener("visibilitychange", onVisChange);
+  w.addEventListener("pagehide", onTerminal);
+  w.addEventListener("beforeunload", onTerminal);
+  return () => {
+    doc.removeEventListener("visibilitychange", onVisChange);
+    w.removeEventListener("pagehide", onTerminal);
+    w.removeEventListener("beforeunload", onTerminal);
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Crossdeck,