@hanzo/event 0.3.19 → 0.3.21

package/dist/index.d.cts

@@ -1,12 +1,12 @@
-import { C as Cohort, A as Attribution, S as SentryEvent, D as Dsn, a as CaptureErrorOptions, b as SentryFrame } from './core-D4PaPlOB.cjs';
-export { c as Analytics, d as AnalyticsConfig, E as EventKind, e as Exception, f as SentryLevel, T as Transport, W as WireEvent, g as createAnalytics } from './core-D4PaPlOB.cjs';
+import { C as Cohort, A as Attribution, S as SentryEvent, D as Dsn, a as CaptureErrorOptions, b as SentryFrame, E as ExceptionEntry, c as SentryLevel, d as ExceptionProperties } from './core-CHLpJy51.cjs';
+export { e as Analytics, f as AnalyticsConfig, g as EventKind, h as Exception, i as ExceptionFrame, T as Transport, W as WireEvent, j as createAnalytics } from './core-CHLpJy51.cjs';
 
 /** Read the persisted first-touch attribution. */
 declare function getFirstTouch(): Attribution | undefined;
 /** Read persisted cohort dimensions. */
 declare function getCohort(): Cohort | undefined;
 
-declare const VERSION = "0.3.19";
+declare const VERSION = "0.3.21";
 
 /**
  * parseDsn parses "https://<version>:<hmac>@<host>/v1/sentry/<projectId>" into its
@@ -110,12 +110,15 @@ declare function uuidv7Time(id: string): number;
  *  project — an explicit map, because the projects predate this and do not derive
  *  cleanly from the product name. */
 declare const PRODUCT_PROJECT: Readonly<Record<string, string>>;
-/** dsnForProduct builds the product's Sentry DSN — the ONE org publishable key at
- *  its project's envelope endpoint — or undefined when the product has no project
- *  yet, which leaves the error plane inert rather than posting into the wrong one.
- *  Same key as the event stream: cloud resolves it to the org and attributes the
- *  errors there. */
-declare function dsnForProduct(product: string | undefined): string | undefined;
+/** dsnForProduct builds the product's Sentry DSN from the caller's resolved
+ *  publishable `key` and the product's project — the SAME key the event stream
+ *  carries, at the product's envelope endpoint. Returns undefined when there is no
+ *  key or no project for the product, leaving the error plane inert rather than
+ *  posting into the wrong one. The key is NOT baked here: it is the value the
+ *  surface resolved (an explicit `ingestKey`, or the KMS-sourced
+ *  NEXT_PUBLIC_PUBLISHABLE_KEY the build inlines) — the ONE live source, never a
+ *  literal committed beside the code. */
+declare function dsnForProduct(product: string | undefined, key: string | undefined): string | undefined;
 
 /** redactSecrets removes known secret shapes. Always applied. */
 declare function redactSecrets(s: string): string;
@@ -170,6 +173,59 @@ declare const EVENTS: {
 type EventName = (typeof EVENTS)[keyof typeof EVENTS];
 /** The reserved event name a pageview is stored under (server + read lens). */
 declare const PAGEVIEW = "$pageview";
+/** The reserved name every captured exception is emitted under. Error Tracking
+ *  reads exactly this name; an exception emitted under its own message instead
+ *  makes every distinct message a permanent entry in the event taxonomy. */
+declare const EXCEPTION = "$exception";
+
+/**
+ * digest is a stable 32-hex-char (128-bit) content hash, computed synchronously.
+ *
+ * Grouping keys are needed on the capture path, which is synchronous and may be
+ * running inside an unload handler — SubtleCrypto is async and unavailable on
+ * insecure origins, so it cannot be used here. This is FNV-1a run over four seeds
+ * and concatenated. It is a GROUPING key, never a security boundary: it is not
+ * collision-resistant against a chosen-input adversary, and nothing authorizes or
+ * authenticates on it. The product treats the value as opaque.
+ */
+declare function digest(s: string): string;
+/**
+ * exceptionEntry builds the single `$exception_list` entry for a throwable.
+ *
+ * One entry, not a chain: `Error.cause` chaining is a distinct fact with its own
+ * ordering rules, and emitting it wrongly is worse than not emitting it.
+ */
+declare function exceptionEntry(err: unknown, opts: {
+    handled: boolean;
+    id: string;
+}): ExceptionEntry;
+/**
+ * fingerprint is the issue grouping key.
+ *
+ * Keyed on exception type plus each in-app frame's function and source — the same
+ * pieces the server-side grouper records ("Exception Type", "Resolved function
+ * name", "Source file name"). Deliberately NOT the message: `Loading chunk 3324
+ * failed` and `Loading chunk 998 failed` are one bug, and grouping on message is
+ * precisely the mistake that made every distinct error string its own event name.
+ *
+ * Falls back to the type alone when no in-app frame survived, which keeps
+ * stackless errors (`Script error.`, cross-origin) in one issue instead of
+ * scattering them.
+ */
+declare function fingerprint(entry: ExceptionEntry): string;
+/**
+ * exceptionProperties builds the full `$exception_*` property bag for one captured
+ * throwable — everything Error Tracking reads off the event.
+ *
+ * The denormalized arrays are ordered like `frames`: last element is the throw
+ * site, which is the element the issue list indexes at -1 for its source/function
+ * columns.
+ */
+declare function exceptionProperties(err: unknown, opts: {
+    handled: boolean;
+    id: string;
+    level?: SentryLevel;
+}): ExceptionProperties;
 
 /** The emitting surfaces — the closed set of `AnalyticsConfig.product` values.
  *  `product` is on every event, so a funnel scopes by product instead of every
@@ -297,4 +353,4 @@ declare function hasAttribution(a: Attribution): boolean;
 /** isoWeek returns the ISO-8601 week label, e.g. "2026-W28". */
 declare function isoWeek(d: Date): string;
 
-export { Attribution, COHORTS, CaptureErrorOptions, Cohort, type CohortDef, Dsn, EVENTS, type ErrorIdentity, type EventName, FUNNELS, type FunnelDef, type FunnelId, type FunnelStep, GOALS, type GoalDef, PAGEVIEW, PRODUCTS, PRODUCT_PROJECT, type ProductId, SentryEvent, SentryFrame, VERSION, buildEnvelope, buildSentryEvent, deriveChannel, dsnForProduct, eventsOf, framesFromStack, getCohort, getFirstTouch, hasAttribution, hostOf, isoWeek, parseAttribution, parseDsn, redactSecrets, scrubPII, scrubText, hzUuidv7 as uuidv7, uuidv7Time };
+export { Attribution, COHORTS, CaptureErrorOptions, Cohort, type CohortDef, Dsn, EVENTS, EXCEPTION, type ErrorIdentity, type EventName, ExceptionEntry, ExceptionProperties, FUNNELS, type FunnelDef, type FunnelId, type FunnelStep, GOALS, type GoalDef, PAGEVIEW, PRODUCTS, PRODUCT_PROJECT, type ProductId, SentryEvent, SentryFrame, SentryLevel, VERSION, buildEnvelope, buildSentryEvent, deriveChannel, digest, dsnForProduct, eventsOf, exceptionEntry, exceptionProperties, fingerprint, framesFromStack, getCohort, getFirstTouch, hasAttribution, hostOf, isoWeek, parseAttribution, parseDsn, redactSecrets, scrubPII, scrubText, hzUuidv7 as uuidv7, uuidv7Time };

package/dist/index.d.ts

@@ -1,12 +1,12 @@
-import { C as Cohort, A as Attribution, S as SentryEvent, D as Dsn, a as CaptureErrorOptions, b as SentryFrame } from './core-D4PaPlOB.js';
-export { c as Analytics, d as AnalyticsConfig, E as EventKind, e as Exception, f as SentryLevel, T as Transport, W as WireEvent, g as createAnalytics } from './core-D4PaPlOB.js';
+import { C as Cohort, A as Attribution, S as SentryEvent, D as Dsn, a as CaptureErrorOptions, b as SentryFrame, E as ExceptionEntry, c as SentryLevel, d as ExceptionProperties } from './core-CHLpJy51.js';
+export { e as Analytics, f as AnalyticsConfig, g as EventKind, h as Exception, i as ExceptionFrame, T as Transport, W as WireEvent, j as createAnalytics } from './core-CHLpJy51.js';
 
 /** Read the persisted first-touch attribution. */
 declare function getFirstTouch(): Attribution | undefined;
 /** Read persisted cohort dimensions. */
 declare function getCohort(): Cohort | undefined;
 
-declare const VERSION = "0.3.19";
+declare const VERSION = "0.3.21";
 
 /**
  * parseDsn parses "https://<version>:<hmac>@<host>/v1/sentry/<projectId>" into its
@@ -110,12 +110,15 @@ declare function uuidv7Time(id: string): number;
  *  project — an explicit map, because the projects predate this and do not derive
  *  cleanly from the product name. */
 declare const PRODUCT_PROJECT: Readonly<Record<string, string>>;
-/** dsnForProduct builds the product's Sentry DSN — the ONE org publishable key at
- *  its project's envelope endpoint — or undefined when the product has no project
- *  yet, which leaves the error plane inert rather than posting into the wrong one.
- *  Same key as the event stream: cloud resolves it to the org and attributes the
- *  errors there. */
-declare function dsnForProduct(product: string | undefined): string | undefined;
+/** dsnForProduct builds the product's Sentry DSN from the caller's resolved
+ *  publishable `key` and the product's project — the SAME key the event stream
+ *  carries, at the product's envelope endpoint. Returns undefined when there is no
+ *  key or no project for the product, leaving the error plane inert rather than
+ *  posting into the wrong one. The key is NOT baked here: it is the value the
+ *  surface resolved (an explicit `ingestKey`, or the KMS-sourced
+ *  NEXT_PUBLIC_PUBLISHABLE_KEY the build inlines) — the ONE live source, never a
+ *  literal committed beside the code. */
+declare function dsnForProduct(product: string | undefined, key: string | undefined): string | undefined;
 
 /** redactSecrets removes known secret shapes. Always applied. */
 declare function redactSecrets(s: string): string;
@@ -170,6 +173,59 @@ declare const EVENTS: {
 type EventName = (typeof EVENTS)[keyof typeof EVENTS];
 /** The reserved event name a pageview is stored under (server + read lens). */
 declare const PAGEVIEW = "$pageview";
+/** The reserved name every captured exception is emitted under. Error Tracking
+ *  reads exactly this name; an exception emitted under its own message instead
+ *  makes every distinct message a permanent entry in the event taxonomy. */
+declare const EXCEPTION = "$exception";
+
+/**
+ * digest is a stable 32-hex-char (128-bit) content hash, computed synchronously.
+ *
+ * Grouping keys are needed on the capture path, which is synchronous and may be
+ * running inside an unload handler — SubtleCrypto is async and unavailable on
+ * insecure origins, so it cannot be used here. This is FNV-1a run over four seeds
+ * and concatenated. It is a GROUPING key, never a security boundary: it is not
+ * collision-resistant against a chosen-input adversary, and nothing authorizes or
+ * authenticates on it. The product treats the value as opaque.
+ */
+declare function digest(s: string): string;
+/**
+ * exceptionEntry builds the single `$exception_list` entry for a throwable.
+ *
+ * One entry, not a chain: `Error.cause` chaining is a distinct fact with its own
+ * ordering rules, and emitting it wrongly is worse than not emitting it.
+ */
+declare function exceptionEntry(err: unknown, opts: {
+    handled: boolean;
+    id: string;
+}): ExceptionEntry;
+/**
+ * fingerprint is the issue grouping key.
+ *
+ * Keyed on exception type plus each in-app frame's function and source — the same
+ * pieces the server-side grouper records ("Exception Type", "Resolved function
+ * name", "Source file name"). Deliberately NOT the message: `Loading chunk 3324
+ * failed` and `Loading chunk 998 failed` are one bug, and grouping on message is
+ * precisely the mistake that made every distinct error string its own event name.
+ *
+ * Falls back to the type alone when no in-app frame survived, which keeps
+ * stackless errors (`Script error.`, cross-origin) in one issue instead of
+ * scattering them.
+ */
+declare function fingerprint(entry: ExceptionEntry): string;
+/**
+ * exceptionProperties builds the full `$exception_*` property bag for one captured
+ * throwable — everything Error Tracking reads off the event.
+ *
+ * The denormalized arrays are ordered like `frames`: last element is the throw
+ * site, which is the element the issue list indexes at -1 for its source/function
+ * columns.
+ */
+declare function exceptionProperties(err: unknown, opts: {
+    handled: boolean;
+    id: string;
+    level?: SentryLevel;
+}): ExceptionProperties;
 
 /** The emitting surfaces — the closed set of `AnalyticsConfig.product` values.
  *  `product` is on every event, so a funnel scopes by product instead of every
@@ -297,4 +353,4 @@ declare function hasAttribution(a: Attribution): boolean;
 /** isoWeek returns the ISO-8601 week label, e.g. "2026-W28". */
 declare function isoWeek(d: Date): string;
 
-export { Attribution, COHORTS, CaptureErrorOptions, Cohort, type CohortDef, Dsn, EVENTS, type ErrorIdentity, type EventName, FUNNELS, type FunnelDef, type FunnelId, type FunnelStep, GOALS, type GoalDef, PAGEVIEW, PRODUCTS, PRODUCT_PROJECT, type ProductId, SentryEvent, SentryFrame, VERSION, buildEnvelope, buildSentryEvent, deriveChannel, dsnForProduct, eventsOf, framesFromStack, getCohort, getFirstTouch, hasAttribution, hostOf, isoWeek, parseAttribution, parseDsn, redactSecrets, scrubPII, scrubText, hzUuidv7 as uuidv7, uuidv7Time };
+export { Attribution, COHORTS, CaptureErrorOptions, Cohort, type CohortDef, Dsn, EVENTS, EXCEPTION, type ErrorIdentity, type EventName, ExceptionEntry, ExceptionProperties, FUNNELS, type FunnelDef, type FunnelId, type FunnelStep, GOALS, type GoalDef, PAGEVIEW, PRODUCTS, PRODUCT_PROJECT, type ProductId, SentryEvent, SentryFrame, SentryLevel, VERSION, buildEnvelope, buildSentryEvent, deriveChannel, digest, dsnForProduct, eventsOf, exceptionEntry, exceptionProperties, fingerprint, framesFromStack, getCohort, getFirstTouch, hasAttribution, hostOf, isoWeek, parseAttribution, parseDsn, redactSecrets, scrubPII, scrubText, hzUuidv7 as uuidv7, uuidv7Time };

package/dist/index.mjs

@@ -80,15 +80,11 @@ var PRODUCT_PROJECT = Object.freeze({
   site: "019f9b1e-5785-7359-ad0b-f75db8e58c99"
   // hanzo.ai (marketing; product `site`)
 });
-function dsnForProduct(product) {
-  if (!product) return void 0;
+function dsnForProduct(product, key) {
+  if (!product || !key) return void 0;
   const projectId = PRODUCT_PROJECT[product];
   if (!projectId) return void 0;
-  return `https://${HANZO_PUBLISHABLE_KEY}@api.hanzo.ai/v1/sentry/${projectId}`;
-}
-var HANZO_PUBLISHABLE_KEY = "pk-live-c88649f1085fb6ad441d8a0072933a9b";
-function defaultPublishableKey(host) {
-  return host === void 0 || host === "https://api.hanzo.ai" ? HANZO_PUBLISHABLE_KEY : void 0;
+  return `https://${key}@api.hanzo.ai/v1/sentry/${projectId}`;
 }
 
 // src/events.ts
@@ -142,6 +138,7 @@ var EVENTS = {
   DEPLOY_FAILED: "deploy_failed"
 };
 var PAGEVIEW = "$pageview";
+var EXCEPTION = "$exception";
 
 // src/scrub.ts
 var REDACTED = "[redacted]";
@@ -371,7 +368,7 @@ function uuidv7Time(id) {
 }
 
 // src/version.ts
-var VERSION = "0.3.19";
+var VERSION = "0.3.21";
 
 // src/sentry.ts
 var MAX_FRAMES = 50;
@@ -563,6 +560,94 @@ ${itemHeader}
 ${payload}
 `;
 }
+var MAX_VALUE = 4096;
+function digest(s2) {
+  let out = "";
+  for (const seed of [2166136261, 16777619, 2654435769, 2246822507]) {
+    let h = seed >>> 0;
+    for (let i = 0; i < s2.length; i++) {
+      h ^= s2.charCodeAt(i);
+      h = h + (h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24) >>> 0;
+    }
+    out += h.toString(16).padStart(8, "0");
+  }
+  return out;
+}
+function frameOf(f) {
+  const source = f.filename ?? "";
+  const name = f.function ?? "<anonymous>";
+  const line = f.lineno ?? 0;
+  const column = f.colno ?? 0;
+  return {
+    // Stable per code location, so the same frame groups and re-renders under one
+    // key. The '/part' suffix is the product's format for one raw frame expanding
+    // into several resolved ones; a browser frame is always part 0.
+    raw_id: `${digest(`${source}|${name}|${line}|${column}`)}/0`,
+    mangled_name: name,
+    source,
+    line,
+    column,
+    in_app: f.in_app ?? false,
+    lang: "javascript",
+    resolved: false,
+    resolve_failure: "no symbol set uploaded for this release",
+    resolved_name: null,
+    module: null
+  };
+}
+function truncate2(s2, max) {
+  if (s2.length <= max) return s2;
+  let end = max;
+  const c = s2.charCodeAt(end - 1);
+  if (c >= 55296 && c <= 56319) end--;
+  return s2.slice(0, end);
+}
+function exceptionEntry(err, opts) {
+  const n = normalizeError(err);
+  const frames = framesFromStack(n.stack).slice(-50);
+  const entry = {
+    id: opts.id,
+    type: n.name,
+    value: truncate2(n.message, MAX_VALUE),
+    mechanism: {
+      type: "generic",
+      handled: opts.handled,
+      // An exception the app reported by hand was constructed, not thrown by the
+      // runtime at a real call site.
+      synthetic: !(err instanceof Error)
+    }
+  };
+  if (frames.length > 0) {
+    entry.stacktrace = { type: "resolved", frames: frames.map(frameOf) };
+  }
+  return entry;
+}
+function fingerprint(entry) {
+  const frames = entry.stacktrace?.frames ?? [];
+  const pieces = frames.filter((f) => f.in_app).map((f) => `${f.mangled_name}@${f.source}`);
+  return digest([entry.type, ...pieces].join("\n"));
+}
+function exceptionProperties(err, opts) {
+  const entry = exceptionEntry(err, opts);
+  const frames = entry.stacktrace?.frames ?? [];
+  const fp = fingerprint(entry);
+  return {
+    $exception_list: [entry],
+    $exception_fingerprint: fp,
+    // Records WHY this fingerprint holds. 'manual' is the honest value: the client
+    // supplied the key rather than a server grouper deriving one.
+    $exception_fingerprint_record: [{ type: "manual" }],
+    $exception_type: entry.type,
+    $exception_message: entry.value,
+    $exception_level: opts.level ?? "error",
+    $exception_handled: opts.handled,
+    $exception_synthetic: entry.mechanism?.synthetic ?? false,
+    $exception_types: [entry.type],
+    $exception_values: [entry.value],
+    $exception_sources: frames.map((f) => f.source).filter((s2) => !!s2),
+    $exception_functions: frames.map((f) => f.resolved_name ?? f.mangled_name).filter((s2) => !!s2)
+  };
+}
 
 // src/storage.ts
 var KEY = {
@@ -734,27 +819,24 @@ var Analytics = class {
       enabled: true,
       captureErrors: true,
       ...config,
-      // The publishable key resolves the SAME way the DSN below does, and now
-      // ends the SAME way too — in a baked default, so declaring nothing is
-      // enough. Most specific first:
+      // The publishable key resolves from ONE live source, never a literal baked
+      // beside the code. Most specific first:
       //   1. an explicit `ingestKey` in config;
       //   2. NEXT_PUBLIC_PUBLISHABLE_KEY, the inlined build-time env the fleet
-      //      carries end to end (KMS `deploy/PUBLISHABLE_KEY` -> the PUBLISHABLE_KEY
-      //      build-arg -> the NEXT_PUBLIC_ prefix Next inlines);
-      //   3. the hanzo org key baked in `dsn.ts`, on the hanzo cloud only.
+      //      carries end to end — KMS `deploy/PUBLISHABLE_KEY` -> the PUBLISHABLE_KEY
+      //      build-arg -> the NEXT_PUBLIC_ prefix Next inlines.
       //
-      // (3) is why this is `publishable_key for all`: a hanzo surface that passes
-      // no key in code and inlines no env still emits attributed, exactly as
-      // declaring `product` is enough for the DSN. Without it that surface sent
-      // its beacons to `$public` — which drops every track/identify/group and
-      // still answers 200 — silent in the page and invisible until you read the
-      // warehouse and find the host missing entirely. A white-label surface on
-      // its own cloud (a non-default host) gets no default, so the org this
-      // attributes to is never the wrong one.
-      ingestKey: config.ingestKey ?? readEnv("NEXT_PUBLIC_PUBLISHABLE_KEY") ?? defaultPublishableKey(config.host ?? DEFAULT_HOST)
+      // A surface that provides neither has no key, and its anonymous traffic
+      // files under `$public` (which drops track/identify/group and answers 200);
+      // the fix is to give it the KMS-sourced env, not to hardcode the org key
+      // here. The key is a credential-class value: its home is KMS, and the ONE
+      // build reads it from there.
+      ingestKey: config.ingestKey ?? readEnv("NEXT_PUBLIC_PUBLISHABLE_KEY")
     };
     this.transport = config.transport ?? new DefaultTransport();
-    this.dsn = parseDsn(config.dsn ?? readEnvDsn() ?? dsnForProduct(this.cfg.product));
+    this.dsn = parseDsn(
+      config.dsn ?? readEnvDsn() ?? dsnForProduct(this.cfg.product, this.cfg.ingestKey)
+    );
   }
   /** errorPlaneEnabled reports whether captured exceptions can actually reach the
    *  error host. False means a DSN was never configured — the documented
@@ -839,9 +921,20 @@ var Analytics = class {
       } catch {
       }
       try {
+        const handled = context?.handled ?? true;
         const ex = normalizeError2(err);
-        ex.handled = context?.handled ?? true;
-        this.enqueue("error", ex.message, { error: ex, properties: context?.properties });
+        ex.handled = handled;
+        this.enqueue("event", EXCEPTION, {
+          error: ex,
+          properties: {
+            ...context?.properties,
+            ...exceptionProperties(err, {
+              handled,
+              id: hzUuidv7(),
+              level: context?.level
+            })
+          }
+        });
         this.flush();
       } catch {
       }
@@ -1148,6 +1241,6 @@ var COHORTS = {
  * reformat of one copy is a diff against the other.
  */
 
-export { Analytics, COHORTS, EVENTS, FUNNELS, GOALS, PAGEVIEW, PRODUCTS, PRODUCT_PROJECT, VERSION, buildEnvelope, buildSentryEvent, createAnalytics, deriveChannel, dsnForProduct, eventsOf, framesFromStack, getCohort, getFirstTouch, hasAttribution, hostOf, isoWeek, parseAttribution, parseDsn, redactSecrets, scrubPII, scrubText, hzUuidv7 as uuidv7, uuidv7Time };
+export { Analytics, COHORTS, EVENTS, EXCEPTION, FUNNELS, GOALS, PAGEVIEW, PRODUCTS, PRODUCT_PROJECT, VERSION, buildEnvelope, buildSentryEvent, createAnalytics, deriveChannel, digest, dsnForProduct, eventsOf, exceptionEntry, exceptionProperties, fingerprint, framesFromStack, getCohort, getFirstTouch, hasAttribution, hostOf, isoWeek, parseAttribution, parseDsn, redactSecrets, scrubPII, scrubText, hzUuidv7 as uuidv7, uuidv7Time };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map