@nekuda/webmcp-sdk 0.4.0-dev.7.3

package/dist/tracking.d.ts

@@ -0,0 +1,208 @@
+/**
+ * Anonymous visitor/session tracking for WebMCP tool calls. Opt-in via the
+ * `tracking` option on `registerTools`.
+ *
+ * This module owns three things: anonymous identity, event payload assembly
+ * (`buildEventPayload` + `boundEventPayload`), and emission (`track`).
+ *
+ * Identity is intentionally minimal and PII-free: random UUIDs only, namespaced
+ * per `apiKey` (a non-reversible hash — the raw key never lands in storage) so
+ * two tenants sharing an origin never mix identity. Event *payloads* are a
+ * separate matter — page URL, tool `input`, and `response` are captured verbatim
+ * and may carry PII; redaction is a downstream/backend concern.
+ *
+ * - `visitorId` lives in `localStorage` and is stable across visits.
+ * - `sessionId` lives in `sessionStorage` and is refreshed by a `last_seen`
+ *   timestamp; after `SESSION_TIMEOUT_MS` of inactivity a new session is minted.
+ *
+ * Browser storage can be absent (non-DOM env) or throw (privacy mode). Every
+ * access is guarded, and on failure the module falls back to per-page-load
+ * in-memory IDs so identity resolution never throws.
+ *
+ * Consent + outputs: *this channel* is silent by default and `disabled: true` is
+ * its hard consent gate — but it is not an SDK-wide one. The default-on usage
+ * telemetry channel (`src/telemetry.ts`) emits derived page and tool signals with
+ * no `apiKey`, has its own opt-outs (`telemetry: false`, `__WEBMCP_TELEMETRY__`,
+ * and GPC), and touches no browser storage at all — so `disabled` does not narrow
+ * it in any way. The identity below is this channel's alone. Otherwise the
+ * two outputs here are independent and composable —
+ * `apiKey` enables the backend transport (`sendToCollect`) and `otel: true`
+ * enables OTEL LogRecords (`emitOtelLog`), both in `src/transport.ts`. With
+ * neither configured `track()` builds nothing at all: no identity resolution,
+ * no storage access, no output. Emission is wrapped end-to-end so telemetry can
+ * never throw into the caller.
+ */
+import { type CollectConfig } from "./transport.js";
+/**
+ * 32-bit FNV-1a over UTF-16 code units, rendered as 8 lowercase hex chars. Not
+ * a security primitive — a cheap, dependency-free way to derive a stable,
+ * non-reversible key from a caller-supplied string (storage namespaces here,
+ * tool schema hashes in the telemetry channel). Collisions are possible and
+ * acceptable for both uses.
+ */
+export declare function fnv1a(input: string): string;
+/**
+ * Stable, non-reversible storage namespace derived from the `apiKey` so one key
+ * ≈ one site keeps its own visitor/session identity without the customer ever
+ * knowing their `org_id` (server-injected) and without exposing the key itself
+ * in `localStorage`. Not for security, only to separate tenants sharing an
+ * origin. An absent/empty key falls back to a shared constant namespace.
+ */
+export declare function storageNamespace(apiKey?: string): string;
+/**
+ * A v4 UUID that resolves in every context. `crypto.randomUUID` is
+ * secure-context-only — `undefined` on plain `http://` pages — so we fall back
+ * to `crypto.getRandomValues` (available in insecure contexts) and finally
+ * {@link fillPseudoRandom}, preserving this module's "identity resolution never
+ * throws" guarantee even on non-HTTPS sites.
+ */
+export declare function randomId(): string;
+/** Stable anonymous visitor ID, persisted in `localStorage` across visits. */
+export declare function getOrCreateVisitorId(namespace: string): string;
+/**
+ * Journey session ID in `sessionStorage`. Reuses the existing session while
+ * `last_seen` is within the timeout, otherwise mints a new one. Every call
+ * refreshes `last_seen`.
+ */
+export declare function getOrCreateSessionId(namespace: string): string;
+/**
+ * Configures tool-call tracking for a `registerTools` batch.
+ *
+ * `apiKey` is the sole tenant credential: it enables the backend transport
+ * (POST to the collect endpoint, authenticated via the `x-api-key` header) and
+ * namespaces identity storage; the backend resolves it to the `org_id`, which
+ * the client never sends or knows. `otel: true` emits each event as an OTEL
+ * LogRecord via the global `LoggerProvider`. These two outputs are independent
+ * and composable. `endpoint` overrides the backend URL. `disabled: true` is the
+ * hard consent gate for both of them — it does not affect the default-on
+ * telemetry channel at all, see the module comment. With neither `apiKey` nor
+ * `otel` set, no event is built at all.
+ */
+export interface TrackingOptions {
+    /** Presence (non-empty) enables the backend transport and namespaces storage. */
+    apiKey?: string;
+    /** Override the collect endpoint; ignored without `apiKey`. */
+    endpoint?: string;
+    /** Emit each event as an OTEL LogRecord via the global `LoggerProvider`. */
+    otel?: boolean;
+    /**
+     * Consent gate for this channel: nothing is built or emitted here. It does not
+     * reach the default-on telemetry channel, which resolves no identity and touches
+     * no storage — `telemetry: false` on `registerTools` is that channel's opt-out.
+     */
+    disabled?: boolean;
+}
+/**
+ * Which of this channel's two outputs these options actually enable, after the
+ * consent gate. The single source of truth for "is this channel live", because
+ * three call sites need exactly this answer and must not drift: {@link track}
+ * fans out to the enabled outputs, `register.ts` skips building a per-call
+ * emitter (and the `callId` behind it) when neither is live, and telemetry's
+ * `config.*` reports what this channel is *doing*.
+ *
+ * Reads a caller-supplied object, so it is guarded: a hostile `apiKey` getter
+ * means "no outputs", never a throw into tool execution or page load.
+ */
+export declare function trackingOutputs(options?: TrackingOptions): {
+    toBackend: boolean;
+    toOtel: boolean;
+};
+/** Best-effort page context on a tracking event; this channel's alone. */
+export interface PageFields {
+    siteOrigin?: string;
+    url?: string;
+    path?: string;
+    referrer?: string;
+    title?: string;
+}
+/**
+ * A single tracking event. Identity + timing fields are always present; page
+ * fields are best-effort (absent in a non-DOM env); event-specific data (e.g.
+ * `toolStableKey`, `input`, `response`) is spread in by the caller.
+ */
+export interface TrackingEvent extends PageFields {
+    /** Dedup key, unique per event. */
+    eventId: string;
+    visitorId: string;
+    sessionId: string;
+    eventName: string;
+    /** Event time as an ISO-8601 string. */
+    ts: string;
+    [key: string]: unknown;
+}
+/**
+ * The error's message, or its string form for a non-`Error` throw. Both a throwing
+ * `message` getter and a throwing `toString` are possible on a value the page threw
+ * at us, so both are guarded; an unreadable value reports as empty rather than
+ * breaking event assembly — or, worse, replacing the tool's own error with ours.
+ *
+ * Shared by both channels, but only one sends it raw: the authenticated one reports
+ * it as `error` on the response event, sliced by the 64 KB bound downstream. The
+ * default-on one carries no raw message at all — this is only the input to
+ * `errorSignature`, which templates and caps it where it is read.
+ */
+export declare function errorMessage(error: unknown): string;
+/** Assemble a tracking event from resolved identity, an event name, and extra data. */
+export declare function buildEventPayload(params: {
+    visitorId: string;
+    sessionId: string;
+    eventName: string;
+    data?: Record<string, unknown>;
+}): TrackingEvent;
+/**
+ * Truncate a string so its JSON-escaped form fits in `maxBytes` UTF-8 bytes,
+ * without splitting a code point. The event size bound (schema §1.5) is on the
+ * *serialized* event, so a raw byte slice is not enough: `"`/`\`/control chars
+ * expand under escaping, so a 16 KB raw slice of escapable text can serialize
+ * to ~96 KB and blow the bound on its own. Measure the escaped length and
+ * binary-search the longest byte-prefix that still fits.
+ *
+ * Exported because the default-on telemetry channel (`src/telemetry.ts`) caps every
+ * string at its source — brands, error signatures, per-tool identities — since the
+ * ladder below reaches none of them.
+ */
+export declare function sliceToBytes(value: string, maxBytes: number): string;
+/**
+ * Serialized UTF-8 byte size of a value, or `undefined` when it cannot be
+ * serialized (a circular structure). Exported because the default-on telemetry
+ * channel reports a tool result's size as `response.bytes` instead of its content
+ * — the same measurement the truncation ladder below makes its decisions on, so
+ * one implementation keeps the reported size and the enforced bound in agreement.
+ */
+export declare function serializedBytes(value: unknown): number | undefined;
+/**
+ * Keep a serialized event under the schema §1.5 64 KB bound. Fields are dropped
+ * in order — `response`, then `input`, then `error` (a string sliced to 16 KB,
+ * anything else replaced) — each replaced by a `{ __truncated: true,
+ * originalBytes }` marker, and only as far as needed to fit. Unserializable
+ * (circular) payload fields are always replaced with a marker. Then the telemetry
+ * channel's `tools[]` degrades in two steps of its own ({@link boundTools}). As a
+ * final guarantee, every caller-uncontrolled page string ({@link pageFields}) is
+ * sliced to a byte cap so a giant URL alone can't exceed the bound. Never
+ * throws: on any failure the original event is returned unchanged.
+ *
+ * Generic over the event shape so one bound serves both channels and the returned
+ * event keeps its type. The rungs are per-field, and a rung whose field the event
+ * does not carry is a no-op: `tool_registration` reaches only the `tools` one, and
+ * `tool_call` reaches none of them — every string it carries is capped where it is
+ * read, and its `response` is metrics rather than the result itself.
+ */
+export declare function boundEventPayload<T extends Record<string, unknown>>(event: T): T;
+/**
+ * The two independent tracking outputs. Injectable so orchestration can be
+ * tested without touching the network or the OTEL packages (spec.ts pattern).
+ */
+export interface TrackingSinks {
+    sendToCollect: (event: TrackingEvent, config: CollectConfig) => void;
+    emitOtelLog: (event: TrackingEvent) => void;
+}
+/**
+ * Emit a tracking event. Silent by default: a no-op when `disabled`, and when
+ * neither `apiKey` nor `otel` is configured it builds nothing at all — no
+ * identity resolution, no storage access, no output. Otherwise it resolves
+ * identity, builds the payload, bounds it to the 64 KB schema limit, and fans
+ * it out to each enabled output (backend transport and/or OTEL), both of which
+ * are themselves best-effort. Wrapped end-to-end in try/catch so tracking can
+ * never break the caller (tool execution owns correctness, not telemetry).
+ */
+export declare function track(options: TrackingOptions, eventName: string, data?: Record<string, unknown>, sinks?: TrackingSinks): void;

package/dist/transport.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Backend transport for tracking events (schema §1). Off unless an `apiKey` is
+ * configured; then `sendToCollect` POSTs each bounded event to the collect
+ * endpoint, fire-and-forget, one request per event — no batching or retries in
+ * 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.
+ *
+ * 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.
+ *
+ * The second, independent output is OTEL (`emitOtelLog`): each event becomes a
+ * LogRecord on the global `LoggerProvider` via the optional peer dep
+ * `@opentelemetry/api-logs`. The host app owns exporters and processing; a
+ * missing package or unregistered provider is a permanent silent no-op.
+ */
+import type { TrackingEvent } from "./tracking.js";
+/** Default ingest endpoint; the base host is baked per flavor (see {@link INGEST_BASE}). */
+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
+ * attribution. Same per-flavor base host (see {@link INGEST_BASE}).
+ */
+export declare const DEFAULT_TELEMETRY_ENDPOINT: string;
+/** Backend transport config; `apiKey` presence is what enables this output. */
+export interface CollectConfig {
+    apiKey: string;
+    /** Override the ingest endpoint; defaults to {@link DEFAULT_COLLECT_ENDPOINT}. */
+    endpoint?: string;
+}
+/**
+ * POST a tracking event to the collect endpoint via `fetch(keepalive)`, sending
+ * the key as the `x-api-key` header. Never throws: any failure is swallowed and
+ * a no-`fetch` environment is a silent no-op.
+ */
+export declare function sendToCollect(event: TrackingEvent, config: CollectConfig, scope?: object): void;
+/**
+ * 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*
+ * 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
+ * no-`fetch` environment is a silent no-op.
+ *
+ * `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.
+ *
+ * The event stays a bare `object` here so this module never has to import the
+ * assembled shape from `telemetry.ts` (which imports this function).
+ */
+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 {
+    emit(record: {
+        severityNumber?: number;
+        body?: unknown;
+        attributes?: Record<string, unknown>;
+    }): void;
+}
+/** The `logs` singleton slice we use from `@opentelemetry/api-logs`. */
+interface LogsApiLike {
+    getLogger(name: string): LoggerLike;
+}
+/** Resolves the logs API, or a nullish value when OTEL is unavailable. */
+type OtelLoader = () => LogsApiLike | null | undefined | Promise<LogsApiLike | null | undefined>;
+/**
+ * Emit a bounded tracking event as an OTEL LogRecord through the global
+ * `LoggerProvider`. Off unless `otel` is configured. Fire-and-forget: the
+ * returned promise always resolves (never rejects) so callers can ignore it.
+ * No provider registered / package absent → silent no-op; `emit` throwing is
+ * swallowed. The host app owns all downstream exporting.
+ */
+export declare function emitOtelLog(event: TrackingEvent, loadLogs?: OtelLoader): Promise<void>;
+export {};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@nekuda/webmcp-sdk",
+  "version": "0.4.0-dev.7.3",
+  "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",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "build": "bun build src/index.ts --outdir dist --target browser --format esm --external @opentelemetry/api-logs",
+    "build:types": "tsc -p tsconfig.build.json"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "1.9.4",
+    "@opentelemetry/api-logs": "^0.205.0",
+    "@types/bun": "^1.3.14",
+    "typescript": "^7.0.2"
+  },
+  "peerDependencies": {
+    "@opentelemetry/api-logs": ">=0.50.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentelemetry/api-logs": {
+      "optional": true
+    }
+  },
+  "trustedDependencies": [
+    "@biomejs/biome"
+  ]
+}