@mushi-mushi/core 1.27.2 → 1.29.0

package/dist/index.d.ts

@@ -26,6 +26,22 @@ interface MushiConfig {
      * host apps. Set false for fully static/offline deployments.
      */
     runtimeConfig?: boolean | 'auto';
+    /**
+     * Product analytics (`Mushi.track()`, Users & Funnels). Enabled by default
+     * and keyed on the same opaque per-project reporter token as sessions;
+     * honours DNT / GPC. Set `enabled: false` to opt out, or
+     * `consent: 'required'` to buffer until `setConsent('granted')`.
+     * Session tracking passes the same gate: `enabled`, DNT / GPC, bot
+     * exclusion and consent all apply to it too.
+     */
+    analytics?: MushiAnalyticsConfig;
+    /**
+     * Session lifecycle tracking for the console's Activity and Users views
+     * (session start / heartbeat / end, page views). Default true. Runs only
+     * while the `analytics` gate allows tracking; `false` turns it off even
+     * then.
+     */
+    trackSessions?: boolean;
     sentry?: MushiSentryConfig;
     widget?: MushiWidgetConfig;
     capture?: MushiCaptureConfig;
@@ -46,6 +62,31 @@ interface MushiConfig {
      * when omitted (legacy Vercel Analytics wiring).
      */
     appVersion?: string;
+    /**
+     * Same-origin (or absolute) ingest proxy. When set, every SDK HTTP call
+     * goes here instead of `apiEndpoint` so ad blockers that drop third-party
+     * `*.supabase.co/functions` hosts cannot silently eat reports.
+     * Relative URLs resolve against the page origin — that is the recommended
+     * form (no CORS preflight; matches Sentry `tunnel`).
+     *
+     * @example
+     * tunnel: '/api/mushi-tunnel'
+     */
+    tunnel?: string;
+    /**
+     * Drop automatic error reports whose message matches any string (substring)
+     * or RegExp. Never applied to user-submitted widget feedback.
+     */
+    ignoreErrors?: Array<string | RegExp>;
+    /**
+     * Drop automatic error reports whose script URL / stack filename matches.
+     */
+    denyUrls?: Array<string | RegExp>;
+    /**
+     * When set, drop automatic error reports unless the script URL matches
+     * at least one entry.
+     */
+    allowUrls?: Array<string | RegExp>;
     /**
      * Probabilistic sampling rate for session-replay recording (rrweb/lite).
      * Range 0–1, default 1 (record all sessions). The sampling decision is made
@@ -59,6 +100,13 @@ interface MushiConfig {
      * replaySampleRate: 0.2  // record replay for ~20% of sessions
      */
     replaySampleRate?: number;
+    /**
+     * When session replay was sampled out, still start the rolling buffer for
+     * this fraction of sessions (0–1, default 0) so an error/feedback report
+     * can attach replay. Keep at 0 unless you have accepted the CPU/egress
+     * cost — do not set to 1 with `capture.replay: 'rrweb'`.
+     */
+    replaysOnErrorSampleRate?: number;
     /**
      * Probabilistic sampling rate for automatic (non-user-initiated) error
      * reports. Range 0–1, default 1 (send all). User-initiated feedback reports
@@ -166,7 +214,21 @@ interface MushiWidgetConfig {
         snapToEdge?: boolean;
         axis?: 'both' | 'x' | 'y';
     };
-    /** Show the tiny "Powered by Mushi vX" footer inside the widget panel. */
+    /**
+     * Show the "Bug reports by Mushi" mark at the bottom of the widget panel.
+     * It links to the Mushi site (`utm_source=widget&utm_medium=powered-by` plus
+     * an anonymous `ref` derived from a SHA-256 prefix of the project id) and
+     * feeds the `loop_impression` / `loop_click` analytics events.
+     *
+     * Precedence (most specific wins):
+     * 1. An explicit value here — the MIT SDK config is a hard override and
+     *    beats anything the runtime config sends.
+     * 2. `widget.brandFooter` from the runtime config (`GET /v1/sdk/config`):
+     *    Mushi Cloud sends `true` for Free Cloud projects and `false` for paid
+     *    plans; self-hosted servers send nothing. Opt out with one toggle in the
+     *    console project settings.
+     * 3. Default `false`.
+     */
     brandFooter?: boolean;
     /** How the widget should surface SDK freshness warnings. Defaults to auto. */
     outdatedBanner?: 'auto' | 'banner' | 'console-only' | 'off';
@@ -406,6 +468,24 @@ interface MushiCaptureConfig {
     screenshotProvider?: () => Promise<string | null>;
     elementSelector?: boolean;
     replay?: 'sentry' | 'rrweb' | 'lite' | 'off';
+    /**
+     * How to load rrweb for `replay: 'rrweb'`. A published SDK cannot import
+     * rrweb itself: its bare `import('rrweb')` is invisible to your bundler, so
+     * rrweb never makes it into your build. Hand the import over and your
+     * bundler code-splits it like any other dynamic import. Install `rrweb`
+     * yourself; the chunk loads only for sessions sampled into replay.
+     *
+     * Without a loader the SDK uses a global `rrweb` (the UMD build from a
+     * script tag) when one exists, and otherwise records lite replay (clicks)
+     * and warns once in the console. Recording masks every input and every
+     * text node.
+     *
+     * @example
+     * capture: { replay: 'rrweb', rrweb: () => import('rrweb') }
+     */
+    rrweb?: () => Promise<{
+        record?: unknown;
+    }>;
     /**
      * Mushi Mushi v2.1 (whitepaper §6 hybrid mode): passive inventory
      * discovery. When enabled the SDK observes navigations and emits a
@@ -1353,8 +1433,23 @@ interface MushiSDKInstance {
      * Manually record a host-defined activity event (e.g. 'lesson_completed').
      * The SDK batches these and flushes to POST /v1/sdk/activity.
      * No-op when rewards are disabled or the user has not opted in.
+     * For product analytics (funnels, paths, people) use `track()` instead.
      */
     recordActivity(action: string, metadata?: Record<string, unknown>): void;
+    /**
+     * Record a product-analytics event, e.g. `track('checkout_started', { plan: 'pro' })`.
+     * Names must match `^[a-z][a-z0-9_]{1,63}$`; properties are flat
+     * (string | number | boolean | null), PII-looking keys are dropped, and
+     * every string value runs through the PII scrubber. Batched to
+     * POST /v1/sdk/events. No-op under DNT/GPC, `analytics.enabled: false`,
+     * or before consent when `analytics.consent === 'required'`.
+     * Returns true when the event was queued.
+     */
+    track(event: string, properties?: Record<string, MushiPropertyValue>): boolean;
+    /** Grant or deny analytics consent (persisted per project in localStorage). */
+    setConsent(state: 'granted' | 'denied'): void;
+    /** The anonymous id analytics events are keyed on, or null when tracking is off. */
+    getAnonymousId(): string | null;
     /**
      * Briefly animate the bug-report trigger button to draw the user's
      * attention without opening the full widget. Ideal for subtle "feedback
@@ -1464,6 +1559,11 @@ interface MushiApiClient {
     postSessionEvent(payload: MushiSessionEventPayload): Promise<MushiApiResponse<{
         accepted: boolean;
     }>>;
+    /** POST /v1/sdk/events — batched product-analytics events (Mushi.track()). */
+    postProductEvents(payload: MushiProductEventPayload): Promise<MushiApiResponse<{
+        accepted: number;
+        dropped: number;
+    }>>;
     listReporterReports(reporterToken: string): Promise<MushiApiResponse<{
         reports: MushiReporterReport[];
     }>>;
@@ -1616,12 +1716,56 @@ interface MushiSessionEventPayload {
     user_agent?: string | null;
     sdk_version?: string;
 }
+type MushiPropertyValue = string | number | boolean | null;
+/** Configuration for `Mushi.track()` product analytics. */
+interface MushiAnalyticsConfig {
+    /** Master switch (default true). */
+    enabled?: boolean;
+    /** 'implied' (default) sends immediately; 'required' buffers until setConsent('granted'). */
+    consent?: 'implied' | 'required';
+    /** 0..1, decided once per person (default 1). */
+    sampleRate?: number;
+    /** Honour navigator.doNotTrack / globalPrivacyControl (default true). */
+    respectDoNotTrack?: boolean;
+    /**
+     * Skip tracking in WebDriver-controlled browsers (Playwright, Puppeteer,
+     * Selenium), headless Chrome, Lighthouse and crawler user agents, so test
+     * runs and bots never count as users (default true). Set false to exercise
+     * analytics from an end-to-end test.
+     */
+    excludeBots?: boolean;
+    /** Emit `pageview` on history navigation (default false; sessions already record page views). */
+    autoPageviews?: boolean;
+    /** Flush cadence in ms (default 5000, min 1000). */
+    flushIntervalMs?: number;
+    /** Property keys allowed through the PII key filter. */
+    propertyAllowlist?: string[];
+    /** Which surface these events come from (default 'web'). */
+    surface?: 'web' | 'console' | 'docs' | 'cli' | 'mcp' | 'server' | 'mobile';
+}
+/** Wire shape for POST /v1/sdk/events. */
+interface MushiProductEventPayload {
+    anon_id?: string | null;
+    user_id?: string | null;
+    user_traits?: Record<string, unknown> | null;
+    session_id?: string | null;
+    sdk_version?: string | null;
+    surface?: MushiAnalyticsConfig['surface'];
+    events: Array<{
+        name: string;
+        ts?: string;
+        properties?: Record<string, MushiPropertyValue>;
+        dedup_key?: string;
+    }>;
+}
 interface MushiApiResponse<T> {
     ok: boolean;
     data?: T;
+    /** `status` is the HTTP status when the server answered; absent for network errors. */
     error?: {
         code: string;
         message: string;
+        status?: number;
     };
 }
 interface MushiRuntimeSdkConfig {
@@ -1711,6 +1855,8 @@ interface MushiTesterReputation {
     total_points: number;
 }
 
+/** Replay the last POST via keepalive/beacon during pagehide. */
+declare function flushLastOutboundOnUnload(): boolean;
 /** Header carrying the signed end-user identity token (verified server-side). */
 declare const MUSHI_USER_TOKEN_HEADER = "X-Mushi-User-Token";
 /** Project scope header — paired with the API key on every SDK request. */
@@ -1759,14 +1905,101 @@ interface ApiClientOptions {
      * backend can verify it and scope identity-bound features to that user.
      */
     getUserToken?: () => string | null | undefined;
+    /**
+     * Same-origin (or absolute) proxy. When set, replaces `apiEndpoint` as the
+     * request base so browser calls stay first-party. See `MushiConfig.tunnel`.
+     */
+    tunnel?: string;
 }
 declare const DEFAULT_API_ENDPOINT = "https://dxptnwrhwsqckaftyymj.supabase.co/functions/v1/api";
 declare const MUSHI_INTERNAL_HEADER = "X-Mushi-Internal";
 declare const MUSHI_INTERNAL_INIT_MARKER = "__mushiInternal";
 type MushiInternalRequestKind = 'sdk-config' | 'report-submit' | 'report-status' | 'reporter-poll' | 'diagnose' | 'discovery' | 'community';
+/** Resolve the HTTP base: tunnel wins so ingest stays first-party. */
+declare function resolveRequestBaseUrl(apiEndpoint: string | undefined, tunnel?: string): string;
 declare const DEFAULT_TIMEOUT = 10000;
 declare const DEFAULT_MAX_RETRIES = 2;
 declare function createApiClient(options: ApiClientOptions): MushiApiClient;
+declare function getBackoffDelay(attempt: number): number;
+/**
+ * Parse a `Retry-After` header into a delay in milliseconds. The header comes
+ * in two shapes (RFC 9110): delta-seconds, or an HTTP-date to wait until.
+ * Returns null when the header is absent, malformed, or negative, so the
+ * caller falls back to its own backoff curve.
+ */
+declare function parseRetryAfter(value: string | null | undefined, now?: number): number | null;
+
+/**
+ * FILE: packages/core/src/error-filters.ts
+ * PURPOSE: Sentry-grade drop filters for automatic error capture.
+ *
+ * OVERVIEW:
+ * - ignoreErrors — drop when the error message matches a string or RegExp
+ * - denyUrls — drop when the script URL / stack frame matches
+ * - allowUrls — when set, drop unless the script URL matches at least one
+ *
+ * USAGE:
+ * - captureException / window.onerror / unhandledrejection only
+ * - Never applied to user-submitted widget feedback
+ *
+ * NOTES:
+ * - String matchers are case-sensitive substrings (Sentry JS semantics)
+ * - Invalid RegExp sources are treated as non-matches, not throws
+ */
+type MushiErrorFilter = string | RegExp;
+declare function matchesErrorFilter(value: string | undefined | null, filters: readonly MushiErrorFilter[] | undefined): boolean;
+declare function shouldDropCapturedError(input: {
+    message: string;
+    filename?: string | null;
+    ignoreErrors?: readonly MushiErrorFilter[];
+    denyUrls?: readonly MushiErrorFilter[];
+    allowUrls?: readonly MushiErrorFilter[];
+}): boolean;
+
+/**
+ * FILE: packages/core/src/unload-transport.ts
+ * PURPOSE: Pagehide-safe report delivery (fetch keepalive + sendBeacon).
+ *
+ * OVERVIEW:
+ * - fetch({ keepalive: true }) keeps custom X-Mushi-* headers (Sentry 2024+ primary)
+ * - sendBeacon cannot set headers, so it wraps credentials in a beacon envelope
+ *   that only the same-origin tunnel unwraps
+ *
+ * NOTES:
+ * - Beacon payloads over 60 KiB are skipped (browser sendBeacon limit ~64 KiB)
+ * - Never put the API key in the query string
+ */
+declare const MUSHI_BEACON_MAX_BYTES: number;
+interface MushiBeaconEnvelope {
+    mushiBeacon: true;
+    path: string;
+    headers: Record<string, string>;
+    body: unknown;
+}
+declare function isMushiBeaconEnvelope(value: unknown): value is MushiBeaconEnvelope;
+declare function buildBeaconEnvelope(opts: {
+    path: string;
+    headers: Record<string, string>;
+    body: unknown;
+}): MushiBeaconEnvelope;
+/** True when the URL is same-origin or relative (safe for sendBeacon + tunnel). */
+declare function isSameOriginOrRelative(url: string, origin?: string): boolean;
+declare function extractTunnelPath(url: string): string;
+interface SendOnUnloadOptions {
+    url: string;
+    headers: Record<string, string>;
+    body: string;
+    path?: string;
+    fetchImpl?: typeof fetch;
+    sendBeacon?: (url: string, data: Blob) => boolean;
+}
+/**
+ * Deliver one JSON POST during pagehide. Prefers fetch keepalive (headers).
+ * Falls back to sendBeacon with a credential envelope on same-origin URLs.
+ */
+declare function sendOnUnload(opts: SendOnUnloadOptions): boolean;
+declare function markPageUnloading(): void;
+declare function isPageUnloading(): boolean;
 
 /**
  * C7: Data residency region resolution.
@@ -2038,31 +2271,62 @@ declare function getSessionId(): string;
  * no offline queue, fire-and-forget after visibility-change.
  *
  * Privacy:
+ *   - Passes the same gate as product events (analytics-gate.ts): nothing is
+ *     sent when `analytics.enabled` is false, under DNT / GPC, in automation
+ *     or crawler browsers, or before consent is granted. A later
+ *     setConsent('granted') starts the session; 'denied' stops it mid-page.
  *   - No PII by default. `reporter_token_hash` is the same opaque device
  *     fingerprint already used in reports. `user_id_hash` is only set when
- *     the host app calls Mushi.identify().
+ *     the host app identifies the user.
+ *   - Routes are sent as the pathname only and the referrer as its origin, so
+ *     query strings (reset tokens, emails in links) never leave the page.
  *   - Respects the SDK-level `trackSessions: false` opt-out option.
- *   - Respects a DNT / Global Privacy Control header at the SDK init layer;
- *     callers should check `shouldRespectDnt()` before calling `initSession`.
+ *
+ * SPA page views:
+ *   The history patch below decides push-vs-replace at wrap time (comparing
+ *   against `history.pushState` inside the wrapper never matches, because by
+ *   then that property is the wrapper). Hosts that already own a history
+ *   patch (`@mushi-mushi/web`'s shared one) pass `patchHistory: false` and
+ *   call `trackPageView()` themselves — a second wrapper assigned to
+ *   `history.pushState` silently discards this one, which is how the web SDK
+ *   recorded zero SPA page views across >1,000 sessions per project.
  */
 
 interface SessionTrackerOptions {
     client: MushiApiClient;
     sdkVersion?: string;
+    /** The raw per-project reporter token; the server stores only its sha256. */
+    reporterToken?: string | null;
+    /** @deprecated Renamed to `reporterToken` (it always carried the raw token, never a hash). */
     reporterTokenHash?: string | null;
     userIdHash?: string | null;
+    /**
+     * Install the built-in `history.pushState` / `popstate` patch that emits
+     * `page_view` events. Default `true`. Pass `false` when the host already
+     * owns a history patch and will call `trackPageView()` itself — stacking a
+     * second wrapper on `history.pushState` is exactly how this tracker's page
+     * views got overwritten and silently dropped in `@mushi-mushi/web`.
+     */
+    patchHistory?: boolean;
+    /** Project the stored analytics consent is keyed on (the SDK passes its projectId). */
+    projectId?: string;
+    /** The SDK's `analytics` block: sessions pass the same gate as product events. */
+    analytics?: MushiAnalyticsConfig;
 }
 /**
  * Initialise the session tracker. Call once at SDK init for web environments.
  * Subsequent calls on the same page are no-ops (idempotent).
  *
- * Emits: session_start immediately, heartbeats every minute, session_end on
- * visibilitychange/pagehide, and page_view on history API navigation.
+ * Emits, once the analytics gate allows it: session_start, heartbeats every
+ * minute, session_end on visibilitychange/pagehide, and page_view on history
+ * API navigation. Under `consent: 'required'` nothing is sent until
+ * setConsent('granted').
  */
 declare function initSessionTracker(opts: SessionTrackerOptions): void;
 /**
  * Record a page view manually — call from framework router hooks where the
- * history patch may fire too early (e.g. React Router v7 loader transitions).
+ * history patch may fire too early (e.g. React Router v7 loader transitions),
+ * or from a host that initialised with `patchHistory: false`.
  */
 declare function trackPageView(route?: string): void;
 /** Update the user identity after a Mushi.identify() call. */
@@ -2070,6 +2334,287 @@ declare function updateSessionIdentity(userIdHash: string | null): void;
 /** Tear down timers (e.g. in tests or SSR environments). */
 declare function destroySessionTracker(): void;
 
+/**
+ * FILE: packages/core/src/analytics-taxonomy.ts
+ * PURPOSE: Single source of truth for Mushi's product-analytics vocabulary —
+ *          the events Mushi emits about its OWN funnel (dogfooding the SDK on
+ *          the landing site, docs, console, CLI and MCP) plus the validation
+ *          rules every `Mushi.track()` call obeys, for every project.
+ *
+ * Naming: `object_verb`, snake_case, past tense for completions, `_view` for
+ * exposure, `_click` for intent. Every event carries `$surface`.
+ *
+ * Mirror: packages/server/supabase/functions/_shared/analytics-taxonomy.generated.ts
+ * is generated from this file by `node scripts/gen-analytics-taxonomy.mjs`
+ * (CI runs `--check`). Edge functions cannot import workspace packages.
+ */
+
+/** Event names: lowercase, start with a letter, 2–64 chars. */
+declare const EVENT_NAME_RE: RegExp;
+/** Hard caps applied client- and server-side. */
+declare const EVENT_PROPERTY_LIMITS: {
+    readonly maxKeys: 40;
+    readonly maxKeyLength: 64;
+    readonly maxValueLength: 256;
+    readonly maxBytes: 8192;
+    /** Client batch size before an immediate flush. */
+    readonly maxClientBatch: 20;
+    /** Server-side per-request ceiling. */
+    readonly maxServerBatch: 50;
+    /** Distinct event names per project before the server returns 422. */
+    readonly maxEventNamesPerProject: 200;
+};
+declare const MUSHI_SURFACES: readonly ["web", "console", "docs", "cli", "mcp", "server", "mobile"];
+type MushiSurface = (typeof MUSHI_SURFACES)[number];
+/**
+ * Mushi's own funnel vocabulary. One entry per line — the generator parses
+ * this block line by line, so keep the `name: { surface: '…', required: […] }`
+ * shape. An event with more than one emitter lists every surface:
+ * `surface: ['console', 'mcp']`.
+ */
+declare const MUSHI_EVENTS: {
+    readonly page_view: {
+        readonly surface: readonly ["web", "docs", "console"];
+        readonly required: readonly [];
+    };
+    readonly docs_page_view: {
+        readonly surface: "docs";
+        readonly required: readonly ["route"];
+    };
+    readonly landing_view: {
+        readonly surface: "docs";
+        readonly required: readonly [];
+    };
+    readonly cta_click: {
+        readonly surface: "docs";
+        readonly required: readonly ["cta_id", "location"];
+    };
+    readonly quickstart_view: {
+        readonly surface: "docs";
+        readonly required: readonly [];
+    };
+    readonly pricing_view: {
+        readonly surface: "docs";
+        readonly required: readonly [];
+    };
+    readonly connect_demo_click: {
+        readonly surface: "docs";
+        readonly required: readonly ["href"];
+    };
+    readonly signup_click: {
+        readonly surface: "docs";
+        readonly required: readonly ["href"];
+    };
+    readonly signup_completed: {
+        readonly surface: "console";
+        readonly required: readonly ["signup_source"];
+    };
+    readonly report_opened: {
+        readonly surface: readonly ["console", "mcp"];
+        readonly required: readonly ["report_id"];
+    };
+    readonly fix_context_pulled: {
+        readonly surface: readonly ["console", "mcp"];
+        readonly required: readonly ["report_id"];
+    };
+    readonly fix_dispatched: {
+        readonly surface: readonly ["console", "mcp"];
+        readonly required: readonly ["report_id", "agent"];
+    };
+    readonly invite_sent: {
+        readonly surface: "console";
+        readonly required: readonly [];
+    };
+    readonly upgrade_clicked: {
+        readonly surface: "console";
+        readonly required: readonly ["plan"];
+    };
+    readonly test_report_sent: {
+        readonly surface: "console";
+        readonly required: readonly ["project_id"];
+    };
+    readonly project_created: {
+        readonly surface: "server";
+        readonly required: readonly ["project_id"];
+    };
+    readonly key_minted: {
+        readonly surface: "server";
+        readonly required: readonly ["project_id"];
+    };
+    readonly first_report_received: {
+        readonly surface: "server";
+        readonly required: readonly ["project_id"];
+    };
+    readonly fix_merged: {
+        readonly surface: "server";
+        readonly required: readonly ["project_id"];
+    };
+    readonly upgrade_completed: {
+        readonly surface: "server";
+        readonly required: readonly ["project_id", "plan"];
+    };
+    readonly loop_impression: {
+        readonly surface: "web";
+        readonly required: readonly [];
+    };
+    readonly loop_click: {
+        readonly surface: "web";
+        readonly required: readonly [];
+    };
+    readonly loop_signup: {
+        readonly surface: "console";
+        readonly required: readonly ["ref"];
+    };
+};
+type MushiEventName = keyof typeof MUSHI_EVENTS;
+declare const MUSHI_EVENT_NAMES: MushiEventName[];
+/** The aha event: a project receives its first SDK-originated report. */
+declare const ACTIVATION_EVENT: MushiEventName;
+/**
+ * Any of these in a week counts as "diagnosis consumed" for the habit metric
+ * (docs/plan-gtm.md: report opened, fix context pulled or fix dispatched, from
+ * the console or an MCP client). company_funnel_weekly counts the same set.
+ */
+declare const HABIT_EVENTS: readonly MushiEventName[];
+type MushiEventProperties = Record<string, MushiPropertyValue>;
+declare function isValidEventName(name: unknown): name is string;
+interface SanitizedProperties {
+    properties: MushiEventProperties;
+    dropped: string[];
+}
+/**
+ * Enforce the property contract: depth 1, ≤ maxKeys, values ≤ maxValueLength,
+ * PII-looking keys dropped unless allowlisted, `$`-prefixed keys dropped unless
+ * `allowReserved` (the SDK sets those itself). Never throws.
+ */
+declare function sanitizeEventProperties(input: unknown, opts?: {
+    allowlist?: readonly string[];
+    allowReserved?: boolean;
+    scrub?: (s: string) => string;
+}): SanitizedProperties;
+/** Approximate serialized size guard (UTF-16 length is a fine upper bound here). */
+declare function propertiesWithinByteLimit(properties: MushiEventProperties): boolean;
+
+/**
+ * FILE: packages/core/src/event-tracker.ts
+ * PURPOSE: Client-side product-analytics tracker behind `Mushi.track()`.
+ *
+ * Batches named events and flushes them to POST /v1/sdk/events. Modelled on
+ * session-tracker.ts (module state, idempotent init) but with a batch buffer,
+ * an interval flush, a pagehide flush (the API client already switches to
+ * keepalive during unload) and a small localStorage spill for unsent batches.
+ *
+ * Privacy:
+ *   - `anon_id` is the same opaque per-project reporter token the SDK already
+ *     uses for reports and sessions; identify() attaches the host's user id.
+ *   - Everything passes the shared gate in analytics-gate.ts (also used by the
+ *     session tracker): analytics.enabled, DNT / GPC, automation, consent.
+ *   - Nothing leaves the page until consent is 'granted'. That covers the
+ *     identify marker and a previous page's spill, not just track() events.
+ *   - `consent: 'required'` buffers up to 50 events in memory until
+ *     setConsent('granted'); 'denied' drops the buffer, the pending identify
+ *     and the spill, and disables tracking.
+ *   - Every string property runs through the caller-supplied PII scrubber and
+ *     the shared property contract in analytics-taxonomy.ts.
+ *   - `sampleRate` is decided once per person (hash of anon_id), never per
+ *     event, so funnels stay consistent.
+ */
+
+interface EventTrackerOptions {
+    client: MushiApiClient;
+    projectId: string;
+    /**
+     * Anonymous id to key events on. Omit it: the tracker then uses its own
+     * random per-project id, stored only after consent. Do not pass the reporter
+     * token — it is a credential for the end user's report threads.
+     */
+    anonId?: string | null;
+    sdkVersion?: string;
+    userId?: string | null;
+    config?: MushiAnalyticsConfig;
+    /** PII scrubber for string values (the SDK passes createPiiScrubber().scrub). */
+    scrub?: (s: string) => string;
+    /** Optional session id resolver (the SDK passes getSessionId). */
+    getSessionId?: () => string;
+}
+/**
+ * True when tracking is active for this person (enabled, consented, sampled
+ * in, no DNT / GPC, not automation). The gate leaves the tracker
+ * uninitialised when it blocks, so `_initialized` covers the first part.
+ */
+declare function isEventTrackingActive(): boolean;
+/** The anonymous id events are keyed on, or null when tracking is off. */
+declare function getEventAnonymousId(): string | null;
+/**
+ * Initialise the tracker. Idempotent per page. Safe to call in SSR (no-op).
+ */
+declare function initEventTracker(opts: EventTrackerOptions): void;
+/**
+ * Record a named event. Invalid names are dropped; properties are sanitised
+ * per analytics-taxonomy.ts. Returns true when the event was queued.
+ */
+declare function trackEvent(name: string, properties?: Record<string, unknown>, opts?: {
+    dedupKey?: string;
+    ts?: string;
+    reserved?: MushiEventProperties;
+}): boolean;
+/**
+ * Grant or deny consent. Persisted per project and broadcast through the
+ * shared gate, so the session tracker follows the same decision. Granting
+ * releases the pending buffer and identify; denying drops them.
+ */
+declare function setEventConsent(state: 'granted' | 'denied'): void;
+/**
+ * Called from identify(): stitches anonymous history to the person. The
+ * identify marker is held until consent is granted and dropped on denial.
+ */
+declare function updateEventIdentity(userId: string | null, traits?: Record<string, unknown> | null): void;
+/** Flush immediately (tests, before navigation). */
+declare function flushEvents(): Promise<void>;
+/** Tear down timers (tests / SSR). */
+declare function destroyEventTracker(): void;
+
+/**
+ * FILE: packages/core/src/analytics-gate.ts
+ * PURPOSE: The one privacy gate every analytics surface in the browser SDK
+ *          passes through: product events (`Mushi.track()`, `identify()`) and
+ *          session lifecycle tracking alike.
+ *
+ * A surface may send only when all of these hold:
+ *   - `analytics.enabled` is not false;
+ *   - Do Not Track / Global Privacy Control is off, or the host opted out of
+ *     honouring it (`respectDoNotTrack: false`);
+ *   - the browser is not automation or a crawler (`excludeBots: false` opts
+ *     back in, e.g. to exercise analytics from Playwright);
+ *   - consent resolves to 'granted'. 'implied' mode grants unless the visitor
+ *     stored a denial; 'required' mode waits for `setConsent('granted')`.
+ *
+ * The first three are fixed for the page, so `analyticsBlockReason()` is read
+ * once at tracker init. Consent can change at any time, so trackers resolve it
+ * from storage at init (the storage is the source of truth, which keeps the
+ * result independent of which tracker starts first) and then follow
+ * `onAnalyticsConsentChange()`.
+ */
+
+type AnalyticsConsentState = 'granted' | 'denied' | 'pending';
+type AnalyticsBlockReason = 'disabled' | 'dnt' | 'automation';
+type ConsentListener = (state: 'granted' | 'denied') => void;
+/** True when the browser signals Do Not Track or Global Privacy Control. */
+declare function dntActive(): boolean;
+/** True for WebDriver-controlled browsers (Playwright, Puppeteer, Selenium) and crawler user agents. */
+declare function isAutomatedBrowser(): boolean;
+/**
+ * Why analytics may not run on this page at all, or null when only consent
+ * stands between the tracker and the network.
+ */
+declare function analyticsBlockReason(config?: MushiAnalyticsConfig): AnalyticsBlockReason | null;
+/** Consent for this page: a stored choice wins, otherwise the configured mode decides. */
+declare function resolveAnalyticsConsent(projectId: string, config?: MushiAnalyticsConfig): AnalyticsConsentState;
+/** Persist a consent decision and tell every subscribed tracker. */
+declare function setAnalyticsConsent(projectId: string, state: 'granted' | 'denied'): void;
+/** Follow consent changes. Returns the unsubscribe function. */
+declare function onAnalyticsConsentChange(listener: ConsentListener): () => void;
+
 interface RateLimiterConfig {
     maxBurst?: number;
     refillRate?: number;
@@ -2632,4 +3177,4 @@ declare function projectInitialsThemeIndex(projectId: string): number;
  */
 declare function readPageFaviconHref(): string | null;
 
-export { type ApiClientOptions, type BreadcrumbBuffer, type BreadcrumbBufferOptions, DEFAULT_API_ENDPOINT, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, type EnvConfigDiagnostics, type EnvNearMiss, type LogEntry, type LogFormat, type LogLevel, type Logger, type LoggerOptions, MAX_REPORT_PAYLOAD_BYTES, MAX_SCREENSHOT_DATA_URL_BYTES, MUSHI_ACCENT_SHADOW, MUSHI_BANNER_BRAND_BORDER, MUSHI_BANNER_NEON, MUSHI_BORDER, MUSHI_COLORS_DARK, MUSHI_COLORS_LIGHT, MUSHI_CONTROL_DISABLED, MUSHI_COPY, MUSHI_DURATION, MUSHI_GEOMETRY, MUSHI_IDENTITY_TOKEN_PREFIX, MUSHI_INTERNAL_HEADER, MUSHI_INTERNAL_INIT_MARKER, MUSHI_INVERSE, MUSHI_LETTER_SPACING, MUSHI_MOTION, MUSHI_ON_ACCENT, MUSHI_OPACITY, MUSHI_PROJECT_HEADER, MUSHI_RADIUS, MUSHI_REPORTER_STATUS, MUSHI_SDK_PACKAGE_HEADER, MUSHI_SDK_VERSION_HEADER, MUSHI_SHADOW_INK, MUSHI_SPACING, MUSHI_TIER_COLORS, MUSHI_TYPE, MUSHI_USER_TOKEN_HEADER, MUSHI_Z, type MushiActivityEvent, type MushiApiCascadeConfig, type MushiApiClient, type MushiApiResponse, type MushiAssistantConfig, type MushiAssistantReply, type MushiAssistantStep, type MushiBannerConfig, type MushiBannerLink, type MushiBetaChangelogEntry, type MushiBetaModeConfig, type MushiBreadcrumb, type MushiCaptureConfig, type MushiCaptureEventInput, type MushiCaptureExceptionOptions, type MushiColorPalette, type MushiConfig, type MushiConsoleEntry, type MushiCooldownConfig, type MushiCrossAppReport, type MushiCustomCategory, type MushiDiagnosticsResult, type MushiDiscoverInventoryConfig, type MushiDiscoveryEventPayload, type MushiEnvironment, type MushiEventHandler, type MushiEventType, type MushiHallOfFameEntry, type MushiIdentityClaims, type MushiIntegrationsConfig, type MushiInternalRequestKind, type MushiLeaderboardEntry, type MushiNetworkEntry, type MushiOfflineConfig, type MushiOnDeviceClassifier, type MushiOnDeviceClassifierInput, type MushiOnDeviceClassifierResult, type MushiPageContext, type MushiPerformanceMetrics, type MushiPreFilterConfig, type MushiPreset, type MushiPrivacyConfig, type MushiProactiveConfig, type MushiRegion, type MushiReport, type MushiReportBuilder, type MushiReportCategory, type MushiReportStatus, type MushiReporterComment, type MushiReporterReport, type MushiReputationResult, type MushiRewardsConfig, type MushiRuntimeSdkConfig, type MushiSDKInstance, type MushiSdkVersionInfo, type MushiSelectedElement, type MushiSentryConfig, type MushiSentryContext, type MushiSessionEventPayload, type MushiTesterReputation, type MushiThemeMode, type MushiTierResult, type MushiTimelineEntry, type MushiTimelineKind, type MushiTokenSnapshot, type MushiTracePropagationConfig, type MushiUrlMatcher, type MushiWidgetAnchor, type MushiWidgetConfig, type NormalisedException, type OfflineQueue, type PayloadGuardResult, type PiiScrubberConfig, type PreFilterResult, type ProjectFaviconSource, REGION_ENDPOINTS, type RateLimiter, type RateLimiterConfig, type ResolvedEnvConfig, type SessionTrackerOptions, buildIdentityClaims, buildSdkIngestHeaders, captureEnvironment, checkReportPayloadSize, createApiClient, createBreadcrumbBuffer, createLogger, createOfflineQueue, createPiiScrubber, createPreFilter, createRateLimiter, destroySessionTracker, diagnoseEnvConfig, estimateJsonBytes, expandPreset, faviconUrlCandidates, formatBytes, getDeviceFingerprintHash, getReporterToken, getSessionId, githubRepoDomainHint, hmacSha256Hex, initSessionTracker, isLikelyGenericFavicon, isUntrustedFaviconUrl, mushiPalette, mushiTokens, newUuid, noopLogger, normaliseThrown, originToDomain, parseIdentityToken, projectFaviconUrlCandidates, projectInitials, projectInitialsThemeIndex, readPageFaviconHref, resolveEnvConfig, resolveProjectDomain, resolveProjectFaviconDomains, resolveRegionEndpoint, resolveWidgetAccent, safeWidgetHex, scrubPii, scrubUrl, sha256Hex, trackPageView, updateSessionIdentity, validateConfig };
+export { ACTIVATION_EVENT, type AnalyticsBlockReason, type AnalyticsConsentState, type ApiClientOptions, type BreadcrumbBuffer, type BreadcrumbBufferOptions, DEFAULT_API_ENDPOINT, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, EVENT_NAME_RE, EVENT_PROPERTY_LIMITS, type EnvConfigDiagnostics, type EnvNearMiss, type EventTrackerOptions, HABIT_EVENTS, type LogEntry, type LogFormat, type LogLevel, type Logger, type LoggerOptions, MAX_REPORT_PAYLOAD_BYTES, MAX_SCREENSHOT_DATA_URL_BYTES, MUSHI_ACCENT_SHADOW, MUSHI_BANNER_BRAND_BORDER, MUSHI_BANNER_NEON, MUSHI_BEACON_MAX_BYTES, MUSHI_BORDER, MUSHI_COLORS_DARK, MUSHI_COLORS_LIGHT, MUSHI_CONTROL_DISABLED, MUSHI_COPY, MUSHI_DURATION, MUSHI_EVENTS, MUSHI_EVENT_NAMES, MUSHI_GEOMETRY, MUSHI_IDENTITY_TOKEN_PREFIX, MUSHI_INTERNAL_HEADER, MUSHI_INTERNAL_INIT_MARKER, MUSHI_INVERSE, MUSHI_LETTER_SPACING, MUSHI_MOTION, MUSHI_ON_ACCENT, MUSHI_OPACITY, MUSHI_PROJECT_HEADER, MUSHI_RADIUS, MUSHI_REPORTER_STATUS, MUSHI_SDK_PACKAGE_HEADER, MUSHI_SDK_VERSION_HEADER, MUSHI_SHADOW_INK, MUSHI_SPACING, MUSHI_SURFACES, MUSHI_TIER_COLORS, MUSHI_TYPE, MUSHI_USER_TOKEN_HEADER, MUSHI_Z, type MushiActivityEvent, type MushiAnalyticsConfig, type MushiApiCascadeConfig, type MushiApiClient, type MushiApiResponse, type MushiAssistantConfig, type MushiAssistantReply, type MushiAssistantStep, type MushiBannerConfig, type MushiBannerLink, type MushiBeaconEnvelope, type MushiBetaChangelogEntry, type MushiBetaModeConfig, type MushiBreadcrumb, type MushiCaptureConfig, type MushiCaptureEventInput, type MushiCaptureExceptionOptions, type MushiColorPalette, type MushiConfig, type MushiConsoleEntry, type MushiCooldownConfig, type MushiCrossAppReport, type MushiCustomCategory, type MushiDiagnosticsResult, type MushiDiscoverInventoryConfig, type MushiDiscoveryEventPayload, type MushiEnvironment, type MushiErrorFilter, type MushiEventHandler, type MushiEventName, type MushiEventProperties, type MushiEventType, type MushiHallOfFameEntry, type MushiIdentityClaims, type MushiIntegrationsConfig, type MushiInternalRequestKind, type MushiLeaderboardEntry, type MushiNetworkEntry, type MushiOfflineConfig, type MushiOnDeviceClassifier, type MushiOnDeviceClassifierInput, type MushiOnDeviceClassifierResult, type MushiPageContext, type MushiPerformanceMetrics, type MushiPreFilterConfig, type MushiPreset, type MushiPrivacyConfig, type MushiProactiveConfig, type MushiProductEventPayload, type MushiPropertyValue, type MushiRegion, type MushiReport, type MushiReportBuilder, type MushiReportCategory, type MushiReportStatus, type MushiReporterComment, type MushiReporterReport, type MushiReputationResult, type MushiRewardsConfig, type MushiRuntimeSdkConfig, type MushiSDKInstance, type MushiSdkVersionInfo, type MushiSelectedElement, type MushiSentryConfig, type MushiSentryContext, type MushiSessionEventPayload, type MushiSurface, type MushiTesterReputation, type MushiThemeMode, type MushiTierResult, type MushiTimelineEntry, type MushiTimelineKind, type MushiTokenSnapshot, type MushiTracePropagationConfig, type MushiUrlMatcher, type MushiWidgetAnchor, type MushiWidgetConfig, type NormalisedException, type OfflineQueue, type PayloadGuardResult, type PiiScrubberConfig, type PreFilterResult, type ProjectFaviconSource, REGION_ENDPOINTS, type RateLimiter, type RateLimiterConfig, type ResolvedEnvConfig, type SessionTrackerOptions, analyticsBlockReason, buildBeaconEnvelope, buildIdentityClaims, buildSdkIngestHeaders, captureEnvironment, checkReportPayloadSize, createApiClient, createBreadcrumbBuffer, createLogger, createOfflineQueue, createPiiScrubber, createPreFilter, createRateLimiter, destroyEventTracker, destroySessionTracker, diagnoseEnvConfig, dntActive, estimateJsonBytes, expandPreset, extractTunnelPath, faviconUrlCandidates, flushEvents, flushLastOutboundOnUnload, formatBytes, getBackoffDelay, getDeviceFingerprintHash, getEventAnonymousId, getReporterToken, getSessionId, githubRepoDomainHint, hmacSha256Hex, initEventTracker, initSessionTracker, isAutomatedBrowser, isEventTrackingActive, isLikelyGenericFavicon, isMushiBeaconEnvelope, isPageUnloading, isSameOriginOrRelative, isUntrustedFaviconUrl, isValidEventName, markPageUnloading, matchesErrorFilter, mushiPalette, mushiTokens, newUuid, noopLogger, normaliseThrown, onAnalyticsConsentChange, originToDomain, parseIdentityToken, parseRetryAfter, projectFaviconUrlCandidates, projectInitials, projectInitialsThemeIndex, propertiesWithinByteLimit, readPageFaviconHref, resolveAnalyticsConsent, resolveEnvConfig, resolveProjectDomain, resolveProjectFaviconDomains, resolveRegionEndpoint, resolveRequestBaseUrl, resolveWidgetAccent, safeWidgetHex, sanitizeEventProperties, scrubPii, scrubUrl, sendOnUnload, setAnalyticsConsent, setEventConsent, sha256Hex, shouldDropCapturedError, trackEvent, trackPageView, updateEventIdentity, updateSessionIdentity, validateConfig };