@nekuda/webmcp-sdk 0.6.0-dev.17.1 → 0.7.0-dev.18.1

package/CHANGELOG.md

@@ -1,6 +1,16 @@
 # Changelog
 
-## Unreleased — telemetry beacons without a preflight
+## 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
@@ -8,6 +18,19 @@
   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

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

@@ -1105,7 +1105,7 @@ function shapeMetrics(inputSchema) {
 
 // src/telemetry.ts
 var SDK_NAME = "@nekuda/webmcp-sdk";
-var SDK_VERSION = "0.6.0-dev.17.1";
+var SDK_VERSION = "0.7.0-dev.18.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) {
@@ -1113,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;
@@ -1461,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) {
@@ -1485,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;
@@ -1543,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")
@@ -1555,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,11 +7,12 @@
  * 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
@@ -370,6 +371,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 +556,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*
@@ -90,8 +92,6 @@ export declare function sendToCollect(event: TrackingEvent, config: CollectConfi
  * The event stays a bare `object` here so this module never has to import the
  * assembled shape from `telemetry.ts` (which imports this function).
  */
-/** CORS-safelisted, so an anonymous beacon needs no preflight — see sendTelemetry. */
-export declare const TELEMETRY_CONTENT_TYPE = "text/plain";
 export declare function sendTelemetry(event: object, scope?: object, endpoint?: string, apiKey?: unknown): void;
 /** The `Logger.emit` slice we use — structural, no hard OTEL type coupling. */
 interface LoggerLike {

package/package.json

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