@hanzo/event 0.3.1 → 0.3.3

package/dist/index.d.ts

@@ -1,16 +1,84 @@
-import { C as Cohort, A as Attribution } from './core-CrbiAQhN.js';
-export { a as Analytics, b as AnalyticsConfig, E as EventKind, c as Exception, T as Transport, V as VERSION, W as WireEvent, d as createAnalytics } from './core-CrbiAQhN.js';
+import { C as Cohort, A as Attribution, S as SentryEvent, D as Dsn, a as CaptureErrorOptions, b as SentryFrame } from './core-B1XEdWLd.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-B1XEdWLd.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.3";
+
+/**
+ * parseDsn parses "https://<version>:<hmac>@<host>/v1/sentry/<projectId>" into its
+ * public key + the derived envelope ingest URL. The key (which itself contains a
+ * ':') is taken verbatim as the userinfo — we do NOT split it as user:pass. The
+ * key rides ?sentry_key= (not the DSN in the body) because that is the credential
+ * channel the server trusts AND the only one sendBeacon can carry on unload.
+ * Returns null for anything malformed (fail-safe: the caller then stays inert).
+ */
+declare function parseDsn(dsn: string | undefined | null): Dsn | null;
+/**
+ * framesFromStack parses a browser Error.stack into Sentry frames, OLDEST-FIRST
+ * (Sentry orders caller->callee; the crash site is last — matching the server's
+ * pickCrashFrame). Handles both V8 ("at fn (file:li:co)") and
+ * Firefox/Safari ("fn@file:li:co"). Unparseable lines are skipped.
+ */
+declare function framesFromStack(stack: string | undefined): SentryFrame[];
+/** Identity carried onto every error event — the SAME ids analytics uses. */
+interface ErrorIdentity {
+    /** OIDC sub (post-identify) or anon id. NEVER email/PII. */
+    userId?: string;
+    sessionId?: string;
+    product?: string;
+    release?: string;
+    environment?: string;
+}
+interface BuildEventInput {
+    error: unknown;
+    options?: CaptureErrorOptions;
+    identity: ErrorIdentity;
+    capturePII?: boolean;
+    /** Injectable for deterministic tests. */
+    now?: number;
+    id?: string;
+}
+/**
+ * buildSentryEvent turns a throwable + identity into a Sentry `event`. The message
+ * (the leak surface) is scrubbed client-side; the user is ONLY the stable subject
+ * id — never email/username/ip. Level defaults to error, or fatal for uncaught.
+ */
+declare function buildSentryEvent(input: BuildEventInput): SentryEvent;
+/**
+ * buildEnvelope frames a Sentry event into a newline-delimited envelope:
+ *
+ *   {"event_id","dsn","sent_at"}\n
+ *   {"type":"event","content_type":"application/json","length":N}\n
+ *   <event json>\n
+ *
+ * The item is length-delimited (N = UTF-8 byte length) — the framing the server's
+ * parseEnvelope reads first (falling back to newline-delimited otherwise).
+ */
+declare function buildEnvelope(event: SentryEvent, dsn: Dsn, sentAt?: string): string;
+
+/** redactSecrets removes known secret shapes. Always applied. */
+declare function redactSecrets(s: string): string;
+/** scrubPII masks emails and IPs. Applied unless PII capture is enabled. */
+declare function scrubPII(s: string): string;
+/** scrubText applies the redaction policy to a free-text field. Input is capped
+ *  first: unbounded text is a denial-of-service surface, not just a size problem. */
+declare function scrubText(s: string | undefined, capturePII?: boolean): string;
+
 declare const EVENTS: {
     readonly SIGNUP_VIEWED: "signup_viewed";
     readonly SIGNUP_SUBMITTED: "signup_submitted";
     readonly SIGNUP_VERIFIED: "signup_verified";
     readonly SIGNUP_COMPLETED: "signup_completed";
+    /** A RETURNING user authenticated — the non-signup half of the IAM callback.
+     *  Keeping it distinct is what stops returning logins from inflating signups. */
+    readonly LOGIN_COMPLETED: "login_completed";
+    /** Activation: the first moment of real value. ONE event for every product —
+     *  the product-specific moment is the `action` property (api_call, app_live,
+     *  chat_reply), never a new event name. */
     readonly FIRST_ACTION: "first_action";
     readonly WAITLIST_JOINED: "waitlist_joined";
     readonly WAITLIST_SHARED: "waitlist_shared";
@@ -23,24 +91,127 @@ declare const EVENTS: {
     readonly FEATURE_USED: "feature_used";
     readonly API_KEY_CREATED: "api_key_created";
     readonly APP_CREATED: "app_created";
-    readonly DEPLOY_STARTED: "deploy_started";
     readonly PROJECT_CREATED: "project_created";
     readonly AGENT_CREATED: "agent_created";
     readonly CHAT_STARTED: "chat_started";
     readonly CHAT_MESSAGE_SENT: "chat_message_sent";
+    /** The user switched model/endpoint — the single strongest quality signal a
+     *  chat surface emits (a switch usually follows a bad answer). */
+    readonly MODEL_SWITCHED: "model_switched";
     readonly TASK_STARTED: "task_started";
     readonly TASK_COMPLETED: "task_completed";
+    readonly BUILD_STARTED: "build_started";
+    /** A model finished producing an artifact (an app build, a chat reply, an agent
+     *  run). Carries `durationMs` — the outcome event owns its own duration, so no
+     *  paired start event is needed. */
+    readonly GENERATION_COMPLETED: "generation_completed";
+    readonly GENERATION_FAILED: "generation_failed";
+    readonly DEPLOY_STARTED: "deploy_started";
+    readonly DEPLOY_SUCCEEDED: "deploy_succeeded";
+    readonly DEPLOY_FAILED: "deploy_failed";
 };
 type EventName = (typeof EVENTS)[keyof typeof EVENTS];
 /** The reserved event name a pageview is stored under (server + read lens). */
 declare const PAGEVIEW = "$pageview";
 
+/** The emitting surfaces — the closed set of `AnalyticsConfig.product` values.
+ *  `product` is on every event, so a funnel scopes by product instead of every
+ *  surface prefixing its event names. */
+declare const PRODUCTS: readonly ["site", "app", "chat", "console", "admin", "cloud"];
+type ProductId = (typeof PRODUCTS)[number];
+interface FunnelStep {
+    /** An EVENTS value (or PAGEVIEW). */
+    event: string;
+    /** Human label for the Insights step. */
+    label: string;
+    /** Property equality that qualifies the step, e.g. first_action{action:'api_call'}. */
+    where?: {
+        property: string;
+        equals: string;
+    };
+}
+interface FunnelDef {
+    label: string;
+    /** Surface(s) the steps are emitted from — matched against the `product` field. */
+    products: ProductId[];
+    /**
+     * How steps are joined:
+     *  • 'person'    — steps join on distinctId (one browser, or one logged-in
+     *                  person across surfaces). The normal case.
+     *  • 'aggregate' — steps are emitted on DIFFERENT origins by a LOGGED-OUT
+     *                  visitor, so there is no shared id: hanzo.ai, hanzo.app and
+     *                  hanzo.chat each mint their own anonymousId in their own
+     *                  storage. Read these as step-over-step COUNTS, never as a
+     *                  per-person conversion. Honest by construction.
+     */
+    join: 'person' | 'aggregate';
+    steps: FunnelStep[];
+}
+declare const FUNNELS: {
+    /** hanzo.ai: land → sign up. IAM hosts the form, so `signup_submitted` is the
+     *  redirect INTO IAM and `signup_completed` is the return at /auth/callback. */
+    readonly signup: {
+        readonly label: "Signup";
+        readonly products: ["site"];
+        readonly join: "person";
+        readonly steps: [FunnelStep, FunnelStep, FunnelStep, FunnelStep, FunnelStep];
+    };
+    /** The developer activation path: an account is worth nothing until a key has
+     *  made a call. `first_action{action:'api_call'}` is emitted SERVER-SIDE by
+     *  Cloud on an org's first successful /v1 request — a browser cannot see it. */
+    readonly apiActivation: {
+        readonly label: "API activation";
+        readonly products: ["site", "cloud"];
+        readonly join: "person";
+        readonly steps: [FunnelStep, FunnelStep, FunnelStep];
+    };
+    /** Upgrade intent → revenue. `order_completed{kind:'plan'}` is the Sale goal. */
+    readonly upgrade: {
+        readonly label: "Upgrade";
+        readonly products: ["site", "app", "console"];
+        readonly join: "person";
+        readonly steps: [FunnelStep, FunnelStep, FunnelStep, FunnelStep];
+    };
+    /** hanzo.app: describe → build → deploy → live URL. The whole product thesis
+     *  in five steps; `deploy_succeeded` is the moment a live URL exists. */
+    readonly appShip: {
+        readonly label: "Describe → ship";
+        readonly products: ["app"];
+        readonly join: "person";
+        readonly steps: [FunnelStep, FunnelStep, FunnelStep, FunnelStep, FunnelStep];
+    };
+    /** hanzo.chat: visit → first message → answer. `generation_completed` is what
+     *  separates "typed something" from "got value". */
+    readonly chatEngage: {
+        readonly label: "Chat engagement";
+        readonly products: ["chat"];
+        readonly join: "person";
+        readonly steps: [FunnelStep, FunnelStep, FunnelStep, FunnelStep];
+    };
+    /** The cross-surface handoff: the hanzo.ai composer forwards its prompt to
+     *  hanzo.chat. Two origins, two anonymousIds — so this is an AGGREGATE funnel.
+     *  The join is the `referrerProduct` property hanzo.chat reads off `?hz_ref=`,
+     *  which makes the drop-off measurable without any cross-domain identity. */
+    readonly siteToChat: {
+        readonly label: "Site → Chat handoff";
+        readonly products: ["site", "chat"];
+        readonly join: "aggregate";
+        readonly steps: [FunnelStep, FunnelStep, FunnelStep];
+    };
+};
+type FunnelId = keyof typeof FUNNELS;
+/** eventsOf flattens a funnel to its ordered event names — what a goal's `funnel`
+ *  field carries, so the steps are defined exactly once (here). */
+declare function eventsOf(id: FunnelId): string[];
+
 interface GoalDef {
     /** Human label shown in Insights. */
     label: string;
     /** The event whose occurrence counts as the goal conversion. */
     event: string;
-    /** Optional ordered funnel leading to the goal (for funnel insights). */
+    /** The funnel leading to the goal — an id into FUNNELS (see funnels.ts). */
+    funnelId?: FunnelId;
+    /** The ordered event names of `funnelId`, derived — never hand-written. */
     funnel?: string[];
     /** Optional property equality filter that qualifies the conversion. */
     filter?: {
@@ -48,7 +219,7 @@ interface GoalDef {
         equals: string;
     };
 }
-declare const GOALS: Record<'signup' | 'sale' | 'upgradeIntent', GoalDef>;
+declare const GOALS: Record<'signup' | 'sale' | 'upgradeIntent' | 'activation', GoalDef>;
 interface CohortDef {
     /** The hanzo.events column the cohort dimension maps to. */
     field: string;
@@ -69,4 +240,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, Cohort, type CohortDef, EVENTS, type EventName, GOALS, type GoalDef, PAGEVIEW, deriveChannel, getCohort, getFirstTouch, hasAttribution, hostOf, isoWeek, parseAttribution };
+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, type ProductId, SentryEvent, SentryFrame, VERSION, buildEnvelope, buildSentryEvent, deriveChannel, eventsOf, framesFromStack, getCohort, getFirstTouch, hasAttribution, hostOf, isoWeek, parseAttribution, parseDsn, redactSecrets, scrubPII, scrubText };