@nekuda/webmcp-sdk 0.4.0-dev.7.3

package/dist/telemetry.d.ts

@@ -0,0 +1,471 @@
+/**
+ * Default-on usage telemetry for `@nekuda/webmcp-sdk`. Independent of the opt-in
+ * `tracking` channel (`src/tracking.ts`): it needs no `apiKey`, so it reports SDK
+ * adoption, browser mix, WebMCP availability, and tool-call reliability from every
+ * site the SDK runs on. A page that *does* configure one has it sent as
+ * `x-api-key`, which only adds tenant attribution. Opt out with `telemetry: false`
+ * on `registerTools`, with `globalThis.__WEBMCP_TELEMETRY__ = false`, or via
+ * Global Privacy Control.
+ *
+ * Event schemas, joined on the in-memory `sessionId`, no batching,
+ * fire-and-forget: `sdk_init` (once per page load, from the one-shot flush this
+ * module schedules at import time), `tool_registration` (once per `registerTools`
+ * call), and `tool_call` (once per settled invocation). Events go to the separate
+ * `/v1/telemetry` endpoint through `sendTelemetry` in `src/transport.ts`.
+ *
+ * No browser storage is touched anywhere in this channel — no `visitorId`, no
+ * stored `sessionId` (the ePrivacy Art. 5(3) concern). Cross-visit stitching is
+ * deliberately impossible here; the authenticated `tracking` channel keeps its own
+ * storage-backed identity, and this one never reads it.
+ *
+ * Every field an event may carry is gated by the baked-in allowlists in
+ * `src/telemetry-fields.ts` — one keyed by event path, one by per-tool field.
+ * Pruning happens on the way out, so flipping a field to `false` there is the
+ * single change needed to stop collecting it.
+ */
+import { type ToolIntent, type ToolSource } from "./define.js";
+import type { ToolAnnotations } from "./spec.js";
+import { type InstallMode, type RegisteredToolEntry, type RegistrationTrigger, type SdkInitEvent, type TelemetryEvent, type ToolCallEvent, type ToolCallOutcome, type ToolRegistrationEvent, type ToolRegistrationOutcome } from "./telemetry-events.js";
+import { type TelemetryFieldMap, type TelemetryToolFieldMap } from "./telemetry-fields.js";
+import { type TrackingOptions } from "./tracking.js";
+/** Reported as `sdk.name` — the npm package identity. */
+export declare const SDK_NAME = "@nekuda/webmcp-sdk";
+/**
+ * Reported as `sdk.version`. The fallback is duplicated from `package.json`
+ * because a browser bundle cannot read it at runtime; a test pins the two
+ * together so a release that bumps one and not the other fails rather than
+ * mislabeling every event.
+ */
+export declare const SDK_VERSION: string;
+/**
+ * Reported as `sdk.installMode`. Defaults to `"npm"` — that is how every published
+ * build reaches a page today, and a mistyped define must degrade to the truth for
+ * the overwhelming majority rather than emit a value no consumer can read.
+ */
+export declare const SDK_INSTALL_MODE: InstallMode;
+/**
+ * Read a value that may not exist, collapsing both an absent property and a
+ * throwing getter to `undefined`. Every browser global this module touches is
+ * optional *and* attacker/extension-reachable, so reaching a property is as
+ * unsafe as calling a method — hence the thunk rather than a property lookup.
+ *
+ * Exported because the same hazard applies to the caller-supplied options object
+ * `register.ts` reads its channel configuration from.
+ */
+export declare function safe<T>(read: () => T): T | undefined;
+/**
+ * Global Privacy Control: `navigator.globalPrivacyControl === true` is a legally
+ * recognized opt-out signal, so the default-on channel goes fully silent for it.
+ * Strictly `true` — a truthy `"1"`/`1` is not the spec'd signal and must not be
+ * read as consent *or* refusal. Absent or hostile `navigator` → not opted out.
+ */
+export declare function gpcOptedOut(scope?: object): boolean;
+/**
+ * Whether the default-on telemetry channel may emit. Default-on means only three
+ * things silence it on a page: the explicit `telemetry: false` opt-out,
+ * {@link globalOptOut}, and GPC. When this is `false` nothing at all happens
+ * downstream — no `sdk_init`, no `tool_call`.
+ *
+ * Called twice per event, deliberately. `registerTools` asks once per call, with the
+ * batch's `option`, to decide whether that batch observes at all — a silent batch
+ * does zero work, not wasted work. {@link emitTelemetry} asks again without the
+ * option, at the moment an event would leave the page, because the two page-level
+ * levers can be flipped after that decision was made.
+ *
+ * A `document` is required on top of that, because this channel measures *browser*
+ * adoption and must never beacon from a non-browser runtime. The documented
+ * codegen shape calls `registerTools` at module scope, which also evaluates during
+ * SSR/prerender (Next, Remix), where an unauthenticated POST from the customer's
+ * own server is both unexpected egress and junk data: a server `fetch` sends no
+ * CORS `Origin`, the only site-attribution signal this channel has, and the event
+ * carries no client context, no page context, and `surface.available: false` for a
+ * runtime that was never going to have one. Every real browser has a `document`; an
+ * unsupported one is missing only `document.modelContext`, so the
+ * unsupported-browser adoption signal still reports.
+ */
+export declare function telemetryEnabled(option?: boolean, scope?: object): boolean;
+/**
+ * `client.browser` / `client.browserMajor` — the browser's own identity, the only
+ * environment fact these events carry. Both absent when UA-Client-Hints is.
+ */
+export interface BrowserBrand {
+    browser?: string;
+    browserMajor?: number;
+}
+/**
+ * A clustering key for the thrown value's message: the message with its
+ * high-cardinality substrings templated to `*`, so `no product for SKU-12345` and
+ * `no product for SKU-98765` land in one bucket. Complements
+ * {@link errorClassOf}, which is class-only and so cannot separate two failure
+ * modes that share a class — nearly every merchant failure is a bare `Error`.
+ *
+ * `undefined`, never an empty string, when the message is unreadable or empty, so
+ * the field is omitted rather than adding a meaningless key to every event. A
+ * nullish throw is one of those cases: `String(undefined)` would otherwise cluster
+ * as the literal signature `"undefined"`, describing an error nobody observed and
+ * mixing `throw undefined` in with the outcome that was recorded without one at all
+ * (`register.ts` carries no `error` for a rejection with `undefined`). Absent here
+ * matches {@link errorClassOf}, which is already `null` for the same value.
+ *
+ * Templating runs before the byte cap but after {@link MAX_INPUT_CHARS}. The prefix
+ * bound is what makes the cost of the scans safe: each rule scans from its own set of
+ * starting positions, and a thrown message is page-controlled, so an unbounded input
+ * turned a multi-megabyte one into a main-thread stall of hundreds of milliseconds on
+ * the error path. It cannot be left
+ * to {@link LONG_RUN} to collapse the run first: a run with no digits and few capitals
+ * reads as prose to `isOpaque` and survives whole. What the bound costs is the tail of
+ * a message whose middle collapses to nothing — two megabytes of digits between
+ * `order ` and ` not found` clusters as `order *` — the accepted trade, since the
+ * opening words are what make the key useful; see {@link MAX_INPUT_CHARS}.
+ *
+ * What the prefix bound does *not* do is license bounding a rule's own candidate. A
+ * rule that matches part of an oversized candidate — or, for {@link QUOTED_LITERAL},
+ * none of it — is a leak of exactly the value it exists to remove, so
+ * {@link QUOTED_LITERAL}, {@link EMAIL}, {@link URL_RUN}, and {@link PATH_RUN} each run
+ * to a delimiter instead — see each for why that costs nothing. Where the *cut* is what
+ * removes a rule's closing delimiter, {@link CUT_CANDIDATE} stands in as that
+ * delimiter, so the bound cannot leak by the back door what the rules no longer leak
+ * by the front.
+ *
+ * Templating before the *byte* cap is what makes a huge message cluster on its
+ * opening words instead of on whatever the byte cut happened to leave behind.
+ *
+ * The rules then run in a fixed order, and four adjacencies are load-bearing.
+ * {@link CUT_CANDIDATE} precedes {@link QUOTED_LITERAL} so the quote the cut left open
+ * cannot be read as an earlier literal's closing delimiter. {@link URL_RUN} precedes
+ * both {@link LONG_RUN} and {@link PATH_RUN} so an absolute URL is taken whole rather
+ * than shredded — {@link LONG_RUN}'s class includes `/`, so it would otherwise collapse
+ * an opaque `//host` run first and destroy the `://` anchor {@link URL_RUN} needs,
+ * leaving the path and query on the wire
+ * (`POST failed https:*.example.com/reset?user=johnsmith`); {@link PATH_RUN} would eat
+ * the `//` and leave `https:*`. {@link DIGIT_RUN} runs last so a partly-numeric token
+ * collapses to a single `*` rather than being shredded into a digit-free remnant —
+ * which is both a worse cluster key and a partial leak of the token.
+ */
+export declare function errorSignature(error: unknown): string | undefined;
+/** What `sdk_init` needs from its caller: nothing but a scope to read. */
+export interface InitEventParams {
+    /**
+     * Injectable global scope for every derived read (tests) — except `timeToInitMs`,
+     * which was read at module load and is not a read of this scope at all.
+     */
+    scope?: object;
+}
+/**
+ * Assemble the `sdk_init` event: one per page load, reporting which build reached
+ * the page, what WebMCP surface it found, and what kind of page and client it
+ * landed in. It carries nothing about any `registerTools` call — that is
+ * `tool_registration`'s job, and this event fires even when no batch ever runs,
+ * which is the only way a broken integration is visible at all.
+ *
+ * The truncation ladder `emitTelemetry` runs on the way out never fires for this
+ * event: every string on it is capped at the read (`browser` at
+ * {@link MAX_BRAND_BYTES}, the route template, the spec version, a two-or-three-letter
+ * language subtag, a bounded `sessionId`), so the assembled event cannot approach the
+ * 64 KB transport bound in the first place.
+ */
+export declare function buildInitEvent(params?: InitEventParams): SdkInitEvent;
+/**
+ * What `tool_registration` reads off a tool. Structurally satisfied by a defined
+ * tool; everything past the identity is optional because this builder must survive
+ * a caller that skipped `defineTool`.
+ */
+export interface RegisteredTelemetryTool {
+    name: string;
+    stableKey: string;
+    version?: string;
+    description?: string;
+    inputSchema?: unknown;
+    annotations?: ToolAnnotations;
+    source?: ToolSource;
+    intent?: ToolIntent;
+}
+/** One tool's registration, as the caller watched it settle. */
+export interface RegisteredToolParams {
+    tool: RegisteredTelemetryTool;
+    outcome: ToolRegistrationOutcome;
+    /** What the surface rejected with; templated into `failureSignature` when `failed`. */
+    error?: unknown;
+}
+/** Where a batch sits in the page load, and what caused it. */
+export interface RegistrationSequence {
+    /** 1-based position among the batches this page load reports. */
+    registrationIndex: number;
+    trigger: RegistrationTrigger;
+}
+/**
+ * Claim the next batch's position and trigger, advancing module state as it goes.
+ *
+ * Called at `registerTools` *call* time, not at settle time: the index is the order
+ * the calls were made in, and two overlapping batches would otherwise be numbered by
+ * whichever surface answered first. It follows that the route read here is the route
+ * the call happened on, which is what a `spa_navigation` trigger is about — the event
+ * itself derives `routeTemplate` again at emit time, and an SPA that navigates mid-
+ * registration is the one case where the two can differ.
+ *
+ * Only a batch that will actually emit may claim, so the reported sequence has no
+ * gaps: an index missing from the stream means a lost beacon, not an opt-out.
+ */
+export declare function nextRegistration(scope?: object): RegistrationSequence;
+/** What `tool_registration` needs from `registerTools`; the rest is derived. */
+export interface ToolRegistrationEventParams {
+    /** 1-based position of this batch within the page load. */
+    registrationIndex: number;
+    trigger: RegistrationTrigger;
+    /** Milliseconds from the call to the batch settling (or to the timeout). */
+    settleMs: number;
+    /** Every tool in the batch, in the order it was passed to `registerTools`. */
+    tools: readonly RegisteredToolParams[];
+    /** The batch's authenticated-channel options — reported as `config.*`. */
+    tracking?: TrackingOptions;
+    /** Injectable global scope for every derived read (tests). */
+    scope?: object;
+}
+/**
+ * Assemble the `tool_registration` event: one per `registerTools` call, carrying
+ * the per-tool outcomes v1 computed and threw away. A site where 3 of 8 tools fail
+ * on a duplicate name is the failure mode this event exists to make visible, and
+ * `tools[]` is the only place it is visible at all.
+ *
+ * `config.*` lives here rather than on `sdk_init` because it is per-batch: at
+ * `sdk_init` flush time no batch may have run, so there is nothing to report.
+ *
+ * The event is unbounded in size by design at this layer — a 500-tool batch is a real
+ * shape, and this is the one event of the three that can exceed the transport's 64 KB
+ * limit. Keeping it inside that limit is the `tools` rung of the truncation ladder in
+ * `src/tracking.ts`, which `emitTelemetry` runs after pruning: entries lose their shape
+ * detail first, and the array degrades to a bare count only if that was not enough.
+ */
+export declare function buildToolRegistrationEvent(params: ToolRegistrationEventParams): ToolRegistrationEvent & {
+    tools: RegisteredToolEntry[];
+};
+/** Where one invocation sits in the page load's sequence of tool calls. */
+export interface ToolCallSequence {
+    /** Per-call random ID — deduplicates a retried beacon, joins nothing else. */
+    callId: string;
+    /** 1-based position among all tool calls in this page load. */
+    callIndex: number;
+    /** 1-based position among calls to *this* tool. */
+    toolCallIndex: number;
+    /** The previously called tool's `stableKey`; absent on the page's first call. */
+    precededBy?: string;
+}
+/**
+ * Claim this invocation's position in the page load, advancing module state as it
+ * goes. The counters are what turn isolated events into a *journey*: which tool an
+ * agent reached for first, how many times it retried the same one, and what it had
+ * just called when this one failed.
+ *
+ * Claimed before the handler runs, not at settle time, so the sequence is the order
+ * the agent made the calls in rather than the order they happened to finish in —
+ * the same reason {@link nextRegistration} claims at call time. `precededBy` may
+ * therefore be this tool's own key: a retry is a real sequence, not a gap.
+ *
+ * The `callId` is this channel's own; the authenticated channel mints a separate one
+ * per invocation, and the two are deliberately not joinable.
+ *
+ * `precededBy` is the one field here scoped to `tenantScope` rather than to the page
+ * load, because it is the only one carrying a *tenant-owned string*. Two tenants
+ * sharing an origin is the topology {@link batchTelemetrySinks} exists for, and module
+ * state that spans them would put tenant A's `stableKey` in an event authenticated with
+ * tenant B's key — A's tool names attributed to B's org, the same misattribution the
+ * per-batch sinks prevent one field over. Omitted rather than remembered per tenant: a
+ * `precededBy` that would have to name another tenant's call is a gap, and the field is
+ * already documented as absent on a page's first call. The counters stay page-scoped —
+ * `callIndex` is defined as a position in the page load and carries no tenant's string.
+ */
+export declare function nextCall(stableKey: string, tenantScope?: string): ToolCallSequence;
+/** What `tool_call` reads off a tool — the two fields worth joining calls on. */
+export interface CalledTelemetryTool {
+    stableKey: string;
+    /** Reported as a hash only; the schema itself never leaves the page. */
+    inputSchema?: unknown;
+    intent?: ToolIntent;
+}
+/** What `tool_call` reports about one settled invocation. */
+export interface ToolCallEventParams extends ToolCallSequence {
+    tool: CalledTelemetryTool;
+    outcome: ToolCallOutcome;
+    /** Client-measured elapsed milliseconds. */
+    durationMs: number;
+    /** The normalized handler result (success path) — measured, never carried. */
+    response?: unknown;
+    /** The thrown value (error path) — reported as `errorClass` + `errorSignature`. */
+    error?: unknown;
+    /** Injectable global scope for every derived read (tests). */
+    scope?: object;
+}
+/**
+ * Assemble the `tool_call` event: one per settled invocation, derived signals only.
+ * The reliability question — did this tool work, how fast, and how did it fail — is
+ * answered by `outcome`, `durationMs`, the error *class* and *signature*, and the
+ * response *measurements*. The raw `input`, `response`, and error message v1 sent
+ * are gone: they carry merchant and visitor content, and none of them was needed to
+ * answer it.
+ *
+ * `outcome` alone decides the conditional halves, so neither a stray `error` on a
+ * successful call nor a stray `response` on a failed one can contradict it. No stack
+ * trace — unbounded, and it leaks code structure.
+ *
+ * The ladder never fires here either, for the same reason `buildInitEvent` never
+ * reaches it: every string is bounded at its source — `stableKey` at 1024 chars by `defineTool`,
+ * `errorClass` at {@link MAX_ERROR_CLASS_BYTES}, `errorSignature` at
+ * {@link MAX_ERROR_SIGNATURE_BYTES}, the route template in `telemetry-context.ts`,
+ * `intent` to one of its declared values by {@link toolEnum}, and
+ * `schemaHash`/`callId`/`sessionId` at fixed widths — so the assembled event
+ * cannot approach the 64 KB transport bound. That matters most inside `tool`, which
+ * no ladder rung can reach without discarding the identity this event joins on.
+ */
+export declare function buildToolCallEvent(params: ToolCallEventParams): ToolCallEvent;
+/**
+ * Drop every field the allowlists map to `false`, keyed by the path the field
+ * occupies in the emitted event: a flat key (`sessionId`) is deleted from the
+ * event, a dotted key (`sdk.version`, `page.routeTemplate`) from its parent object,
+ * and a per-tool key from every `tools[]` entry and from `tool_call.tool`. A parent
+ * left empty by pruning is dropped too, so a disabled group leaves no
+ * `"response": {}` husk behind. Keys absent from the allowlists pass through
+ * untouched — they gate what they know about, they are not a whitelist of the
+ * event's shape.
+ *
+ * Copy-on-write: the input event and any nested object or tool entry it owns are
+ * never mutated, and untouched nested values are shared by reference.
+ *
+ * Event-level paths are at most two levels deep (that is the full extent of the
+ * event schemas), which is why this splits on the first dot rather than walking an
+ * arbitrary path; the third level, inside `tools[]`, is what `toolFields` is for.
+ */
+export declare function pruneByAllowlist(event: Record<string, unknown>, fields?: TelemetryFieldMap, toolFields?: TelemetryToolFieldMap): Record<string, unknown>;
+/**
+ * The channel's single output. Injectable so orchestration can be tested without
+ * touching the network (the `TrackingSinks` pattern in `src/tracking.ts`).
+ */
+export interface TelemetrySinks {
+    sendTelemetry: (event: object) => void;
+}
+/**
+ * The sink for the two events a *batch* owns. They carry that batch's tool identity —
+ * `stableKey`, `routeTemplate`, `errorSignature` — so they authenticate with that
+ * batch's own key rather than with module state. Two tenants sharing an origin is a
+ * topology `TrackingOptions.apiKey` designs for, and reading the last-captured key at
+ * emit time would send tenant A's stableKeys under tenant B's key, attributing A's
+ * tools to B's org.
+ *
+ * A keyless batch falls back to whatever key the page supplied, resolved at emit time
+ * for the reason {@link defaultSinks} resolves late: the batch has no tenant of its
+ * own, and the page it registered on does. `sdk_init` keeps the module key because it
+ * carries page context only — no batch, and so nothing to misattribute.
+ *
+ * That late fallback is why a `tool_call`, whose `precededBy` can name a *different*
+ * tenant's tool, passes {@link resolveTelemetryKey}'s answer through here rather than
+ * the raw batch option: a key resolved to a value pins it, closing the window in which
+ * the module key changes between the claim and the emit.
+ */
+export declare function batchTelemetrySinks(apiKey: unknown): TelemetrySinks;
+/**
+ * The key a batch's beacons authenticate with, resolved now instead of at emit time:
+ * its own when it supplied one, otherwise the page's.
+ *
+ * Exists so a caller can resolve *once* and use the one answer for both halves of a
+ * beacon — the tenant it is claimed under ({@link telemetryTenantScope}) and the key it
+ * is sent with ({@link batchTelemetrySinks}). Both fall back to module state on a
+ * keyless batch, and `tool_call` consults them at two different moments: the scope
+ * before the handler runs, the key after it settles. A `registerTools` call landing in
+ * that window with a different `apiKey` made the two disagree, and the disagreement was
+ * exactly the misattribution the scope exists to prevent — tenant A's `stableKey`
+ * arriving via `precededBy` on a beacon authenticated as tenant C.
+ *
+ * Idempotent, so the resolved value can be handed straight back to either function: the
+ * result is `undefined` or an already-usable key, never a blank string.
+ */
+export declare function resolveTelemetryKey(apiKey: unknown): string | undefined;
+/**
+ * The tenant a batch's beacons belong to, as an opaque token — which tenant, never
+ * which key. Resolved exactly as {@link batchTelemetrySinks} resolves the key it
+ * authenticates with, so the scope a `tool_call` is claimed under is the scope its
+ * beacon is sent under. Hashed for the reason `storageNamespace` is: this is only ever
+ * compared, so there is no call for holding the key itself in a second place.
+ *
+ * An unkeyed page is one scope (`""`), which is the single-tenant case and the common
+ * one; see {@link nextCall} for what the scope gates.
+ */
+export declare function telemetryTenantScope(apiKey: unknown): string;
+/**
+ * Build one event, prune it by the allowlist, then hand it to the transport.
+ * Pruning happens **here**, on the way out, so it is the single choke point every
+ * event passes through — a field flipped to `false` in `telemetry-fields.ts`
+ * cannot leak through some builder that forgot to check.
+ *
+ * The 64 KB truncation ladder (`src/tracking.ts`) runs last, after pruning: a
+ * disabled field cannot be what pushes an event over the bound, and only
+ * `tool_registration` can approach it at all — every other string this channel emits
+ * is capped where it is read. An event still oversized after the ladder is dropped
+ * whole by `fetch(keepalive)`, which is why the ladder's `tools` rung degrades to a
+ * count rather than giving up.
+ *
+ * The page-level opt-outs are re-read here too, for the same reason pruning lives
+ * here: this is the only place all three events pass through. `registerTools`
+ * decides its batch's channel once, but a page can reach for a lever *after* that
+ * call — `__WEBMCP_TELEMETRY__` set from a consent callback, a `navigator` patched
+ * with GPC after load — and both are documented as silencing every event, not every
+ * event registered from then on. Trusting the latched decision instead would keep
+ * beaconing a page that asked for silence, which for GPC is a legally recognized
+ * opt-out. The cost is that a `callIndex`/`registrationIndex` claimed before the
+ * lever flipped leaves a gap; `docs/telemetry-schema.md` names that as one of the
+ * causes a gap can have.
+ *
+ * Never throws, which is why the event arrives as a thunk rather than a value: an
+ * argument is evaluated at the call site, *outside* this guard, so passing
+ * `buildToolCallEvent(...)` directly would leave assembly unprotected — and on the
+ * error path a builder throw would replace the tool's own error with a telemetry
+ * one, the worst possible failure for a channel that must stay an observer. Every
+ * global the builders read is guarded individually too; this is the backstop that
+ * keeps the guarantee true of assembly as a whole, not of each read in turn.
+ */
+export declare function emitTelemetry(build: () => TelemetryEvent, sinks?: TelemetrySinks, fields?: TelemetryFieldMap, toolFields?: TelemetryToolFieldMap): void;
+/**
+ * Record the `apiKey` of a `registerTools` call so the deferred `sdk_init` flush —
+ * which runs with no batch in hand, and may run before any batch exists — can
+ * authenticate. Non-string, empty, and whitespace-only values are ignored, so a
+ * page that never keys the authenticated channel simply stays anonymous.
+ *
+ * A later keyless batch does **not** clear a key an earlier one supplied: the page
+ * belongs to that tenant either way, and dropping the attribution because the
+ * second `registerTools` call omitted it would lose the more specific fact. A later
+ * *differing* key does overwrite, and on a two-tenant page one of them will be wrong
+ * — which is why only `sdk_init` reads this. The batch-owned events, the ones
+ * carrying tool identity, go through {@link batchTelemetrySinks} instead.
+ */
+export declare function captureTelemetryApiKey(apiKey: unknown): void;
+/** The key {@link captureTelemetryApiKey} last recorded, if any. */
+export declare function telemetryApiKey(): string | undefined;
+/**
+ * Cancel the deferred `sdk_init` below. Called by `registerTools({ telemetry: false })`,
+ * whose opt-out is page-level and not merely batch-level: the flush describes the
+ * *page load*, so one call asking for silence has to silence it even though the
+ * flush knows nothing about batches.
+ *
+ * Irreversible on purpose — a later batch that omits the option is not consent.
+ */
+export declare function cancelInitEvent(): void;
+/**
+ * Emit `sdk_init` — at most once per module instance, ever. The flag is set before
+ * the opt-out is consulted, so a cancelled flush cannot fire later and a second
+ * attempt (a re-entrant timer, a test) is a no-op rather than a duplicate page-load
+ * event.
+ *
+ * Only `telemetry: false` is checked here; the rest of the cancellation set — the
+ * `__WEBMCP_TELEMETRY__` kill switch, GPC, and a runtime with no `document`
+ * (SSR/prerender) — is {@link emitTelemetry}'s to read, at the same moment it reads
+ * it for the other two events. That is *now* rather than at import either way, so a
+ * page that sets the switch inside a consent callback still wins the race.
+ *
+ * Exported for tests; the scheduled timer below is the one that runs it on a real page.
+ */
+export declare function flushInitEvent(sinks?: TelemetrySinks): void;
+/**
+ * Run `run` after `ms`, returning a canceller. Guarded end to end: a runtime with no
+ * timers (SSR) and a hostile `setTimeout` (an extension, a fake-timer harness) both
+ * mean the callback never runs, never a throw out of the import or out of
+ * `registerTools`. The canceller is safe to call when nothing was scheduled.
+ */
+export declare function afterDelay(run: () => void, ms: number): () => void;

package/dist/tool-metrics.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Derived, non-personal metadata about a tool's `inputSchema`: a stable hash and
+ * a handful of shape metrics. Both feed the `tools[]` entries on the
+ * `tool_registration` telemetry event (and `tool.schemaHash` on `tool_call`), so
+ * schema drift and schema *shape* are measurable without the schema itself ever
+ * leaving the page — a schema carries merchant vocabulary and is not ours to send.
+ *
+ * `inputSchema` is caller-supplied and `defineTool` validates only that the top
+ * level is a plain object, so everything below is untrusted input: it can be
+ * cyclic, arbitrarily deep, arbitrarily wide, and studded with throwing getters.
+ * Every traversal here is therefore depth-capped, cycle-guarded, node-budgeted,
+ * and reads properties through a guard. Nothing in this module throws.
+ */
+/**
+ * Deterministic, key-sorted JSON-ish encoding of any value. Not valid JSON for
+ * hostile input (trimmed branches become marker tokens) and never parsed — it
+ * exists only to be hashed. `depth` lets a caller start the depth budget partway
+ * down; it defaults to the top.
+ */
+export declare function canonicalize(value: unknown, depth?: number): string;
+/**
+ * Stable 8-hex-char fingerprint of a tool's input schema. An absent — or
+ * non-object, which `defineTool` already rejects — schema is *omitted* rather
+ * than hashed, so "no schema" and "empty schema" stay distinguishable downstream.
+ */
+export declare function schemaHash(inputSchema?: unknown): string | undefined;
+/**
+ * Shape of a tool's parameters — enough to correlate tool design with agent
+ * success without carrying any parameter names or text. All counts are top-level
+ * parameters; `maxDepth` measures nesting (a flat object schema is `1`).
+ */
+export interface ToolShapeMetrics {
+    /** Keys in `properties`. */
+    paramCount: number;
+    /** String entries in `required`. */
+    requiredCount: number;
+    /** Params typed `string` with neither `enum` nor `format` — the ones an agent
+     * has to invent a value for, and the usual source of failed calls. */
+    freeTextParamCount: number;
+    /** Params constrained by an `enum`. */
+    enumParamCount: number;
+    /** Nesting depth of the parameter tree; `0` when there are no params. */
+    maxDepth: number;
+    /** Params carrying a non-empty `description`. */
+    describedParamCount: number;
+}
+/**
+ * Shape metrics for a tool's input schema, or `undefined` when there is no schema
+ * to measure — matching `schemaHash`, so an entry either carries both or neither.
+ * A present but unreadable schema reports zeros rather than disappearing.
+ */
+export declare function shapeMetrics(inputSchema?: unknown): ToolShapeMetrics | undefined;