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

package/CHANGELOG.md

@@ -4,8 +4,8 @@
 
 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.
@@ -13,10 +13,23 @@ byte 0.6.0's.
 ### 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/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

@@ -180,16 +180,25 @@ function sendToCollect(event, config, scope = globalThis) {
   } catch {}
 }
 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);
     if (json === undefined)
       return;
-    const url = endpoint || DEFAULT_TELEMETRY_ENDPOINT;
+    const base = endpoint || DEFAULT_TELEMETRY_ENDPOINT;
     const headers = { "content-type": TELEMETRY_CONTENT_TYPE };
     const authenticated = typeof apiKey === "string" && apiKey.trim().length > 0;
-    if (authenticated)
-      headers["x-api-key"] = apiKey;
+    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.19.1";
+var SDK_VERSION = "0.7.0-dev.21.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;
@@ -58,9 +63,11 @@ export interface CollectConfig {
 export declare function sendToCollect(event: TrackingEvent, config: CollectConfig, scope?: object): void;
 /** CORS-safelisted, so an anonymous beacon needs no preflight — see sendTelemetry. */
 export declare const TELEMETRY_CONTENT_TYPE = "text/plain";
+/** Query parameter carrying the publishable key; a header would force a preflight (see sendTelemetry). */
+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
@@ -69,8 +76,8 @@ export declare const TELEMETRY_CONTENT_TYPE = "text/plain";
  * `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,
@@ -79,8 +86,17 @@ export declare const TELEMETRY_CONTENT_TYPE = "text/plain";
  * 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.
+ * 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
+ * paid the preflight whatever its content type — and every hosted-snippet install IS
+ * keyed, because the manifest hands it a default publishable key (ADR-0020). Measured
+ * the morning after the content-type change, those keyed preflights were still ~200k
+ * requests per two hours on the telemetry route. The key is public by design (it sits
+ * in the page's HTML), the authorizer reads the query parameter and the header alike,
+ * and the WAF redacts the query string from its logs. `x-api-key` stays accepted for
+ * older bundles.
  *
  * 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

package/package.json

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