@hanzo/event 0.3.42 → 0.3.43

package/dist/link.d.ts

@@ -0,0 +1,28 @@
+import type { Attribution } from './types';
+export declare const LINK_PARAMS: {
+    readonly anon: 'hz_aid';
+    readonly session: 'hz_sid';
+    readonly firstTouch: 'hz_ft';
+};
+export declare const isId: (v: string | null | undefined) => v is string;
+/** What a link carries. Any field may be absent. */
+export interface LinkState {
+    anonId?: string;
+    sessionId?: string;
+    firstTouch?: Attribution;
+}
+/** First touch as a compact tuple: utm source, medium, campaign, term, content, refCode,
+ *  referrer, channel. Short because it rides a URL; a tuple because keys cost bytes. */
+export declare function encodeFirstTouch(a: Attribution): string;
+export declare function decodeFirstTouch(raw: string | null | undefined): Attribution | undefined;
+/** linkUrl returns `url` with the visitor's identity appended when its host is
+ *  Hanzo-owned and is not `fromHost`; otherwise `url` unchanged. Relative URLs
+ *  resolve against `base`. Never throws. */
+export declare function linkUrl(url: string, state: LinkState, fromHost: string, base?: string): string;
+/** readLink parses what a link carried out of a location.search value. Invalid
+ *  values are dropped, not repaired. */
+export declare function readLink(search: string): LinkState;
+/** stripLink returns the path, query and hash of `href` without the link parameters, or
+ *  undefined when there were none. */
+export declare function stripLink(href: string): string | undefined;
+//# sourceMappingURL=link.d.ts.map

package/dist/link.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"link.d.ts","sourceRoot":"","sources":["../src/link.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAE1C,eAAO,MAAM,WAAW;aAAK,IAAI,EAAE,QAAQ;aAAE,OAAO,EAAE,QAAQ;aAAE,UAAU,EAAE,OAAO;CAAW,CAAA;AAK9F,eAAO,MAAM,IAAI,MAAO,MAAM,GAAG,IAAI,GAAG,SAAS,KAAG,CAAC,IAAI,MAA6B,CAAA;AAEtF,oDAAoD;AACpD,MAAM,WAAW,SAAS;IACxB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,UAAU,CAAC,EAAE,WAAW,CAAA;CACzB;AAED;wFACwF;AACxF,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,WAAW,GAAG,MAAM,CAKvD;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,CAgBxF;AAED;;4CAE4C;AAC5C,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAc9F;AAED;wCACwC;AACxC,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CASlD;AAED;sCACsC;AACtC,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAU1D"}

package/dist/react.cjs

@@ -386,9 +386,18 @@ function hzAnonId() {
   }
   return id;
 }
+function hzAnonAdopt(id) {
+  hzAnonMemo = id;
+  hzAnonWrite(HZ_ANON_KEY, id);
+  try {
+    var s = hzAnonStore();
+    if (s) s.setItem(HZ_ANON_KEY, id);
+  } catch (e) {
+  }
+}
 
 // package.json
-var version = "0.3.42";
+var version = "0.3.43";
 
 // src/version.ts
 var VERSION = version;
@@ -708,6 +717,13 @@ function sessionId(now = Date.now()) {
   s.setItem(KEY.session, JSON.stringify(state));
   return state.id;
 }
+function adoptSession(id, now = Date.now()) {
+  const s = ls();
+  if (s) s.setItem(KEY.session, JSON.stringify({ id, last: now }));
+}
+function adoptAnonId(id) {
+  hzAnonAdopt(id);
+}
 function getFirstTouch() {
   const s = ls();
   if (!s) return void 0;
@@ -747,6 +763,76 @@ function mergeCohort(patch) {
   return next;
 }
 
+// src/link.ts
+var LINK_PARAMS = { anon: "hz_aid", session: "hz_sid", firstTouch: "hz_ft" };
+var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var isId = (v) => !!v && UUID.test(v);
+function encodeFirstTouch(a) {
+  return JSON.stringify([
+    a.utm.source,
+    a.utm.medium,
+    a.utm.campaign,
+    a.utm.term,
+    a.utm.content,
+    a.refCode,
+    a.referrer,
+    a.channel
+  ].map((v) => v ?? ""));
+}
+function decodeFirstTouch(raw) {
+  if (!raw || raw.length > 1024) return void 0;
+  try {
+    const t = JSON.parse(raw);
+    if (!Array.isArray(t) || t.length !== 8 || t.some((v) => typeof v !== "string")) return void 0;
+    const [source, medium, campaign, term, content, refCode, referrer, channel] = t;
+    const u = (v) => v || void 0;
+    return {
+      utm: { source: u(source), medium: u(medium), campaign: u(campaign), term: u(term), content: u(content) },
+      refCode: u(refCode),
+      referrer: u(referrer),
+      channel: u(channel)
+    };
+  } catch {
+    return void 0;
+  }
+}
+function linkUrl(url, state, fromHost, base) {
+  let u;
+  try {
+    u = new URL(url, base);
+  } catch {
+    return url;
+  }
+  if (u.protocol !== "https:" && u.protocol !== "http:") return url;
+  if (!orgOf(u.hostname) || u.hostname === fromHost) return url;
+  const set = (k, v) => v && u.searchParams.set(k, v);
+  if (isId(state.anonId)) set(LINK_PARAMS.anon, state.anonId);
+  if (isId(state.sessionId)) set(LINK_PARAMS.session, state.sessionId);
+  if (state.firstTouch) set(LINK_PARAMS.firstTouch, encodeFirstTouch(state.firstTouch));
+  return u.toString();
+}
+function readLink(search) {
+  const q = new URLSearchParams(search || "");
+  const a = q.get(LINK_PARAMS.anon);
+  const s = q.get(LINK_PARAMS.session);
+  return {
+    anonId: isId(a) ? a : void 0,
+    sessionId: isId(s) ? s : void 0,
+    firstTouch: decodeFirstTouch(q.get(LINK_PARAMS.firstTouch))
+  };
+}
+function stripLink(href) {
+  const u = new URL(href);
+  let hit = false;
+  for (const k of Object.values(LINK_PARAMS)) {
+    if (u.searchParams.has(k)) {
+      u.searchParams.delete(k);
+      hit = true;
+    }
+  }
+  return hit ? u.pathname + u.search + u.hash : void 0;
+}
+
 // src/core.ts
 var EVENT_PATH = "/v1/event";
 var DEFAULT_HOST = "https://api.hanzo.ai";
@@ -907,8 +993,19 @@ var Analytics = class {
     if (this.started || !this.cfg.enabled) return;
     this.started = true;
     if (!isBrowser()) return;
+    const linked = readLink(window.location.search);
+    if (linked.anonId) adoptAnonId(linked.anonId);
+    if (linked.sessionId) adoptSession(linked.sessionId);
+    const clean = stripLink(window.location.href);
+    if (clean !== void 0) {
+      try {
+        window.history.replaceState(window.history.state, "", clean);
+      } catch {
+      }
+    }
     const parsed = parseAttribution(window.location.search, document.referrer);
-    this.attribution = hasAttribution(parsed) ? setFirstTouchOnce(parsed) : getFirstTouch() ?? parsed;
+    const first = linked.firstTouch && !getFirstTouch() ? setFirstTouchOnce(linked.firstTouch) : void 0;
+    this.attribution = first ?? (hasAttribution(parsed) ? setFirstTouchOnce(parsed) : getFirstTouch() ?? parsed);
     this.cohort = mergeCohort({
       channel: this.attribution.channel ?? deriveChannel(this.attribution),
       refCode: this.attribution.refCode
@@ -927,6 +1024,27 @@ var Analytics = class {
       });
     }
   }
+  /** link returns `url` carrying this visitor's anonymous id, session and first
+   *  touch when the destination is a Hanzo-owned host, so the journey continues
+   *  across the hop. Any other URL comes back unchanged. */
+  link(url) {
+    if (!isBrowser()) return url;
+    if (!this.started) this.init();
+    return linkUrl(
+      url,
+      { anonId: anonId(), sessionId: sessionId(), firstTouch: this.attribution },
+      window.location.hostname,
+      window.location.href
+    );
+  }
+  /** authorize decorates an OAuth authorize URL for the redirect to IAM and flushes
+   *  what is queued, because the page is about to unload. Assign the result to
+   *  `location`. */
+  authorize(url) {
+    const out = this.link(url);
+    this.flush(true);
+    return out;
+  }
   /** identify binds the current visitor to a stable person id (post-login). */
   identify(personId, traits) {
     this.personId = personId;