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

package/CHANGELOG.md

@@ -10,6 +10,13 @@ the second of them puts a request shape on the wire that no earlier backend pars
 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

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.js

@@ -1114,7 +1114,7 @@ function shapeMetrics(inputSchema) {
 
 // src/telemetry.ts
 var SDK_NAME = "@nekuda/webmcp-sdk";
-var SDK_VERSION = "0.7.0-dev.21.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/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@nekuda/webmcp-sdk",
-  "version": "0.7.0-dev.21.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": {