@hanzo/event 0.3.44 → 0.3.48

package/dist/tags.d.ts

@@ -15,6 +15,13 @@ export interface TagOptions {
     /** Domains one visit crosses, so GA4 keeps it one session. */
     domains?: string[];
 }
+/**
+ * The publishable key of each site's project, which is how cloud finds the site's
+ * tag set. A `pk-` is public by design (it ships in every page); it names a site,
+ * never a platform id. A host absent here has no tag config unless `start` is
+ * given a key.
+ */
+export declare const SITE_KEY: Readonly<Record<string, string>>;
 /**
  * Starts the tag manager: fetches the site's tag set and loads what consent
  * allows, again on every consent change. Safe to call on every page load, and
@@ -35,8 +42,14 @@ export declare function mirror(name: string, params: Record<string, unknown>, id
  * forwards on), and each browser tag that is running hears it too. A moment
  * that arrives while gtag.js is still on its way waits for it, so GA4 sees it
  * with a session; a page that is leaving sends what it holds as things stand.
+ *
+ * A paid order is stated by the SERVER on our stream (and forwarded server-side);
+ * its browser copy is `track(stream, 'order_completed', {event_id: order, order_id:
+ * order, …}, 'tags')`: the same id, the pixels only, so nothing counts twice.
  */
-export declare function track(stream: Analytics | undefined, name: string, params?: Record<string, unknown>): void;
+export declare function track(stream: Analytics | undefined, name: string, params?: Record<string, unknown>, 
+/** `'tags'` fires the browser pixels only: the server states this moment on our stream itself. */
+only?: 'tags'): void;
 /** What cloud needs to forward a moment a page states itself, as if the browser had sent it. */
 export declare function visit(): Record<string, unknown>;
 //# sourceMappingURL=tags.d.ts.map

package/dist/tags.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tags.d.ts","sourceRoot":"","sources":["../src/tags.ts"],"names":[],"mappings":"AAoCA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAA;AAEvC,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,EAAE,MAAM,CAAA;IACV,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAChC;AAED,MAAM,WAAW,UAAU;IACzB,wDAAwD;IACxD,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,wDAAwD;IACxD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;CACnB;AAuND;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,CAAC,GAAE,UAAe,GAAG,MAAM,IAAI,CAiCpD;AAOD,uFAAuF;AACvF,wBAAgB,KAAK,IAAI,MAAM,CAc9B;AA+CD;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,SAAU,GAAG,IAAI,CAiCpG;AAED;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,IAAI,CAmB7G;AAED,gGAAgG;AAChG,wBAAgB,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAG/C"}
+{"version":3,"file":"tags.d.ts","sourceRoot":"","sources":["../src/tags.ts"],"names":[],"mappings":"AAoCA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAA;AAEvC,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,EAAE,MAAM,CAAA;IACV,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAChC;AAED,MAAM,WAAW,UAAU;IACzB,wDAAwD;IACxD,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,wDAAwD;IACxD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;CACnB;AAED;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAUpD,CAAA;AAuNF;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,CAAC,GAAE,UAAe,GAAG,MAAM,IAAI,CAmCpD;AAOD,uFAAuF;AACvF,wBAAgB,KAAK,IAAI,MAAM,CAc9B;AA+CD;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,SAAU,GAAG,IAAI,CAiCpG;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,KAAK,CACnB,MAAM,EAAE,SAAS,GAAG,SAAS,EAC7B,IAAI,EAAE,MAAM,EACZ,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;AACpC,kGAAkG;AAClG,IAAI,CAAC,EAAE,MAAM,GACZ,IAAI,CAsBN;AAED,gGAAgG;AAChG,wBAAgB,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAG/C"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzo/event",
-  "version": "0.3.44",
+  "version": "0.3.48",
   "description": "Hanzo Event — the ONE telemetry client. Emits pageview/event/identify/group to the Hanzo Cloud event stream (POST /v1/event), AND reports errors to Sentry as real Sentry envelopes — the error plane needs a DSN, without one nothing reaches Sentry. First-touch attribution, beacon-on-unload, auto error capture, client-side secret/PII scrubbing, a shared event + goal vocabulary. Subsumes @sentry.",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",

package/src/index.ts

@@ -31,8 +31,10 @@ export {
 } from './consent'
 export type { Choice, Region } from './consent'
 export { CLICK_IDS, capture as captureClick, touch } from './touch'
-export { start as startTags, track, mirror, reach, visit } from './tags'
+export { start as startTags, track, mirror, reach, visit, SITE_KEY } from './tags'
 export type { BrowserTag, TagOptions } from './tags'
+export { commerceItem, worth } from './items'
+export type { CommerceItem, PlanLine } from './items'
 export { GOALS, COHORTS } from './goals'
 export type { GoalDef, CohortDef } from './goals'
 export { FUNNELS, PRODUCTS, eventsOf } from './funnels'

package/src/items.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest'
+import { commerceItem, worth } from './items'
+
+describe('commerceItem', () => {
+  it('names an individual plan by its id, term and price', () => {
+    expect(commerceItem({ id: 'dev', name: 'Dev', interval: 'month', price: 19 })).toEqual({
+      item_id: 'dev', item_name: 'Dev', item_category: 'individual', item_variant: 'monthly', price: 19, quantity: 1,
+    })
+  })
+
+  it('names a team plan by its seats, and an annual term however commerce spells it', () => {
+    for (const interval of ['year', 'yearly', 'annual', 'Year']) {
+      const i = commerceItem({ id: 'team_standard', team: true, interval, price: 24, quantity: 3 })
+      expect(i).toMatchObject({ item_category: 'team', item_variant: 'annual', quantity: 3 })
+      expect(worth(i)).toBe(72)
+    }
+  })
+
+  it('a plan with no price is free, not unknown', () => {
+    expect(commerceItem({ id: 'free', interval: 'month', price: null }).price).toBe(0)
+  })
+})

package/src/items.ts

@@ -0,0 +1,44 @@
+// A plan as every ecommerce event names it: GA4's item shape, which the tag
+// manager hands Meta, TikTok and X, and which cloud's forwarder lifts from the
+// events the server states. One function, so a plan carries the same line from
+// the pricing page to the checkout to the order.
+//
+// `item_id` is the plan's id as the catalog spells it (free, dev, max, and the
+// team plans), `item_category` says who it is for, `item_variant` the term,
+// `price` the unit price for that term in US dollars and `quantity` the seats
+// (1 for an individual plan).
+
+export interface CommerceItem {
+  item_id: string
+  item_name?: string
+  item_category: 'individual' | 'team'
+  item_variant: 'monthly' | 'annual'
+  price: number
+  quantity: number
+}
+
+export interface PlanLine {
+  id: string
+  name?: string
+  /** A team plan is sold per seat. */
+  team?: boolean
+  /** The term, as commerce (`month`, `year`) or the funnel (`monthly`, `annual`) says it. */
+  interval: string
+  price: number | null
+  quantity?: number
+}
+
+export function commerceItem(p: PlanLine): CommerceItem {
+  const annual = /^(year|yearly|annual)$/i.test(p.interval)
+  return {
+    item_id: p.id,
+    ...(p.name ? { item_name: p.name } : {}),
+    item_category: p.team ? 'team' : 'individual',
+    item_variant: annual ? 'annual' : 'monthly',
+    price: p.price ?? 0,
+    quantity: p.quantity ?? 1,
+  }
+}
+
+/** What the whole order is worth: the unit price times the seats. */
+export const worth = (i: CommerceItem): number => i.price * i.quantity

package/src/react.tsx

@@ -16,11 +16,13 @@ import {
   useContext,
   useEffect,
   useRef,
+  useSyncExternalStore,
   type ErrorInfo,
   type ReactNode,
 } from 'react'
 import { Analytics, createAnalytics } from './core'
 import type { AnalyticsConfig } from './types'
+import { CONSENT_EVENT, read, render, type Choice } from './consent'
 
 const Ctx = createContext<Analytics | null>(null)
 
@@ -120,3 +122,23 @@ export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundarySt
     return fallback ?? null
   }
 }
+
+const listen = (on: () => void) => {
+  window.addEventListener(CONSENT_EVENT, on)
+  return () => window.removeEventListener(CONSENT_EVENT, on)
+}
+
+/**
+ * The visitor's consent, live: what a region presumes until they choose, then
+ * what they chose, re-rendering the moment they do. `enabled: choice.analytics`
+ * on the provider's config is how a stream that started silent for an EU visitor
+ * starts on Accept, with no reload.
+ */
+export function useConsent(): Choice {
+  const kept = useSyncExternalStore(listen, () => render(read()), () => '')
+  return {
+    analytics: kept.includes('analytics'),
+    marketing: kept.includes('marketing'),
+    ads: kept.includes('ads'),
+  }
+}

package/src/tags.test.ts

@@ -185,3 +185,21 @@ describe('one event, every tag', () => {
     expect(sent.items[0].price).toBe(0)
   })
 })
+
+describe('a paid order the server also states', () => {
+  it('fires the pixels under the order id and does not touch our stream', async () => {
+    browser('America/New_York')
+    const { startTags, track } = await import('./index')
+    startTags({ key: 'pk-x' })
+    await tick()
+    const w = g.window as unknown as Record<string, unknown>
+    const fbq: unknown[][] = []
+    const captured: unknown[] = []
+    w.gtag = () => undefined
+    w.fbq = (...a: unknown[]) => fbq.push(a)
+    track({ capture: (...a: unknown[]) => captured.push(a) } as never, 'order_completed', { event_id: 'sub_1', order_id: 'sub_1', value: 19 }, 'tags')
+    await tick()
+    expect(captured).toEqual([])
+    expect(fbq.map((a) => (a[3] as { eventID: string }).eventID)).toEqual(['sub_1', 'sub_1'])
+  })
+})

package/src/tags.ts

@@ -54,6 +54,24 @@ export interface TagOptions {
   domains?: string[]
 }
 
+/**
+ * The publishable key of each site's project, which is how cloud finds the site's
+ * tag set. A `pk-` is public by design (it ships in every page); it names a site,
+ * never a platform id. A host absent here has no tag config unless `start` is
+ * given a key.
+ */
+export const SITE_KEY: Readonly<Record<string, string>> = Object.freeze({
+  'hanzo.ai': 'pk-CmfLA2K6kvsPflrS9DSkt06H_kSoQB_21sjedt6VJdc',
+  'www.hanzo.ai': 'pk-CmfLA2K6kvsPflrS9DSkt06H_kSoQB_21sjedt6VJdc',
+  'hanzo.app': 'pk-wlnXN2a9_vmCm60yTFtQ629Q8TyuaxBNZbY1RWT72gQ',
+  'hanzo.team': 'pk-NCzD2FiHpZv8KUpkCX4olT1LJOJsMxBC_Z8NkiQsOFQ',
+  'pay.hanzo.ai': 'pk-eX6kv7JZNoiYn1WkeJH3tT_8OvkVYScmCXnLMwxTKf8',
+  'platform.hanzo.ai': 'pk-My1RpZLEUnTj8vAdPbWKYdDUuhxZJ4dVjHcwjZN4rZ8',
+  'docs.hanzo.ai': 'pk-jukhtjMT2ymoeBDAeFjINQWlBv-v9sNn1TPztiCrrwk',
+  'hanzo.bot': 'pk-W5d7Mn7ZukT7igyscIy6Pqe8JpA0Ge604Yn4xNR4JCU',
+  'cloud.hanzo.ai': 'pk-RAfEGHPoNdCEU9fnA_cPd_Xo9Tci44rlYQV9xuJ1Ob0',
+})
+
 type Call = (...args: unknown[]) => void
 type Page = {
   dataLayer?: unknown[]
@@ -281,8 +299,10 @@ export function start(o: TagOptions = {}): () => void {
     configured = true
     const base = (o.base ?? 'https://api.hanzo.ai').replace(/\/$/, '')
     const q = new URLSearchParams()
-    if (o.key) q.set('key', o.key)
-    q.set('host', o.host ?? window.location.hostname)
+    const host = o.host ?? window.location.hostname
+    const key = o.key ?? SITE_KEY[host]
+    if (key) q.set('key', key)
+    q.set('host', host)
     const answer = (list: BrowserTag[]) => {
       tags = list
       configAnswered = true
@@ -420,17 +440,30 @@ export function mirror(name: string, params: Record<string, unknown>, id: string
  * forwards on), and each browser tag that is running hears it too. A moment
  * that arrives while gtag.js is still on its way waits for it, so GA4 sees it
  * with a session; a page that is leaving sends what it holds as things stand.
+ *
+ * A paid order is stated by the SERVER on our stream (and forwarded server-side);
+ * its browser copy is `track(stream, 'order_completed', {event_id: order, order_id:
+ * order, …}, 'tags')`: the same id, the pixels only, so nothing counts twice.
  */
-export function track(stream: Analytics | undefined, name: string, params: Record<string, unknown> = {}): void {
+export function track(
+  stream: Analytics | undefined,
+  name: string,
+  params: Record<string, unknown> = {},
+  /** `'tags'` fires the browser pixels only: the server states this moment on our stream itself. */
+  only?: 'tags',
+): void {
   if (typeof window === 'undefined') return
   if (!leaving && !settled()) {
-    held.push(() => track(stream, name, params))
+    held.push(() => track(stream, name, params, only))
     return
   }
   const c = read()
-  const event_id = crypto.randomUUID()
+  // A moment the server also states (a paid order) brings its own id, the order's,
+  // so each platform sees the browser's copy and the server's as one.
+  const event_id = typeof params.event_id === 'string' && params.event_id ? params.event_id : crypto.randomUUID()
   const to = reach()
   mirror(name, params, event_id, to)
+  if (only === 'tags') return
   stream?.capture(name, {
     ...params,
     ...touch(c),