@nekuda/webmcp-sdk 0.7.0-dev.20.1 → 0.7.0-dev.22.1

package/CHANGELOG.md

@@ -1,29 +1,42 @@
 # Changelog
 
-## Unreleased — the telemetry key rides the query string
-
-- A keyed telemetry beacon sends its publishable key as the `key` query parameter
-  instead of the `x-api-key` header. The header made every keyed beacon a non-simple
-  request with an `OPTIONS` preflight, and every hosted-snippet install is keyed. The
-  backend reads both; nothing else changes.
-
 ## 0.7.0 — 2026-09-21
 
 One change, made twice: a page load costs the ingest edge one request instead of
 four. The wire schema stays at `2` and every event still arrives — the two savings
-are a header and an envelope, not a sample. **A minor, not a patch**, because the
-second of them puts a request shape on the wire that no earlier backend parses: a
+are a request shape and an envelope, not a sample. **A minor, not a patch**, because
+the second of them puts a request shape on the wire that no earlier backend parses: a
 `batch` is quarantined as `unknown_event` by any transform older than the one that
 ships with it. The events an install emits, and the fields on them, are byte for
 byte 0.6.0's.
 
+### Documentation
+
+- The README is rewritten for people using the package: what it does, install, defining
+  and registering tools, page-scoped tools, browser support, the optional tool-call
+  analytics, and exactly what the default-on usage telemetry sends, never sends, and how
+  to turn it off. The npm description now says what the package does.
+
 ### 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.
+  body is unchanged; the content type makes an anonymous beacon a CORS simple
+  request, so the browser stops sending an `OPTIONS` preflight before every event.
+  The edge has mapped `text/plain` to the same template since ADR-0014, so no server
+  change is needed.
+- A **keyed** beacon sends its publishable key as the `key` query parameter instead
+  of the `x-api-key` header, because the content type alone was not enough: a custom
+  request header is what makes a request non-simple, so a keyed beacon kept paying
+  the preflight — and every hosted-snippet install is keyed, since the manifest hands
+  it a default publishable key. The backend accepts both and the header still wins,
+  so older bundles are unaffected.
+- **This reverses 0.2.0's "not `?api_key=`" for this channel only.** That decision is
+  unchanged for `/v1/collect`, which carries the *secret* key and whose authorizer
+  declares the header as its identity source. It does not carry to telemetry: the key
+  there is *publishable* and already sits in the page's HTML, the soft authorizer
+  declares no identity source at all, the stage keeps no access logs, and the WAF both
+  redacts the query string from its logs and now disables sampled requests, which
+  would otherwise have shown the URI in the console.
 
 ### One beacon per page load
 

package/README.md

@@ -1,32 +1,275 @@
 # @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.
+Let AI agents use your website. This SDK turns the things your site already does,
+such as searching products, adding to cart or booking a slot, into **tools** that a
+browser agent can call through [WebMCP](https://webmachinelearning.github.io/webmcp/),
+the draft web standard for exposing page actions to agents.
+
+You describe each tool once. The SDK registers it with the browser, adds and removes it
+as the user moves between pages, keeps working when the WebMCP draft changes, and does
+nothing at all in browsers that don't support it yet.
+
+```ts
+import { defineTool, registerTools } from "@nekuda/webmcp-sdk";
+
+const addToCart = defineTool({
+  stableKey: "cart.add",
+  name: "add_to_cart",
+  description: "Add a product to the shopping cart by SKU.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      sku: { type: "string", description: "Product SKU" },
+      quantity: { type: "integer", minimum: 1, default: 1 },
+    },
+    required: ["sku"],
+  },
+  async execute({ sku, quantity = 1 }: { sku: string; quantity?: number }) {
+    const res = await fetch("/cart/add", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ sku, quantity }),
+    });
+    if (!res.ok) throw new Error(`Could not add ${sku} to the cart`);
+    return await res.json();
+  },
+});
+
+registerTools([addToCart]);
+```
+
+An agent visiting the page now sees an `add_to_cart` tool, with your description and
+input schema, and can call it.
+
+## Install
+
+```sh
+npm install @nekuda/webmcp-sdk
+# or: pnpm add @nekuda/webmcp-sdk · yarn add @nekuda/webmcp-sdk · bun add @nekuda/webmcp-sdk
+```
+
+The package is a browser ES module with TypeScript types included. It has no runtime
+dependencies. `@opentelemetry/api-logs` is an optional peer, needed only if you turn on
+[OpenTelemetry output](#tool-call-analytics-optional).
+
+**No bundler?** Serve `node_modules/@nekuda/webmcp-sdk/dist/index.js` from your site and
+map the package name to it:
+
+```html
+<script type="importmap">
+  { "imports": { "@nekuda/webmcp-sdk": "/vendor/webmcp-sdk/index.js" } }
+</script>
+<script type="module" src="/webmcp/entry.js"></script>
+```
+
+## Defining a tool
+
+`defineTool` checks the definition straight away, freezes it and returns it. It does not
+touch the browser, so a module that only defines tools is safe to import anywhere,
+including tests and server-side code. An invalid definition throws a `TypeError` when the
+module loads, not later when an agent calls the tool.
+
+| Field | Required | What it is |
+|---|---|---|
+| `stableKey` | yes | Your permanent ID for the tool, in `domain.action` form (`cart.add`, `catalog.search`): lowercase letters, digits and `_`, with at least one dot. Keep it the same when you rename the tool; analytics follow the tool through renames by this key. It is never sent to the browser API. |
+| `name` | no | The name agents see: 1–128 characters of `A–Z a–z 0–9 _ - .`. Defaults to `stableKey`. |
+| `description` | yes | What the tool does, written for the agent. Be specific about when to use it. |
+| `inputSchema` | no | A JSON Schema object describing `execute`'s input. |
+| `title` | no | A human-readable display name. |
+| `annotations` | no | WebMCP hints, for example `{ readOnlyHint: true }` for a tool that only reads. |
+| `pages` | no | Paths the tool is available on. Leave it out to make the tool available everywhere. See [Tools for specific pages](#tools-for-specific-pages). |
+| `version` | no | Your version string for the tool (semver, a build hash, anything). |
+| `intent` | no | `"answer"`, `"act"` or `"transact"`: whether the tool reads, changes something, or moves money. |
+| `source` | no | `"scanner_generated"` or `"merchant_authored"`. |
+| `execute` | yes | Your code. It receives the agent's input and may be `async`. |
+
+**Return values.** Return any JSON value or a plain string and the SDK wraps it in the
+result format agents expect. If you already build a WebMCP `{ content: [...] }` result,
+it is passed through unchanged.
+
+**Errors.** Throw when the action fails. The error goes back to the agent as it is, so
+write the message for the agent ("No product with SKU 123") and not for your logs.
+
+**TypeScript.** Declare the input as a `type`, not an `interface`:
+`defineTool<{ sku: string }>(…)` works, but an `interface` fails the
+`Record<string, unknown>` constraint.
+
+## Registering tools
+
+```ts
+const registration = registerTools([addToCart, searchProducts], options);
+
+const results = await registration.ready;
+// [{ stableKey: "cart.add", name: "add_to_cart", state: "registered" }, …]
+
+registration.current();    // names registered right now, e.g. ["add_to_cart"]
+registration.unregister(); // remove every tool in this call
+```
+
+Each tool in `ready` ends in one of four states:
+
+| State | Meaning |
+|---|---|
+| `registered` | The browser accepted the tool. |
+| `unsupported` | This browser has no WebMCP API. Nothing happened, and nothing needs to be done. |
+| `aborted` | The registration was cancelled before the tool registered. |
+| `failed` | The browser refused the tool. The reason is on `error`. |
+
+`ready` never rejects, so you don't need a `try`/`catch` around it. `registerTools` itself
+throws only for a programming error: two tools in one call with the same `name` or the
+same `stableKey`.
+
+| Option | What it does |
+|---|---|
+| `signal` | An `AbortSignal`. Aborting it is the same as calling `unregister()`. |
+| `onChange(names)` | Called with the current tool names whenever they change, for example after navigation. |
+| `tracking` | Connects tool calls to your AgentLane account. See [Tool-call analytics](#tool-call-analytics-optional). |
+| `telemetry` | Set to `false` to turn off anonymous usage telemetry for this call. See [Usage telemetry](#usage-telemetry). |
+
+### Where to call it
+
+Keep tool definitions in their own modules and call `registerTools` in one place that
+owns the tools' lifetime.
+
+**React (and Vite, Remix or any React SPA)**: register in an effect and unregister on
+cleanup.
+
+```tsx
+import { useEffect } from "react";
+import { registerTools } from "@nekuda/webmcp-sdk";
+import { addToCart } from "./tools/cart";
+
+export function WebMCPTools() {
+  useEffect(() => {
+    const registration = registerTools([addToCart]);
+    return () => registration.unregister();
+  }, []);
+  return null;
+}
+```
+
+**Next.js App Router**: put the same component in a file marked `"use client"` and render
+it from `app/layout.tsx`. Never call `registerTools` from a server component.
+
+**Plain or server-rendered pages**: load one module with `<script type="module">` from
+your shared layout.
+
+```ts
+import { registerTools } from "@nekuda/webmcp-sdk";
+import { addToCart } from "./tools/cart.js";
+
+const registration = registerTools([addToCart]);
+addEventListener("pagehide", () => registration.unregister(), { once: true });
+```
+
+**Tools that need state**: register tools such as "update cart item" or "start checkout"
+only while that state exists (for example, a non-empty cart or a signed-in user). Tie the
+`registerTools` call to that state and unregister when it goes away.
+
+## Tools for specific pages
+
+Give a tool a `pages` list and it is only offered on matching pages:
+
+```ts
+defineTool({
+  stableKey: "product.add_review",
+  description: "Post a review of the product on this page.",
+  pages: ["/products/*"],
+  execute: postReview,
+});
+```
+
+- `*` matches within one path segment (`/products/*`, `/product.html*`), and `**` matches
+  any number of segments (`/docs/**`).
+- A tool with several patterns is available when any of them matches.
+- Query strings and trailing slashes are ignored, and repeated slashes count as one.
+- Hash routers work too: `/#/product/*`.
+- During server-side rendering there is no location to check, so every tool counts as
+  eligible.
+
+In a single-page app the SDK adds and removes page-scoped tools on every navigation
+(`pushState`, `replaceState`, back/forward and hash changes), so you don't need to call
+anything yourself. `ready` reports only the tools eligible on the first page; use
+`onChange` or `current()` to follow later changes. If your app locks down the History
+API, navigation is still detected through back/forward and hash changes.
+
+## Browser support
+
+The SDK works wherever the WebMCP API is present, as `document.modelContext` or
+`navigator.modelContext`, whether a browser provides it natively or an extension does.
+WebMCP is a draft that still changes month to month. The SDK tracks it so your code
+doesn't have to, which is why you should call the SDK and not `modelContext` directly.
+
+Where the API is missing, every tool reports `unsupported` and nothing else happens: no
+errors and no changes to your page. You can ship the same code to every browser.
+
+## Tool-call analytics (optional)
+
+Connect your site in the [AgentLane dashboard](https://app.agentlane.com) to see which tools agents call, how
+often they succeed and where they fail. Connecting means adding the site's publishable
+key. Your tool definitions don't change.
+
+```ts
+registerTools([addToCart], {
+  tracking: { apiKey: "wmk_…" }, // publishable key from the AgentLane dashboard
+});
+```
+
+With a key, the SDK sends an event for each tool call to AgentLane. It is off unless you
+set it. Two other settings are available:
+
+- `otel: true` also, or instead, emits each tool-call event as an OpenTelemetry log record
+  through your app's global `LoggerProvider`, so you can send it to your own
+  observability stack. Your app owns the exporter, and `apiKey` isn't needed for this.
+- `disabled: true` switches tool-call analytics off completely, for example until the
+  visitor accepts analytics cookies. While it is set, no identifier is created, nothing
+  is stored and nothing is sent.
+
+Tool-call analytics keeps an anonymous visitor and session identifier in the browser's
+storage, so ask for consent wherever your analytics consent rules require it.
+
+## Usage telemetry
+
+The SDK sends anonymous usage telemetry by default, so we can see which versions are in
+use and catch breakage. It needs no key and **stores nothing in the browser** (no
+cookies, no localStorage, no identifiers).
+
+**Sent:** SDK version, whether WebMCP is available, browser family, device type, page
+language and route pattern (`/products/:id`, never the URL); each tool's name, whether it
+registered, and the shape of its schema; and per tool call, the outcome, duration, result
+size and a scrubbed error template.
+
+**Never sent:** tool inputs or results, raw error messages, URLs, query strings, referrer
+URLs, page titles or the full user-agent.
+
+To count daily visitors, our server stores a one-way hash of site, IP and user-agent under
+a key that rotates every day. It can't be reversed or linked across sites or days. If the
+page sets `tracking.apiKey`, telemetry is attributed to your site.
+
+**Turn it off:**
+
+```ts
+globalThis.__WEBMCP_TELEMETRY__ = false; // whole page; set before the SDK loads
+registerTools(tools, { telemetry: false }); // one call
+```
+
+It is also off automatically when the browser sends
+[Global Privacy Control](https://globalprivacycontrol.org/) and during server-side
+rendering. `tracking.disabled` does not affect it.
+
+## Advanced
+
+These exports are for code that hosts the SDK on a page it controls, such as a tag
+loader. Most sites don't need them.
+
+- `matchPage(patterns, location)` and `currentPageKey()`: the page matcher `pages` uses.
+- `resolveModelContext()`: returns the WebMCP object the SDK would use, or `undefined`.
+- `registerTools(tools, { modelContext })`: register against a specific WebMCP object.
+- `tracking.sessionId` and `createCallTracker(tool, tracking)`: report tool calls under
+  your own session ID, including for tools you registered with the browser yourself.
+- The telemetry event types (`TelemetryEvent`, `SdkInitEvent`, `ToolRegistrationEvent`,
+  `ToolCallEvent`, …) are exported for anyone consuming the beacons.
+
+## Changelog
+
+See `CHANGELOG.md`, which ships in the package.

package/dist/index.d.ts

@@ -56,8 +56,10 @@
  *    separate `/v1/telemetry` endpoint, fire-and-forget; the two page-level ones may
  *    share one request as a `batch` envelope, `tool_call` never does. Arrival order
  *    is NOT guaranteed, so consumers join on `sessionId` and never on ordering. A
- *    page that configures point 5's `apiKey` has it sent here as `x-api-key` too,
- *    which only adds tenant attribution — an unkeyed page sends anonymously to the
+ *    page that configures point 5's `apiKey` has it sent here too, as the `key`
+ *    query parameter rather than point 5's header (a custom header would make the
+ *    beacon non-simple under CORS and cost it a preflight); it only adds tenant
+ *    attribution — an unkeyed page sends anonymously to the
  *    same path. It composes with point 5: a call can emit to neither channel, either
  *    one, or both. Three page-level levers silence it entirely (no event, no
  *    network), because all three are read at emit time:

package/dist/index.js

@@ -181,6 +181,15 @@ function sendToCollect(event, config, scope = globalThis) {
 }
 var TELEMETRY_CONTENT_TYPE = "text/plain";
 var TELEMETRY_KEY_PARAM = "key";
+function withTelemetryKey(base, apiKey) {
+  try {
+    const url = new URL(base);
+    url.searchParams.set(TELEMETRY_KEY_PARAM, apiKey);
+    return url.toString();
+  } catch {
+    return `${base}${base.includes("?") ? "&" : "?"}${TELEMETRY_KEY_PARAM}=${encodeURIComponent(apiKey)}`;
+  }
+}
 function sendTelemetry(event, scope = globalThis, endpoint, apiKey) {
   try {
     const json = JSON.stringify(event);
@@ -189,7 +198,7 @@ function sendTelemetry(event, scope = globalThis, endpoint, apiKey) {
     const base = endpoint || DEFAULT_TELEMETRY_ENDPOINT;
     const headers = { "content-type": TELEMETRY_CONTENT_TYPE };
     const authenticated = typeof apiKey === "string" && apiKey.trim().length > 0;
-    const url = authenticated ? `${base}${base.includes("?") ? "&" : "?"}${TELEMETRY_KEY_PARAM}=${encodeURIComponent(apiKey)}` : base;
+    const url = authenticated ? withTelemetryKey(base, apiKey) : base;
     tryFetch(scope, url, headers, json, authenticated ? (response) => {
       if (isUnauthorized(response))
         warnKeyRejected(scope);
@@ -1105,7 +1114,7 @@ function shapeMetrics(inputSchema) {
 
 // src/telemetry.ts
 var SDK_NAME = "@nekuda/webmcp-sdk";
-var SDK_VERSION = "0.7.0-dev.20.1";
+var SDK_VERSION = "0.7.0-dev.22.1";
 var INSTALL_MODES = ["npm", "cdn_snippet"];
 var SDK_INSTALL_MODE = INSTALL_MODES.find((mode) => mode === (typeof __WEBMCP_INSTALL_MODE__ === "string" ? __WEBMCP_INSTALL_MODE__ : "")) ?? "npm";
 function parseSampleRate(raw) {

package/dist/register.d.ts

@@ -33,8 +33,9 @@ export interface RegisterToolsOptions {
      * event before its handler runs and a `tool_call_response` event after.
      * `disabled: true` is this channel's consent gate; it does not narrow the
      * default-on telemetry channel below, which resolves no identity and touches no
-     * storage. An `apiKey` set here is also sent as `x-api-key` on that channel's
-     * beacons, which only attributes them to this tenant.
+     * storage. An `apiKey` set here also rides that channel's beacons — on the URL as
+     * `?key=`, not as this channel's header — which only attributes them to this
+     * tenant.
      */
     tracking?: TrackingOptions;
     /**

package/dist/telemetry.d.ts

@@ -2,8 +2,9 @@
  * 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`
+ * site the SDK runs on. A page that *does* configure one has it sent as the `key`
+ * query parameter — never a header, which would cost every keyed beacon a CORS
+ * preflight — and it only adds tenant attribution. Opt out with `telemetry: false`
  * on `registerTools`, with `globalThis.__WEBMCP_TELEMETRY__ = false`, or via
  * Global Privacy Control.
  *
@@ -388,7 +389,7 @@ export interface TelemetrySinks {
  * navigation could then lose.
  *
  * The queue is keyed on the destination — endpoint plus key — because a batch is one
- * request with one `x-api-key`, and two tenants sharing an origin must never travel
+ * request under one key, and two tenants sharing an origin must never travel
  * under each other's key (see {@link batchTelemetrySinks}). The init flush a batch
  * defers (`deferInitEventForBatch`) uses that batch's sinks, so the common case lands
  * in one queue. A `pagehide` or a hidden tab flushes everything at once, through the

package/dist/transport.d.ts

@@ -5,23 +5,28 @@
  * v0.
  *
  * Transport is `fetch(..., { keepalive: true })` — unload-safe and, unlike
- * `sendBeacon`, able to set custom headers. Auth travels as the `x-api-key`
- * **header** (never a query param or body field): the deployed API Gateway
- * authorizer's identity source is that header, so a request without it is
- * rejected 401 before the authorizer runs, and keeping the key out of the URL
- * keeps it out of referrer logs and out of the canonical `payload` column. The
- * event JSON is the bare POST body; `org_id` is server-injected from the key.
+ * `sendBeacon`, able to set custom headers. On **this** channel auth travels as
+ * the `x-api-key` **header** (never a query param or body field): the deployed
+ * API Gateway authorizer's identity source is that header, so a request without
+ * it is rejected 401 before the authorizer runs, and keeping the secret key out
+ * of the URL keeps it out of referrer logs and out of the canonical `payload`
+ * column. The event JSON is the bare POST body; `org_id` is server-injected from
+ * the key.
  *
  * The scope is injectable for tests (spec.ts pattern). Every browser global is
  * guarded and the whole function is wrapped so telemetry never throws into the
  * caller.
  *
  * `sendTelemetry` is the sibling sender for the default-on usage-telemetry
- * channel (`src/telemetry.ts`): same keepalive/fire-and-forget discipline and the
- * same `x-api-key` header *when the page configured a key*, on a distinct
- * `/v1/telemetry` path that accepts the request either way. That channel runs on
- * 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.
+ * channel (`src/telemetry.ts`): same keepalive/fire-and-forget discipline, on a
+ * distinct `/v1/telemetry` path that accepts the request with or without a key.
+ * It does **not** share the header above — it puts the *publishable* key on the
+ * URL as `?key=`, because a custom header would cost that channel a CORS
+ * preflight it exists to avoid; see {@link sendTelemetry} for the whole reason
+ * and for why the exposure that argues against a URL here does not argue against
+ * it there. That channel runs on 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
@@ -40,7 +45,7 @@ export declare const DEFAULT_COLLECT_ENDPOINT: string;
  * Default ingest endpoint for the default-on usage-telemetry channel — a
  * **separate path** from {@link DEFAULT_COLLECT_ENDPOINT} so the backend can route
  * the two channels independently: one authorizer-protected, this one unauthenticated
- * by default and accepting the same request with an optional `x-api-key` for tenant
+ * by default and accepting the same request with an optional `?key=` for tenant
  * attribution. Same per-flavor base host (see {@link INGEST_BASE}).
  */
 export declare const DEFAULT_TELEMETRY_ENDPOINT: string;
@@ -62,7 +67,7 @@ export declare const TELEMETRY_CONTENT_TYPE = "text/plain";
 export declare const TELEMETRY_KEY_PARAM = "key";
 /**
  * POST a usage-telemetry event to the telemetry endpoint via `fetch(keepalive)`.
- * The path is the same whether or not `apiKey` is given: the header only *adds*
+ * The path is the same whether or not `apiKey` is given: the key only *adds*
  * tenant attribution to an event the backend would accept anyway, so a page that
  * never configures the authenticated channel keeps sending, and the backend falls
  * back to the CORS `Origin` header. Never throws: any failure is swallowed and a
@@ -71,8 +76,8 @@ export declare const TELEMETRY_KEY_PARAM = "key";
  * `apiKey` is `unknown` because it originates in caller-supplied options that no
  * compiler checked; anything that is not a non-blank string sends unauthenticated
  * rather than putting `"undefined"` (or a hostile object's `toString`) on the
- * 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.
+ * wire. A keyed beacon differs from an anonymous one only in its URL: the request
+ * stays CORS-simple either way, so neither costs a preflight.
  *
  * 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,
@@ -81,7 +86,7 @@ export declare const TELEMETRY_KEY_PARAM = "key";
  * 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.
+ * on the wire but the content type.
  *
  * The publishable key travels as the `key` query parameter, not as `x-api-key`. A
  * custom header is what makes a request non-simple, so a keyed beacon with the header

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@nekuda/webmcp-sdk",
-  "version": "0.7.0-dev.20.1",
+  "version": "0.7.0-dev.22.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).",
+  "description": "Let AI agents use your website: define tools once and register them through WebMCP, with page-scoped tools, SPA navigation and unsupported browsers handled for you.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {