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

package/CHANGELOG.md

@@ -1,6 +1,105 @@
 # Changelog
 
-## Unreleased — usage telemetry schema 2 (breaking wire format)
+## Unreleased — telemetry beacons without a preflight
+
+- The telemetry beacon is sent as `text/plain` instead of `application/json`. The
+  body is unchanged; the header makes an anonymous beacon a CORS simple request, so
+  the browser stops sending an `OPTIONS` preflight before every event. Keyed beacons
+  still carry `x-api-key` and still preflight. The edge has mapped `text/plain` to
+  the same template since ADR-0014, so no server change is needed.
+
+## 0.6.0 — 2026-09-18
+
+Five additive changes, no breaking change. The wire schema stays at `2`. Four of them
+are opt-in options — `builtWith`, `pages`, `sessionId` and `createCallTracker` — each
+silent when unset, so **an npm consumer who sets none of them sends exactly the bytes
+0.5.0 sent**. The fifth is a non-enumerable mark this SDK writes on the tool objects it
+registers under a batch that is already posting to the collect edge; it is invisible to
+enumeration and to `JSON` and never reaches the wire, so it changes no bytes either.
+
+Beside them is a **mechanism nothing switches on**: page-level telemetry sampling exists
+as a `bun build --define`, and no build this release ships passes a rate. **Every
+install, npm and CDN snippet alike, is unsampled** and sends every page-level event,
+exactly as 0.5.0 did.
+
+### Page-level telemetry sampling — available, off everywhere
+
+- A build **may** sample the two page-level telemetry events (`sdk_init`,
+  `tool_registration`) with `--define '__WEBMCP_TELEMETRY_SAMPLE_RATE__="0.1"'`. The
+  decision is one coin per page load from the `sessionId`, so a page's events are kept
+  or dropped together, and every kept event carries `sampleRate` for weighting.
+  `tool_call` is never sampled. Unset, `1`, or anything outside (0, 1), sends
+  everything — the previous behaviour byte for byte.
+- **Nothing opts in.** Neither publish lane passes the define, and the CDN snippet
+  build (`infra/deploy-snippet.sh`) defines the rate as `1`. These two events carry
+  the connects, registered-tool counts, refreshes and unique user agents the product
+  counts active users from, so they ship complete; the beacon volume gets a fast-path
+  ingest queue rather than a tenth of the observations. Turning sampling on for one
+  deploy is `SNIPPET_TELEMETRY_SAMPLE_RATE=<rate>` in front of that script, and the
+  kept events then say what rate they were kept at.
+
+### `tracking.builtWith`
+
+- **`TrackingOptions.builtWith`** names what generated the integration, as
+  `<tool>[/<path>]@<version>` (`webmcp-kit/implement@<plugin version>`,
+  `webmcp-kit/connect-existing-tools@<plugin version>`), and is reported verbatim
+  as `config.builtWith` on `tool_registration`. Additive and optional: unset emits
+  exactly the bytes it did before. It exists so kit-built sites are countable on
+  the default-on channel without a Connect. Dropped, never truncated, when empty
+  or over 64 characters.
+
+### Page-scoped tools
+
+- `defineTool({ pages })` filters registration on load and SPA navigation; `matchPage`
+  and `currentPageKey` expose the fixture-pinned matching rule. SDK metadata stays off
+  the native tool object. `ready` covers the initial filtered set; `current()` and
+  `onChange` expose live names. Unregistration uses native abort signals, with legacy
+  `unregisterTool` support and explicit retention on surfaces supporting neither.
+
+### A host may own the session and track its own tools
+
+Two additive `tracking`-channel surfaces for a host that owns the page it runs on
+(the CDN snippet). Nothing existing changes: both are opt-in, both are silent
+under the same `trackingOutputs` gate as everything else on this channel, and a
+consumer that sets neither emits exactly the bytes it did before.
+
+- **`TrackingOptions.sessionId`** reports under a session identity the host
+  already has — a tab session that predates any `registerTools` call, or a
+  Journey runner's synthetic `syn_…` id — instead of the one this channel mints
+  in `sessionStorage` under an `apiKey`-derived namespace, which would split one
+  visit into two sessions the pipeline cannot rejoin. Supplying it means no
+  `sessionStorage` read or write at all for that batch, `last_seen` included, so
+  the 30-minute inactivity boundary becomes the host's to enforce; `visitorId` is
+  untouched. Validated like a stored id (non-empty, ≤ 64 chars, a string) —
+  anything else falls back to the minted session, because identity fields skip the
+  truncation ladder.
+- **`createCallTracker(tool, tracking)`** emits the request/response pair for a
+  tool the host registered on `document.modelContext` itself, in the same bytes an
+  SDK-registered tool's call produces — same event names, same correlated `callId`,
+  same anonymous identity — so the projection reads one shape rather than two. The
+  host owns the rest: one tracker per invocation, `tool_call_request` before the
+  handler and `tool_call_response` after, and the `duration_ms` it reports. The
+  tool's `name` is its `stableKey`, since a host-wrapped tool has no
+  developer-authored durable identity to carry — and that rule is applied *over*
+  the caller's object, so a `stableKey` riding in on a tool descriptor from a page
+  the host does not control cannot key that tool differently from every other
+  reader of the same page.
+
+### A tracked tool says so, for a host that owns the surface
+
+- A tool registered by a batch that posts to the collect edge now carries the registry
+  symbol `Symbol.for("webmcp.sdk.tracked")` (non-enumerable, value `true`) on the object
+  handed to `registerTool`. It exists for a host that owns the page's WebMCP surface and
+  wraps what it finds there — the CDN snippet's coexistence gate — which could not
+  otherwise tell a tool whose calls this SDK already reports from a merchant's bare one,
+  and reported every such invocation a second time. Nothing else changes: the mark is
+  written only when the channel really is posting (an unkeyed batch, an empty
+  `tracking: {}`, a closed consent gate and an otel-only batch carry none), it is
+  invisible to enumeration and to `JSON`, and no export is added. It is the one change
+  here that is not an option a consumer sets — but being non-enumerable it reaches
+  neither the wire nor `JSON.stringify`, so no bytes move.
+
+## 0.5.0 — 2026-08-24 — usage telemetry schema 2 (breaking wire format)
 
 The usage-telemetry channel emits **three events instead of two**, carrying
 derived signals instead of raw page and payload strings. `schema` bumps `1` → `2`.
@@ -11,11 +110,11 @@ unchanged. See `docs/telemetry-schema.md`.
 
 ### Breaking
 
-- **`sdk_init` fires once per page load, not once per `registerTools` call.** It is
-  scheduled at import time and flushed on the next task, so it now fires even when
-  nobody registers anything — which is the only way a broken integration is
-  visible. A page with three `registerTools` calls no longer emits three "init"
-  events.
+- **`sdk_init` fires once per page load, not once per `registerTools` call.** The
+  first telemetry-live batch schedules a next-task flush with its own key and
+  endpoint; an import-time one-second fallback still fires when nobody registers
+  anything, which is the only way a broken integration is visible. A page with
+  three `registerTools` calls no longer emits three "init" events.
 - **Per-call information moved to the new `tool_registration` event**, one per
   `registerTools` call: `registrationIndex`, `trigger`, `settleMs`, the `config.*`
   booleans (moved off `sdk_init`, which fires before any batch may have run), and
@@ -65,6 +164,17 @@ unchanged. See `docs/telemetry-schema.md`.
 
 ### Added
 
+- **One `console.error` when a configured publishable key is refused.** The telemetry
+  route now answers `401` for a key that was *sent* and did not resolve; the beacon is
+  still recorded, anonymously, so nothing is lost but the attribution. The SDK reports
+  that at most once per page load — naming the SDK, saying recording continues
+  anonymously before saying what broke, and pointing at re-running Connect. It never
+  echoes the key or anything off the wire. No throw, no retry, no second send, and no
+  change to the send path. Anonymous beacons are never inspected (they have no key to
+  be wrong about), and every other status, a network failure, and an environment with
+  no `console` stay silent as before. This narrows 0.2.0's "the SDK is silent by
+  default": it is the only output the package produces, and only a broken key produces
+  it.
 - **`globalThis.__WEBMCP_TELEMETRY__ = false`** silences the channel page-wide
   without touching a `registerTools` call site — the only lever a site has when the
   calls come from generated code it does not edit. Strictly `false`, like GPC is

package/README.md

@@ -0,0 +1,32 @@
+# @nekuda/webmcp-sdk
+
+Define tools with `defineTool`, then pass them to `registerTools(tools, options)`.
+`ready` resolves with initial per-tool outcomes; `unregister()` or `options.signal`
+ends the batch. Browsers without a WebMCP surface report `unsupported`.
+
+## Page-scoped tools
+
+Set `pages: ["/products/*"]` on a tool definition to register it only on matching
+pages. Missing/empty `pages` means everywhere; lists match any entry. `*` matches
+any characters within one segment (`/products/*`, `/product.html*`), `**` zero or
+more segments; queries and trailing slashes are ignored on both patterns and locations,
+and repeated slashes collapse to one. Hash
+routers use patterns such as `/#/product/*`. With no readable location (SSR),
+all tools are eligible because the page cannot be evaluated.
+
+The SDK reconciles tools on `pushState`, `replaceState`, `popstate`, and
+`hashchange`, sharing one route listener. If History cannot be patched, registration
+still succeeds and navigation detection falls back to `popstate`/`hashchange` only.
+A failing route subscriber never escapes into the merchant's History calls or blocks
+other subscribers. `registration.current()` lists live
+names; `options.onChange(names)` keeps host displays in sync. `ready` covers only
+the initially eligible tools. SDK-only `pages` never reaches native `registerTool`.
+
+The [WebMCP draft](https://webmachinelearning.github.io/webmcp/), checked
+2026-09-10, unregisters via the registration's **AbortSignal**, not
+`unregisterTool`; this works on either resolved modelContext global. Legacy
+surfaces exposing `unregisterTool(name)` are supported too. A surface that neither
+reads the registration signal nor exposes that method keeps a tool once registered;
+the SDK reports it as still live rather than claiming removal. Ending a batch always
+removes its route subscription. Fixtures under `fixtures/` pin matching semantics
+for tests and stay out of the published package.

package/dist/define.d.ts

@@ -1,4 +1,22 @@
 import type { ToolAnnotations } from "./spec.js";
+/**
+ * Spec rule: tool names are 1–128 chars of ASCII alphanumerics, `_`, `-`, `.`.
+ *
+ * Exported for the seam pin only (`tests/tool-key-patterns.test.ts`), not re-exported by
+ * `index.ts`: the platform's catalog CHECKs the same shape, and a widening here that the
+ * database refuses would reject tools this SDK already accepted in the wild.
+ */
+export declare const NAME_PATTERN: RegExp;
+/**
+ * `stableKey` rule: dot-namespaced `domain.action` — two or more `[a-z0-9_]+`
+ * segments joined by `.`. Rejects the common authoring mistake of copying the
+ * wire `name` into `stableKey` (e.g. `search_blog_posts`), which defeats the
+ * field's purpose: a `name` can be renamed freely, but a `stableKey` that is
+ * just a `name` copy renames right along with it.
+ *
+ * Exported for the seam pin only — see {@link NAME_PATTERN}.
+ */
+export declare const STABLE_KEY_PATTERN: RegExp;
 /** How the tool came to exist. Reported on telemetry as `tools[].source`. */
 export type ToolSource = "scanner_generated" | "merchant_authored";
 /** What the tool is for. Reported on telemetry as `tools[].intent`. */
@@ -33,6 +51,8 @@ export interface ToolDefinition<TInput extends Record<string, unknown> = Record<
     /** JSON Schema for `execute`'s input, as a plain object. */
     inputSchema?: Record<string, unknown>;
     annotations?: ToolAnnotations;
+    /** Page patterns where this tool is available; absent/empty means everywhere. SDK-only. */
+    pages?: string[];
     /**
      * Optional per-tool version, surfaced on emitted tracking events as `toolVersion`
      * for drift analytics. Free-form string (e.g. semver or a codegen hash); when
@@ -51,6 +71,25 @@ export interface ToolDefinition<TInput extends Record<string, unknown> = Record<
      * rather than per-batch because one tool answers while another transacts.
      */
     intent?: ToolIntent;
+    /**
+     * The identity the connected platform assigned this tool, if the host knows it —
+     * an opaque string the SDK copies and never interprets.
+     *
+     * `stableKey` is the DEVELOPER's durable identity and survives renames; this is the
+     * server's, handed back once a site is connected. Both are reported because they
+     * answer different questions: a key the developer chose can collide across two
+     * scopes of one site, while the assigned id cannot, and only the developer's key
+     * exists before a site is connected at all. Absent is the ordinary state — a tool
+     * declared in a codebase that has never been connected simply has no such id, and
+     * the SDK never invents one.
+     */
+    inventoryToolId?: string;
+    /**
+     * The contract revision the host believes this tool matches, if it knows one.
+     * Reported so a stale bundle can be told apart from a tool that genuinely changed
+     * shape; never validated here, and never used for anything on the page.
+     */
+    contractRevision?: number;
     /**
      * The page-owned behavior. May return anything JSON-serializable, a plain string,
      * or a ready-made `{ content: [...] }` result — the SDK normalizes for the agent.

package/dist/index.d.ts

@@ -14,13 +14,14 @@
  *    and is never sent to the browser.
  * 3. Registration lifecycle: `registerTools(tools, { signal?, tracking?, telemetry? })`
  *    registers on call
- *    and returns `{ ready, unregister, signal }`. Unregistration happens ONLY via
- *    `unregister()` or the external signal aborting (page teardown / SPA unmount).
+ *    and returns `{ ready, current, unregister, signal }`. Page-scoped tools also
+ *    register/unregister as routes change; `unregister()` or an external abort ends the batch.
  *    Browsers without a WebMCP surface are a graceful no-op (`state: "unsupported"`).
  * 4. "Connect later without rewrite": generated modules only `defineTool` and
  *    EXPORT tools; one entry module calls `registerTools`. Connecting a site to the
- *    platform later (API key, telemetry) changes wrapper internals and config only —
- *    generated modules and their imports do not change. See `examples/add-to-cart.ts`.
+ *    platform later adds a publishable tracking key to wrapper config only — generated
+ *    modules and their imports do not change. The default-on anonymous channel in point 6
+ *    is independent of Connect. See `examples/add-to-cart.ts`.
  * 5. Anonymous tool-call tracking is opt-in via `registerTools`'s `tracking`
  *    option (see `TrackingOptions`) and default-silent: with neither `apiKey`
  *    nor `otel` set, no event is built at all — no identity resolution, no
@@ -37,7 +38,13 @@
  *    both outputs — but for THIS channel only; the default-on telemetry channel of
  *    point 6 has its own opt-out (`telemetry: false`) and `disabled` does not
  *    narrow it. See `src/tracking.ts`, `src/transport.ts`, and
- *    `examples/add-to-cart.ts`.
+ *    `examples/add-to-cart.ts`. `TrackingOptions.sessionId` lets a host that is
+ *    already the page's session authority report under its own id instead of the
+ *    one this channel mints; `createCallTracker(tool, tracking)` lets that same
+ *    host emit the pair for a tool it registered on the surface *itself*, in the
+ *    same bytes. Both exist for one caller — a host of this SDK that owns the page
+ *    (the CDN snippet) — and neither is part of what plugin codegen targets:
+ *    generated code registers tools and reads nothing here.
  * 6. Anonymous usage telemetry is a SECOND, independent channel: default-ON, so it
  *    reports from every site the SDK runs on, not only from `apiKey` tenants. Three
  *    events (`TelemetryEvent`), all `schema: 2` and joined on an in-memory
@@ -73,7 +80,8 @@
  *    platform stays a config-only change to the entry module (point 4).
  */
 export { type AnyWebMCPTool, type ToolDefinition, type ToolIntent, type ToolSource, type WebMCPTool, defineTool, } from "./define.js";
-export { type RegisterToolsOptions, type ToolRegistration, type ToolRegistrationResult, type ToolRegistrationState, registerTools, } from "./register.js";
+export { currentPageKey, matchPage } from "./pages.js";
+export { type CallTracker, type RegisterToolsOptions, type ToolRegistration, type ToolRegistrationResult, type ToolRegistrationState, type TrackedCall, createCallTracker, registerTools, } from "./register.js";
 export { type ModelContextLike, type RegisterToolOptions, type SpecTool, type ToolAnnotations, resolveModelContext, } from "./spec.js";
 export type { AgentRuntime, FormFactor, FrameContext, PageVisibility, ReferrerClass, SurfaceGlobal, SurfaceInfo, SurfaceProvenance, } from "./telemetry-context.js";
 export type { ClientContext, InstallMode, PageContext, RegisteredToolEntry, RegistrationTrigger, SdkInfo, SdkInitEvent, StrippedToolEntry, TelemetryEnvelope, TelemetryEvent, TelemetryEventName, ToolCallEvent, ToolCallOutcome, ToolCallResponseMetrics, ToolCallToolInfo, ToolRegistrationEvent, ToolRegistrationOutcome, TrackingConfigInfo, TruncatedTools, } from "./telemetry-events.js";