stitchkit 0.80.1 → 0.81.0

package/dist/tracking/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/tracking/client.ts"],"names":[],"mappings":"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"}

package/dist/tracking/contract.d.ts

@@ -0,0 +1,46 @@
+import type { z } from 'zod';
+import { type ContractDef } from '../contract/index.js';
+import { type TrackingEventShape, type TrackingSchemas, type TrackingSchemasConfig } from './schemas.js';
+export interface TrackingContractConfig<TType extends string, TExtras extends z.ZodRawShape | undefined, TScope extends string> extends TrackingSchemasConfig<TType, TExtras> {
+    /** Route prefix; default `tracking`. */
+    prefix?: string;
+    /**
+     * Almost always the application's public scope: the landing page and the
+     * sign-in page are read by anonymous visitors, and their path is part of the
+     * funnel. Identity, when there is one, comes from the cookie on the server
+     * side; the client claims nothing about itself.
+     */
+    scope: TScope;
+    /** Byte ceiling for one batch; default 256 KiB. */
+    maxJsonBodyBytes?: number;
+}
+/** The two operations every tracking surface has, typed by the application's schemas. */
+export type TrackingContractEndpoints<TSchemas extends TrackingSchemas<z.ZodObject>> = {
+    bootstrap: {
+        method: 'POST';
+        path: '/visit';
+        expose: readonly ['HTTP'];
+        desc: string;
+        input: TSchemas['entry'];
+        output: TSchemas['bootstrap'];
+    };
+    track: {
+        method: 'POST';
+        path: '/events';
+        desc: string;
+        input: TSchemas['request'];
+        output: TSchemas['response'];
+        safelistedBody: true;
+        maxJsonBodyBytes: number;
+    };
+};
+/**
+ * `bootstrap` issues or renews a visit lease; `track` receives a batch. `track`
+ * declares `safelistedBody` because the page-leave event is sent by
+ * `sendUnloadBeacon` with a string body — the only body a document that is
+ * being unloaded can deliver to another origin (ADR 0165) — and the server
+ * therefore needs an explicit `cors.origin` allow-list for it to arrive.
+ */
+export declare function createTrackingContract<TType extends string, TScope extends string>(config: TrackingContractConfig<TType, undefined, TScope>): ContractDef<TrackingContractEndpoints<TrackingSchemas<z.ZodObject<TrackingEventShape<TType>>>>, TScope>;
+export declare function createTrackingContract<TType extends string, TExtras extends z.ZodRawShape, TScope extends string>(config: TrackingContractConfig<TType, TExtras, TScope>): ContractDef<TrackingContractEndpoints<TrackingSchemas<z.ZodObject<TrackingEventShape<TType> & TExtras>>>, TScope>;
+//# sourceMappingURL=contract.d.ts.map

package/dist/tracking/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../src/tracking/contract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,EAAE,KAAK,WAAW,EAAkB,MAAM,aAAa,CAAC;AAC/D,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC3B,MAAM,WAAW,CAAC;AAEnB,MAAM,WAAW,sBAAsB,CACrC,KAAK,SAAS,MAAM,EACpB,OAAO,SAAS,CAAC,CAAC,WAAW,GAAG,SAAS,EACzC,MAAM,SAAS,MAAM,CACrB,SAAQ,qBAAqB,CAAC,KAAK,EAAE,OAAO,CAAC;IAC7C,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,mDAAmD;IACnD,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,yFAAyF;AACzF,MAAM,MAAM,yBAAyB,CAAC,QAAQ,SAAS,eAAe,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI;IACrF,SAAS,EAAE;QACT,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,QAAQ,CAAC;QACf,MAAM,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;QAC1B,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;QACzB,MAAM,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;KAC/B,CAAC;IACF,KAAK,EAAE;QACL,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,SAAS,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC;QAC3B,MAAM,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC;QAC7B,cAAc,EAAE,IAAI,CAAC;QACrB,gBAAgB,EAAE,MAAM,CAAC;KAC1B,CAAC;CACH,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,SAAS,MAAM,EAAE,MAAM,SAAS,MAAM,EAChF,MAAM,EAAE,sBAAsB,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,GACvD,WAAW,CACZ,yBAAyB,CAAC,eAAe,CAAC,CAAC,CAAC,SAAS,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAClF,MAAM,CACP,CAAC;AACF,wBAAgB,sBAAsB,CACpC,KAAK,SAAS,MAAM,EACpB,OAAO,SAAS,CAAC,CAAC,WAAW,EAC7B,MAAM,SAAS,MAAM,EAErB,MAAM,EAAE,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,GACrD,WAAW,CACZ,yBAAyB,CAAC,eAAe,CAAC,CAAC,CAAC,SAAS,CAAC,kBAAkB,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAC5F,MAAM,CACP,CAAC"}

package/dist/tracking/delivery.d.ts

@@ -0,0 +1,24 @@
+export type TrackingDeliveryOutcome = 'delivered' | 'failed' | 'auth-invalidated';
+export interface TrackingDeliveryOptions {
+    request: () => Promise<unknown>;
+    onFailure: (error: unknown) => void;
+    /**
+     * A `401` or `403` means the session the batch was sent under is gone or
+     * may no longer write. When given,
+     * this is asked to recover it (re-authenticate, refresh); `true` retries the
+     * batch once, `false` reports `auth-invalidated` and the batch stays queued
+     * for a flush under the next session.
+     */
+    onUnauthorized?: () => Promise<boolean>;
+    wait?: (delayMs: number) => Promise<void>;
+    retryDelayMs?: number;
+}
+/**
+ * One batch, one bounded retry. A network failure or a `5xx` earns a single
+ * second attempt after `retryDelayMs`; anything else is reported once. Nothing
+ * is lost on `failed`: the batch is still in the outbox, the next flush sends
+ * the same events with the same ids, and the server answers `duplicate` for
+ * whatever it had already accepted.
+ */
+export declare function deliverTrackingBatch({ request, onFailure, onUnauthorized, wait, retryDelayMs, }: TrackingDeliveryOptions): Promise<TrackingDeliveryOutcome>;
+//# sourceMappingURL=delivery.d.ts.map

package/dist/tracking/delivery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery.d.ts","sourceRoot":"","sources":["../../src/tracking/delivery.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,uBAAuB,GAAG,WAAW,GAAG,QAAQ,GAAG,kBAAkB,CAAC;AAElF,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAChC,SAAS,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACpC;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IACxC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAUD;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CAAC,EACzC,OAAO,EACP,SAAS,EACT,cAAc,EACd,IAA0E,EAC1E,YAAkB,GACnB,EAAE,uBAAuB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAqB5D"}

package/dist/tracking/host.d.ts

@@ -0,0 +1,43 @@
+import type { AttributionStorage } from './attribution.js';
+import type { ClickTarget } from './clicks.js';
+/** What the client reads about the current page. */
+export interface TrackingPageContext {
+    pathname: string;
+    /** With the leading `?`, or empty. */
+    search: string;
+    origin: string;
+    hostname: string;
+    title: string;
+    referrer: string;
+    viewportWidth: number;
+    viewportHeight: number;
+    screenWidth: number;
+    screenHeight: number;
+    displayMode: 'browser' | 'standalone';
+}
+/**
+ * Everything the tracking client takes from a browser, behind one interface,
+ * so the client is a plain object that can be driven by a test without a
+ * DOM — and so a host that is not a browser tab (a WebView, a worker) can
+ * supply its own. `browserTrackingHost()` is the tab.
+ */
+export interface TrackingHost {
+    page(): TrackingPageContext;
+    visible(): boolean;
+    /** Current scroll depth, 0–100. */
+    scrollDepth(): number;
+    /** Subscribe; returns the unsubscribe. */
+    on(event: 'pagehide' | 'visibilitychange' | 'online' | 'scroll', handler: () => void): () => void;
+    /** Clicks, capture phase — a link navigates before bubbling reaches it. */
+    onClick(handler: (target: ClickTarget | null) => void): () => void;
+    interval(handler: () => void, ms: number): () => void;
+    /** Monotonic clock, ms. */
+    now(): number;
+    wallClock(): number;
+    randomUUID(): string;
+    /** Where attribution persists; `null` when there is none. */
+    storage: AttributionStorage | null;
+}
+/** The host a browser tab provides. Reads `window` and `document` lazily, never at import. */
+export declare function browserTrackingHost(): TrackingHost;
+//# sourceMappingURL=host.d.ts.map

package/dist/tracking/host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../src/tracking/host.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5C,oDAAoD;AACpD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,SAAS,GAAG,YAAY,CAAC;CACvC;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,IAAI,mBAAmB,CAAC;IAC5B,OAAO,IAAI,OAAO,CAAC;IACnB,mCAAmC;IACnC,WAAW,IAAI,MAAM,CAAC;IACtB,0CAA0C;IAC1C,EAAE,CACA,KAAK,EAAE,UAAU,GAAG,kBAAkB,GAAG,QAAQ,GAAG,QAAQ,EAC5D,OAAO,EAAE,MAAM,IAAI,GAClB,MAAM,IAAI,CAAC;IACd,2EAA2E;IAC3E,OAAO,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACnE,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,IAAI,CAAC;IACtD,2BAA2B;IAC3B,GAAG,IAAI,MAAM,CAAC;IACd,SAAS,IAAI,MAAM,CAAC;IACpB,UAAU,IAAI,MAAM,CAAC;IACrB,6DAA6D;IAC7D,OAAO,EAAE,kBAAkB,GAAG,IAAI,CAAC;CACpC;AAED,8FAA8F;AAC9F,wBAAgB,mBAAmB,IAAI,YAAY,CAmDlD"}

package/dist/tracking/once-per-page.d.ts

@@ -0,0 +1,17 @@
+/**
+ * One fact per key per page within a window.
+ *
+ * A component that records "opened X" can mount twice on the same page —
+ * StrictMode, an RSC tree refresh, a layout re-render — and each mount has its
+ * own fresh refs, so a guard inside the component cannot see the first one.
+ * The memory lives at document scope instead: the same key on the same page
+ * within the window is the same fact. A different page is a new one.
+ */
+export interface OncePerPage {
+    should(key: string, page: string): boolean;
+}
+export declare function createOncePerPage(options?: {
+    windowMs?: number;
+    now?: () => number;
+}): OncePerPage;
+//# sourceMappingURL=once-per-page.d.ts.map

package/dist/tracking/once-per-page.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"once-per-page.d.ts","sourceRoot":"","sources":["../../src/tracking/once-per-page.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;CAC5C;AAED,wBAAgB,iBAAiB,CAC/B,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CAAO,GACtD,WAAW,CAcb"}

package/dist/tracking/outbox-storage-indexeddb.d.ts

@@ -0,0 +1,12 @@
+import type { TrackingOutboxStorage, TrackingQueuedEvent } from './outbox.js';
+/**
+ * The outbox in IndexedDB — the store every tab of one origin shares, which is
+ * what makes the sequence counter and the flush lease lineage-wide. Each
+ * `transact` is one `readwrite` transaction over both object stores; the
+ * database is opened per transaction and closed after it, so a tab holds no
+ * connection open across the page's life.
+ *
+ * `factory` is injectable so the adapter can be exercised outside a browser.
+ */
+export declare function indexedDbOutboxStorage<TEvent extends TrackingQueuedEvent = TrackingQueuedEvent>(name: string, factory?: () => IDBFactory): TrackingOutboxStorage<TEvent>;
+//# sourceMappingURL=outbox-storage-indexeddb.d.ts.map

package/dist/tracking/outbox-storage-indexeddb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbox-storage-indexeddb.d.ts","sourceRoot":"","sources":["../../src/tracking/outbox-storage-indexeddb.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,qBAAqB,EACrB,mBAAmB,EACpB,MAAM,UAAU,CAAC;AAsDlB;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,SAAS,mBAAmB,GAAG,mBAAmB,EACxD,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,UAA4B,GAAG,qBAAqB,CAAC,MAAM,CAAC,CAyC1F"}

package/dist/tracking/outbox-storage-memory.d.ts

@@ -0,0 +1,12 @@
+import type { TrackingOutboxStorage, TrackingQueuedEvent } from './outbox.js';
+/**
+ * The outbox over two maps. Transactions are serialised through one promise
+ * chain and are all-or-nothing: `fn` works on copies that replace the store
+ * only when it returns, so two concurrent `reserveSequences` see each other
+ * exactly as they would through IndexedDB, and one that throws leaves
+ * nothing behind. For tests, and for a browser whose IndexedDB is
+ * unavailable — then it is one tab's private queue, which is what the
+ * `unavailable` health state tells the server.
+ */
+export declare function memoryOutboxStorage<TEvent extends TrackingQueuedEvent = TrackingQueuedEvent>(): TrackingOutboxStorage<TEvent>;
+//# sourceMappingURL=outbox-storage-memory.d.ts.map

package/dist/tracking/outbox-storage-memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbox-storage-memory.d.ts","sourceRoot":"","sources":["../../src/tracking/outbox-storage-memory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,qBAAqB,EACrB,mBAAmB,EACpB,MAAM,UAAU,CAAC;AAElB;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,SAAS,mBAAmB,GAAG,mBAAmB,KACrD,qBAAqB,CAAC,MAAM,CAAC,CAiCjC"}

package/dist/tracking/outbox.d.ts

@@ -0,0 +1,98 @@
+/**
+ * A bounded, tab-shared outbox for browser events.
+ *
+ * Every event is written here before it is sent, so a batch the network drops
+ * is sent again on the next flush and a page the user leaves does not lose the
+ * facts it recorded. The server's dispositions are all terminal, so an
+ * acknowledged event is simply deleted — the outbox never re-sends what the
+ * server has already answered.
+ *
+ * Two things here are the difference between an outbox that works and one
+ * that quietly loses the page-leave event, and both are consumer scars:
+ *
+ * - **Sequences are reserved, not assigned at write time.** On `pagehide`
+ *   there is no time to wait for a storage transaction, so the event's number
+ *   has to exist before the event is written anywhere. `reserveSequences`
+ *   hands out a block atomically; a tab spends it synchronously.
+ * - **The flush lease is short and is released on `pagehide`.** A ten-second
+ *   lease that a dying document did not release delayed the next document's
+ *   first flush by the whole ten seconds — the time it takes a person to leave
+ *   again. The lease guards against two tabs flushing at once, not against
+ *   retries, which the server answers with `duplicate` anyway.
+ *
+ * Storage is an interface: IndexedDB in a browser, memory in a test or as the
+ * degraded mode when IndexedDB is unavailable. → ADR 0166.
+ */
+/** The least an event needs for the outbox to order and acknowledge it. */
+export interface TrackingQueuedEvent {
+    eventId: string;
+    browserSequence: number;
+}
+export interface TrackingOutboxRecord<TEvent extends TrackingQueuedEvent = TrackingQueuedEvent> {
+    event: TEvent;
+    enqueuedAt: number;
+}
+/** A key/value store inside one atomic transaction. */
+export interface TrackingOutboxMeta {
+    get(key: string): Promise<unknown>;
+    put(key: string, value: unknown): void;
+    delete(key: string): void;
+}
+/** The event store inside the same transaction. */
+export interface TrackingOutboxEvents<TEvent extends TrackingQueuedEvent = TrackingQueuedEvent> {
+    put(record: TrackingOutboxRecord<TEvent>): void;
+    delete(eventId: string): void;
+    /** Every record, ordered by `browserSequence`. */
+    all(): Promise<TrackingOutboxRecord<TEvent>[]>;
+    count(): Promise<number>;
+}
+/**
+ * One atomic read-modify-write over both stores. Atomicity is the whole
+ * contract: two tabs reserving sequences or racing for the lease must see each
+ * other's writes, which is what a single IndexedDB `readwrite` transaction —
+ * and the memory adapter's serialised queue — provide.
+ */
+export interface TrackingOutboxStorage<TEvent extends TrackingQueuedEvent = TrackingQueuedEvent> {
+    transact<T>(fn: (tx: {
+        meta: TrackingOutboxMeta;
+        events: TrackingOutboxEvents<TEvent>;
+    }) => Promise<T>, 
+    /** `readonly` for a pure read, so one tab's reads do not queue behind another's writes. */
+    mode?: 'readonly' | 'readwrite'): Promise<T>;
+}
+export interface TrackingOutboxOptions {
+    /** Records kept; the oldest beyond it are dropped and counted. Default 1000. */
+    maxEvents?: number;
+    /** Age beyond which a record is dropped and counted. Default 7 days. */
+    maxAgeMs?: number;
+    /** Flush lease duration. Default 3 s — short, because it is released on leave. */
+    leaseMs?: number;
+    /** Wall clock; injectable for tests. */
+    now?: () => number;
+    randomUUID?: () => string;
+}
+export interface TrackingOutboxHealth {
+    state: 'available' | 'unavailable';
+    queued: number;
+    dropped: number;
+}
+export interface TrackingOutbox<TEvent extends TrackingQueuedEvent = TrackingQueuedEvent> {
+    /** Browser lineage — shared by every tab, survives reload and login. */
+    streamId(): Promise<string>;
+    /** Atomically reserve `count` consecutive sequence numbers. */
+    reserveSequences(count: number): Promise<number[]>;
+    /** Write an event that already carries its identity, then trim. */
+    enqueue(event: TEvent): Promise<void>;
+    /** One flusher per lineage: tabs compete for a renewable lease. */
+    acquireLease(owner: string): Promise<boolean>;
+    /** Give the lease back on leave so the next document flushes at once. */
+    releaseLease(owner: string): Promise<void>;
+    /** The oldest `limit` events in sequence order. */
+    readBatch(limit?: number): Promise<TEvent[]>;
+    /** Delete the events the server answered — every disposition is terminal. */
+    acknowledge(eventIds: readonly string[]): Promise<void>;
+    /** Queue depth and drops; `unavailable` when storage throws. */
+    health(): Promise<TrackingOutboxHealth>;
+}
+export declare function createTrackingOutbox<TEvent extends TrackingQueuedEvent>(storage: TrackingOutboxStorage<TEvent>, options?: TrackingOutboxOptions): TrackingOutbox<TEvent>;
+//# sourceMappingURL=outbox.d.ts.map

package/dist/tracking/outbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbox.d.ts","sourceRoot":"","sources":["../../src/tracking/outbox.ts"],"names":[],"mappings":"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"}

package/dist/tracking/schemas.d.ts

@@ -0,0 +1,183 @@
+/**
+ * The shapes two consuming applications arrived at independently, word for
+ * word — an event envelope, a batch, its dispositions, a visit's entry context
+ * and lease. They carry no domain: the event *types* and any extra per-event
+ * fields are the application's, handed in as parameters. → ADR 0166.
+ */
+import { z } from 'zod';
+/** Campaign tags. Every field optional — `utm_source` alone is a legal entry. */
+export declare const UtmDataSchema: z.ZodObject<{
+    source: z.ZodOptional<z.ZodString>;
+    medium: z.ZodOptional<z.ZodString>;
+    campaign: z.ZodOptional<z.ZodString>;
+    content: z.ZodOptional<z.ZodString>;
+    term: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type UtmData = z.infer<typeof UtmDataSchema>;
+export declare const AttributionDataSchema: z.ZodObject<{
+    utm: z.ZodOptional<z.ZodObject<{
+        source: z.ZodOptional<z.ZodString>;
+        medium: z.ZodOptional<z.ZodString>;
+        campaign: z.ZodOptional<z.ZodString>;
+        content: z.ZodOptional<z.ZodString>;
+        term: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    referrer: z.ZodOptional<z.ZodString>;
+    landingPage: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type AttributionData = z.infer<typeof AttributionDataSchema>;
+/**
+ * The build that produced an event: a git SHA, or `dev`. Shared by both
+ * consumers already; `createTrackingSchemas({ buildIdPattern })` overrides it.
+ */
+export declare const DEFAULT_BUILD_ID_PATTERN: RegExp;
+/**
+ * What the server decided about one event. Every value is terminal — the
+ * outbox drops the event on any of them — because a retry would produce the
+ * same answer: `duplicate` is the answer a re-sent accepted event gets, an
+ * `identity-invalid` event belongs to a visit this browser does not own, and a
+ * bot's events are never written.
+ */
+export declare const TrackingDispositionStatusSchema: z.ZodEnum<{
+    accepted: "accepted";
+    duplicate: "duplicate";
+    "excluded-bot": "excluded-bot";
+    "identity-invalid": "identity-invalid";
+}>;
+export type TrackingDispositionStatus = z.infer<typeof TrackingDispositionStatusSchema>;
+export declare const TrackingDispositionSchema: z.ZodObject<{
+    eventId: z.ZodUUID;
+    status: z.ZodEnum<{
+        accepted: "accepted";
+        duplicate: "duplicate";
+        "excluded-bot": "excluded-bot";
+        "identity-invalid": "identity-invalid";
+    }>;
+}, z.core.$strip>;
+export type TrackingDisposition = z.infer<typeof TrackingDispositionSchema>;
+export declare const TrackEventsResponseSchema: z.ZodObject<{
+    accepted: z.ZodNumber;
+    dispositions: z.ZodArray<z.ZodObject<{
+        eventId: z.ZodUUID;
+        status: z.ZodEnum<{
+            accepted: "accepted";
+            duplicate: "duplicate";
+            "excluded-bot": "excluded-bot";
+            "identity-invalid": "identity-invalid";
+        }>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type TrackEventsResponse = z.infer<typeof TrackEventsResponseSchema>;
+export declare const VisitBootstrapResponseSchema: z.ZodObject<{
+    visitId: z.ZodUUID;
+    expiresAt: z.ZodISODateTime;
+}, z.core.$strip>;
+export type VisitBootstrapResponse = z.infer<typeof VisitBootstrapResponseSchema>;
+/** The state of the browser-side outbox, reported with every visit bootstrap. */
+export declare const TrackingOutboxStateSchema: z.ZodEnum<{
+    available: "available";
+    unavailable: "unavailable";
+}>;
+export type TrackingOutboxState = z.infer<typeof TrackingOutboxStateSchema>;
+declare function trackingEventShape<TType extends string>(eventTypes: readonly [TType, ...TType[]]): {
+    /** Client-minted, the idempotency key of the event. */
+    eventId: z.ZodUUID;
+    visitId: z.ZodUUID;
+    /** Browser lineage — shared by every tab, survives reload and login. */
+    browserStreamId: z.ZodUUID;
+    /** Monotonic per lineage; reserved before the event is written anywhere. */
+    browserSequence: z.ZodNumber;
+    type: z.ZodEnum<{ [k in TType]: k; } extends infer T ? { [k in keyof T]: T[k]; } : never>;
+    page: z.ZodString;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    clientTimestamp: z.ZodNumber;
+};
+export type TrackingEventShape<TType extends string> = ReturnType<typeof trackingEventShape<TType>>;
+/**
+ * The envelope every browser event travels in, before the application's extras.
+ *
+ * Written out rather than inferred: `z.infer` over a generic enum emits the
+ * `type` field into the declaration as a mapped type the compiler cannot prove
+ * is a `string`, and every generic constrained on this envelope then fails in
+ * `dist/*.d.ts` while passing in `src` — the defect class of ADR 0161, caught
+ * by `check-declarations-strict`. The schema stays the source of truth:
+ * `tests/tracking-browser.test.ts` holds this type equal to its inference.
+ */
+export interface TrackingEventEnvelope<TType extends string = string> {
+    eventId: string;
+    visitId: string;
+    browserStreamId: string;
+    browserSequence: number;
+    type: TType;
+    page: string;
+    metadata?: Record<string, unknown> | undefined;
+    clientTimestamp: number;
+}
+/** A batch as the client sends it. */
+export interface TrackEventsRequest<TEvent extends TrackingEventEnvelope = TrackingEventEnvelope> {
+    buildId: string;
+    events: TEvent[];
+    utm?: UtmData;
+}
+declare function visitEntryContextShape(buildIdPattern: RegExp): {
+    browserStreamId: z.ZodUUID;
+    previousVisitId: z.ZodOptional<z.ZodUUID>;
+    origin: z.ZodURL;
+    landingPath: z.ZodString;
+    referrer: z.ZodOptional<z.ZodURL>;
+    utm: z.ZodOptional<z.ZodObject<{
+        source: z.ZodOptional<z.ZodString>;
+        medium: z.ZodOptional<z.ZodString>;
+        campaign: z.ZodOptional<z.ZodString>;
+        content: z.ZodOptional<z.ZodString>;
+        term: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    displayMode: z.ZodEnum<{
+        browser: "browser";
+        standalone: "standalone";
+    }>;
+    screenWidth: z.ZodNumber;
+    screenHeight: z.ZodNumber;
+    buildId: z.ZodString;
+    outboxState: z.ZodEnum<{
+        available: "available";
+        unavailable: "unavailable";
+    }>;
+    outboxQueued: z.ZodNumber;
+    outboxDropped: z.ZodNumber;
+};
+export type VisitEntryContextShape = ReturnType<typeof visitEntryContextShape>;
+export type VisitEntryContext = z.infer<z.ZodObject<VisitEntryContextShape>>;
+export interface TrackingSchemasConfig<TType extends string, TExtras extends z.ZodRawShape | undefined> {
+    /** The event types the browser may write. Server-side types are not on this list. */
+    eventTypes: readonly [TType, ...TType[]];
+    /** Extra per-event fields the application carries beside the envelope. */
+    eventExtras?: TExtras extends z.ZodRawShape ? z.ZodObject<TExtras> : undefined;
+    /** Default {@link DEFAULT_BUILD_ID_PATTERN}. */
+    buildIdPattern?: RegExp;
+    /** Events per batch; default 50 — the outbox reads batches of this size. */
+    maxEventsPerBatch?: number;
+}
+/** Every schema of one tracking surface, built from the application's event types. */
+export interface TrackingSchemas<TEvent extends z.ZodObject> {
+    event: TEvent;
+    request: z.ZodObject<{
+        buildId: z.ZodString;
+        events: z.ZodArray<TEvent>;
+        utm: z.ZodOptional<typeof UtmDataSchema>;
+    }>;
+    response: typeof TrackEventsResponseSchema;
+    disposition: typeof TrackingDispositionSchema;
+    entry: z.ZodObject<VisitEntryContextShape>;
+    bootstrap: typeof VisitBootstrapResponseSchema;
+}
+/**
+ * The schemas of one tracking surface. Two overloads rather than a conditional
+ * spread: a shape that TypeScript keeps internal while checking `src` is
+ * written into the declaration as a union zod's shape constraint rejects
+ * (0.78.0, 0.79.0 — ADR 0161), so the two cases are two signatures.
+ */
+export declare function createTrackingSchemas<TType extends string>(config: TrackingSchemasConfig<TType, undefined>): TrackingSchemas<z.ZodObject<TrackingEventShape<TType>>>;
+export declare function createTrackingSchemas<TType extends string, TExtras extends z.ZodRawShape>(config: TrackingSchemasConfig<TType, TExtras>): TrackingSchemas<z.ZodObject<TrackingEventShape<TType> & TExtras>>;
+export {};
+//# sourceMappingURL=schemas.d.ts.map

package/dist/tracking/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/tracking/schemas.ts"],"names":[],"mappings":"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"}

package/dist/tracking/scroll.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Scroll depth as a percentage of the scrollable range — 0 at the top, 100 at
+ * the bottom, 0 for a page shorter than its viewport (nothing to scroll).
+ */
+export declare function scrollDepthPercent(view: {
+    scrollHeight: number;
+    innerHeight: number;
+    scrollY: number;
+}): number;
+export interface ScrollMilestones {
+    /** Record a depth without firing — the scroll listener's job. */
+    record(percent: number): void;
+    /** Record a depth and return the milestones newly reached, ascending. */
+    observe(percent: number): number[];
+    /** The deepest point seen since the last reset. */
+    max(): number;
+    /** A new page. */
+    reset(): void;
+}
+/** Milestones fire once each per page, in order, from the deepest point seen. */
+export declare function createScrollMilestones(milestones?: readonly number[]): ScrollMilestones;
+//# sourceMappingURL=scroll.d.ts.map

package/dist/tracking/scroll.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scroll.d.ts","sourceRoot":"","sources":["../../src/tracking/scroll.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACvC,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,MAAM,CAIT;AAED,MAAM,WAAW,gBAAgB;IAC/B,iEAAiE;IACjE,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,yEAAyE;IACzE,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACnC,mDAAmD;IACnD,GAAG,IAAI,MAAM,CAAC;IACd,kBAAkB;IAClB,KAAK,IAAI,IAAI,CAAC;CACf;AAED,iFAAiF;AACjF,wBAAgB,sBAAsB,CACpC,UAAU,GAAE,SAAS,MAAM,EAAsB,GAChD,gBAAgB,CAyBlB"}

package/dist/tracking/sequence-reserve.d.ts

@@ -0,0 +1,34 @@
+/**
+ * A pool of reserved sequence numbers a tab can spend **synchronously**.
+ *
+ * The page-leave event is materialised inside `pagehide`, where awaiting a
+ * storage transaction means the document dies first. So the tab keeps a block
+ * reserved ahead of time and refills it below a low-water mark; uniqueness
+ * across tabs comes from the atomic reservation, not from the moment of use.
+ *
+ * When the reservation source fails (no IndexedDB), the pool switches to a
+ * per-tab fallback: a random base plus a counter — the honest minimum, and the
+ * event then goes straight to the network without a queue.
+ */
+export interface SequenceReserveOptions {
+    /** Numbers reserved per refill. Default 16. */
+    blockSize?: number;
+    /** Refill when fewer than this remain. Default 4. */
+    lowWater?: number;
+    /** Called once when the source fails and the fallback takes over. */
+    onUnavailable?: (error: unknown) => void;
+    /** Random base for the fallback; injectable for tests. */
+    fallbackBase?: () => number;
+}
+export interface SequenceReserve {
+    /** The next number, or `null` when the pool is empty and a refill is pending. */
+    take(): number | null;
+    /** Reserve a block now; resolves when the pool is refilled (or the fallback engaged). */
+    refill(): Promise<void>;
+    /** Whether numbers still come from the shared source. */
+    shared(): boolean;
+    /** Forget the fallback and the pool — the shared source is back. */
+    reset(): void;
+}
+export declare function createSequenceReserve(reserve: (count: number) => Promise<number[]>, options?: SequenceReserveOptions): SequenceReserve;
+//# sourceMappingURL=sequence-reserve.d.ts.map

package/dist/tracking/sequence-reserve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sequence-reserve.d.ts","sourceRoot":"","sources":["../../src/tracking/sequence-reserve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,sBAAsB;IACrC,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACzC,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,eAAe;IAC9B,iFAAiF;IACjF,IAAI,IAAI,MAAM,GAAG,IAAI,CAAC;IACtB,yFAAyF;IACzF,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,yDAAyD;IACzD,MAAM,IAAI,OAAO,CAAC;IAClB,oEAAoE;IACpE,KAAK,IAAI,IAAI,CAAC;CACf;AAED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,EAC7C,OAAO,GAAE,sBAA2B,GACnC,eAAe,CAkDjB"}

package/dist/tracking/server/active-interval.d.ts

@@ -0,0 +1,26 @@
+export interface ActiveTimeInterval {
+    intervalId: string;
+    page: string;
+    deltaMs: number;
+    startedAt: Date;
+    endedAt: Date;
+}
+export interface ActiveIntervalOptions {
+    /** Longest interval a client may claim. Default 30 minutes. */
+    maxMs?: number;
+    /** The event types that carry an interval. Default `PAGE_LEAVE` and `SESSION_HEARTBEAT`. */
+    types?: readonly string[];
+}
+/**
+ * The visible-time interval an event carries, dated by the **server**: the
+ * client reports only a duration, its `intervalStartedAt` is carried for the
+ * timeline and never used — a client's clock is not admitted to the record.
+ * `null` when the event has no interval, an unshaped one, or one longer than
+ * a tab could plausibly have been visible.
+ */
+export declare function activeIntervalOf(event: {
+    type: string;
+    page: string;
+    metadata?: Record<string, unknown> | undefined;
+}, serverNow: Date, { maxMs, types, }?: ActiveIntervalOptions): ActiveTimeInterval | null;
+//# sourceMappingURL=active-interval.d.ts.map

package/dist/tracking/server/active-interval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"active-interval.d.ts","sourceRoot":"","sources":["../../../src/tracking/server/active-interval.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;IAChB,OAAO,EAAE,IAAI,CAAC;CACf;AAED,MAAM,WAAW,qBAAqB;IACpC,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4FAA4F;IAC5F,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;CAAE,EACrF,SAAS,EAAE,IAAI,EACf,EACE,KAAsB,EACtB,KAA2C,GAC5C,GAAE,qBAA0B,GAC5B,kBAAkB,GAAG,IAAI,CAgB3B"}

package/dist/tracking/server/bot.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Crawlers and monitors are not visitors. The pattern is the one two
+ * consuming applications converged on; it includes `headlesschrome`, so an
+ * agent's browser is a bot too — probe with a real user agent, set at browser
+ * launch (a context override does not reach `sendBeacon`).
+ */
+export declare const DEFAULT_BOT_USER_AGENT_PATTERN: RegExp;
+export declare function isBotUserAgent(userAgent: string | null | undefined, pattern?: RegExp): boolean;
+//# sourceMappingURL=bot.d.ts.map

package/dist/tracking/server/bot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bot.d.ts","sourceRoot":"","sources":["../../../src/tracking/server/bot.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,8BAA8B,QACwH,CAAC;AAEpK,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACpC,OAAO,GAAE,MAAuC,GAC/C,OAAO,CAET"}