@hanzo/event 0.3.2 → 0.3.4

package/dist/index.d.ts

@@ -6,7 +6,7 @@ declare function getFirstTouch(): Attribution | undefined;
 /** Read persisted cohort dimensions. */
 declare function getCohort(): Cohort | undefined;
 
-declare const VERSION = "0.3.2";
+declare const VERSION = "0.3.3";
 
 /**
  * parseDsn parses "https://<version>:<hmac>@<host>/v1/sentry/<projectId>" into its
@@ -60,6 +60,39 @@ declare function buildSentryEvent(input: BuildEventInput): SentryEvent;
  */
 declare function buildEnvelope(event: SentryEvent, dsn: Dsn, sentAt?: string): string;
 
+/**
+ * The product → Sentry DSN registry.
+ *
+ * An app declares WHAT it is (`product: 'console'`); this module knows WHERE its
+ * errors go. That split is the whole point: no surface has to learn a DSN, carry
+ * a build argument, or grow a config file to report errors — declaring the
+ * product it already declares is enough.
+ *
+ * A Sentry DSN is PUBLIC by construction. It ships inside the client bundle and
+ * is readable in devtools on any deployed page, and it grants exactly one
+ * capability: submitting new events. It cannot read issues, projects, or any
+ * other data. So committing it is not leaking a secret — it is recording a public
+ * identifier next to the code that needs it. (Contrast the server-side collector
+ * DSN in the `team-analytics-sentry` Secret, which is HMAC-derived and revocable
+ * precisely because a server-side credential is NOT public.)
+ *
+ * Why a literal map instead of deriving `hanzo-${product}`: the projects predate
+ * this registry and do not derive cleanly — `site` lives in `hanzo-ai`, not
+ * `hanzo-site`. An explicit map is honest about that; a derivation rule plus an
+ * exception table is the same data with a trap in it.
+ *
+ * Projects are org-scoped and named `<org>-<app>`. To add one: create the project
+ * (POST /v1/sentry/projects with X-Org-Id), then add its `dsn` here keyed by the
+ * product name the app passes to `createAnalytics`.
+ */
+/** PRODUCT_DSN maps a `product` to the DSN its errors are submitted to. */
+declare const PRODUCT_DSN: Readonly<Record<string, string>>;
+/** dsnForProduct resolves the registered DSN for a product, or undefined when the
+ *  product has no project yet — which leaves the error plane inert rather than
+ *  guessing a destination and silently posting a surface's errors into the wrong
+ *  project. */
+declare function dsnForProduct(product: string | undefined): string | undefined;
+
 /** redactSecrets removes known secret shapes. Always applied. */
 declare function redactSecrets(s: string): string;
 /** scrubPII masks emails and IPs. Applied unless PII capture is enabled. */
@@ -73,6 +106,12 @@ declare const EVENTS: {
     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";
@@ -85,24 +124,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?: {
@@ -110,7 +252,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;
@@ -131,4 +273,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, GOALS, type GoalDef, PAGEVIEW, SentryEvent, SentryFrame, VERSION, buildEnvelope, buildSentryEvent, deriveChannel, framesFromStack, getCohort, getFirstTouch, hasAttribution, hostOf, isoWeek, parseAttribution, parseDsn, redactSecrets, scrubPII, scrubText };
+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_DSN, type ProductId, SentryEvent, SentryFrame, VERSION, buildEnvelope, buildSentryEvent, deriveChannel, dsnForProduct, eventsOf, framesFromStack, getCohort, getFirstTouch, hasAttribution, hostOf, isoWeek, parseAttribution, parseDsn, redactSecrets, scrubPII, scrubText };