@nekuda/webmcp-sdk 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-## Unreleased — usage telemetry schema 2 (breaking wire format)
+## 0.5.0 — 2026-08-24 — usage telemetry schema 2 (breaking wire format)
 
 The usage-telemetry channel emits **three events instead of two**, carrying
 derived signals instead of raw page and payload strings. `schema` bumps `1` → `2`.
@@ -11,11 +11,11 @@ unchanged. See `docs/telemetry-schema.md`.
 
 ### Breaking
 
-- **`sdk_init` fires once per page load, not once per `registerTools` call.** It is
-  scheduled at import time and flushed on the next task, so it now fires even when
-  nobody registers anything — which is the only way a broken integration is
-  visible. A page with three `registerTools` calls no longer emits three "init"
-  events.
+- **`sdk_init` fires once per page load, not once per `registerTools` call.** The
+  first telemetry-live batch schedules a next-task flush with its own key and
+  endpoint; an import-time one-second fallback still fires when nobody registers
+  anything, which is the only way a broken integration is visible. A page with
+  three `registerTools` calls no longer emits three "init" events.
 - **Per-call information moved to the new `tool_registration` event**, one per
   `registerTools` call: `registrationIndex`, `trigger`, `settleMs`, the `config.*`
   booleans (moved off `sdk_init`, which fires before any batch may have run), and

package/dist/index.d.ts

@@ -19,8 +19,9 @@
  *    Browsers without a WebMCP surface are a graceful no-op (`state: "unsupported"`).
  * 4. "Connect later without rewrite": generated modules only `defineTool` and
  *    EXPORT tools; one entry module calls `registerTools`. Connecting a site to the
- *    platform later (API key, telemetry) changes wrapper internals and config only —
- *    generated modules and their imports do not change. See `examples/add-to-cart.ts`.
+ *    platform later adds a publishable tracking key to wrapper config only — generated
+ *    modules and their imports do not change. The default-on anonymous channel in point 6
+ *    is independent of Connect. See `examples/add-to-cart.ts`.
  * 5. Anonymous tool-call tracking is opt-in via `registerTools`'s `tracking`
  *    option (see `TrackingOptions`) and default-silent: with neither `apiKey`
  *    nor `otel` set, no event is built at all — no identity resolution, no

package/dist/index.js

@@ -999,7 +999,7 @@ function shapeMetrics(inputSchema) {
 
 // src/telemetry.ts
 var SDK_NAME = "@nekuda/webmcp-sdk";
-var SDK_VERSION = "0.4.0";
+var SDK_VERSION = "0.5.0";
 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 isFieldParent(value) {
@@ -1334,12 +1334,13 @@ function pruneByAllowlist(event, fields = TELEMETRY_FIELDS, toolFields = TELEMET
   return pruned;
 }
 var defaultSinks2 = {
-  sendTelemetry: (event) => sendTelemetry(event, globalThis, undefined, telemetryApiKey())
+  sendTelemetry: (event) => sendTelemetry(event, globalThis, telemetryEndpoint(), telemetryApiKey())
 };
-function batchTelemetrySinks(apiKey) {
+function batchTelemetrySinks(apiKey, endpoint) {
   const own = batchApiKey(apiKey);
+  const ownEndpoint = telemetryEndpointFrom(endpoint);
   return {
-    sendTelemetry: (event) => sendTelemetry(event, globalThis, undefined, own ?? telemetryApiKey())
+    sendTelemetry: (event) => sendTelemetry(event, globalThis, ownEndpoint ?? telemetryEndpoint(), own ?? telemetryApiKey())
   };
 }
 function batchApiKey(apiKey) {
@@ -1361,7 +1362,9 @@ function emitTelemetry(build, sinks = defaultSinks2, fields = TELEMETRY_FIELDS,
 }
 var initCancelled = false;
 var initFlushed = false;
+var cancelInitFallback = () => {};
 var capturedApiKey;
+var capturedEndpoint;
 function captureTelemetryApiKey(apiKey) {
   if (typeof apiKey === "string" && apiKey.trim().length > 0)
     capturedApiKey = apiKey;
@@ -1369,17 +1372,44 @@ function captureTelemetryApiKey(apiKey) {
 function telemetryApiKey() {
   return capturedApiKey;
 }
+function telemetryEndpointFrom(endpoint) {
+  if (typeof endpoint !== "string")
+    return;
+  return safe(() => {
+    const url = new URL(endpoint);
+    if (!["http:", "https:"].includes(url.protocol) || !url.pathname.endsWith("/v1/collect") || url.search !== "" || url.hash !== "") {
+      return;
+    }
+    url.pathname = `${url.pathname.slice(0, -"/v1/collect".length)}/v1/telemetry`;
+    return url.toString();
+  });
+}
+function captureTelemetryEndpoint(endpoint) {
+  const derived = telemetryEndpointFrom(endpoint);
+  if (derived !== undefined)
+    capturedEndpoint = derived;
+}
+function telemetryEndpoint() {
+  return capturedEndpoint;
+}
 function cancelInitEvent() {
   initCancelled = true;
+  cancelInitFallback();
 }
 function flushInitEvent(sinks) {
   if (initFlushed)
     return;
   initFlushed = true;
+  cancelInitFallback();
   if (initCancelled)
     return;
   emitTelemetry(() => buildInitEvent(), sinks);
 }
+function deferInitEventForBatch(sinks) {
+  if (initFlushed || initCancelled)
+    return;
+  afterDelay(() => flushInitEvent(sinks), 0);
+}
 function afterDelay(run, ms) {
   const schedule = safe(() => globalThis.setTimeout);
   if (typeof schedule !== "function")
@@ -1392,7 +1422,8 @@ function afterDelay(run, ms) {
     safe(() => clear.call(globalThis, handle));
   };
 }
-afterDelay(() => flushInitEvent(), 0);
+var INIT_FALLBACK_MS = 1000;
+cancelInitFallback = afterDelay(() => flushInitEvent(), INIT_FALLBACK_MS);
 
 // src/register.ts
 function isContentResult(value) {
@@ -1438,7 +1469,7 @@ function trackerFor(tool, tracking) {
   return (eventName, data) => track(tracking, eventName, { ...shared, ...data });
 }
 function toSpecTool(tool, channels) {
-  const { tracking, telemetry, telemetrySinks, telemetryKey } = channels;
+  const { tracking, telemetry, telemetrySinks, telemetryKey, telemetryEndpoint: telemetryEndpoint2 } = channels;
   return {
     name: tool.name,
     ...tool.title !== undefined ? { title: tool.title } : {},
@@ -1451,7 +1482,7 @@ function toSpecTool(tool, channels) {
         return normalizeResult(await tool.execute(input));
       const callKey = telemetry ? resolveTelemetryKey(telemetryKey) : undefined;
       const sequence = telemetry ? nextCall(tool.stableKey, telemetryTenantScope(callKey)) : undefined;
-      const callSinks = sequence ? batchTelemetrySinks(callKey) : telemetrySinks;
+      const callSinks = sequence ? batchTelemetrySinks(callKey, telemetryEndpoint2) : telemetrySinks;
       const elapsed = clock();
       trackCall?.("tool_call_request", { input });
       try {
@@ -1543,15 +1574,24 @@ function registerTools(tools, options = {}) {
   const tracking = safe(() => options.tracking);
   const telemetryLive = telemetryOption !== undefined && telemetryEnabled(telemetryOption.value);
   const apiKey = telemetryLive ? safe(() => tracking?.apiKey) : undefined;
+  const endpoint = telemetryLive ? safe(() => tracking?.endpoint) : undefined;
+  const telemetrySinks = telemetryLive ? batchTelemetrySinks(apiKey, endpoint) : undefined;
   const channels = {
     tracking,
     telemetry: telemetryLive,
-    ...telemetryLive ? { telemetrySinks: batchTelemetrySinks(apiKey), telemetryKey: apiKey } : {}
+    ...telemetryLive ? {
+      telemetrySinks,
+      telemetryKey: apiKey,
+      telemetryEndpoint: endpoint
+    } : {}
   };
   if (telemetryOption?.value === false)
     cancelInitEvent();
-  if (telemetryLive)
+  if (telemetrySinks) {
     captureTelemetryApiKey(apiKey);
+    captureTelemetryEndpoint(endpoint);
+    deferInitEventForBatch(telemetrySinks);
+  }
   assertUniqueIdentities(tools);
   const controller = new AbortController;
   const external = options.signal;
@@ -1601,7 +1641,7 @@ function registerTools(tools, options = {}) {
   };
 }
 export {
-  resolveModelContext,
+  defineTool,
   registerTools,
-  defineTool
+  resolveModelContext
 };

package/dist/register.d.ts

@@ -44,10 +44,11 @@ export interface RegisterToolsOptions {
      *
      * The other two events are per-batch, so the option is read per call: a *later*
      * `registerTools` that omits it reports its own batch and calls. Cancelling
-     * `sdk_init` also requires winning the race with its deferred flush — a batch
-     * registered at module scope does, one registered from a mount effect or a consent
-     * callback may not. A site that wants the whole page silent regardless of where its
-     * `registerTools` calls come from (generated code, a CDN snippet) should use a
+     * `sdk_init` also requires winning the race with its deferred flush. A batch
+     * registered at module scope or from an ordinary mount effect schedules the keyed
+     * batch flush; a later consent decision can still arrive after the bounded
+     * no-registration fallback. A site that wants the whole page silent regardless of
+     * when its `registerTools` calls run (generated code, a CDN snippet) should use a
      * page-level lever instead: `globalThis.__WEBMCP_TELEMETRY__ = false` — strictly
      * `false`, so a truthy `"0"` does not opt out — or Global Privacy Control
      * (`navigator.globalPrivacyControl === true`), both of which are read at emit time

package/dist/telemetry.d.ts

@@ -360,7 +360,7 @@ export interface TelemetrySinks {
  * the raw batch option: a key resolved to a value pins it, closing the window in which
  * the module key changes between the claim and the emit.
  */
-export declare function batchTelemetrySinks(apiKey: unknown): TelemetrySinks;
+export declare function batchTelemetrySinks(apiKey: unknown, endpoint?: unknown): TelemetrySinks;
 /**
  * The key a batch's beacons authenticate with, resolved now instead of at emit time:
  * its own when it supplied one, otherwise the page's.
@@ -438,6 +438,15 @@ export declare function emitTelemetry(build: () => TelemetryEvent, sinks?: Telem
 export declare function captureTelemetryApiKey(apiKey: unknown): void;
 /** The key {@link captureTelemetryApiKey} last recorded, if any. */
 export declare function telemetryApiKey(): string | undefined;
+/**
+ * Record the telemetry endpoint for the deferred `sdk_init` flush. Like the captured
+ * key, a later usable value overwrites an earlier one while an absent or malformed
+ * value leaves the last usable value in place. URL parsing is best-effort because an
+ * observability option must never break the visitor's page.
+ */
+export declare function captureTelemetryEndpoint(endpoint: unknown): void;
+/** The endpoint {@link captureTelemetryEndpoint} last recorded, if any. */
+export declare function telemetryEndpoint(): string | undefined;
 /**
  * Cancel the deferred `sdk_init` below. Called by `registerTools({ telemetry: false })`,
  * whose opt-out is page-level and not merely batch-level: the flush describes the
@@ -462,6 +471,12 @@ export declare function cancelInitEvent(): void;
  * Exported for tests; the scheduled timer below is the one that runs it on a real page.
  */
 export declare function flushInitEvent(sinks?: TelemetrySinks): void;
+/**
+ * Give a telemetry-live registration batch the next task's `sdk_init` flush. This
+ * keeps the batch's key and endpoint together while leaving the rest of the current
+ * task available for a page-level opt-out or another synchronous registration.
+ */
+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
@@ -469,3 +484,5 @@ export declare function flushInitEvent(sinks?: TelemetrySinks): void;
  * `registerTools`. The canceller is safe to call when nothing was scheduled.
  */
 export declare function afterDelay(run: () => void, ms: number): () => void;
+/** How long a page that never registers gets to expose a real batch configuration. */
+export declare const INIT_FALLBACK_MS = 1000;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nekuda/webmcp-sdk",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "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",