@siteverb/webmcp 0.1.0-rc.0

package/dist/src/telemetry.js

@@ -0,0 +1,218 @@
+import { createFetchTelemetryTransport } from './transport.js';
+import { SITEVERB_WEBMCP_VERSION } from './version.js';
+function randomId() {
+    if (typeof globalThis.crypto?.randomUUID === 'function')
+        return globalThis.crypto.randomUUID();
+    const bytes = new Uint8Array(16);
+    globalThis.crypto?.getRandomValues?.(bytes);
+    return Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+function resolveSessionId(siteId) {
+    const key = `__siteverb_session:${siteId}`;
+    try {
+        const existing = globalThis.sessionStorage?.getItem(key);
+        if (existing)
+            return existing;
+        const created = randomId();
+        globalThis.sessionStorage?.setItem(key, created);
+        return created;
+    }
+    catch {
+        return randomId();
+    }
+}
+function resolveRouteTemplate(route) {
+    try {
+        return typeof route === 'function' ? route() : route;
+    }
+    catch {
+        return undefined;
+    }
+}
+function positiveInteger(value, fallback, name) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new TypeError(`${name} must be a positive integer.`);
+    }
+    return value;
+}
+function report(options, diagnostic) {
+    try {
+        options.onDiagnostic?.(diagnostic);
+    }
+    catch {
+        // Diagnostics must never alter application behavior.
+    }
+}
+function disabledManager() {
+    return Object.freeze({
+        enabled: false,
+        emit: () => undefined,
+        flush: async () => undefined,
+        nextSequence: () => 0,
+        status: () => ({ droppedEvents: 0, enabled: false, pendingEvents: 0 }),
+        dispose: () => undefined,
+    });
+}
+export function createTelemetryManager(options, webmcpSupported) {
+    if (!options.telemetry)
+        return disabledManager();
+    const siteId = options.siteId;
+    if (!siteId)
+        throw new TypeError('siteId is required when telemetry is enabled.');
+    const telemetry = options.telemetry;
+    const transport = telemetry.transport ??
+        (telemetry.endpoint
+            ? createFetchTelemetryTransport({ endpoint: telemetry.endpoint })
+            : (() => {
+                throw new TypeError('telemetry requires either a transport or endpoint.');
+            })());
+    const flushIntervalMs = positiveInteger(telemetry.flushIntervalMs, 5_000, 'telemetry.flushIntervalMs');
+    const maxBatchSize = positiveInteger(telemetry.maxBatchSize, 20, 'telemetry.maxBatchSize');
+    const maxQueueSize = positiveInteger(telemetry.maxQueueSize, 1_000, 'telemetry.maxQueueSize');
+    if (maxBatchSize > maxQueueSize) {
+        throw new TypeError('telemetry.maxBatchSize cannot exceed telemetry.maxQueueSize.');
+    }
+    const pageSessionId = resolveSessionId(siteId);
+    let queue = [];
+    let pendingBatch;
+    let inFlight;
+    let timer;
+    let disposed = false;
+    let droppedEvents = 0;
+    let eventIndex = 0;
+    let sequenceIndex = 0;
+    const schedule = () => {
+        if (disposed || timer || (queue.length === 0 && !pendingBatch))
+            return;
+        timer = setTimeout(() => {
+            timer = undefined;
+            void flush('interval');
+        }, flushIntervalMs);
+    };
+    const emit = (event, fields = {}) => {
+        if (disposed)
+            return;
+        if (queue.length + (pendingBatch?.events.length ?? 0) >= maxQueueSize) {
+            droppedEvents += 1;
+            report(options, {
+                code: 'telemetry-dropped',
+                message: 'A Siteverb telemetry event was dropped because the bounded queue is full.',
+                severity: 'warning',
+            });
+            return;
+        }
+        const routeTemplate = resolveRouteTemplate(options.routeTemplate);
+        queue.push(Object.freeze({
+            dataClass: 'production',
+            event,
+            eventId: randomId(),
+            eventIndex: eventIndex++,
+            occurredAt: new Date().toISOString(),
+            pageSessionId,
+            ...(options.environment === undefined ? {} : { environment: options.environment }),
+            ...(options.release === undefined ? {} : { release: options.release }),
+            ...(routeTemplate === undefined ? {} : { routeTemplate }),
+            ...fields,
+        }));
+        if (queue.length >= maxBatchSize)
+            void flush('size');
+        else
+            schedule();
+    };
+    const flush = async (reason = 'manual') => {
+        if (timer) {
+            clearTimeout(timer);
+            timer = undefined;
+        }
+        if (inFlight) {
+            await inFlight;
+            if (queue.length > 0)
+                return flush(reason);
+            return;
+        }
+        if (!pendingBatch && queue.length === 0)
+            return;
+        const batch = pendingBatch ??
+            Object.freeze({
+                batchId: randomId(),
+                events: Object.freeze(queue.splice(0, maxBatchSize)),
+                protocolVersion: 1,
+                sdkVersion: SITEVERB_WEBMCP_VERSION,
+                sentAt: new Date().toISOString(),
+                siteId,
+            });
+        pendingBatch = batch;
+        inFlight = Promise.resolve()
+            .then(() => transport.send(batch, reason))
+            .then(() => {
+            if (pendingBatch?.batchId === batch.batchId)
+                pendingBatch = undefined;
+        })
+            .catch((cause) => {
+            report(options, {
+                cause,
+                code: 'telemetry-send-failed',
+                message: 'Siteverb could not deliver a telemetry batch; the same batch will be retried.',
+                severity: 'warning',
+            });
+            throw cause;
+        })
+            .finally(() => {
+            inFlight = undefined;
+            schedule();
+        });
+        return inFlight;
+    };
+    const lifecycleFlush = () => {
+        void flush('lifecycle').catch(() => undefined);
+    };
+    const visibilityFlush = () => {
+        if (typeof document !== 'undefined' && document.visibilityState === 'hidden')
+            lifecycleFlush();
+    };
+    globalThis.addEventListener?.('pagehide', lifecycleFlush);
+    globalThis.document?.addEventListener?.('visibilitychange', visibilityFlush);
+    const manager = {
+        enabled: true,
+        emit,
+        flush,
+        nextSequence: () => sequenceIndex++,
+        status: () => ({
+            droppedEvents,
+            enabled: true,
+            pendingEvents: queue.length + (pendingBatch?.events.length ?? 0),
+        }),
+        dispose: () => {
+            if (disposed)
+                return;
+            disposed = true;
+            if (timer)
+                clearTimeout(timer);
+            timer = undefined;
+            globalThis.removeEventListener?.('pagehide', lifecycleFlush);
+            globalThis.document?.removeEventListener?.('visibilitychange', visibilityFlush);
+            lifecycleFlush();
+        },
+    };
+    emit('surface_loaded', { webmcpSupported });
+    return Object.freeze(manager);
+}
+export function classifyTelemetryError(error, signal) {
+    if (signal.aborted || (error instanceof DOMException && error.name === 'AbortError'))
+        return 'abort';
+    const name = error instanceof Error ? error.name.toLowerCase() : '';
+    if (name.includes('timeout'))
+        return 'timeout';
+    if (name.includes('network'))
+        return 'network';
+    if (name.includes('notfound') || name.includes('not_found'))
+        return 'not-found';
+    if (name.includes('permission') || name.includes('notallowed'))
+        return 'permission';
+    if (name.includes('validation') || error instanceof TypeError)
+        return 'validation';
+    return 'unknown';
+}
+//# sourceMappingURL=telemetry.js.map

package/dist/src/telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.js","sourceRoot":"","sources":["../../src/telemetry.ts"],"names":[],"mappings":"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"}

package/dist/src/testing/index.d.ts

@@ -0,0 +1,3 @@
+export { createMemoryModelContext, createMemoryTelemetryTransport, } from './memory.js';
+export type { MemoryModelContext, MemoryTelemetryTransport } from './memory.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/testing/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,8BAA8B,GAC/B,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC"}

package/dist/src/testing/index.js

@@ -0,0 +1,2 @@
+export { createMemoryModelContext, createMemoryTelemetryTransport, } from './memory.js';
+//# sourceMappingURL=index.js.map

package/dist/src/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/testing/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,8BAA8B,GAC/B,MAAM,aAAa,CAAC"}

package/dist/src/testing/memory.d.ts

@@ -0,0 +1,17 @@
+import type { NativeModelContext, NativeModelContextTool, NativeRegisteredTool, TelemetryBatch, TelemetryFlushReason, TelemetryTransport } from '../types.js';
+export interface MemoryModelContext extends NativeModelContext {
+    readonly registrations: ReadonlyMap<string, NativeModelContextTool>;
+    addUninstrumentedTool(tool: NativeRegisteredTool): void;
+    executeTool(name: string, input?: Record<string, unknown>, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<unknown>;
+}
+export declare function createMemoryModelContext(): MemoryModelContext;
+export interface MemoryTelemetryTransport extends TelemetryTransport {
+    readonly batches: readonly TelemetryBatch[];
+    readonly reasons: readonly TelemetryFlushReason[];
+    failWith(error: unknown): void;
+    recover(): void;
+}
+export declare function createMemoryTelemetryTransport(): MemoryTelemetryTransport;
+//# sourceMappingURL=memory.d.ts.map

package/dist/src/testing/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../../src/testing/memory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,sBAAsB,EAEtB,oBAAoB,EACpB,cAAc,EACd,oBAAoB,EACpB,kBAAkB,EACnB,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,kBAAmB,SAAQ,kBAAkB;IAC5D,QAAQ,CAAC,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;IACpE,qBAAqB,CAAC,IAAI,EAAE,oBAAoB,GAAG,IAAI,CAAC;IACxD,WAAW,CACT,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAC1C,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB;AAED,wBAAgB,wBAAwB,IAAI,kBAAkB,CAoD7D;AAED,MAAM,WAAW,wBAAyB,SAAQ,kBAAkB;IAClE,QAAQ,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;IAC5C,QAAQ,CAAC,OAAO,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAClD,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAC/B,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,wBAAgB,8BAA8B,IAAI,wBAAwB,CAoBzE"}

package/dist/src/testing/memory.js

@@ -0,0 +1,72 @@
+export function createMemoryModelContext() {
+    const registrations = new Map();
+    const uninstrumented = new Map();
+    return {
+        registrations,
+        async registerTool(tool, options) {
+            if (registrations.has(tool.name) || uninstrumented.has(tool.name)) {
+                throw new DOMException(`Tool "${tool.name}" is already registered.`, 'InvalidStateError');
+            }
+            if (options?.signal?.aborted)
+                throw options.signal.reason;
+            registrations.set(tool.name, tool);
+            options?.signal?.addEventListener('abort', () => registrations.delete(tool.name), {
+                once: true,
+            });
+        },
+        async getTools() {
+            return [
+                ...Array.from(registrations.values(), (tool) => ({
+                    name: tool.name,
+                    title: tool.title ?? '',
+                    description: tool.description,
+                    ...(tool.inputSchema === undefined ? {} : { inputSchema: tool.inputSchema }),
+                    ...(tool.annotations === undefined ? {} : { annotations: tool.annotations }),
+                })),
+                ...uninstrumented.values(),
+            ].sort((left, right) => left.name.localeCompare(right.name));
+        },
+        addUninstrumentedTool(tool) {
+            uninstrumented.set(tool.name, tool);
+        },
+        async executeTool(name, input = {}, options = {}) {
+            const tool = registrations.get(name);
+            if (!tool)
+                throw new DOMException(`Tool "${name}" was not found.`, 'NotFoundError');
+            const controller = new AbortController();
+            const onAbort = () => controller.abort(options.signal?.reason);
+            if (options.signal?.aborted)
+                onAbort();
+            else
+                options.signal?.addEventListener('abort', onAbort, { once: true });
+            try {
+                return await tool.execute(input, { signal: controller.signal });
+            }
+            finally {
+                options.signal?.removeEventListener('abort', onAbort);
+            }
+        },
+    };
+}
+export function createMemoryTelemetryTransport() {
+    const batches = [];
+    const reasons = [];
+    let failure;
+    return {
+        batches,
+        reasons,
+        send(batch, reason) {
+            if (failure !== undefined)
+                throw failure;
+            batches.push(batch);
+            reasons.push(reason);
+        },
+        failWith(error) {
+            failure = error;
+        },
+        recover() {
+            failure = undefined;
+        },
+    };
+}
+//# sourceMappingURL=memory.js.map

package/dist/src/testing/memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.js","sourceRoot":"","sources":["../../../src/testing/memory.ts"],"names":[],"mappings":"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"}

package/dist/src/transport.d.ts

@@ -0,0 +1,8 @@
+import type { TelemetryTransport } from './types.js';
+export interface FetchTelemetryTransportOptions {
+    readonly endpoint: string;
+    readonly fetch?: typeof globalThis.fetch;
+    readonly sendBeacon?: Navigator['sendBeacon'];
+}
+export declare function createFetchTelemetryTransport(options: FetchTelemetryTransportOptions): TelemetryTransport;
+//# sourceMappingURL=transport.d.ts.map

package/dist/src/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/transport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAwC,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAE3F,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IACzC,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,CAAC,YAAY,CAAC,CAAC;CAC/C;AAED,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,8BAA8B,GACtC,kBAAkB,CA+BpB"}

package/dist/src/transport.js

@@ -0,0 +1,29 @@
+export function createFetchTelemetryTransport(options) {
+    if (typeof options.endpoint !== 'string' || options.endpoint.trim() === '') {
+        throw new TypeError('A non-empty telemetry endpoint is required.');
+    }
+    const fetcher = options.fetch ?? globalThis.fetch?.bind(globalThis);
+    const beacon = options.sendBeacon ??
+        (typeof navigator === 'undefined' ? undefined : navigator.sendBeacon?.bind(navigator));
+    return Object.freeze({
+        async send(batch, reason) {
+            const body = JSON.stringify(batch);
+            if (reason === 'lifecycle' &&
+                beacon?.(options.endpoint, new Blob([body], { type: 'application/json' }))) {
+                return;
+            }
+            if (!fetcher)
+                throw new Error('fetch is unavailable for the telemetry transport.');
+            const response = await fetcher(options.endpoint, {
+                body,
+                credentials: 'omit',
+                headers: { 'content-type': 'application/json' },
+                keepalive: true,
+                method: 'POST',
+            });
+            if (!response.ok)
+                throw new Error(`Telemetry endpoint returned HTTP ${response.status}.`);
+        },
+    });
+}
+//# sourceMappingURL=transport.js.map

package/dist/src/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../../src/transport.ts"],"names":[],"mappings":"AAQA,MAAM,UAAU,6BAA6B,CAC3C,OAAuC;IAEvC,IAAI,OAAO,OAAO,CAAC,QAAQ,KAAK,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QAC3E,MAAM,IAAI,SAAS,CAAC,6CAA6C,CAAC,CAAC;IACrE,CAAC;IAED,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;IACpE,MAAM,MAAM,GACV,OAAO,CAAC,UAAU;QAClB,CAAC,OAAO,SAAS,KAAK,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;IAEzF,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,KAAK,CAAC,IAAI,CAAC,KAAqB,EAAE,MAA4B;YAC5D,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;YACnC,IACE,MAAM,KAAK,WAAW;gBACtB,MAAM,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,IAAI,IAAI,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,kBAAkB,EAAE,CAAC,CAAC,EAC1E,CAAC;gBACD,OAAO;YACT,CAAC;YACD,IAAI,CAAC,OAAO;gBAAE,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;YAEnF,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,QAAQ,EAAE;gBAC/C,IAAI;gBACJ,WAAW,EAAE,MAAM;gBACnB,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;gBAC/C,SAAS,EAAE,IAAI;gBACf,MAAM,EAAE,MAAM;aACf,CAAC,CAAC;YACH,IAAI,CAAC,QAAQ,CAAC,EAAE;gBAAE,MAAM,IAAI,KAAK,CAAC,oCAAoC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;QAC5F,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}

package/dist/src/types.d.ts

@@ -0,0 +1,185 @@
+export type JsonPrimitive = boolean | null | number | string;
+export type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type JsonSchema = Readonly<Record<string, unknown>>;
+export interface WebMcpToolAnnotations {
+    readonly readOnlyHint?: boolean;
+    readonly untrustedContentHint?: boolean;
+}
+export interface NativeToolExecutionOptions {
+    readonly signal: AbortSignal;
+}
+export interface NativeModelContextTool {
+    readonly name: string;
+    readonly title?: string;
+    readonly description: string;
+    readonly inputSchema?: object;
+    readonly annotations?: WebMcpToolAnnotations;
+    readonly execute: (input: Record<string, unknown>, options: NativeToolExecutionOptions) => unknown | PromiseLike<unknown>;
+}
+export interface NativeRegisteredTool {
+    readonly name: string;
+    readonly title?: string;
+    readonly description: string;
+    readonly inputSchema?: object;
+    readonly annotations?: WebMcpToolAnnotations;
+    readonly origin?: string;
+    readonly window?: Window;
+}
+export interface NativeRegisterToolOptions {
+    readonly exposedTo?: string[];
+    readonly signal?: AbortSignal;
+}
+export interface NativeModelContext {
+    registerTool(tool: NativeModelContextTool, options?: NativeRegisterToolOptions): Promise<void>;
+    getTools?(): Promise<readonly NativeRegisteredTool[]>;
+}
+export interface SiteverbToolExecutionContext extends NativeToolExecutionOptions {
+    readonly invocationId: string;
+}
+export interface SiteverbToolDefinition<TInput extends object = Record<string, unknown>, TResult = unknown> {
+    readonly id: string;
+    readonly name: string;
+    readonly title?: string;
+    readonly description: string;
+    readonly inputSchema?: JsonSchema;
+    readonly annotations?: WebMcpToolAnnotations;
+    readonly execute: (input: TInput, context: SiteverbToolExecutionContext) => TResult | PromiseLike<TResult>;
+}
+declare const definedToolBrand: unique symbol;
+export type DefinedSiteverbTool<TInput extends object = Record<string, unknown>, TResult = unknown> = Readonly<SiteverbToolDefinition<TInput, TResult>> & {
+    readonly [definedToolBrand]: true;
+};
+export type AnySiteverbTool = SiteverbToolDefinition<any, any> | DefinedSiteverbTool<any, any>;
+export type ToolDiagnosticCode = 'description-budget' | 'invalid-annotations' | 'invalid-description' | 'invalid-execute' | 'invalid-input-schema' | 'invalid-stable-id' | 'invalid-title' | 'invalid-tool-name' | 'parameter-description-budget' | 'tool-name-budget';
+export interface ToolDiagnostic {
+    readonly code: ToolDiagnosticCode;
+    readonly message: string;
+    readonly path: string;
+    readonly severity: 'error' | 'warning';
+}
+export interface RegisterToolOptions {
+    readonly exposedTo?: readonly string[];
+    readonly signal?: AbortSignal;
+}
+export type RegistrationStatus = 'pending' | 'registered' | 'unsupported' | 'unregistered' | 'failed';
+export interface RegistrationResult {
+    readonly id: string;
+    readonly name: string;
+    readonly status: Extract<RegistrationStatus, 'registered' | 'unsupported'>;
+}
+export interface RegistrationHandle {
+    readonly id: string;
+    readonly name: string;
+    readonly ready: Promise<RegistrationResult>;
+    readonly signal: AbortSignal;
+    readonly status: RegistrationStatus;
+    unregister(reason?: unknown): void;
+}
+export interface RegisterToolsOptions extends RegisterToolOptions {
+    readonly atomic?: boolean;
+}
+export interface BatchRegistrationHandle {
+    readonly handles: readonly RegistrationHandle[];
+    readonly ready: Promise<readonly RegistrationResult[]>;
+    readonly signal: AbortSignal;
+    unregister(reason?: unknown): void;
+}
+export interface SiteverbOptions {
+    readonly environment?: string;
+    readonly modelContext?: NativeModelContext | (() => NativeModelContext | undefined);
+    readonly onDiagnostic?: (diagnostic: SiteverbDiagnostic) => void;
+    readonly release?: string;
+    readonly routeTemplate?: string | (() => string | undefined);
+    readonly siteId?: string;
+    readonly telemetry?: false | TelemetryOptions;
+}
+export interface RegisteredToolSnapshot {
+    readonly id: string;
+    readonly name: string;
+    readonly status: RegistrationStatus;
+}
+export interface RuntimeSnapshot {
+    readonly environment?: string;
+    readonly release?: string;
+    readonly siteId?: string;
+    readonly supported: boolean;
+    readonly telemetry: TelemetryStatus;
+    readonly tools: readonly RegisteredToolSnapshot[];
+}
+export interface CoverageSnapshot {
+    readonly completeness: number | null;
+    readonly discovered: readonly string[];
+    readonly instrumented: readonly string[];
+    readonly inventoryOnly: readonly string[];
+    readonly missing: readonly string[];
+    readonly status: 'available' | 'unavailable';
+}
+export interface SiteverbClient {
+    readonly supported: boolean;
+    readonly telemetry: TelemetryStatus;
+    registerTool<TInput extends object, TResult>(tool: SiteverbToolDefinition<TInput, TResult> | DefinedSiteverbTool<TInput, TResult>, options?: RegisterToolOptions): RegistrationHandle;
+    registerTools(tools: readonly AnySiteverbTool[], options?: RegisterToolsOptions): BatchRegistrationHandle;
+    coverage(): Promise<CoverageSnapshot>;
+    dispose(reason?: unknown): void;
+    flush(): Promise<void>;
+    snapshot(): RuntimeSnapshot;
+}
+export type SiteverbDiagnosticCode = 'coverage-unavailable' | 'telemetry-dropped' | 'telemetry-send-failed';
+export interface SiteverbDiagnostic {
+    readonly cause?: unknown;
+    readonly code: SiteverbDiagnosticCode;
+    readonly message: string;
+    readonly severity: 'warning';
+}
+export type TelemetryEventName = 'surface_loaded' | 'tool_registered' | 'tool_unregistered' | 'tool_registration_failed' | 'tool_call_started' | 'tool_call_completed' | 'tool_call_failed' | 'tool_call_cancelled';
+export type TelemetryErrorClass = 'abort' | 'network' | 'not-found' | 'permission' | 'timeout' | 'validation' | 'unknown';
+export interface TelemetryToolIdentity {
+    readonly schemaHash: string;
+    readonly stableKey: string;
+    readonly wireName: string;
+}
+export interface SiteverbTelemetryEvent {
+    readonly dataClass: 'production';
+    readonly durationMs?: number;
+    readonly environment?: string;
+    readonly errorClass?: TelemetryErrorClass;
+    readonly event: TelemetryEventName;
+    readonly eventId: string;
+    readonly eventIndex: number;
+    readonly invocationId?: string;
+    readonly occurredAt: string;
+    readonly pageSessionId: string;
+    readonly release?: string;
+    readonly routeTemplate?: string;
+    readonly sequenceIndex?: number;
+    readonly tool?: TelemetryToolIdentity;
+    readonly webmcpSupported?: boolean;
+}
+export interface TelemetryBatch {
+    readonly batchId: string;
+    readonly events: readonly SiteverbTelemetryEvent[];
+    readonly protocolVersion: 1;
+    readonly sdkVersion: string;
+    readonly sentAt: string;
+    readonly siteId: string;
+}
+export type TelemetryFlushReason = 'interval' | 'lifecycle' | 'manual' | 'size';
+export interface TelemetryTransport {
+    send(batch: TelemetryBatch, reason: TelemetryFlushReason): Promise<void> | void;
+}
+export interface TelemetryOptions {
+    readonly endpoint?: string;
+    readonly flushIntervalMs?: number;
+    readonly maxBatchSize?: number;
+    readonly maxQueueSize?: number;
+    readonly transport?: TelemetryTransport;
+}
+export interface TelemetryStatus {
+    readonly droppedEvents: number;
+    readonly enabled: boolean;
+    readonly pendingEvents: number;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/src/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}

package/dist/src/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":""}

package/dist/src/validation.d.ts

@@ -0,0 +1,5 @@
+import type { DefinedSiteverbTool, SiteverbToolDefinition, ToolDiagnostic } from './types.js';
+export declare function inspectToolDefinition(definition: SiteverbToolDefinition): readonly ToolDiagnostic[];
+export declare function defineTool<TInput extends object, TResult>(definition: SiteverbToolDefinition<TInput, TResult>): DefinedSiteverbTool<TInput, TResult>;
+export declare function isDefinedTool(value: unknown): value is DefinedSiteverbTool;
+//# sourceMappingURL=validation.d.ts.map

package/dist/src/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,mBAAmB,EAEnB,sBAAsB,EACtB,cAAc,EAEf,MAAM,YAAY,CAAC;AAoFpB,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,sBAAsB,GAAG,SAAS,cAAc,EAAE,CAuGnG;AAED,wBAAgB,UAAU,CAAC,MAAM,SAAS,MAAM,EAAE,OAAO,EACvD,UAAU,EAAE,sBAAsB,CAAC,MAAM,EAAE,OAAO,CAAC,GAClD,mBAAmB,CAAC,MAAM,EAAE,OAAO,CAAC,CAuBtC;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,mBAAmB,CAM1E"}