stitchkit 0.80.1 → 0.81.0

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

@@ -0,0 +1,55 @@
+import type { TrackingDisposition } from '../schemas.js';
+/** What the decision needs from a stored visit. */
+export interface KnownVisit {
+    id: string;
+    browserStreamId: string;
+    /** The visit's owner, or `null` for an anonymous visit. */
+    ownerId: string | null;
+}
+/** The least an incoming event needs for the decision. */
+export interface DispositionEvent {
+    eventId: string;
+    visitId: string;
+    browserStreamId: string;
+}
+export interface DispositionInput<TEvent extends DispositionEvent> {
+    events: readonly TEvent[];
+    /** The visits the batch names, as the application read them. */
+    visits: readonly KnownVisit[];
+    /** `eventId → stored payload hash` for the batch's ids the application already holds. */
+    existing: ReadonlyMap<string, string>;
+    /** The caller's identity, or `null` for an anonymous caller. */
+    actorOwnerId: string | null;
+    userAgent?: string | null;
+    botPattern?: RegExp;
+}
+export interface DispositionResult<TEvent extends DispositionEvent> {
+    /** Events to write, in batch order. */
+    accepted: TEvent[];
+    /** One per incoming event, in batch order. */
+    dispositions: TrackingDisposition[];
+    /** Duplicates whose payload differs from the stored one — worth a warning. */
+    conflicts: string[];
+    /**
+     * Anonymous visits the batch names while the caller is identified: the
+     * application may adopt them (assign the owner, back-fill the events, record
+     * the merge) in the same transaction it writes the batch with.
+     */
+    adoptable: string[];
+}
+/**
+ * Decide every event of a batch without touching storage.
+ *
+ * - a bot's batch is `excluded-bot` in full, and nothing is written;
+ * - an event naming a visit the batch's browser does not own — unknown, a
+ *   different lineage, or owned by someone else — is `identity-invalid`;
+ * - an `eventId` already stored is `duplicate` (a redelivery), and a
+ *   `conflict` besides if the payload changed;
+ * - the rest is `accepted`.
+ *
+ * An anonymous visit (`ownerId: null`) accepts events from anyone holding the
+ * lineage: that is the visit that started before sign-in. When the caller is
+ * identified it is also listed as `adoptable`.
+ */
+export declare function dispositionTrackingBatch<TEvent extends DispositionEvent>({ events, visits, existing, actorOwnerId, userAgent, botPattern, }: DispositionInput<TEvent>): DispositionResult<TEvent>;
+//# sourceMappingURL=disposition.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"disposition.d.ts","sourceRoot":"","sources":["../../../src/tracking/server/disposition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAItD,mDAAmD;AACnD,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,eAAe,EAAE,MAAM,CAAC;IACxB,2DAA2D;IAC3D,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,0DAA0D;AAC1D,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,gBAAgB,CAAC,MAAM,SAAS,gBAAgB;IAC/D,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,gEAAgE;IAChE,MAAM,EAAE,SAAS,UAAU,EAAE,CAAC;IAC9B,yFAAyF;IACzF,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,gEAAgE;IAChE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB,CAAC,MAAM,SAAS,gBAAgB;IAChE,uCAAuC;IACvC,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,8CAA8C;IAC9C,YAAY,EAAE,mBAAmB,EAAE,CAAC;IACpC,8EAA8E;IAC9E,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB;;;;OAIG;IACH,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,SAAS,gBAAgB,EAAE,EACxE,MAAM,EACN,MAAM,EACN,QAAQ,EACR,YAAY,EACZ,SAAS,EACT,UAA2C,GAC5C,EAAE,gBAAgB,CAAC,MAAM,CAAC,GAAG,iBAAiB,CAAC,MAAM,CAAC,CA4CtD"}

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

@@ -0,0 +1,13 @@
+/**
+ * The payload hash stored beside an accepted event, and compared when the same
+ * `eventId` arrives again: an identical hash is a benign redelivery, a
+ * different one is a conflict worth a warning.
+ *
+ * Deliberately `sha256(JSON.stringify(event))` over the **schema-parsed**
+ * value, with no key sorting: that is exactly what consuming applications
+ * already store, and zod fixes key order when it parses, so the hash is
+ * stable. A canonicalised form would mismatch every stored hash for the seven
+ * days an outbox can hold an event.
+ */
+export declare function hashTrackingEvent(event: unknown): string;
+//# sourceMappingURL=hash.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../../src/tracking/server/hash.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAExD"}

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

@@ -0,0 +1,27 @@
+/**
+ * Who is on the site right now. A process-local snapshot, not history: it is
+ * honestly empty after a restart until the first heartbeat, and a second
+ * process has its own.
+ */
+export interface PresenceEntry<TExtra extends Record<string, unknown> = Record<string, unknown>> {
+    browserStreamId: string;
+    visitId: string | null;
+    ownerId: string | null;
+    page: string;
+    extra: TExtra;
+}
+export interface PresenceRegistry<TExtra extends Record<string, unknown>> {
+    touch(entry: PresenceEntry<TExtra>): void;
+    /** Everyone seen within the TTL, optionally filtered — a tenant, an area. */
+    snapshot(filter?: (entry: PresenceEntry<TExtra>) => boolean): Array<PresenceEntry<TExtra> & {
+        lastSeen: Date;
+    }>;
+    /** The most recently seen visit of one owner — for server-side events with no browser request. */
+    presentVisitOf(ownerId: string): string | null;
+    clear(): void;
+}
+export declare function createPresenceRegistry<TExtra extends Record<string, unknown>>(options?: {
+    ttlMs?: number;
+    now?: () => number;
+}): PresenceRegistry<TExtra>;
+//# sourceMappingURL=presence.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"presence.d.ts","sourceRoot":"","sources":["../../../src/tracking/server/presence.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,aAAa,CAC5B,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAEhE,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACtE,KAAK,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;IAC1C,6EAA6E;IAC7E,QAAQ,CACN,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,KAAK,OAAO,GACjD,KAAK,CAAC,aAAa,CAAC,MAAM,CAAC,GAAG;QAAE,QAAQ,EAAE,IAAI,CAAA;KAAE,CAAC,CAAC;IACrD,kGAAkG;IAClG,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC/C,KAAK,IAAI,IAAI,CAAC;CACf;AAED,wBAAgB,sBAAsB,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3E,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CAAO,GACnD,gBAAgB,CAAC,MAAM,CAAC,CAgC1B"}

package/dist/tracking/server/visit-lease.d.ts

@@ -0,0 +1,92 @@
+import type { VisitBootstrapResponse, VisitEntryContext } from '../schemas.js';
+/** Who is asking for the lease. */
+export interface VisitActor {
+    /** The caller's identity, or `null` for an anonymous caller. */
+    ownerId: string | null;
+    userAgent?: string | null;
+}
+/** An active visit as the store reports it. */
+export interface ActiveVisit {
+    id: string;
+    ownerId: string | null;
+    startedAt: Date;
+}
+/**
+ * The outbox health a bootstrap reports, written onto the visit so the
+ * server can see a browser whose queue is unavailable or overflowing.
+ */
+export interface VisitOutboxHealth {
+    outboxState: VisitEntryContext['outboxState'];
+    outboxQueued: number;
+    outboxDropped: number;
+    outboxReportedAt: Date;
+}
+/**
+ * Which visits the caller may continue. `adopting`: an anonymous visit or the
+ * caller's own — the visit that started before sign-in is continued and
+ * adopted. `owned`: only the caller's own — every visitor already has an
+ * identity, an anonymous visit is never continued.
+ */
+export type VisitOwnership = 'adopting' | 'owned';
+export interface FindActiveVisitQuery {
+    browserStreamId: string;
+    /** A visit whose `lastActivityAt` is before this is not active. */
+    cutoff: Date;
+    actorOwnerId: string | null;
+    ownership: VisitOwnership;
+    /** The visit the browser believes it is in; preferred when still active. */
+    previousVisitId?: string;
+}
+/**
+ * The store the application implements over its database. Everything runs
+ * inside `withLineageLock`, which serialises bootstraps of one browser
+ * lineage — two tabs starting at once must not each open a visit.
+ */
+export interface TrackingVisitStore<TTx = unknown> {
+    withLineageLock<T>(browserStreamId: string, fn: (tx: TTx) => Promise<T>): Promise<T>;
+    findActive(tx: TTx, query: FindActiveVisitQuery): Promise<ActiveVisit | null>;
+    /** Extend the lease; `health` is the browser's outbox report. */
+    touch(tx: TTx, visitId: string, now: Date, health: VisitOutboxHealth): Promise<void>;
+    /**
+     * Give an anonymous visit to the caller. Required under `ownership:
+     * 'adopting'` — `issueVisitLease` refuses to run without it rather than
+     * continue an anonymous visit and leave it anonymous; an `owned` store
+     * never adopts and may omit it.
+     */
+    adopt?(tx: TTx, visit: ActiveVisit, actorOwnerId: string, now: Date): Promise<void>;
+    /** Close every open visit of the lineage before a new one starts. */
+    endOpen(tx: TTx, browserStreamId: string, now: Date): Promise<void>;
+    /** Write a new visit; the application derives device, geo and source itself. */
+    create(tx: TTx, visit: {
+        id: string;
+        actor: VisitActor;
+        entry: VisitEntryContext;
+        startedAt: Date;
+    }, health: VisitOutboxHealth): Promise<void>;
+}
+export interface IssueVisitLeaseOptions {
+    ownership: VisitOwnership;
+    /** Idle time that ends a visit. Default 30 minutes. */
+    idleMs?: number;
+    now?: () => Date;
+    randomUUID?: () => string;
+    botPattern?: RegExp;
+}
+export interface IssuedVisitLease extends VisitBootstrapResponse {
+    /** `continued` when an active visit was extended, `started` when a new one opened. */
+    outcome: 'continued' | 'started' | 'bot';
+    /** The anonymous visit that was adopted by the caller, when one was. */
+    adopted: ActiveVisit | null;
+}
+/**
+ * Issue or renew a visit lease.
+ *
+ * A bot gets a lease that exists in no store: its later events are then
+ * `identity-invalid`, and neither the visit nor the events reach a report.
+ * Otherwise, under the lineage lock: the visit the browser names if it is
+ * still active and continuable, else the most recent active one; found —
+ * touch it (and adopt it when anonymous and the caller is identified); not
+ * found — end whatever is open and start a new one.
+ */
+export declare function issueVisitLease<TTx>(store: TrackingVisitStore<TTx>, actor: VisitActor, entry: VisitEntryContext, { ownership, idleMs, now, randomUUID, botPattern, }: IssueVisitLeaseOptions): Promise<IssuedVisitLease>;
+//# sourceMappingURL=visit-lease.d.ts.map

package/dist/tracking/server/visit-lease.d.ts.map

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

package/dist/tracking/visible-time.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Visible time, measured additively.
+ *
+ * Every cut yields an interval with its own id and a duration since the last
+ * checkpoint; the server sums intervals by id, so a re-delivered event does not
+ * double-count and a heartbeat that never arrives loses only its own slice.
+ * The server dates the interval from its own clock and the duration; the
+ * client's `intervalStartedAt` is carried for the timeline, never trusted.
+ */
+export interface VisibleInterval {
+    activeIntervalId: string;
+    activeDurationMs: number;
+    intervalStartedAt: number;
+}
+/** What a heartbeat carries: an interval while visible, only the fact while hidden. */
+export type VisibleHeartbeat = (VisibleInterval & {
+    isVisible: true;
+}) | {
+    isVisible: false;
+    activeDurationMs: 0;
+};
+export interface VisibleTimeMeter {
+    /** Restart the measurement — a new page, or the tab became visible again. */
+    checkpoint(): void;
+    /** Close the interval since the last checkpoint and start a new one. */
+    cut(): VisibleInterval;
+    /** A heartbeat's view: a cut while visible; while hidden, no interval at all. */
+    heartbeat(visible: boolean): VisibleHeartbeat;
+}
+export interface VisibleTimeMeterOptions {
+    /** Monotonic clock (default `performance.now`). */
+    now?: () => number;
+    /** Wall clock (default `Date.now`). */
+    wallClock?: () => number;
+    randomUUID?: () => string;
+}
+export declare function createVisibleTimeMeter(options?: VisibleTimeMeterOptions): VisibleTimeMeter;
+//# sourceMappingURL=visible-time.d.ts.map

package/dist/tracking/visible-time.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visible-time.d.ts","sourceRoot":"","sources":["../../src/tracking/visible-time.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B,gBAAgB,EAAE,MAAM,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,uFAAuF;AACvF,MAAM,MAAM,gBAAgB,GACxB,CAAC,eAAe,GAAG;IAAE,SAAS,EAAE,IAAI,CAAA;CAAE,CAAC,GACvC;IAAE,SAAS,EAAE,KAAK,CAAC;IAAC,gBAAgB,EAAE,CAAC,CAAA;CAAE,CAAC;AAE9C,MAAM,WAAW,gBAAgB;IAC/B,6EAA6E;IAC7E,UAAU,IAAI,IAAI,CAAC;IACnB,wEAAwE;IACxE,GAAG,IAAI,eAAe,CAAC;IACvB,iFAAiF;IACjF,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,gBAAgB,CAAC;CAC/C;AAED,MAAM,WAAW,uBAAuB;IACtC,mDAAmD;IACnD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,MAAM,CAAC;CAC3B;AAED,wBAAgB,sBAAsB,CACpC,OAAO,GAAE,uBAA4B,GACpC,gBAAgB,CAyBlB"}

package/dist/tracking-server.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `stitchkit/tracking/server` — the decisions a tracking backend makes,
+ * without the storage it makes them over. The application reads visits and
+ * stored hashes from its own database, hands them here, and writes what comes
+ * back; `issueVisitLease` runs the visit algorithm over a store interface the
+ * application implements. No database, no schema, no domain. → ADR 0166.
+ */
+export { type ActiveIntervalOptions, type ActiveTimeInterval, activeIntervalOf, } from './tracking/server/active-interval.js';
+export { DEFAULT_BOT_USER_AGENT_PATTERN, isBotUserAgent } from './tracking/server/bot.js';
+export { type DispositionEvent, type DispositionInput, type DispositionResult, dispositionTrackingBatch, type KnownVisit, } from './tracking/server/disposition.js';
+export { hashTrackingEvent } from './tracking/server/hash.js';
+export { createPresenceRegistry, type PresenceEntry, type PresenceRegistry, } from './tracking/server/presence.js';
+export { type ActiveVisit, type FindActiveVisitQuery, type IssuedVisitLease, type IssueVisitLeaseOptions, issueVisitLease, type TrackingVisitStore, type VisitActor, type VisitOutboxHealth, type VisitOwnership, } from './tracking/server/visit-lease.js';
+//# sourceMappingURL=tracking-server.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tracking-server.d.ts","sourceRoot":"","sources":["../src/tracking-server.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,gBAAgB,GACjB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,8BAA8B,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvF,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,wBAAwB,EACxB,KAAK,UAAU,GAChB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EACL,sBAAsB,EACtB,KAAK,aAAa,EAClB,KAAK,gBAAgB,GACtB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAC3B,eAAe,EACf,KAAK,kBAAkB,EACvB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,cAAc,GACpB,MAAM,+BAA+B,CAAC"}

package/dist/tracking-server.js

@@ -0,0 +1,173 @@
+// src/tracking/server/active-interval.ts
+var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function activeIntervalOf(event, serverNow, {
+  maxMs = 30 * 60 * 1000,
+  types = ["PAGE_LEAVE", "SESSION_HEARTBEAT"]
+} = {}) {
+  if (!types.includes(event.type) || !event.metadata)
+    return null;
+  const intervalId = event.metadata.activeIntervalId;
+  const deltaMs = event.metadata.activeDurationMs;
+  if (typeof intervalId !== "string" || !UUID.test(intervalId))
+    return null;
+  if (typeof deltaMs !== "number" || !Number.isFinite(deltaMs))
+    return null;
+  const rounded = Math.round(deltaMs);
+  if (rounded <= 0 || rounded > maxMs)
+    return null;
+  return {
+    intervalId,
+    page: event.page,
+    deltaMs: rounded,
+    startedAt: new Date(serverNow.getTime() - rounded),
+    endedAt: serverNow
+  };
+}
+// src/tracking/server/bot.ts
+var DEFAULT_BOT_USER_AGENT_PATTERN = /bot|crawl|spider|slurp|mediapartners|facebookexternalhit|bingpreview|yandex|baidu|duckduckbot|uptimerobot|pingdom|gtmetrix|pagespeed|lighthouse|headlesschrome/i;
+function isBotUserAgent(userAgent, pattern = DEFAULT_BOT_USER_AGENT_PATTERN) {
+  return userAgent ? pattern.test(userAgent) : false;
+}
+// src/tracking/server/hash.ts
+import { createHash } from "node:crypto";
+function hashTrackingEvent(event) {
+  return createHash("sha256").update(JSON.stringify(event)).digest("hex");
+}
+
+// src/tracking/server/disposition.ts
+function dispositionTrackingBatch({
+  events,
+  visits,
+  existing,
+  actorOwnerId,
+  userAgent,
+  botPattern = DEFAULT_BOT_USER_AGENT_PATTERN
+}) {
+  if (isBotUserAgent(userAgent, botPattern)) {
+    return {
+      accepted: [],
+      dispositions: events.map((event) => ({
+        eventId: event.eventId,
+        status: "excluded-bot"
+      })),
+      conflicts: [],
+      adoptable: []
+    };
+  }
+  const visitsById = new Map(visits.map((visit) => [visit.id, visit]));
+  const accepted = [];
+  const dispositions = [];
+  const conflicts = [];
+  const adoptable = new Set;
+  const acceptedHashes = new Map;
+  for (const event of events) {
+    const visit = visitsById.get(event.visitId);
+    if (!visit || visit.browserStreamId !== event.browserStreamId || visit.ownerId !== null && visit.ownerId !== actorOwnerId) {
+      dispositions.push({ eventId: event.eventId, status: "identity-invalid" });
+      continue;
+    }
+    const stored = existing.get(event.eventId) ?? acceptedHashes.get(event.eventId);
+    if (stored !== undefined) {
+      if (stored !== hashTrackingEvent(event))
+        conflicts.push(event.eventId);
+      dispositions.push({ eventId: event.eventId, status: "duplicate" });
+      continue;
+    }
+    if (visit.ownerId === null && actorOwnerId)
+      adoptable.add(visit.id);
+    acceptedHashes.set(event.eventId, hashTrackingEvent(event));
+    accepted.push(event);
+    dispositions.push({ eventId: event.eventId, status: "accepted" });
+  }
+  return { accepted, dispositions, conflicts, adoptable: [...adoptable] };
+}
+// src/tracking/server/presence.ts
+function createPresenceRegistry(options = {}) {
+  const ttlMs = options.ttlMs ?? 45000;
+  const now = options.now ?? (() => Date.now());
+  const active = new Map;
+  const sweep = () => {
+    const at = now();
+    for (const [key, entry] of active) {
+      if (at - entry.lastSeen > ttlMs)
+        active.delete(key);
+    }
+  };
+  return {
+    touch(entry) {
+      active.set(entry.browserStreamId, { ...entry, lastSeen: now() });
+    },
+    snapshot(filter = () => true) {
+      sweep();
+      return [...active.values()].filter(filter).map((entry) => ({ ...entry, lastSeen: new Date(entry.lastSeen) }));
+    },
+    presentVisitOf(ownerId) {
+      sweep();
+      let best = null;
+      for (const entry of active.values()) {
+        if (entry.ownerId !== ownerId)
+          continue;
+        if (!best || entry.lastSeen > best.lastSeen)
+          best = entry;
+      }
+      return best?.visitId ?? null;
+    },
+    clear: () => active.clear()
+  };
+}
+// src/tracking/server/visit-lease.ts
+async function issueVisitLease(store, actor, entry, {
+  ownership,
+  idleMs = 30 * 60 * 1000,
+  now = () => new Date,
+  randomUUID = () => crypto.randomUUID(),
+  botPattern = DEFAULT_BOT_USER_AGENT_PATTERN
+}) {
+  if (ownership === "adopting" && !store.adopt) {
+    throw new Error("issueVisitLease: ownership 'adopting' requires store.adopt");
+  }
+  const at = now();
+  const expiresAt = new Date(at.getTime() + idleMs).toISOString();
+  if (isBotUserAgent(actor.userAgent, botPattern)) {
+    return { visitId: randomUUID(), expiresAt, outcome: "bot", adopted: null };
+  }
+  const health = {
+    outboxState: entry.outboxState,
+    outboxQueued: entry.outboxQueued,
+    outboxDropped: entry.outboxDropped,
+    outboxReportedAt: at
+  };
+  return store.withLineageLock(entry.browserStreamId, async (tx) => {
+    const query = {
+      browserStreamId: entry.browserStreamId,
+      cutoff: new Date(at.getTime() - idleMs),
+      actorOwnerId: actor.ownerId,
+      ownership
+    };
+    const continuable = (visit) => visit && (visit.ownerId === actor.ownerId || visit.ownerId === null && ownership === "adopting") ? visit : null;
+    const requested = entry.previousVisitId ? continuable(await store.findActive(tx, { ...query, previousVisitId: entry.previousVisitId })) : null;
+    const active = requested ?? continuable(await store.findActive(tx, query));
+    if (active) {
+      let adopted = null;
+      if (ownership === "adopting" && active.ownerId === null && actor.ownerId && store.adopt) {
+        await store.adopt(tx, active, actor.ownerId, at);
+        adopted = active;
+      }
+      await store.touch(tx, active.id, at, health);
+      return { visitId: active.id, expiresAt, outcome: "continued", adopted };
+    }
+    await store.endOpen(tx, entry.browserStreamId, at);
+    const visitId = randomUUID();
+    await store.create(tx, { id: visitId, actor, entry, startedAt: at }, health);
+    return { visitId, expiresAt, outcome: "started", adopted: null };
+  });
+}
+export {
+  issueVisitLease,
+  isBotUserAgent,
+  hashTrackingEvent,
+  dispositionTrackingBatch,
+  createPresenceRegistry,
+  activeIntervalOf,
+  DEFAULT_BOT_USER_AGENT_PATTERN
+};

package/dist/tracking.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `stitchkit/tracking` — the browser mechanics of visitor tracking: a
+ * tab-shared outbox with reserved sequences and a short flush lease, delivery
+ * with one bounded retry, the page-leave beacon that actually arrives, visible
+ * time, scroll milestones, declarative clicks, attribution, and the client
+ * that composes them. No React, no DOM at import time, no event vocabulary of
+ * its own. The server half is `stitchkit/tracking/server`. → ADR 0166.
+ */
+export { type AttributionStorage, parseReferrer, parseUtmFromSearch, type ReferrerRule, type ResolveAttributionInput, type ResolvedAttribution, resolveAttribution, } from './tracking/attribution.js';
+export { sendUnloadBeacon } from './tracking/beacon.js';
+export { type ClickTarget, type ResolveTrackedClickOptions, resolveTrackedClick, type TrackedClick, type TrackedClickAttributes, } from './tracking/clicks.js';
+export { type BuiltinTrackingEventTypes, CONVENTIONAL_TRACKING_EVENT_TYPES, createTrackingClient, type EventsWithMetadata, type EventsWithoutMetadata, type TrackFn, type TrackingClient, type TrackingClientConfig, } from './tracking/client.js';
+export { createTrackingContract, type TrackingContractConfig, type TrackingContractEndpoints, } from './tracking/contract.js';
+export { deliverTrackingBatch, type TrackingDeliveryOptions, type TrackingDeliveryOutcome, } from './tracking/delivery.js';
+export { browserTrackingHost, type TrackingHost, type TrackingPageContext, } from './tracking/host.js';
+export { createOncePerPage, type OncePerPage } from './tracking/once-per-page.js';
+export { createTrackingOutbox, type TrackingOutbox, type TrackingOutboxEvents, type TrackingOutboxHealth, type TrackingOutboxMeta, type TrackingOutboxOptions, type TrackingOutboxRecord, type TrackingOutboxStorage, type TrackingQueuedEvent, } from './tracking/outbox.js';
+export { indexedDbOutboxStorage } from './tracking/outbox-storage-indexeddb.js';
+export { memoryOutboxStorage } from './tracking/outbox-storage-memory.js';
+export { type AttributionData, AttributionDataSchema, createTrackingSchemas, DEFAULT_BUILD_ID_PATTERN, type TrackEventsRequest, type TrackEventsResponse, TrackEventsResponseSchema, type TrackingDisposition, TrackingDispositionSchema, type TrackingDispositionStatus, TrackingDispositionStatusSchema, type TrackingEventEnvelope, type TrackingEventShape, type TrackingOutboxState, TrackingOutboxStateSchema, type TrackingSchemas, type TrackingSchemasConfig, type UtmData, UtmDataSchema, type VisitBootstrapResponse, VisitBootstrapResponseSchema, type VisitEntryContext, type VisitEntryContextShape, } from './tracking/schemas.js';
+export { createScrollMilestones, type ScrollMilestones, scrollDepthPercent, } from './tracking/scroll.js';
+export { createSequenceReserve, type SequenceReserve, type SequenceReserveOptions, } from './tracking/sequence-reserve.js';
+export { createVisibleTimeMeter, type VisibleHeartbeat, type VisibleInterval, type VisibleTimeMeter, type VisibleTimeMeterOptions, } from './tracking/visible-time.js';
+//# sourceMappingURL=tracking.d.ts.map

package/dist/tracking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracking.d.ts","sourceRoot":"","sources":["../src/tracking.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,KAAK,kBAAkB,EACvB,aAAa,EACb,kBAAkB,EAClB,KAAK,YAAY,EACjB,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EACxB,kBAAkB,GACnB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,0BAA0B,EAC/B,mBAAmB,EACnB,KAAK,YAAY,EACjB,KAAK,sBAAsB,GAC5B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,KAAK,yBAAyB,EAC9B,iCAAiC,EACjC,oBAAoB,EACpB,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,OAAO,EACZ,KAAK,cAAc,EACnB,KAAK,oBAAoB,GAC1B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,sBAAsB,EACtB,KAAK,sBAAsB,EAC3B,KAAK,yBAAyB,GAC/B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,oBAAoB,EACpB,KAAK,uBAAuB,EAC5B,KAAK,uBAAuB,GAC7B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,mBAAmB,EACnB,KAAK,YAAY,EACjB,KAAK,mBAAmB,GACzB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,iBAAiB,EAAE,KAAK,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC/E,OAAO,EACL,oBAAoB,EACpB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,GACzB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAC;AAC7E,OAAO,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AACvE,OAAO,EACL,KAAK,eAAe,EACpB,qBAAqB,EACrB,qBAAqB,EACrB,wBAAwB,EACxB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,yBAAyB,EACzB,KAAK,mBAAmB,EACxB,yBAAyB,EACzB,KAAK,yBAAyB,EAC9B,+BAA+B,EAC/B,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,yBAAyB,EACzB,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,OAAO,EACZ,aAAa,EACb,KAAK,sBAAsB,EAC3B,4BAA4B,EAC5B,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,GAC5B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,sBAAsB,EACtB,KAAK,gBAAgB,EACrB,kBAAkB,GACnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,qBAAqB,EACrB,KAAK,eAAe,EACpB,KAAK,sBAAsB,GAC5B,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,sBAAsB,EACtB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,GAC7B,MAAM,yBAAyB,CAAC"}