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

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # 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

package/dist/index.js

@@ -180,16 +180,16 @@ function sendToCollect(event, config, scope = globalThis) {
   } catch {}
 }
 var TELEMETRY_CONTENT_TYPE = "text/plain";
+var TELEMETRY_KEY_PARAM = "key";
 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 ? `${base}${base.includes("?") ? "&" : "?"}${TELEMETRY_KEY_PARAM}=${encodeURIComponent(apiKey)}` : base;
     tryFetch(scope, url, headers, json, authenticated ? (response) => {
       if (isUnauthorized(response))
         warnKeyRejected(scope);
@@ -1105,7 +1105,7 @@ function shapeMetrics(inputSchema) {
 
 // src/telemetry.ts
 var SDK_NAME = "@nekuda/webmcp-sdk";
-var SDK_VERSION = "0.7.0-dev.18.1";
+var SDK_VERSION = "0.7.0-dev.20.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/telemetry.d.ts

@@ -15,9 +15,12 @@
  * may share a request as a `batch` envelope (see {@link PAGE_BATCH_WINDOW_MS}).
  *
  * No browser storage is touched anywhere in this channel — no `visitorId`, no
- * stored `sessionId` (the ePrivacy Art. 5(3) concern). Cross-visit stitching is
- * deliberately impossible here; the authenticated `tracking` channel keeps its own
- * storage-backed identity, and this one never reads it.
+ * stored `sessionId` (the ePrivacy Art. 5(3) concern). Nothing this SDK sends can
+ * stitch two visits together; the authenticated `tracking` channel keeps its own
+ * storage-backed identity, and this one never reads it. The ingest edge derives a
+ * bounded identifier of its own from the request it receives (a daily-salted hash,
+ * see *Privacy posture* in `docs/telemetry-schema.md`), which is not something the
+ * client participates in or can observe.
  *
  * Every field an event may carry is gated by the baked-in allowlists in
  * `src/telemetry-fields.ts` — one keyed by event path, one by per-tool field.

package/dist/transport.d.ts

@@ -58,6 +58,8 @@ 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*
@@ -79,8 +81,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 header.
+ *
+ * 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.18.1",
+  "version": "0.7.0-dev.20.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",