@useragent-kit/sdk 0.0.0 → 0.0.1

package/dist/chain.d.ts

@@ -0,0 +1,198 @@
+/**
+ * Chain client — smoldot light client integration for the browser.
+ *
+ * Uses the `smoldot` NPM package for the actual light client, with WASM-side
+ * state management via `ChainClientHandle` from `host-wasm`.
+ *
+ * ## Architecture
+ *
+ * ```
+ * TypeScript (this module)              Rust WASM (ChainClientHandle)
+ * ─────────────────────────             ────────────────────────────
+ * SmoldotDriver                         ChainStateMachine
+ *   creates smoldot Client                processes JSON-RPC responses
+ *   adds/removes chains                   tracks chain status
+ *   drives event loops                    generates request payloads
+ *   forwards responses → WASM             persists DB to localStorage
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { start as startSmoldot } from "smoldot";
+ * import { SmoldotDriver } from "@polkadot-apps/host-sdk";
+ *
+ * const smoldotClient = startSmoldot();
+ * const driver = new SmoldotDriver(chainHandle, smoldotClient);
+ *
+ * await driver.connect("PaseoAssetHub");
+ * console.log(driver.status("PaseoAssetHub")); // { state: "Connecting", ... }
+ * ```
+ */
+/** Chain status as returned by the WASM handle. */
+export interface ChainStatus {
+    id: string;
+    name: string;
+    state: "Disconnected" | "Connecting" | "Syncing" | "Live" | "Error";
+    bestBlock: number;
+    finalizedBlock: number | null;
+    peers: number;
+    error?: string;
+}
+/** Supported chain names for smoldot on WASM. */
+export type SmoldotChainName = "PolkadotAssetHub" | "PaseoAssetHub" | "PolkadotPeople" | "PaseoPeople" | "PaseoBulletin";
+/**
+ * Minimal interface for the smoldot NPM package's `Client`.
+ * Matches the `smoldot` package's `Client` type without requiring the package as a dependency.
+ */
+export interface SmoldotClient {
+    addChain(options: {
+        chainSpec: string;
+        potentialRelayChains?: SmoldotChain[];
+        databaseContent?: string;
+    }): Promise<SmoldotChain>;
+    terminate(): Promise<void>;
+}
+/** Minimal interface for a smoldot chain handle. */
+export interface SmoldotChain {
+    sendJsonRpc(rpc: string): void;
+    nextJsonRpcResponse(): Promise<string>;
+    remove(): void;
+}
+/**
+ * JS-side chain store passed to `ChainClientHandle.fromStore()`.
+ * Implement this to provide a custom persistence backend (e.g. IndexedDB).
+ *
+ * Mirrors the `JsChainStore` extern type in `crates/host-wasm/src/chain.rs`.
+ */
+export interface JsChainStore {
+    /**
+     * Load persisted data for the given key.
+     * Return an empty string, null, or undefined if the key is not found.
+     * Returning null or undefined is safe — the Rust adapter treats both as
+     * an empty string to prevent smoldot from reading "null" as corrupt data.
+     */
+    load(key: string): string | null | undefined;
+    /** Persist data for the given key. */
+    save(key: string, data: string): void;
+}
+/** WASM handle interface (matches ChainClientHandle from host-wasm). */
+export interface WasmChainClientHandle {
+    registerChain(chainName: string): void;
+    unregisterChain(chainName: string): void;
+    processResponse(chainName: string, text: string): void;
+    processRelayResponse(chainName: string, text: string): void;
+    setError(chainName: string, msg: string): void;
+    status(chainName: string): ChainStatus;
+    allStatuses(): ChainStatus[];
+    subscribeNewHeadsRequest(): string;
+    subscribeFinalizedHeadsRequest(): string;
+    knownGenesisHash(chainName: string): string | null;
+    healthCheckRequest(chainName: string): string;
+    paraDbSaveRequest(): string;
+    relayDbSaveRequest(): string;
+    chainSpecs(chainName: string): [string, string] | null;
+    loadRelayDb(chainName: string): string;
+    loadParaDb(chainName: string): string;
+    statementSubmitRequest(encodedHex: string, requestId: number): string;
+    statementSubscribeRequest(requestId: number): string;
+    statementUnsubscribeRequest(subId: string, requestId: number): string;
+    statementBroadcastsRequest(topicHexes: string[], requestId: number): string;
+    parseStatementNotification(text: string): string[];
+    free(): void;
+}
+/**
+ * Boot stage event emitted during chain warmup.
+ *
+ * `"ready"` is emitted immediately after `"first-finalized-block"` today.
+ * It exists as a separate stage so that readiness criteria can be tightened
+ * in the future (e.g. require peer count > 0) without breaking consumers
+ * that listen for `"ready"`.
+ */
+export interface BootDiagnosticsEvent {
+    chainName: string;
+    stage: "connect-start" | "relay-added" | "para-added" | "first-best-block" | "first-finalized-block" | "ready";
+    elapsedMs: number;
+}
+/** Callback for boot-stage diagnostics. */
+export type BootDiagnosticsCallback = (event: BootDiagnosticsEvent) => void;
+/** Options for chain readiness waiting. */
+export interface ChainReadinessOptions {
+    /** Milliseconds before waitUntilReady rejects. Default: 120_000. */
+    timeoutMs?: number;
+    /** Poll interval in milliseconds. Default: 500. */
+    pollIntervalMs?: number;
+}
+/** Thrown when waitUntilReady exceeds the timeout. */
+export declare class ChainReadinessTimeoutError extends Error {
+    constructor(chainName: string, timeoutMs: number);
+}
+/**
+ * Drives a smoldot light client in the browser, wired to the WASM state machine.
+ *
+ * Manages the lifecycle of smoldot chains: adding/removing chains, forwarding
+ * responses to WASM for state tracking, and running periodic health checks
+ * and database saves.
+ */
+export declare class SmoldotDriver {
+    private handle;
+    private client;
+    private chains;
+    private responseInterceptors;
+    private relayResponseInterceptors;
+    private diagnosticsCallbacks;
+    constructor(handle: WasmChainClientHandle, client: SmoldotClient);
+    /** Get the WASM chain client handle. */
+    get chainHandle(): WasmChainClientHandle;
+    /**
+     * Get the raw para SmoldotChain handle for a chain.
+     * Used by StatementStoreDriver to send RPC on the same connection.
+     */
+    getParaChain(chainName: string): SmoldotChain | null;
+    /** Get the raw relay SmoldotChain handle for a chain. */
+    getRelayChain(chainName: string): SmoldotChain | null;
+    /**
+     * Register a response interceptor for a chain. The interceptor is called
+     * with each JSON-RPC response text before it reaches the WASM state machine.
+     * Return `true` to consume the message (skip WASM processing), `false` to
+     * let it pass through.
+     */
+    registerResponseInterceptor(chainName: string, handler: (text: string) => boolean): void;
+    /** Unregister a response interceptor. */
+    unregisterResponseInterceptor(chainName: string): void;
+    registerRelayResponseInterceptor(chainName: string, handler: (text: string) => boolean): void;
+    unregisterRelayResponseInterceptor(chainName: string): void;
+    /** Connect a smoldot-backed chain. Starts syncing in the background. */
+    connect(chainName: SmoldotChainName): Promise<void>;
+    /** Disconnect a chain. */
+    disconnect(chainName: string): void;
+    /** Get current status of a chain. */
+    status(chainName: string): ChainStatus;
+    /** Get all chain statuses. */
+    allStatuses(): ChainStatus[];
+    /** Disconnect all chains and terminate the smoldot client. */
+    destroy(): Promise<void>;
+    /**
+     * Persist the current relay/parachain databases for one or all connected chains.
+     *
+     * This is best-effort only: smoldot persists asynchronously after receiving the
+     * JSON-RPC save requests, so callers should treat this as a freshness hint rather
+     * than a durability barrier.
+     */
+    persistState(chainName?: SmoldotChainName): void;
+    /**
+     * Wait until the chain has a finalized head, indicating it is query-ready.
+     * Resolves when status.finalizedBlock is non-null, or rejects after timeoutMs.
+     */
+    waitUntilReady(chainName: SmoldotChainName, options?: ChainReadinessOptions): Promise<void>;
+    /**
+     * Register a diagnostics callback for a chain's boot process.
+     * The callback receives events at each boot stage transition.
+     * Pass null to remove an existing callback.
+     */
+    setBootDiagnostics(chainName: string, callback: BootDiagnosticsCallback | null): void;
+    private runParaResponseLoop;
+    private runRelayResponseLoop;
+    private runMaintenanceLoop;
+    private persistEntryState;
+}
+//# sourceMappingURL=chain.d.ts.map

package/dist/chain.d.ts.map

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

package/dist/chain.js

@@ -0,0 +1,424 @@
+/**
+ * Chain client — smoldot light client integration for the browser.
+ *
+ * Uses the `smoldot` NPM package for the actual light client, with WASM-side
+ * state management via `ChainClientHandle` from `host-wasm`.
+ *
+ * ## Architecture
+ *
+ * ```
+ * TypeScript (this module)              Rust WASM (ChainClientHandle)
+ * ─────────────────────────             ────────────────────────────
+ * SmoldotDriver                         ChainStateMachine
+ *   creates smoldot Client                processes JSON-RPC responses
+ *   adds/removes chains                   tracks chain status
+ *   drives event loops                    generates request payloads
+ *   forwards responses → WASM             persists DB to localStorage
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { start as startSmoldot } from "smoldot";
+ * import { SmoldotDriver } from "@polkadot-apps/host-sdk";
+ *
+ * const smoldotClient = startSmoldot();
+ * const driver = new SmoldotDriver(chainHandle, smoldotClient);
+ *
+ * await driver.connect("PaseoAssetHub");
+ * console.log(driver.status("PaseoAssetHub")); // { state: "Connecting", ... }
+ * ```
+ */
+/** Thrown when waitUntilReady exceeds the timeout. */
+export class ChainReadinessTimeoutError extends Error {
+    constructor(chainName, timeoutMs) {
+        super(`chain ${chainName} did not become ready within ${timeoutMs}ms`);
+        this.name = "ChainReadinessTimeoutError";
+    }
+}
+const BLOCKED_BOOTNODE_HOST_FRAGMENTS = Object.freeze(["radiumblock.com"]);
+/**
+ * Drives a smoldot light client in the browser, wired to the WASM state machine.
+ *
+ * Manages the lifecycle of smoldot chains: adding/removing chains, forwarding
+ * responses to WASM for state tracking, and running periodic health checks
+ * and database saves.
+ */
+export class SmoldotDriver {
+    constructor(handle, client) {
+        this.chains = new Map();
+        this.responseInterceptors = new Map();
+        this.relayResponseInterceptors = new Map();
+        this.diagnosticsCallbacks = new Map();
+        this.handle = handle;
+        this.client = client;
+    }
+    /** Get the WASM chain client handle. */
+    get chainHandle() {
+        return this.handle;
+    }
+    /**
+     * Get the raw para SmoldotChain handle for a chain.
+     * Used by StatementStoreDriver to send RPC on the same connection.
+     */
+    getParaChain(chainName) {
+        return this.chains.get(chainName)?.para ?? null;
+    }
+    /** Get the raw relay SmoldotChain handle for a chain. */
+    getRelayChain(chainName) {
+        return this.chains.get(chainName)?.relay ?? null;
+    }
+    /**
+     * Register a response interceptor for a chain. The interceptor is called
+     * with each JSON-RPC response text before it reaches the WASM state machine.
+     * Return `true` to consume the message (skip WASM processing), `false` to
+     * let it pass through.
+     */
+    registerResponseInterceptor(chainName, handler) {
+        if (this.responseInterceptors.has(chainName)) {
+            throw new Error(`Response interceptor already registered for ${chainName}. Call unregisterResponseInterceptor first.`);
+        }
+        this.responseInterceptors.set(chainName, handler);
+    }
+    /** Unregister a response interceptor. */
+    unregisterResponseInterceptor(chainName) {
+        this.responseInterceptors.delete(chainName);
+    }
+    registerRelayResponseInterceptor(chainName, handler) {
+        if (this.relayResponseInterceptors.has(chainName)) {
+            throw new Error(`Relay response interceptor already registered for ${chainName}. Call unregisterRelayResponseInterceptor first.`);
+        }
+        this.relayResponseInterceptors.set(chainName, handler);
+    }
+    unregisterRelayResponseInterceptor(chainName) {
+        this.relayResponseInterceptors.delete(chainName);
+    }
+    /** Connect a smoldot-backed chain. Starts syncing in the background. */
+    async connect(chainName) {
+        // Disconnect existing connection for this chain.
+        this.disconnect(chainName);
+        const diagnostics = this.diagnosticsCallbacks.get(chainName);
+        const connectStart = Date.now();
+        const specs = this.handle.chainSpecs(chainName);
+        if (!specs) {
+            this.handle.setError(chainName, `no chain specs for ${chainName}`);
+            return;
+        }
+        const [relaySpec, paraSpec] = specs;
+        const sanitizedRelaySpec = sanitizeSmoldotChainSpec(relaySpec);
+        const sanitizedParaSpec = sanitizeSmoldotChainSpec(paraSpec);
+        const relayDb = this.handle.loadRelayDb(chainName);
+        const paraDb = this.handle.loadParaDb(chainName);
+        try {
+            diagnostics?.({ chainName, stage: "connect-start", elapsedMs: Date.now() - connectStart });
+            // Add relay chain.
+            const relay = await this.client.addChain({
+                chainSpec: sanitizedRelaySpec,
+                databaseContent: relayDb || undefined,
+            });
+            diagnostics?.({ chainName, stage: "relay-added", elapsedMs: Date.now() - connectStart });
+            // Add parachain with relay as potential relay chain.
+            const para = await this.client.addChain({
+                chainSpec: sanitizedParaSpec,
+                potentialRelayChains: [relay],
+                databaseContent: paraDb || undefined,
+            });
+            diagnostics?.({ chainName, stage: "para-added", elapsedMs: Date.now() - connectStart });
+            this.handle.registerChain(chainName);
+            const entry = {
+                relay,
+                para,
+                stop: false,
+                connectStart,
+                sawBestBlock: false,
+                sawFinalizedBlock: false,
+            };
+            this.chains.set(chainName, entry);
+            // Subscribe to new heads and finalized heads for readiness tracking.
+            para.sendJsonRpc(this.handle.subscribeNewHeadsRequest());
+            para.sendJsonRpc(this.handle.subscribeFinalizedHeadsRequest());
+            // Start the response processing loops.
+            this.runParaResponseLoop(chainName, entry);
+            this.runRelayResponseLoop(chainName, entry);
+            this.runMaintenanceLoop(chainName, entry);
+        }
+        catch (err) {
+            this.handle.setError(chainName, String(err));
+        }
+    }
+    /** Disconnect a chain. */
+    disconnect(chainName) {
+        const entry = this.chains.get(chainName);
+        if (entry) {
+            entry.stop = true;
+            try {
+                entry.para.remove();
+            }
+            catch {
+                /* already removed */
+            }
+            try {
+                entry.relay.remove();
+            }
+            catch {
+                /* already removed */
+            }
+            this.chains.delete(chainName);
+            this.diagnosticsCallbacks.delete(chainName);
+            this.handle.unregisterChain(chainName);
+        }
+    }
+    /** Get current status of a chain. */
+    status(chainName) {
+        return this.handle.status(chainName);
+    }
+    /** Get all chain statuses. */
+    allStatuses() {
+        return this.handle.allStatuses();
+    }
+    /** Disconnect all chains and terminate the smoldot client. */
+    async destroy() {
+        for (const name of this.chains.keys()) {
+            this.disconnect(name);
+        }
+        await this.client.terminate();
+    }
+    /**
+     * Persist the current relay/parachain databases for one or all connected chains.
+     *
+     * This is best-effort only: smoldot persists asynchronously after receiving the
+     * JSON-RPC save requests, so callers should treat this as a freshness hint rather
+     * than a durability barrier.
+     */
+    persistState(chainName) {
+        if (chainName != null) {
+            const entry = this.chains.get(chainName);
+            if (entry != null) {
+                this.persistEntryState(entry);
+            }
+            return;
+        }
+        for (const entry of this.chains.values()) {
+            this.persistEntryState(entry);
+        }
+    }
+    /**
+     * Wait until the chain has a finalized head, indicating it is query-ready.
+     * Resolves when status.finalizedBlock is non-null, or rejects after timeoutMs.
+     */
+    async waitUntilReady(chainName, options) {
+        const timeoutMs = options?.timeoutMs ?? 120000;
+        const pollIntervalMs = options?.pollIntervalMs ?? 500;
+        return new Promise((resolve, reject) => {
+            const check = () => {
+                const s = this.handle.status(chainName);
+                if (s.state === "Error") {
+                    cleanup();
+                    reject(new Error(`chain ${chainName} entered error state: ${s.error ?? "unknown"}`));
+                    return;
+                }
+                if (s.finalizedBlock !== null && s.finalizedBlock !== undefined) {
+                    cleanup();
+                    resolve();
+                    return;
+                }
+                if (s.state === "Disconnected") {
+                    cleanup();
+                    reject(new Error(`chain ${chainName} is disconnected`));
+                    return;
+                }
+            };
+            const timer = setInterval(check, pollIntervalMs);
+            const timeout = setTimeout(() => {
+                cleanup();
+                reject(new ChainReadinessTimeoutError(chainName, timeoutMs));
+            }, timeoutMs);
+            const cleanup = () => {
+                clearInterval(timer);
+                clearTimeout(timeout);
+            };
+            // Check immediately in case already ready.
+            check();
+        });
+    }
+    /**
+     * Register a diagnostics callback for a chain's boot process.
+     * The callback receives events at each boot stage transition.
+     * Pass null to remove an existing callback.
+     */
+    setBootDiagnostics(chainName, callback) {
+        if (callback) {
+            this.diagnosticsCallbacks.set(chainName, callback);
+        }
+        else {
+            this.diagnosticsCallbacks.delete(chainName);
+        }
+    }
+    // -- Internal event loops --
+    async runParaResponseLoop(chainName, entry) {
+        try {
+            while (!entry.stop) {
+                const text = await entry.para.nextJsonRpcResponse();
+                if (entry.stop)
+                    break;
+                // Let interceptors handle the response first.
+                const interceptor = this.responseInterceptors.get(chainName);
+                if (interceptor) {
+                    try {
+                        if (interceptor(text))
+                            continue; // consumed
+                    }
+                    catch {
+                        /* interceptor error — fall through to WASM */
+                    }
+                }
+                this.handle.processResponse(chainName, text);
+                // Emit diagnostics for first-best-block and first-finalized-block transitions.
+                // Skip the WASM status() call once both flags are set to avoid per-response overhead.
+                if (!entry.sawBestBlock || !entry.sawFinalizedBlock) {
+                    const diag = this.diagnosticsCallbacks.get(chainName);
+                    if (diag) {
+                        const s = this.handle.status(chainName);
+                        if (!entry.sawBestBlock && s.bestBlock > 0) {
+                            entry.sawBestBlock = true;
+                            diag({
+                                chainName,
+                                stage: "first-best-block",
+                                elapsedMs: Date.now() - entry.connectStart,
+                            });
+                        }
+                        if (!entry.sawFinalizedBlock &&
+                            s.finalizedBlock !== null &&
+                            s.finalizedBlock !== undefined) {
+                            entry.sawFinalizedBlock = true;
+                            this.persistEntryState(entry);
+                            diag({
+                                chainName,
+                                stage: "first-finalized-block",
+                                elapsedMs: Date.now() - entry.connectStart,
+                            });
+                            diag({ chainName, stage: "ready", elapsedMs: Date.now() - entry.connectStart });
+                        }
+                    }
+                }
+            }
+        }
+        catch (err) {
+            if (!entry.stop) {
+                this.handle.setError(chainName, `para response loop: ${err}`);
+            }
+        }
+    }
+    async runRelayResponseLoop(chainName, entry) {
+        try {
+            while (!entry.stop) {
+                const text = await entry.relay.nextJsonRpcResponse();
+                if (entry.stop)
+                    break;
+                const interceptor = this.relayResponseInterceptors.get(chainName);
+                if (interceptor) {
+                    try {
+                        if (interceptor(text))
+                            continue;
+                    }
+                    catch {
+                        /* interceptor error — fall through to WASM */
+                    }
+                }
+                this.handle.processRelayResponse(chainName, text);
+            }
+        }
+        catch (err) {
+            // Relay response errors are non-fatal (only DB saves).
+            if (!entry.stop) {
+                console.warn(`[chain] relay response error for ${chainName}:`, err);
+            }
+        }
+    }
+    runMaintenanceLoop(chainName, entry) {
+        let lastHealthCheck = Date.now();
+        let lastParaDbSave = Date.now();
+        let lastRelayDbSave = Date.now() - 30000; // Offset from para save.
+        const tick = () => {
+            if (entry.stop)
+                return;
+            const now = Date.now();
+            // Health check every 2s.
+            if (now - lastHealthCheck > 2000) {
+                lastHealthCheck = now;
+                try {
+                    entry.para.sendJsonRpc(this.handle.healthCheckRequest(chainName));
+                }
+                catch {
+                    /* chain removed */
+                }
+            }
+            // Parachain DB save every 60s.
+            if (now - lastParaDbSave > 60000) {
+                lastParaDbSave = now;
+                try {
+                    entry.para.sendJsonRpc(this.handle.paraDbSaveRequest());
+                }
+                catch {
+                    /* chain removed */
+                }
+            }
+            // Relay DB save every 60s (offset 30s from para).
+            if (now - lastRelayDbSave > 60000) {
+                lastRelayDbSave = now;
+                try {
+                    entry.relay.sendJsonRpc(this.handle.relayDbSaveRequest());
+                }
+                catch {
+                    /* chain removed */
+                }
+            }
+            setTimeout(tick, 2000);
+        };
+        setTimeout(tick, 2000);
+    }
+    persistEntryState(entry) {
+        try {
+            entry.para.sendJsonRpc(this.handle.paraDbSaveRequest());
+        }
+        catch {
+            /* chain removed */
+        }
+        try {
+            entry.relay.sendJsonRpc(this.handle.relayDbSaveRequest());
+        }
+        catch {
+            /* chain removed */
+        }
+    }
+}
+function sanitizeSmoldotChainSpec(chainSpec) {
+    const parsed = safeParseJson(chainSpec);
+    if (!isJsonRecord(parsed)) {
+        return chainSpec;
+    }
+    const bootNodes = parsed.bootNodes;
+    if (!Array.isArray(bootNodes) || bootNodes.length === 0) {
+        return chainSpec;
+    }
+    const filteredBootNodes = bootNodes.filter((bootNode) => typeof bootNode === "string" &&
+        !BLOCKED_BOOTNODE_HOST_FRAGMENTS.some((fragment) => bootNode.includes(fragment)));
+    if (filteredBootNodes.length === bootNodes.length) {
+        return chainSpec;
+    }
+    return JSON.stringify({
+        ...parsed,
+        bootNodes: filteredBootNodes,
+    });
+}
+function safeParseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+function isJsonRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+//# sourceMappingURL=chain.js.map

package/dist/chain.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Canonical JavaScript error codes for the product-facing host bridge.
+ *
+ * Public callers should prefer matching on `error.code` when present and
+ * continue treating `error.message` as the backward-compatible fallback.
+ */
+import type { BridgeErrorCode } from "./bridge/contract.js";
+export type HostErrorCode = BridgeErrorCode;
+export declare class HostError extends Error {
+    readonly code: HostErrorCode;
+    constructor(code: HostErrorCode, message: string);
+}
+export declare function isHostError(error: unknown): error is HostError;
+export declare function bridgeDestroyedError(): HostError;
+export declare function rateLimitError(operation: string, maxCalls: number, windowMs: number): HostError;
+export declare function unsupportedCapabilityError(capability: string): HostError;
+export declare function hostRuntimeUnavailableError(subject: string): HostError;
+export declare function binaryBridgeUnavailableError(): HostError;
+export declare function invalidArgumentError(message: string): HostError;
+export declare function timeoutError(message: string): HostError;
+export declare function hostRejectedError(message: string): HostError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D,MAAM,MAAM,aAAa,GAAG,eAAe,CAAC;AAE5C,qBAAa,SAAU,SAAQ,KAAK;IAClC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;gBAEjB,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM;CAKjD;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAE9D;AAED,wBAAgB,oBAAoB,IAAI,SAAS,CAEhD;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,CAK/F;AAED,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAExE;AAED,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAKtE;AAED,wBAAgB,4BAA4B,IAAI,SAAS,CAKxD;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAE/D;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAEvD;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAE5D"}