@nekuda/webmcp-sdk 0.4.0 → 0.6.0-dev.17.1

package/dist/register.d.ts

@@ -16,6 +16,8 @@ export interface ToolRegistrationResult {
     error?: unknown;
 }
 export interface RegisterToolsOptions {
+    /** Called after the live name set changes, including initial registration and navigation. */
+    onChange?: (names: string[]) => void;
     /**
      * External lifetime for the registration (e.g. a component's unmount signal).
      * Aborting it unregisters every tool in this batch, same as `unregister()`.
@@ -44,10 +46,11 @@ export interface RegisterToolsOptions {
      *
      * The other two events are per-batch, so the option is read per call: a *later*
      * `registerTools` that omits it reports its own batch and calls. Cancelling
-     * `sdk_init` also requires winning the race with its deferred flush — a batch
-     * registered at module scope does, one registered from a mount effect or a consent
-     * callback may not. A site that wants the whole page silent regardless of where its
-     * `registerTools` calls come from (generated code, a CDN snippet) should use a
+     * `sdk_init` also requires winning the race with its deferred flush. A batch
+     * registered at module scope or from an ordinary mount effect schedules the keyed
+     * batch flush; a later consent decision can still arrive after the bounded
+     * no-registration fallback. A site that wants the whole page silent regardless of
+     * when its `registerTools` calls run (generated code, a CDN snippet) should use a
      * page-level lever instead: `globalThis.__WEBMCP_TELEMETRY__ = false` — strictly
      * `false`, so a truthy `"0"` does not opt out — or Global Privacy Control
      * (`navigator.globalPrivacyControl === true`), both of which are read at emit time
@@ -63,18 +66,55 @@ export interface ToolRegistration {
      * cannot mask the rest.
      */
     ready: Promise<ToolRegistrationResult[]>;
+    /** Currently registered names, in declaration order; `ready` covers only the initial page. */
+    current(): string[];
     /** Unregister every tool in this batch. Idempotent. */
     unregister(): void;
     /** The signal carrying this registration's lifetime (aborted once unregistered). */
     signal: AbortSignal;
 }
+/**
+ * Emits one invocation's authenticated-channel events. The `callId` correlating a
+ * `tool_call_request` with its `tool_call_response` is closed over, so one tracker
+ * is one call — never one tool, never one page.
+ */
+export type CallTracker = (eventName: string, data: Record<string, unknown>) => void;
+/**
+ * A tool a host observes but did not register through {@link registerTools} — the
+ * only identity it can offer is the wire `name` the agent surface already knows.
+ */
+export interface TrackedCall {
+    name: string;
+    /** Optional per-tool version, surfaced on the events as `toolVersion`. */
+    version?: string;
+}
+/**
+ * Emitter for a call on a tool this SDK did not register, or `undefined` when the
+ * authenticated channel has no live output — the same `trackingOutputs` answer
+ * {@link registerTools} gates its own per-call emitter on, so the two cannot
+ * disagree about whether the channel is live.
+ *
+ * This exists for one caller shape: a host that owns the page's WebMCP surface and
+ * wraps tools registered on it directly (the CDN snippet's coexistence path). Those
+ * calls must land on `/v1/collect` as the same bytes an SDK-registered tool's do —
+ * same event names, same correlated pair, same anonymous identity — so the
+ * projection reads one shape rather than two. Everything else the host must do
+ * itself: call it once per invocation (a reused tracker collapses two calls into
+ * one `callId`), emit `tool_call_request` before the handler and
+ * `tool_call_response` after, and measure the `duration_ms` it reports.
+ *
+ * `stableKey` is the tool's `name`: a host-wrapped tool has no developer-authored
+ * durable identity to carry, and inventing one would key the same tool differently
+ * from every other reader of the same page.
+ */
+export declare function createCallTracker(tool: TrackedCall, tracking: TrackingOptions): CallTracker | undefined;
 /**
  * Register a batch of `defineTool` tools on the page's WebMCP surface.
  *
- * Lifecycle: registration starts immediately; the tools stay live until
- * `unregister()` is called or the external `options.signal` aborts (both funnel
- * into one internal `AbortController`, the spec's only unregistration mechanism).
- * On browsers without a WebMCP surface this is a graceful no-op — generated code
- * can run unconditionally on every page.
+ * Registration starts immediately, filtered by `pages`; `ready` covers that initial set.
+ * Route changes reconcile scoped tools using per-tool signals (or legacy unregisterTool).
+ * A legacy surface that never reads the signal and has no unregister method retains a
+ * tool once registered. `unregister()`/external abort also removes the route subscription.
+ * Without a readable location (SSR), all tools are eligible; without a surface, no-op.
  */
 export declare function registerTools(tools: readonly AnyWebMCPTool[], options?: RegisterToolsOptions): ToolRegistration;

package/dist/spec.d.ts

@@ -11,9 +11,9 @@
  *   - `registerTool(tool, { signal })` returns a promise that settles when the
  *     registration completes; it rejects on a duplicate name, an invalid tool, an
  *     inactive document, or an abort.
- *   - Unregistration happens ONLY by aborting the `AbortSignal` passed at
- *     registration. `unregisterTool()` and `provideContext()` are dead APIs and are
- *     never referenced.
+ *   - Current unregistration is the `AbortSignal` passed at registration (also
+ *     verified against the 2026-09-10 draft). Legacy surfaces may instead expose
+ *     `unregisterTool(name)`; a surface supporting neither retains registered tools.
  *   - Tool names: 1–128 chars of [A-Za-z0-9_\-.].
  *   - `annotations.readOnlyHint` / `annotations.untrustedContentHint`.
  *
@@ -48,9 +48,20 @@ export interface RegisterToolOptions {
  */
 export interface ModelContextLike {
     registerTool(tool: SpecTool, options?: RegisterToolOptions): Promise<void>;
+    /** Pre-draft compatibility only; current native surfaces use the registration signal. */
+    unregisterTool?(name: string): void;
+}
+interface GlobalWithModelContext {
+    document?: {
+        modelContext?: ModelContextLike;
+    };
+    navigator?: {
+        modelContext?: ModelContextLike;
+    };
 }
 /**
  * Resolve the page's WebMCP surface; `undefined` on non-supporting browsers.
  * Injectable global scope for tests.
  */
-export declare function resolveModelContext(g?: object): ModelContextLike | undefined;
+export declare function resolveModelContext(scope?: GlobalWithModelContext): ModelContextLike | undefined;
+export {};

package/dist/telemetry-events.d.ts

@@ -81,7 +81,17 @@ export interface ClientContext {
  * even when nobody ever calls `registerTools`: a site that loads the SDK and never
  * registers is a broken integration, and this event is the only way to see it.
  */
-export interface SdkInitEvent extends TelemetryEnvelope {
+/**
+ * Present only when a build sampled the page-level events: the rate this page was kept
+ * at, strictly between 0 and 1. Absent means every such event on the page was sent. A
+ * consumer counting page loads weights each sampled event by `1 / sampleRate`. Not on
+ * the envelope, because `tool_call` never carries it — sampling is per page, and a
+ * tool invocation is not a page-level fact.
+ */
+export interface SampledEvent {
+    sampleRate?: number;
+}
+export interface SdkInitEvent extends TelemetryEnvelope, SampledEvent {
     event: "sdk_init";
     sdk: SdkInfo;
     surface: SurfaceInfo;
@@ -108,6 +118,8 @@ export interface TrackingConfigInfo {
     trackingEnabled: boolean;
     otelEnabled: boolean;
     customEndpoint: boolean;
+    /** `TrackingOptions.builtWith`, verbatim, when set and within its length cap. */
+    builtWith?: string;
 }
 /**
  * One tool in a `tool_registration` batch. The shape metrics are inherited as
@@ -117,6 +129,14 @@ export interface TrackingConfigInfo {
 export interface RegisteredToolEntry extends Partial<ToolShapeMetrics> {
     name: string;
     stableKey: string;
+    /**
+     * The connected platform's own id for this tool, when the host supplied one. Opaque
+     * and optional: a tool declared in a codebase that has never been connected has none,
+     * and its absence is the honest reading rather than a degraded one.
+     */
+    inventoryToolId?: string;
+    /** The contract revision the host believed this tool matched, when it knew one. */
+    contractRevision?: number;
     version?: string;
     schemaHash?: string;
     source?: ToolSource;
@@ -154,7 +174,7 @@ export interface TruncatedTools {
  * 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.
  */
-export interface ToolRegistrationEvent extends TelemetryEnvelope {
+export interface ToolRegistrationEvent extends TelemetryEnvelope, SampledEvent {
     event: "tool_registration";
     /** 1-based position of this batch within the page load. */
     registrationIndex: number;
@@ -176,6 +196,10 @@ export type ToolCallOutcome = "success" | "error";
 /** `tool.*` on `tool_call` — identity and the two fields worth joining calls on. */
 export interface ToolCallToolInfo {
     stableKey: string;
+    /** The connected platform's own id, when the host supplied one. See the registration
+     * entry's field of the same name — same value, same optionality, same opacity. */
+    inventoryToolId?: string;
+    contractRevision?: number;
     schemaHash?: string;
     intent?: ToolIntent;
 }

package/dist/telemetry-fields.d.ts

@@ -40,6 +40,7 @@ export declare const TELEMETRY_FIELDS: {
     readonly event: true;
     readonly ts: true;
     readonly sessionId: true;
+    readonly sampleRate: true;
     readonly "sdk.name": true;
     readonly "sdk.version": true;
     readonly "sdk.installMode": true;
@@ -64,6 +65,7 @@ export declare const TELEMETRY_FIELDS: {
     readonly "config.trackingEnabled": true;
     readonly "config.otelEnabled": true;
     readonly "config.customEndpoint": true;
+    readonly "config.builtWith": true;
     readonly tools: true;
     readonly callId: true;
     readonly callIndex: true;
@@ -90,6 +92,8 @@ export declare const TELEMETRY_FIELDS: {
 export declare const TELEMETRY_TOOL_FIELDS: {
     readonly name: true;
     readonly stableKey: true;
+    readonly inventoryToolId: true;
+    readonly contractRevision: true;
     readonly version: true;
     readonly schemaHash: true;
     readonly source: true;

package/dist/telemetry.d.ts

@@ -43,6 +43,22 @@ export declare const SDK_VERSION: string;
  * the overwhelming majority rather than emit a value no consumer can read.
  */
 export declare const SDK_INSTALL_MODE: InstallMode;
+/**
+ * Parse a sampling rate. Anything that is not a number strictly between 0 and 1 means
+ * "send everything": an unset define is how every npm build reaches a page, and a
+ * mistyped one must degrade to complete data rather than to silence.
+ */
+export declare function parseSampleRate(raw: unknown): number;
+/** The rate this build samples page-level events at; `1` sends everything. */
+export declare const SDK_TELEMETRY_SAMPLE_RATE: number;
+/**
+ * Whether this page load is in the sample. Decided from the session id, which every
+ * event on the page shares, so `sdk_init` and the `tool_registration`s beside it are
+ * kept or dropped together — a sampled page is a complete page, never half of one. The
+ * hash is the same FNV-1a the channel already uses for `schemaHash`; its top 32 bits
+ * over 2^32 is a uniform enough coin for a rate that only has to hold on average.
+ */
+export declare function pageSampled(sessionId: string, rate?: number): boolean;
 /**
  * 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
@@ -173,6 +189,9 @@ export declare function buildInitEvent(params?: InitEventParams): SdkInitEvent;
 export interface RegisteredTelemetryTool {
     name: string;
     stableKey: string;
+    /** The connected platform's own id for this tool; opaque, copied, never interpreted. */
+    inventoryToolId?: string;
+    contractRevision?: number;
     version?: string;
     description?: string;
     inputSchema?: unknown;
@@ -187,6 +206,12 @@ export interface RegisteredToolParams {
     /** What the surface rejected with; templated into `failureSignature` when `failed`. */
     error?: unknown;
 }
+/**
+ * Cap on `config.builtWith`, in characters. Sized for `<tool>@<semver-with-prerelease>`
+ * with room to spare; it is the one caller-supplied string on `tool_registration`
+ * that is not copied off a tool, so the per-entry byte cap below does not cover it.
+ */
+export declare const MAX_BUILT_WITH_LENGTH = 64;
 /** 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. */
@@ -278,6 +303,9 @@ export declare function nextCall(stableKey: string, tenantScope?: string): ToolC
 /** What `tool_call` reads off a tool — the two fields worth joining calls on. */
 export interface CalledTelemetryTool {
     stableKey: string;
+    /** The connected platform's own id for this tool; opaque, copied, never interpreted. */
+    inventoryToolId?: string;
+    contractRevision?: number;
     /** Reported as a hash only; the schema itself never leaves the page. */
     inputSchema?: unknown;
     intent?: ToolIntent;
@@ -360,7 +388,7 @@ export interface TelemetrySinks {
  * 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;
+export declare function batchTelemetrySinks(apiKey: unknown, endpoint?: 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.
@@ -421,7 +449,7 @@ export declare function telemetryTenantScope(apiKey: unknown): string;
  * 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;
+export declare function emitTelemetry(build: () => TelemetryEvent, sinks?: TelemetrySinks, fields?: TelemetryFieldMap, toolFields?: TelemetryToolFieldMap, sampleRate?: number): 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
@@ -438,6 +466,15 @@ export declare function emitTelemetry(build: () => TelemetryEvent, sinks?: Telem
 export declare function captureTelemetryApiKey(apiKey: unknown): void;
 /** The key {@link captureTelemetryApiKey} last recorded, if any. */
 export declare function telemetryApiKey(): string | undefined;
+/**
+ * Record the telemetry endpoint for the deferred `sdk_init` flush. Like the captured
+ * key, a later usable value overwrites an earlier one while an absent or malformed
+ * value leaves the last usable value in place. URL parsing is best-effort because an
+ * observability option must never break the visitor's page.
+ */
+export declare function captureTelemetryEndpoint(endpoint: unknown): void;
+/** The endpoint {@link captureTelemetryEndpoint} last recorded, if any. */
+export declare function telemetryEndpoint(): 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
@@ -462,6 +499,12 @@ export declare function cancelInitEvent(): void;
  * Exported for tests; the scheduled timer below is the one that runs it on a real page.
  */
 export declare function flushInitEvent(sinks?: TelemetrySinks): void;
+/**
+ * Give a telemetry-live registration batch the next task's `sdk_init` flush. This
+ * keeps the batch's key and endpoint together while leaving the rest of the current
+ * task available for a page-level opt-out or another synchronous registration.
+ */
+export declare function deferInitEventForBatch(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
@@ -469,3 +512,5 @@ export declare function flushInitEvent(sinks?: TelemetrySinks): void;
  * `registerTools`. The canceller is safe to call when nothing was scheduled.
  */
 export declare function afterDelay(run: () => void, ms: number): () => void;
+/** How long a page that never registers gets to expose a real batch configuration. */
+export declare const INIT_FALLBACK_MS = 1000;

package/dist/tracking.d.ts

@@ -81,8 +81,39 @@ export declare function getOrCreateSessionId(namespace: string): string;
 export interface TrackingOptions {
     /** Presence (non-empty) enables the backend transport and namespaces storage. */
     apiKey?: string;
+    /**
+     * What generated this integration, as `<tool>[/<path>]@<version>` —
+     * `webmcp-kit/implement@<plugin version>` for the plugin's codegen,
+     * `webmcp-kit/connect-existing-tools@<plugin version>` for its migration of
+     * hand-written tools. Reported once per batch as `config.builtWith` on the
+     * default-on channel so kit-built sites are countable without a Connect; a
+     * hand-written integration leaves it unset. Free text under {@link MAX_BUILT_WITH_LENGTH}
+     * characters; anything else is dropped rather than truncated, because a partial
+     * `<tool>@<vers` is a wrong answer, not a shorter one.
+     */
+    builtWith?: string;
     /** Override the collect endpoint; ignored without `apiKey`. */
     endpoint?: string;
+    /**
+     * Report under a session identity the host already owns, verbatim, instead of
+     * the one this module mints in `sessionStorage`. For a host that is itself the
+     * page's session authority — the CDN snippet, whose tab session predates any
+     * `registerTools` call, or a Journey runner replaying under a synthetic `syn_…`
+     * id — the storage-minted id would split one visit into two sessions the
+     * pipeline cannot rejoin, because it lives in an `apiKey`-derived namespace the
+     * host does not share.
+     *
+     * Supplying it takes this module out of the session business entirely for that
+     * batch: nothing is read from or written to `sessionStorage`, including
+     * `last_seen`, so the 30-minute inactivity boundary is the host's to enforce.
+     * The `visitorId` is unaffected — a different lifetime, still this module's.
+     *
+     * Validated like a stored id ({@link MAX_ID_LENGTH}), because identity fields are
+     * copied onto every event without passing through the truncation ladder: an
+     * empty, oversized or non-string value falls back to the minted session rather
+     * than breaking `boundEventPayload`'s fit guarantee.
+     */
+    sessionId?: string;
     /** Emit each event as an OTEL LogRecord via the global `LoggerProvider`. */
     otel?: boolean;
     /**

package/dist/transport.d.ts

@@ -23,6 +23,11 @@
  * pages that never key the authenticated one, so a keyless send is the normal
  * case, not a failure — the backend attributes those by CORS `Origin` instead.
  *
+ * That path has exactly one observable failure signal, and it is a `console.error`,
+ * never a throw or a retry: a *keyed* beacon whose key the backend cannot resolve
+ * is still recorded (anonymously) and answered `401`, so a site shipping a broken
+ * key is otherwise indistinguishable from a working one. See {@link warnKeyRejected}.
+ *
  * The second, independent output is OTEL (`emitOtelLog`): each event becomes a
  * LogRecord on the global `LoggerProvider` via the optional peer dep
  * `@opentelemetry/api-logs`. The host app owns exporters and processing; a
@@ -65,9 +70,28 @@ export declare function sendToCollect(event: TrackingEvent, config: CollectConfi
  * wire. Note that adding the header makes the request non-simple under CORS, so
  * an authenticated beacon costs a preflight the anonymous one does not.
  *
+ * The body is sent as `text/plain`, not `application/json`, and that is a cost
+ * decision, not a formatting one: `text/plain` is a CORS-safelisted content type,
+ * so an anonymous beacon is a "simple request" and the browser sends it with no
+ * OPTIONS preflight. With `application/json` every page load paid two requests
+ * per event at the edge; at 2026-09 volume that preflight was roughly half of the
+ * seven million requests a day the collect API billed. The edge maps `text/plain`
+ * to the same template as JSON (ingestion-edge/telemetry.tf), so nothing changes
+ * on the wire but the header. The keyed beacon keeps `x-api-key`, which forces a
+ * preflight regardless of content type; that path is a small fraction of traffic.
+ *
+ * A `401` on this path means the key that WAS sent resolved to nothing; the beacon
+ * itself was still recorded, anonymously. That is reported through
+ * {@link warnKeyRejected} and nothing else — no throw, no retry, no second send.
+ * The response is only inspected for an authenticated beacon: an anonymous one has
+ * no key to be wrong about, so a `401` there would be a backend fault the developer
+ * can do nothing with, and blaming their key for it is worse than silence.
+ *
  * The event stays a bare `object` here so this module never has to import the
  * assembled shape from `telemetry.ts` (which imports this function).
  */
+/** CORS-safelisted, so an anonymous beacon needs no preflight — see sendTelemetry. */
+export declare const TELEMETRY_CONTENT_TYPE = "text/plain";
 export declare function sendTelemetry(event: object, scope?: object, endpoint?: string, apiKey?: unknown): void;
 /** The `Logger.emit` slice we use — structural, no hard OTEL type coupling. */
 interface LoggerLike {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nekuda/webmcp-sdk",
-  "version": "0.4.0",
+  "version": "0.6.0-dev.17.1",
   "type": "module",
   "description": "Phase-1 WebMCP SDK: a thin wrapper over document.modelContext that plugin-generated code targets — defineTool + register/unregister lifecycle. This package pins the plugin↔SDK seam; anonymous tool-call tracking (backend transport via apiKey, OTEL LogRecords via otel) is opt-in through registerTools and default-silent, while anonymous usage telemetry is a separate unauthenticated channel that is on by default (opt out with telemetry: false).",
   "main": "./dist/index.js",
@@ -11,7 +11,10 @@
       "default": "./dist/index.js"
     }
   },
-  "files": ["dist", "CHANGELOG.md"],
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
   "publishConfig": {
     "access": "public"
   },
@@ -36,5 +39,7 @@
       "optional": true
     }
   },
-  "trustedDependencies": ["@biomejs/biome"]
+  "trustedDependencies": [
+    "@biomejs/biome"
+  ]
 }