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

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 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
+`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.
+
+### 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.
+
+### One beacon per page load
+
+- `sdk_init` and `tool_registration` are held for 50 ms per destination (endpoint
+  plus key) and, when two or more are waiting, sent as one `batch` envelope
+  (`{"schema":2,"event":"batch","events":[…]}`); a lone event is sent as it was.
+  `tool_call` never waits, and drains the queue ahead of itself. `pagehide` and a
+  hidden tab flush at once, through the same `keepalive` fetch. The backend explodes
+  a batch into its events, so nothing downstream changes shape.
+- Three bounds, each a fallback rather than a drop: at most 16 events per batch (the
+  count the backend accepts — the queue flushes at the cap and opens a new window),
+  at most 60 KB per request (an over-large batch goes as the per-event requests it
+  replaced), and a runtime that cannot schedule a timer sends immediately.
+
 ## 0.6.0 — 2026-09-18
 
 Five additive changes, no breaking change. The wire schema stays at `2`. Four of them
@@ -9,20 +40,26 @@ silent when unset, so **an npm consumer who sets none of them sends exactly the
 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.
 
-One behaviour is **CDN-build-only**. Page-level telemetry sampling is switched on by a
-`bun build --define`, which only `infra/deploy-snippet.sh` passes when it builds the CDN
-snippet; neither publish lane passes it, so **an npm install is unsampled** and sends
-every page-level event, exactly as before.
+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 — CDN builds only
+### Page-level telemetry sampling — available, off everywhere
 
-- A build may sample the two page-level telemetry events (`sdk_init`,
+- 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, or anything outside (0, 1), sends everything,
-  which is the npm default and the previous behaviour byte for byte. The CDN snippet
-  builds at `0.1`: installed sites had reached five million page-level beacons a day.
+  `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`
 

package/dist/index.d.ts

@@ -53,7 +53,8 @@
  *    `tool_registration` once per `registerTools` call, carrying each tool's
  *    outcome; and `tool_call` once per settled invocation, as derived signals only —
  *    no raw `input`, `response`, or error message, unlike point 5. All three go to a
- *    separate `/v1/telemetry` endpoint, fire-and-forget, no batching; arrival order
+ *    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

package/dist/index.js

@@ -136,7 +136,7 @@ function resolveModelContext(scope = globalThis) {
 }
 
 // src/transport.ts
-var INGEST_BASE = "https://ingest.agentlane.com";
+var INGEST_BASE = "https://ingest.agentlane.dev";
 var DEFAULT_COLLECT_ENDPOINT = `${INGEST_BASE}/v1/collect`;
 var DEFAULT_TELEMETRY_ENDPOINT = `${INGEST_BASE}/v1/telemetry`;
 function tryFetch(scope, url, headers, json, onResponse) {
@@ -179,13 +179,14 @@ function sendToCollect(event, config, scope = globalThis) {
     tryFetch(scope, url, headers, json);
   } catch {}
 }
+var TELEMETRY_CONTENT_TYPE = "text/plain";
 function sendTelemetry(event, scope = globalThis, endpoint, apiKey) {
   try {
     const json = JSON.stringify(event);
     if (json === undefined)
       return;
     const url = endpoint || DEFAULT_TELEMETRY_ENDPOINT;
-    const headers = { "content-type": "application/json" };
+    const headers = { "content-type": TELEMETRY_CONTENT_TYPE };
     const authenticated = typeof apiKey === "string" && apiKey.trim().length > 0;
     if (authenticated)
       headers["x-api-key"] = apiKey;
@@ -1104,7 +1105,7 @@ function shapeMetrics(inputSchema) {
 
 // src/telemetry.ts
 var SDK_NAME = "@nekuda/webmcp-sdk";
-var SDK_VERSION = "0.6.0";
+var SDK_VERSION = "0.7.0-dev.19.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) {
@@ -1112,7 +1113,7 @@ function parseSampleRate(raw) {
   return Number.isFinite(rate) && rate > 0 && rate < 1 ? rate : 1;
 }
 var SDK_TELEMETRY_SAMPLE_RATE = parseSampleRate(typeof __WEBMCP_TELEMETRY_SAMPLE_RATE__ === "string" ? __WEBMCP_TELEMETRY_SAMPLE_RATE__ : undefined);
-var SAMPLED_EVENTS = new Set(["sdk_init", "tool_registration"]);
+var PAGE_LEVEL_EVENTS = new Set(["sdk_init", "tool_registration"]);
 function pageSampled(sessionId, rate = SDK_TELEMETRY_SAMPLE_RATE) {
   if (rate >= 1)
     return true;
@@ -1460,13 +1461,90 @@ function pruneByAllowlist(event, fields = TELEMETRY_FIELDS, toolFields = TELEMET
   return pruned;
 }
 var defaultSinks2 = {
-  sendTelemetry: (event) => sendTelemetry(event, globalThis, telemetryEndpoint(), telemetryApiKey())
+  sendTelemetry: (event) => queueOrSend(event, telemetryEndpoint(), telemetryApiKey())
 };
+var PAGE_BATCH_WINDOW_MS = 50;
+var PAGE_BATCH_MAX_BYTES = 60000;
+var PAGE_BATCH_EVENT = "batch";
+var PAGE_BATCH_EVENTS_KEY = "events";
+var PAGE_BATCH_MAX_EVENTS = 16;
+var pendingPageEvents = new Map;
+function queueOrSend(event, endpoint, apiKey) {
+  const name = String(event.event);
+  if (!PAGE_LEVEL_EVENTS.has(name)) {
+    flushPageEventQueue();
+    sendTelemetry(event, globalThis, endpoint, apiKey);
+    return;
+  }
+  const key = `${endpoint ?? ""}
+${typeof apiKey === "string" ? apiKey : ""}`;
+  const pending = pendingPageEvents.get(key);
+  if (pending) {
+    pending.events.push(event);
+    if (pending.events.length >= PAGE_BATCH_MAX_EVENTS)
+      flushPendingBatch(key);
+    return;
+  }
+  const entry = { events: [event], endpoint, apiKey, cancel: () => {} };
+  pendingPageEvents.set(key, entry);
+  const cancel = tryAfterDelay(() => flushPendingBatch(key), PAGE_BATCH_WINDOW_MS);
+  if (!cancel) {
+    flushPendingBatch(key);
+    return;
+  }
+  entry.cancel = cancel;
+}
+function flushPendingBatch(key) {
+  const entry = pendingPageEvents.get(key);
+  if (!entry)
+    return;
+  pendingPageEvents.delete(key);
+  entry.cancel();
+  const { events, endpoint, apiKey } = entry;
+  const one = events[0];
+  if (events.length === 1 && one) {
+    sendTelemetry(one, globalThis, endpoint, apiKey);
+    return;
+  }
+  const batch = {
+    schema: TELEMETRY_SCHEMA_VERSION,
+    event: PAGE_BATCH_EVENT,
+    ts: new Date().toISOString(),
+    sessionId: sessionId(),
+    [PAGE_BATCH_EVENTS_KEY]: events
+  };
+  const json = safe(() => JSON.stringify(batch));
+  const bytes = json === undefined ? Number.POSITIVE_INFINITY : utf8Length(json);
+  if (bytes <= PAGE_BATCH_MAX_BYTES) {
+    sendTelemetry(batch, globalThis, endpoint, apiKey);
+    return;
+  }
+  for (const event of events)
+    sendTelemetry(event, globalThis, endpoint, apiKey);
+}
+function utf8Length(text) {
+  const encoded = safe(() => new TextEncoder().encode(text).length);
+  return typeof encoded === "number" ? encoded : text.length * 3;
+}
+function flushPageEventQueue() {
+  for (const key of Array.from(pendingPageEvents.keys()))
+    flushPendingBatch(key);
+}
+safe(() => {
+  const g = globalThis;
+  if (typeof g.addEventListener !== "function")
+    return;
+  g.addEventListener("pagehide", flushPageEventQueue);
+  g.addEventListener("visibilitychange", () => {
+    if (g.document?.visibilityState === "hidden")
+      flushPageEventQueue();
+  });
+});
 function batchTelemetrySinks(apiKey, endpoint) {
   const own = batchApiKey(apiKey);
   const ownEndpoint = telemetryEndpointFrom(endpoint);
   return {
-    sendTelemetry: (event) => sendTelemetry(event, globalThis, ownEndpoint ?? telemetryEndpoint(), own ?? telemetryApiKey())
+    sendTelemetry: (event) => queueOrSend(event, ownEndpoint ?? telemetryEndpoint(), own ?? telemetryApiKey())
   };
 }
 function batchApiKey(apiKey) {
@@ -1484,7 +1562,7 @@ function emitTelemetry(build, sinks = defaultSinks2, fields = TELEMETRY_FIELDS,
     if (!telemetryEnabled())
       return;
     const event = { ...build() };
-    if (SAMPLED_EVENTS.has(String(event.event)) && sampleRate < 1) {
+    if (PAGE_LEVEL_EVENTS.has(String(event.event)) && sampleRate < 1) {
       if (!pageSampled(String(event.sessionId), sampleRate))
         return;
       event.sampleRate = sampleRate;
@@ -1542,11 +1620,18 @@ function deferInitEventForBatch(sinks) {
     return;
   afterDelay(() => flushInitEvent(sinks), 0);
 }
-function afterDelay(run, ms) {
+function tryAfterDelay(run, ms) {
   const schedule = safe(() => globalThis.setTimeout);
   if (typeof schedule !== "function")
-    return () => {};
-  const handle = safe(() => schedule.call(globalThis, () => run(), ms));
+    return;
+  let armed = false;
+  const handle = safe(() => {
+    const id = schedule.call(globalThis, () => run(), ms);
+    armed = true;
+    return id;
+  });
+  if (!armed)
+    return;
   return () => {
     const clear = safe(() => globalThis.clearTimeout);
     if (typeof clear !== "function")
@@ -1554,6 +1639,9 @@ function afterDelay(run, ms) {
     safe(() => clear.call(globalThis, handle));
   };
 }
+function afterDelay(run, ms) {
+  return tryAfterDelay(run, ms) ?? (() => {});
+}
 var INIT_FALLBACK_MS = 1000;
 cancelInitFallback = afterDelay(() => flushInitEvent(), INIT_FALLBACK_MS);
 

package/dist/telemetry.d.ts

@@ -7,16 +7,20 @@
  * on `registerTools`, with `globalThis.__WEBMCP_TELEMETRY__ = false`, or via
  * Global Privacy Control.
  *
- * Event schemas, joined on the in-memory `sessionId`, no batching,
- * fire-and-forget: `sdk_init` (once per page load, from the one-shot flush this
- * module schedules at import time), `tool_registration` (once per `registerTools`
- * call), and `tool_call` (once per settled invocation). Events go to the separate
- * `/v1/telemetry` endpoint through `sendTelemetry` in `src/transport.ts`.
+ * Event schemas, joined on the in-memory `sessionId`, fire-and-forget: `sdk_init`
+ * (once per page load, from the one-shot flush this module schedules at import
+ * time), `tool_registration` (once per `registerTools` call), and `tool_call`
+ * (once per settled invocation). Events go to the separate `/v1/telemetry`
+ * endpoint through `sendTelemetry` in `src/transport.ts`; the two page-level ones
+ * 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.
@@ -370,6 +374,55 @@ export declare function pruneByAllowlist(event: Record<string, unknown>, fields?
 export interface TelemetrySinks {
     sendTelemetry: (event: object) => void;
 }
+/**
+ * One beacon per page load, where the page allows it.
+ *
+ * `sdk_init` flushes one task after import and the first `tool_registration` settles a
+ * few milliseconds after `registerTools`, so on most pages the two page-level events
+ * leave within the same few milliseconds — as two requests. Each request is billed at
+ * the edge, and in 2026-09 page-level beacons were the whole of a seven-million-a-day
+ * request bill. Both events are therefore held for {@link PAGE_BATCH_WINDOW_MS} and
+ * sent as one `batch` envelope when two or more are waiting; a lone event is sent as
+ * itself, byte for byte what it was before. `tool_call` never waits: it is one per
+ * invocation, carries the call's own timing, and batching it would hold a signal a
+ * 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
+ * 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
+ * same `keepalive` fetch. A runtime that cannot schedule — no `setTimeout`, or one
+ * that throws — sends immediately: a queue that could never drain would be a queue
+ * that loses, and the events would sit until `pagehide` or forever.
+ *
+ * The transform explodes a `batch` into its events (internal/telemetrytransform); the
+ * server-written attribution is applied to every one, so a batch cannot say anything
+ * its events could not have said alone.
+ */
+export declare const PAGE_BATCH_WINDOW_MS = 50;
+/** Under `fetch(keepalive)`'s 64 KB in-flight ceiling, with room for the wrapper. */
+export declare const PAGE_BATCH_MAX_BYTES = 60000;
+/**
+ * The batch envelope's `event` name and member-list key, and the member cap — the
+ * three spellings this file shares with the Go transform that explodes a batch
+ * (`internal/telemetrytransform`: `eventBatch`, `wireBatchEvents`, `MaxBatchEvents`).
+ * Nothing compiles the two together, so `analytics/telemetry_batch_contract_test.go`
+ * reads these three declarations out of this source and asserts they equal the Go
+ * constants. Exported for that gate, and used below rather than restated: a pin
+ * against a constant the envelope does not actually use is a tautology.
+ *
+ * The cap is the one the SERVER enforces. A seventeenth member does not make a
+ * larger batch, it makes an `unparseable_body` — one request in which every event is
+ * lost — so the queue flushes at the cap and starts a new batch instead. A page can
+ * reach it: `registerTools` may be called many times on an SPA entry, and each call
+ * emits its own `tool_registration`.
+ */
+export declare const PAGE_BATCH_EVENT = "batch";
+export declare const PAGE_BATCH_EVENTS_KEY = "events";
+export declare const PAGE_BATCH_MAX_EVENTS = 16;
+/** Send every waiting page-level batch now — on `pagehide`, a hidden tab, or a test. */
+export declare function flushPageEventQueue(): void;
 /**
  * The sink for the two events a *batch* owns. They carry that batch's tool identity —
  * `stableKey`, `routeTemplate`, `errorSignature` — so they authenticate with that
@@ -506,10 +559,22 @@ export declare function flushInitEvent(sinks?: TelemetrySinks): void;
  */
 export declare function deferInitEventForBatch(sinks: TelemetrySinks): void;
 /**
- * Run `run` after `ms`, returning a canceller. Guarded end to end: a runtime with no
- * timers (SSR) and a hostile `setTimeout` (an extension, a fake-timer harness) both
- * mean the callback never runs, never a throw out of the import or out of
- * `registerTools`. The canceller is safe to call when nothing was scheduled.
+ * Run `run` after `ms`, returning a canceller — or `undefined` when nothing was
+ * scheduled. Guarded end to end: a runtime with no timers (SSR) and a hostile
+ * `setTimeout` (an extension, a fake-timer harness) both mean the callback never
+ * runs, never a throw out of the import or out of `registerTools`.
+ *
+ * The `undefined` is the part {@link afterDelay} cannot express, and it matters to
+ * exactly one caller: the page-level batch holds events until its timer fires, so a
+ * `setTimeout` that exists and THROWS would leave them queued until `pagehide` — a
+ * silent loss on any page the user closes from a different tab. A caller that only
+ * defers work is happy with a no-op; a caller that defers DATA has to know.
+ */
+export declare function tryAfterDelay(run: () => void, ms: number): (() => void) | undefined;
+/**
+ * {@link tryAfterDelay} for the callers that have nothing to do when the runtime
+ * cannot schedule: the canceller is safe to call when nothing was scheduled, and an
+ * unscheduled flush is simply one that never happens.
  */
 export declare function afterDelay(run: () => void, ms: number): () => void;
 /** How long a page that never registers gets to expose a real batch configuration. */

package/dist/transport.d.ts

@@ -56,6 +56,8 @@ export interface CollectConfig {
  * a no-`fetch` environment is a silent no-op.
  */
 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";
 /**
  * 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*
@@ -70,6 +72,16 @@ export declare function sendToCollect(event: TrackingEvent, config: CollectConfi
  * 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.
  *
+ * 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,
+ * so an anonymous beacon is a "simple request" and the browser sends it with no
+ * OPTIONS preflight. With `application/json` every page load paid two requests
+ * 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.
+ *
  * 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
  * {@link warnKeyRejected} and nothing else — no throw, no retry, no second send.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nekuda/webmcp-sdk",
-  "version": "0.6.0",
+  "version": "0.7.0-dev.19.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",
@@ -11,7 +11,10 @@
       "default": "./dist/index.js"
     }
   },
-  "files": ["dist", "CHANGELOG.md"],
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
   "publishConfig": {
     "access": "public"
   },
@@ -36,5 +39,7 @@
       "optional": true
     }
   },
-  "trustedDependencies": ["@biomejs/biome"]
+  "trustedDependencies": [
+    "@biomejs/biome"
+  ]
 }