@useragent-kit/sdk 0.0.0 → 0.0.1

package/README.md

@@ -1,5 +1,63 @@
-# @useragent-kit/sdk
+# `@polkadot-apps/host-sdk`
 
-This package is a name reservation for the upcoming UserAgentKit release.
+UserAgentKit's TypeScript SDK for building browser **Triangle User Agents**.
 
-For the current release, install [`@polkadot-apps/host-sdk`](https://www.npmjs.com/package/@polkadot-apps/host-sdk).
+Use this package when you are building the trusted browser shell that owns:
+
+- wallet state
+- `ProductView` mounting
+- chain/runtime wiring
+- `window.host.__bridge` policy and capabilities
+
+If you are building the product that runs inside that shell, use `@polkadot-apps/product-sdk` instead.
+
+## Install
+
+```sh
+npm install @polkadot-apps/host-sdk @polkadot-apps/host-wasm
+```
+
+Add these only if your integration needs them:
+
+- `@polkadot-apps/host-coinage-wasm` for Coinage vault/path/value helpers
+- `@polkadot-apps/host-extensions-wasm`
+- `smoldot`
+
+## Minimal example
+
+```ts
+import { createHostSdk } from "@polkadot-apps/host-sdk";
+
+const sdk = await createHostSdk();
+sdk.wallet.loadMnemonic(
+  "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about",
+);
+
+console.log("wallet state", sdk.wallet.state());
+console.log("root address", sdk.wallet.rootAddress());
+```
+
+## Main entry points
+
+- `createHostSdk()` for wallet, runtime, and WASM setup
+- `mountProductView()` for sandboxed product embedding
+- `HostRuntime` / `HostRuntimeRegistry` for shared runtime ownership
+- `mountHostRuntimeFrame()` for runtime-in-a-frame web hosts
+
+## Compatibility
+
+- Node.js 18+
+- ESM package
+- peer dependency on `@polkadot-apps/host-wasm`
+- optional peer dependencies on `@polkadot-apps/host-extensions-wasm` and `smoldot`
+- separate optional package `@polkadot-apps/host-coinage-wasm` for Coinage helpers
+
+## Documentation
+
+- Quickstart: <https://github.com/paritytech/host-sdk/blob/main/site/src/content/docs/getting-started/index.md>
+- Web integration: <https://github.com/paritytech/host-sdk/blob/main/site/src/content/docs/getting-started/web.md>
+- Browser host guide: <https://github.com/paritytech/host-sdk/blob/main/site/src/content/docs/getting-started/web-host.md>
+
+## Experimental surface
+
+This package also includes an `experimental` subpath for APIs that are still settling. Treat those exports as unstable and pin versions tightly if you adopt them.

package/dist/adapters.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Built-in analytics adapter implementations.
+ *
+ * Each adapter translates Segment-shaped events into a specific backend's
+ * HTTP API format. All adapters are stateless — they send events immediately
+ * via `fetch()`. For batching, wrap with a buffering layer or use the
+ * backend's own batching SDK.
+ *
+ * @example
+ * ```ts
+ * import { createAnalyticsRouter, createPostHogAdapter } from "@polkadot-apps/host-sdk";
+ *
+ * const router = createAnalyticsRouter();
+ * router.register("com.example.app", createPostHogAdapter({
+ *   apiKey: "phc_abc123",
+ *   host: "https://us.i.posthog.com",
+ * }));
+ * ```
+ */
+import type { AnalyticsAdapter } from "./telemetry.js";
+/** Configuration for the PostHog adapter. */
+export interface PostHogAdapterOptions {
+    /** PostHog project API key (e.g. "phc_abc123..."). */
+    apiKey: string;
+    /**
+     * PostHog instance host. Default: "https://us.i.posthog.com".
+     * Use "https://eu.i.posthog.com" for EU cloud, or your self-hosted URL.
+     */
+    host?: string;
+    /**
+     * Called when a request to PostHog fails.
+     * Default: silent (errors are swallowed).
+     */
+    onError?: (error: unknown) => void;
+}
+/**
+ * Create a PostHog analytics adapter.
+ *
+ * Maps Segment-shaped events to PostHog's `/capture` and `/engage` APIs.
+ *
+ * @see https://posthog.com/docs/api/capture
+ */
+export declare function createPostHogAdapter(options: PostHogAdapterOptions): AnalyticsAdapter;
+/** Configuration for the generic webhook adapter. */
+export interface WebhookAdapterOptions {
+    /** HTTPS endpoint that accepts POST requests with JSON body. */
+    endpoint: string;
+    /**
+     * Optional headers to include in every request.
+     * Use for API keys, auth tokens, etc.
+     *
+     * @example
+     * ```ts
+     * { "Authorization": "Bearer token123" }
+     * ```
+     */
+    headers?: Record<string, string>;
+    /**
+     * Called when a request to the webhook fails.
+     * Default: silent (errors are swallowed).
+     */
+    onError?: (error: unknown) => void;
+}
+/**
+ * Create a generic webhook adapter.
+ *
+ * Sends Segment-shaped events as-is (JSON POST) to any HTTPS endpoint.
+ * Compatible with RudderStack, Jitsu, Segment HTTP API, or any custom
+ * backend that accepts Segment-format payloads.
+ *
+ * @example
+ * ```ts
+ * const adapter = createWebhookAdapter({
+ *   endpoint: "https://my-api.example.com/v1/events",
+ *   headers: { "Authorization": "Bearer secret" },
+ * });
+ * ```
+ */
+export declare function createWebhookAdapter(options: WebhookAdapterOptions): AnalyticsAdapter;
+/**
+ * Create a console adapter for development/debugging.
+ *
+ * Logs all analytics events to `console.debug` with a `[telemetry]` prefix.
+ * Useful for verifying that products emit the expected events without
+ * configuring a backend.
+ *
+ * @example
+ * ```ts
+ * const router = createAnalyticsRouter();
+ * router.register("my-product", createConsoleAdapter());
+ * ```
+ */
+export declare function createConsoleAdapter(): AnalyticsAdapter;
+//# sourceMappingURL=adapters.d.ts.map

package/dist/adapters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapters.d.ts","sourceRoot":"","sources":["../src/adapters.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAKjB,MAAM,gBAAgB,CAAC;AAMxB,6CAA6C;AAC7C,MAAM,WAAW,qBAAqB;IACpC,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACpC;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,qBAAqB,GAAG,gBAAgB,CA6ErF;AAMD,qDAAqD;AACrD,MAAM,WAAW,qBAAqB;IACpC,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACpC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,qBAAqB,GAAG,gBAAgB,CAqBrF;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,IAAI,gBAAgB,CAuCvD"}

package/dist/adapters.js

@@ -0,0 +1,188 @@
+/**
+ * Built-in analytics adapter implementations.
+ *
+ * Each adapter translates Segment-shaped events into a specific backend's
+ * HTTP API format. All adapters are stateless — they send events immediately
+ * via `fetch()`. For batching, wrap with a buffering layer or use the
+ * backend's own batching SDK.
+ *
+ * @example
+ * ```ts
+ * import { createAnalyticsRouter, createPostHogAdapter } from "@polkadot-apps/host-sdk";
+ *
+ * const router = createAnalyticsRouter();
+ * router.register("com.example.app", createPostHogAdapter({
+ *   apiKey: "phc_abc123",
+ *   host: "https://us.i.posthog.com",
+ * }));
+ * ```
+ */
+/**
+ * Create a PostHog analytics adapter.
+ *
+ * Maps Segment-shaped events to PostHog's `/capture` and `/engage` APIs.
+ *
+ * @see https://posthog.com/docs/api/capture
+ */
+export function createPostHogAdapter(options) {
+    const host = (options.host ?? "https://us.i.posthog.com").replace(/\/$/, "");
+    const apiKey = options.apiKey;
+    function send(endpoint, body) {
+        fetch(`${host}${endpoint}`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ api_key: apiKey, ...body }),
+        }).catch((err) => options.onError?.(err));
+    }
+    return {
+        track(event) {
+            send("/capture/", {
+                event: event.event,
+                properties: {
+                    ...event.properties,
+                    $lib: "host-sdk",
+                    product_id: event.context.app.productId,
+                },
+                timestamp: event.timestamp,
+                distinct_id: event.context.app.productId,
+            });
+        },
+        identify(event) {
+            send("/capture/", {
+                event: "$identify",
+                properties: {
+                    $set: event.traits,
+                    distinct_id: event.userId,
+                    $lib: "host-sdk",
+                    product_id: event.context.app.productId,
+                },
+                distinct_id: event.userId,
+                timestamp: event.timestamp,
+            });
+        },
+        page(event) {
+            send("/capture/", {
+                event: "$pageview",
+                properties: {
+                    ...event.properties,
+                    $current_url: event.name,
+                    $lib: "host-sdk",
+                    product_id: event.context.app.productId,
+                },
+                timestamp: event.timestamp,
+                distinct_id: event.context.app.productId,
+            });
+        },
+        timing(event) {
+            send("/capture/", {
+                event: "$performance",
+                properties: {
+                    span_name: event.name,
+                    duration_ms: event.durationMs,
+                    start_ms: event.startMs,
+                    span_id: event.spanId,
+                    parent_span_id: event.parentSpanId,
+                    ...event.attributes,
+                    $lib: "host-sdk",
+                    product_id: event.context.app.productId,
+                },
+                timestamp: event.timestamp,
+                distinct_id: event.context.app.productId,
+            });
+        },
+        flush() {
+            // PostHog capture is fire-and-forget; nothing to flush.
+            return Promise.resolve();
+        },
+    };
+}
+/**
+ * Create a generic webhook adapter.
+ *
+ * Sends Segment-shaped events as-is (JSON POST) to any HTTPS endpoint.
+ * Compatible with RudderStack, Jitsu, Segment HTTP API, or any custom
+ * backend that accepts Segment-format payloads.
+ *
+ * @example
+ * ```ts
+ * const adapter = createWebhookAdapter({
+ *   endpoint: "https://my-api.example.com/v1/events",
+ *   headers: { "Authorization": "Bearer secret" },
+ * });
+ * ```
+ */
+export function createWebhookAdapter(options) {
+    const { endpoint, headers = {}, onError } = options;
+    function send(event) {
+        fetch(endpoint, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", ...headers },
+            body: JSON.stringify(event),
+        }).catch((err) => onError?.(err));
+    }
+    return {
+        track: send,
+        identify: send,
+        page: send,
+        timing: send,
+        flush() {
+            return Promise.resolve();
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Console adapter (development)
+// ---------------------------------------------------------------------------
+/**
+ * Create a console adapter for development/debugging.
+ *
+ * Logs all analytics events to `console.debug` with a `[telemetry]` prefix.
+ * Useful for verifying that products emit the expected events without
+ * configuring a backend.
+ *
+ * @example
+ * ```ts
+ * const router = createAnalyticsRouter();
+ * router.register("my-product", createConsoleAdapter());
+ * ```
+ */
+export function createConsoleAdapter() {
+    function log(label, event) {
+        // eslint-disable-next-line no-console
+        console.debug(`[telemetry] ${label}`, event);
+    }
+    return {
+        track(event) {
+            log("track", {
+                event: event.event,
+                properties: event.properties,
+                productId: event.context.app.productId,
+            });
+        },
+        identify(event) {
+            log("identify", {
+                userId: event.userId,
+                traits: event.traits,
+                productId: event.context.app.productId,
+            });
+        },
+        page(event) {
+            log("page", {
+                name: event.name,
+                properties: event.properties,
+                productId: event.context.app.productId,
+            });
+        },
+        timing(event) {
+            log("timing", {
+                name: event.name,
+                durationMs: event.durationMs,
+                productId: event.context.app.productId,
+            });
+        },
+        flush() {
+            return Promise.resolve();
+        },
+    };
+}
+//# sourceMappingURL=adapters.js.map

package/dist/adapters.js.map

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

package/dist/api-protocol.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Shared host-product protocol surface.
+ *
+ * Re-exported from the internal protocol source so hosts consuming
+ * `host-sdk` can adopt the same external product protocol without
+ * requiring the standalone package at install time.
+ */
+export * from "./internal/api-protocol/index.js";
+//# sourceMappingURL=api-protocol.d.ts.map

package/dist/api-protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-protocol.d.ts","sourceRoot":"","sources":["../src/api-protocol.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,kCAAkC,CAAC"}

package/dist/api-protocol.js

@@ -0,0 +1,9 @@
+/**
+ * Shared host-product protocol surface.
+ *
+ * Re-exported from the internal protocol source so hosts consuming
+ * `host-sdk` can adopt the same external product protocol without
+ * requiring the standalone package at install time.
+ */
+export * from "./internal/api-protocol/index.js";
+//# sourceMappingURL=api-protocol.js.map

package/dist/api-protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-protocol.js","sourceRoot":"","sources":["../src/api-protocol.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,kCAAkC,CAAC"}

package/dist/bridge/contract.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Canonical schema and metadata for the stable `window.host` bridge surface.
+ *
+ * This is the hand-maintained product contract model used by the JS bridge,
+ * guest typings, tests, and docs. Hosts should treat this module as the
+ * single source of truth for the current bridge version, method surface,
+ * canonical event names, and canonical error codes.
+ */
+export declare const BRIDGE_VERSION: "1.0";
+export declare const DEFAULT_BRIDGE_PROFILE: "web-srcdoc";
+/**
+ * Canonical stable surface entries for the current bridge generation.
+ *
+ * These entries define the supported names and namespaces, not unconditional
+ * availability in every host profile. Products should still consult
+ * `window.host.__bridge` before assuming a capability is implemented.
+ */
+export declare const BRIDGE_STABLE_SURFACE: readonly ["__bridge", "getAddress", "storage.get", "storage.set", "storage.remove", "statements.subscribe", "statements.write", "statements.status", "identity.resolveUsername", "on", "off"];
+export declare const BRIDGE_EXPERIMENTAL_SURFACE: readonly ["ext.claw.ask", "ext.claw.status", "ext.data.getPeerId", "ext.data.connect", "ext.data.startListening", "ext.data.close", "ext.data.send", "ext.data.sendBytes", "ext.media.getUserMedia", "ext.media.getDisplayMedia", "ext.media.connect", "ext.media.accept", "ext.media.reject", "ext.media.close", "ext.media.attachTrack", "ext.media.getPeerId", "ext.media.startListening", "ext.media.setTrackEnabled", "ext.media.groupConnect", "ext.media.groupAccept", "ext.media.addTrack", "ext.media.removeTrack", "ext.media.getStats", "ext.files.save", "ext.mesh.transport.publish", "ext.mesh.transport.heartbeat", "ext.mesh.transport.subscribe", "ext.mesh.objects.put", "ext.mesh.objects.get", "ext.mesh.objects.getResult", "ext.mesh.query.request", "ext.mesh.query.scopedRequest", "ext.mesh.query.respond", "ext.mesh.query.scopedRespond", "ext.mesh.status.status", "ext.mesh.private.objects.put", "ext.mesh.private.objects.get", "ext.mesh.private.query.request", "ext.mesh.private.control.publish", "ext.mesh.private.control.subscribe", "ext.mesh.private.receipts.publish", "ext.mesh.private.receipts.subscribe", "ext.vrf.deriveMemberKey", "ext.vrf.sign", "ext.vrf.createProof", "ext.vrf.aliasInContext", "ext.crdt.join", "ext.crdt.applyUpdate", "ext.crdt.getStateVector", "ext.crdt.getFullState", "ext.crdt.setAwareness", "ext.crdt.destroy"];
+export declare const BRIDGE_EVENT_NAMES: readonly ["dataConnected", "dataMessage", "dataBinary", "dataClosed", "dataError", "dataIncomingCall", "mediaTrackReady", "mediaConnected", "mediaRemoteTrack", "mediaClosed", "mediaError", "mediaIncomingCall", "mediaSignalingProgress", "mediaTrackStopped", "statement", "meshTopic", "meshQuery", "meshReply", "meshScopedQuery", "meshScopedReply", "meshPresence", "meshHeartbeat", "meshPrivateControl", "meshPrivateReceipt", "indexEvent", "indexSyncProgress", "indexScanCompleted", "crdtRemoteUpdate", "crdtAwareness", "crdtPeerChange"];
+export declare const BRIDGE_ERROR_CODES: readonly ["ERR_BRIDGE_DESTROYED", "ERR_RATE_LIMIT", "ERR_UNSUPPORTED_CAPABILITY", "ERR_HOST_RUNTIME_UNAVAILABLE", "ERR_BINARY_BRIDGE_UNAVAILABLE", "ERR_INVALID_ARGUMENT", "ERR_TIMEOUT", "ERR_HOST_REJECTED"];
+export type BridgeStableSurfaceEntry = (typeof BRIDGE_STABLE_SURFACE)[number];
+export type BridgeExperimentalSurfaceEntry = (typeof BRIDGE_EXPERIMENTAL_SURFACE)[number];
+export type BridgeEventName = (typeof BRIDGE_EVENT_NAMES)[number];
+export type BridgeErrorCode = (typeof BRIDGE_ERROR_CODES)[number];
+export type BridgeProfile = "web-srcdoc" | "web-relay" | "native-webview";
+export interface BridgeExtensionCapabilities {
+    readonly claw: boolean;
+    readonly crdt: boolean;
+    readonly data: boolean;
+    readonly media: boolean;
+    readonly files: boolean;
+    readonly mesh: boolean;
+    readonly vrf: boolean;
+}
+export interface BridgeCapabilities {
+    readonly storage: boolean;
+    readonly statements: boolean;
+    readonly identity: boolean;
+    readonly ext: BridgeExtensionCapabilities;
+}
+export interface BridgeProductProtocolMetadata {
+    readonly package: "@polkadot/api-protocol";
+    readonly version: "v1";
+    readonly transport: "message-port";
+    readonly wireFormat: "scale-host-api";
+}
+export interface BridgeMetadata {
+    readonly version: string;
+    readonly profile: BridgeProfile;
+    readonly capabilities: BridgeCapabilities;
+    readonly productProtocol: BridgeProductProtocolMetadata;
+}
+export interface BridgeMetadataOptions {
+    /** Host profile implementing the canonical bridge. */
+    profile?: BridgeProfile;
+    /** Optional overrides for stable core capabilities during phased rollouts. */
+    coreCapabilities?: Partial<Pick<BridgeCapabilities, "storage" | "statements">>;
+    /** Optional extension capability flags exposed alongside the core bridge. */
+    extCapabilities?: Partial<BridgeExtensionCapabilities>;
+}
+/**
+ * Create the immutable metadata object exposed at `window.host.__bridge`.
+ */
+export declare function createBridgeMetadata(options: BridgeMetadataOptions | undefined, identitySupported: boolean): BridgeMetadata;
+//# sourceMappingURL=contract.d.ts.map

package/dist/bridge/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../src/bridge/contract.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAmCH,eAAO,MAAM,cAAc,EAAG,KAAc,CAAC;AAC7C,eAAO,MAAM,sBAAsB,EAAG,YAAqB,CAAC;AAE5D;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,+LAYvB,CAAC;AAEZ,eAAO,MAAM,2BAA2B,8zCAqD7B,CAAC;AAEZ,eAAO,MAAM,kBAAkB,yhBA+BpB,CAAC;AAEZ,eAAO,MAAM,kBAAkB,gNASpB,CAAC;AAEZ,MAAM,MAAM,wBAAwB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAC9E,MAAM,MAAM,8BAA8B,GAAG,CAAC,OAAO,2BAA2B,CAAC,CAAC,MAAM,CAAC,CAAC;AAC1F,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAClE,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAElE,MAAM,MAAM,aAAa,GAAG,YAAY,GAAG,WAAW,GAAG,gBAAgB,CAAC;AAE1E,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,GAAG,EAAE,2BAA2B,CAAC;CAC3C;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,OAAO,EAAE,wBAAwB,CAAC;IAC3C,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC;CACvC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,kBAAkB,CAAC;IAC1C,QAAQ,CAAC,eAAe,EAAE,6BAA6B,CAAC;CACzD;AAED,MAAM,WAAW,qBAAqB;IACpC,sDAAsD;IACtD,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,8EAA8E;IAC9E,gBAAgB,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,kBAAkB,EAAE,SAAS,GAAG,YAAY,CAAC,CAAC,CAAC;IAC/E,6EAA6E;IAC7E,eAAe,CAAC,EAAE,OAAO,CAAC,2BAA2B,CAAC,CAAC;CACxD;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,qBAAqB,GAAG,SAAS,EAC1C,iBAAiB,EAAE,OAAO,GACzB,cAAc,CA+BhB"}

package/dist/bridge/contract.js

@@ -0,0 +1,160 @@
+/**
+ * Canonical schema and metadata for the stable `window.host` bridge surface.
+ *
+ * This is the hand-maintained product contract model used by the JS bridge,
+ * guest typings, tests, and docs. Hosts should treat this module as the
+ * single source of truth for the current bridge version, method surface,
+ * canonical event names, and canonical error codes.
+ */
+import { CRDT_AWARENESS, CRDT_PEER_CHANGE, CRDT_REMOTE_UPDATE, DATA_BINARY, DATA_CLOSED, DATA_CONNECTED, DATA_ERROR, DATA_INCOMING_CALL, DATA_MESSAGE, INDEX_EVENT, INDEX_SCAN_COMPLETED, INDEX_SYNC_PROGRESS, MEDIA_CLOSED, MEDIA_CONNECTED, MEDIA_ERROR, MEDIA_INCOMING_CALL, MEDIA_REMOTE_TRACK, MEDIA_SIGNALING_PROGRESS, MEDIA_TRACK_READY, MEDIA_TRACK_STOPPED, MESH_HEARTBEAT, MESH_PRESENCE, MESH_PRIVATE_CONTROL, MESH_PRIVATE_RECEIPT, MESH_QUERY, MESH_REPLY, MESH_SCOPED_QUERY, MESH_SCOPED_REPLY, MESH_TOPIC, STATEMENT, } from "../events.js";
+export const BRIDGE_VERSION = "1.0";
+export const DEFAULT_BRIDGE_PROFILE = "web-srcdoc";
+/**
+ * Canonical stable surface entries for the current bridge generation.
+ *
+ * These entries define the supported names and namespaces, not unconditional
+ * availability in every host profile. Products should still consult
+ * `window.host.__bridge` before assuming a capability is implemented.
+ */
+export const BRIDGE_STABLE_SURFACE = Object.freeze([
+    "__bridge",
+    "getAddress",
+    "storage.get",
+    "storage.set",
+    "storage.remove",
+    "statements.subscribe",
+    "statements.write",
+    "statements.status",
+    "identity.resolveUsername",
+    "on",
+    "off",
+]);
+export const BRIDGE_EXPERIMENTAL_SURFACE = Object.freeze([
+    "ext.claw.ask",
+    "ext.claw.status",
+    "ext.data.getPeerId",
+    "ext.data.connect",
+    "ext.data.startListening",
+    "ext.data.close",
+    "ext.data.send",
+    "ext.data.sendBytes",
+    "ext.media.getUserMedia",
+    "ext.media.getDisplayMedia",
+    "ext.media.connect",
+    "ext.media.accept",
+    "ext.media.reject",
+    "ext.media.close",
+    "ext.media.attachTrack",
+    "ext.media.getPeerId",
+    "ext.media.startListening",
+    "ext.media.setTrackEnabled",
+    "ext.media.groupConnect",
+    "ext.media.groupAccept",
+    "ext.media.addTrack",
+    "ext.media.removeTrack",
+    "ext.media.getStats",
+    "ext.files.save",
+    "ext.mesh.transport.publish",
+    "ext.mesh.transport.heartbeat",
+    "ext.mesh.transport.subscribe",
+    "ext.mesh.objects.put",
+    "ext.mesh.objects.get",
+    "ext.mesh.objects.getResult",
+    "ext.mesh.query.request",
+    "ext.mesh.query.scopedRequest",
+    "ext.mesh.query.respond",
+    "ext.mesh.query.scopedRespond",
+    "ext.mesh.status.status",
+    "ext.mesh.private.objects.put",
+    "ext.mesh.private.objects.get",
+    "ext.mesh.private.query.request",
+    "ext.mesh.private.control.publish",
+    "ext.mesh.private.control.subscribe",
+    "ext.mesh.private.receipts.publish",
+    "ext.mesh.private.receipts.subscribe",
+    "ext.vrf.deriveMemberKey",
+    "ext.vrf.sign",
+    "ext.vrf.createProof",
+    "ext.vrf.aliasInContext",
+    "ext.crdt.join",
+    "ext.crdt.applyUpdate",
+    "ext.crdt.getStateVector",
+    "ext.crdt.getFullState",
+    "ext.crdt.setAwareness",
+    "ext.crdt.destroy",
+]);
+export const BRIDGE_EVENT_NAMES = Object.freeze([
+    DATA_CONNECTED,
+    DATA_MESSAGE,
+    DATA_BINARY,
+    DATA_CLOSED,
+    DATA_ERROR,
+    DATA_INCOMING_CALL,
+    MEDIA_TRACK_READY,
+    MEDIA_CONNECTED,
+    MEDIA_REMOTE_TRACK,
+    MEDIA_CLOSED,
+    MEDIA_ERROR,
+    MEDIA_INCOMING_CALL,
+    MEDIA_SIGNALING_PROGRESS,
+    MEDIA_TRACK_STOPPED,
+    STATEMENT,
+    MESH_TOPIC,
+    MESH_QUERY,
+    MESH_REPLY,
+    MESH_SCOPED_QUERY,
+    MESH_SCOPED_REPLY,
+    MESH_PRESENCE,
+    MESH_HEARTBEAT,
+    MESH_PRIVATE_CONTROL,
+    MESH_PRIVATE_RECEIPT,
+    INDEX_EVENT,
+    INDEX_SYNC_PROGRESS,
+    INDEX_SCAN_COMPLETED,
+    CRDT_REMOTE_UPDATE,
+    CRDT_AWARENESS,
+    CRDT_PEER_CHANGE,
+]);
+export const BRIDGE_ERROR_CODES = Object.freeze([
+    "ERR_BRIDGE_DESTROYED",
+    "ERR_RATE_LIMIT",
+    "ERR_UNSUPPORTED_CAPABILITY",
+    "ERR_HOST_RUNTIME_UNAVAILABLE",
+    "ERR_BINARY_BRIDGE_UNAVAILABLE",
+    "ERR_INVALID_ARGUMENT",
+    "ERR_TIMEOUT",
+    "ERR_HOST_REJECTED",
+]);
+/**
+ * Create the immutable metadata object exposed at `window.host.__bridge`.
+ */
+export function createBridgeMetadata(options, identitySupported) {
+    const ext = Object.freeze({
+        claw: options?.extCapabilities?.claw ?? false,
+        crdt: options?.extCapabilities?.crdt ?? false,
+        data: options?.extCapabilities?.data ?? false,
+        media: options?.extCapabilities?.media ?? false,
+        files: options?.extCapabilities?.files ?? false,
+        mesh: options?.extCapabilities?.mesh ?? false,
+        vrf: options?.extCapabilities?.vrf ?? false,
+    });
+    const capabilities = Object.freeze({
+        storage: options?.coreCapabilities?.storage ?? true,
+        statements: options?.coreCapabilities?.statements ?? true,
+        identity: identitySupported,
+        ext,
+    });
+    const productProtocol = Object.freeze({
+        package: "@polkadot/api-protocol",
+        version: "v1",
+        transport: "message-port",
+        wireFormat: "scale-host-api",
+    });
+    return Object.freeze({
+        version: BRIDGE_VERSION,
+        profile: options?.profile ?? DEFAULT_BRIDGE_PROFILE,
+        capabilities,
+        productProtocol,
+    });
+}
+//# sourceMappingURL=contract.js.map

package/dist/bridge/contract.js.map

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