@parity/product-sdk-host 0.16.0 → 0.17.0

package/dist/{chain-discovery-nLrPzb3d.d.ts → chain-discovery-BEvu7HaV.d.ts}

@@ -1,12 +1,14 @@
 import { TrUApiClient, ChainIdentifier, HexString } from '@parity/truapi';
+import { ConnectionStatus } from '@parity/truapi/sandbox';
 
 /**
  * Access to the in-house TruAPI client (`@parity/truapi`) for the host package.
  *
- * Environment detection and the lazily-built, cached client come from
- * `@parity/truapi/sandbox`; this module layers the product-sdk-specific glue on
- * top — an async {@link getClient} accessor and {@link subscribeWithInterrupt},
- * which adapts a truapi stream into the host's {@link HostSubscription} shape.
+ * Environment detection, the lazily-built cached client, and the connection-status
+ * signal come from `@parity/truapi/sandbox`; this module layers the
+ * product-sdk-specific glue on top — an async {@link getClient} accessor,
+ * {@link subscribeConnectionStatus}, and {@link subscribeWithInterrupt}, which
+ * adapts a truapi stream into the host's {@link HostSubscription} shape.
  *
  * @module
  */
@@ -20,6 +22,9 @@ import { TrUApiClient, ChainIdentifier, HexString } from '@parity/truapi';
  * Calling this in a production build silently reroutes every host accessor to
  * the injected client, so we warn — it almost always means a `/testing` import
  * leaked into a production path.
+ *
+ * Injecting or clearing notifies {@link subscribeConnectionStatus} subscribers,
+ * so a product's "host lost" path can be exercised by disposing the fake host.
  */
 declare function setTruApiClient(client: TrUApiClient | null): void;
 /**
@@ -27,6 +32,38 @@ declare function setTruApiClient(client: TrUApiClient | null): void;
  * sandbox heuristic (iframe / webview marker / injected message port).
  */
 declare function isCorrectEnvironment(): boolean;
+/**
+ * Connection lifecycle of the host channel: `"connecting"` while the client waits
+ * for the host, `"connected"` once the channel is established, `"disconnected"`
+ * outside a host container or after the channel closes.
+ *
+ * Not the same concept as `@parity/product-sdk-signer`'s identically-shaped
+ * `ConnectionStatus`, which tracks a signer provider rather than the transport.
+ */
+type HostConnectionStatus = ConnectionStatus;
+/**
+ * Test-only: push `status` to every {@link subscribeConnectionStatus} subscriber,
+ * so a product can exercise its reconnecting / offline UI. The host-side
+ * counterpart of `@parity/product-sdk-signer`'s `FakeSignerProvider.emitStatus`.
+ * Exposed through `@parity/product-sdk-host/testing`, not the main entry.
+ */
+declare function emitConnectionStatus(status: HostConnectionStatus): void;
+/**
+ * Subscribe to host-channel connection status. The callback fires synchronously
+ * with the current status and again on every change; the returned function
+ * unsubscribes. Repeats of the status you already have are suppressed.
+ *
+ * This is the **transport** channel. For the host's account-level connection —
+ * what drives `@parity/product-sdk-signer`'s `ConnectionStatus` — use
+ * `AccountsProvider.subscribeAccountConnectionStatus` instead.
+ *
+ * Subscribing is not passive: outside an established channel the first subscribe
+ * builds the client and provider, so this can be what constructs the transport.
+ *
+ * Honours the `setTruApiClient` seam — an injected client is connected by
+ * definition, and injecting or clearing one notifies live subscribers.
+ */
+declare function subscribeConnectionStatus(callback: (status: HostConnectionStatus) => void): () => void;
 
 /**
  * Host chain discovery. Resolves chain roles to genesis hashes against the
@@ -67,4 +104,4 @@ interface HostChainDiscovery {
  */
 declare function getHostChainInfo(identifiers: readonly HostChainIdentifier[]): Promise<HostChainDiscovery | null>;
 
-export { type HostChainDiscovery as H, type HostChainIdentifier as a, getHostChainInfo as g, isCorrectEnvironment as i, setTruApiClient as s };
+export { type HostChainDiscovery as H, type HostChainIdentifier as a, type HostConnectionStatus as b, setTruApiClient as c, emitConnectionStatus as e, getHostChainInfo as g, isCorrectEnvironment as i, subscribeConnectionStatus as s };

package/dist/chunk-PAKEUP2Q.js

@@ -0,0 +1,89 @@
+import { isCorrectEnvironment as isCorrectEnvironment$1, subscribeConnectionStatus as subscribeConnectionStatus$1, getClientSync as getClientSync$1 } from '@parity/truapi/sandbox';
+
+// src/transport.ts
+var clientOverride = null;
+var localStatusListeners = /* @__PURE__ */ new Set();
+function isProductionBuild() {
+  try {
+    return process.env.NODE_ENV === "production";
+  } catch {
+    return false;
+  }
+}
+function setTruApiClient(client) {
+  if (client !== null && isProductionBuild()) {
+    console.warn(
+      "[product-sdk] setTruApiClient() was called in a production build. This is a test-only seam from @parity/product-sdk-host/testing; a leaked import will silently reroute all host access to the injected client."
+    );
+  }
+  const wasOverridden = clientOverride !== null;
+  clientOverride = client;
+  if (wasOverridden !== (client !== null)) {
+    notifyLocalStatusListeners(client !== null ? "connected" : "disconnected");
+  }
+}
+function getClientSync() {
+  return clientOverride ?? getClientSync$1();
+}
+function isCorrectEnvironment() {
+  return clientOverride !== null || isCorrectEnvironment$1();
+}
+async function getClient() {
+  return getClientSync();
+}
+function latchDisconnected(previous, next) {
+  return next === "connecting" && previous === "disconnected" ? "disconnected" : next;
+}
+function notifyLocalStatusListeners(status) {
+  for (const listener of [...localStatusListeners]) listener(status);
+}
+function emitConnectionStatus(status) {
+  if (isProductionBuild()) {
+    console.warn(
+      "[product-sdk] emitConnectionStatus() was called in a production build. This is a test-only seam from @parity/product-sdk-host/testing; a leaked import will report a fabricated connection status to real subscribers."
+    );
+  }
+  notifyLocalStatusListeners(status);
+}
+function subscribeConnectionStatus(callback) {
+  let last = null;
+  const deliver = (status, fromSandbox) => {
+    const next = fromSandbox ? latchDisconnected(last, status) : status;
+    if (next === last) return;
+    last = next;
+    callback(next);
+  };
+  const onLocal = (status) => deliver(status, false);
+  localStatusListeners.add(onLocal);
+  if (clientOverride !== null) {
+    onLocal("connected");
+    return () => void localStatusListeners.delete(onLocal);
+  }
+  const unsubscribeSandbox = subscribeConnectionStatus$1((status) => deliver(status, true));
+  return () => {
+    localStatusListeners.delete(onLocal);
+    unsubscribeSandbox();
+  };
+}
+function subscribeWithInterrupt(observable, onNext) {
+  let interruptCallback;
+  const sub = observable.subscribe({
+    next: onNext,
+    error: (reason) => interruptCallback?.(reason),
+    complete: () => interruptCallback?.()
+  });
+  return {
+    subscriptionId: sub.subscriptionId,
+    unsubscribe: () => sub.unsubscribe(),
+    onInterrupt: (callback) => {
+      interruptCallback = callback;
+      return () => {
+        if (interruptCallback === callback) interruptCallback = void 0;
+      };
+    }
+  };
+}
+
+export { emitConnectionStatus, getClient, isCorrectEnvironment, setTruApiClient, subscribeConnectionStatus, subscribeWithInterrupt };
+//# sourceMappingURL=chunk-PAKEUP2Q.js.map
+//# sourceMappingURL=chunk-PAKEUP2Q.js.map

package/dist/chunk-PAKEUP2Q.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/transport.ts"],"names":["sandboxGetClientSync","sandboxIsCorrectEnvironment","sandboxSubscribeConnectionStatus"],"mappings":"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","file":"chunk-PAKEUP2Q.js","sourcesContent":["// Copyright 2026 Parity Technologies (UK) Ltd.\n// SPDX-License-Identifier: Apache-2.0\n/**\n * Access to the in-house TruAPI client (`@parity/truapi`) for the host package.\n *\n * Environment detection, the lazily-built cached client, and the connection-status\n * signal come from `@parity/truapi/sandbox`; this module layers the\n * product-sdk-specific glue on top — an async {@link getClient} accessor,\n * {@link subscribeConnectionStatus}, and {@link subscribeWithInterrupt}, which\n * adapts a truapi stream into the host's {@link HostSubscription} shape.\n *\n * @module\n */\n\nimport type { ObservableLike, TrUApiClient } from \"@parity/truapi\";\nimport {\n    type ConnectionStatus,\n    getClientSync as sandboxGetClientSync,\n    isCorrectEnvironment as sandboxIsCorrectEnvironment,\n    subscribeConnectionStatus as sandboxSubscribeConnectionStatus,\n} from \"@parity/truapi/sandbox\";\n\nimport type { HostSubscription } from \"./types.js\";\n\n/** A {@link HostSubscription} carrying the transport-assigned subscription id. */\nexport interface TransportSubscription extends HostSubscription {\n    readonly subscriptionId: string;\n}\n\n// Test-only override. When set — via `setTruApiClient`, exposed through\n// `@parity/product-sdk-host/testing` — every host accessor resolves this client\n// instead of the sandbox one. `null` in production, so the branches below are\n// no-ops there.\nlet clientOverride: TrUApiClient | null = null;\n\n// Status subscribers registered here rather than only in the sandbox, so that\n// flipping the test seam is an *event*. The sandbox tracks only the client it\n// built itself, so it cannot know an injected client appeared or went away.\nconst localStatusListeners = new Set<(status: HostConnectionStatus) => void>();\n\nfunction isProductionBuild(): boolean {\n    try {\n        // Must stay a plain `process.env.NODE_ENV` member expression: bundlers\n        // (Vite, esbuild, webpack) substitute it textually, which is how this\n        // check works in browser builds where `process` doesn't exist.\n        return process.env.NODE_ENV === \"production\";\n    } catch {\n        // No `process` and no bundler define — can't tell, stay quiet.\n        return false;\n    }\n}\n\n/**\n * Test-only seam: force {@link getClient} / {@link getClientSync} to return\n * `client`, and {@link isCorrectEnvironment} to report `true`. Pass `null` to\n * restore normal detection. Exposed through `@parity/product-sdk-host/testing`,\n * not the package's main entry.\n *\n * Calling this in a production build silently reroutes every host accessor to\n * the injected client, so we warn — it almost always means a `/testing` import\n * leaked into a production path.\n *\n * Injecting or clearing notifies {@link subscribeConnectionStatus} subscribers,\n * so a product's \"host lost\" path can be exercised by disposing the fake host.\n */\nexport function setTruApiClient(client: TrUApiClient | null): void {\n    if (client !== null && isProductionBuild()) {\n        console.warn(\n            \"[product-sdk] setTruApiClient() was called in a production build. This is a test-only seam from @parity/product-sdk-host/testing; a leaked import will silently reroute all host access to the injected client.\",\n        );\n    }\n    const wasOverridden = clientOverride !== null;\n    clientOverride = client;\n    if (wasOverridden !== (client !== null)) {\n        notifyLocalStatusListeners(client !== null ? \"connected\" : \"disconnected\");\n    }\n}\n\n/**\n * Synchronous TruAPI client accessor. Returns the injected test client when one\n * is set, otherwise the sandbox client (`null` outside a host container).\n */\nexport function getClientSync(): TrUApiClient | null {\n    return clientOverride ?? sandboxGetClientSync();\n}\n\n/**\n * Host-container detection. `true` when a test client is injected, otherwise the\n * sandbox heuristic (iframe / webview marker / injected message port).\n */\nexport function isCorrectEnvironment(): boolean {\n    return clientOverride !== null || sandboxIsCorrectEnvironment();\n}\n\n/**\n * Get the TruAPI client. Returns `null` outside a host container. Async wrapper\n * over {@link getClientSync} for the host wrappers that already `await` it.\n */\nexport async function getClient(): Promise<TrUApiClient | null> {\n    return getClientSync();\n}\n\n/**\n * Connection lifecycle of the host channel: `\"connecting\"` while the client waits\n * for the host, `\"connected\"` once the channel is established, `\"disconnected\"`\n * outside a host container or after the channel closes.\n *\n * Not the same concept as `@parity/product-sdk-signer`'s identically-shaped\n * `ConnectionStatus`, which tracks a signer provider rather than the transport.\n */\nexport type HostConnectionStatus = ConnectionStatus;\n\n/**\n * Correct one defect in the sandbox's status signal: `@parity/truapi` never clears\n * its cached client when the pipe closes, so a subscriber arriving after a\n * disconnect re-derives `\"connecting\"` from the dead client — and because the\n * sandbox fans every change out to all listeners, that rewrites everyone's state\n * with no way back. Hold `\"disconnected\"` until a real `\"connected\"` arrives.\n *\n * Applies to sandbox-sourced statuses only. A status pushed by the test seam is\n * deliberate and passes through, so a fake host can still drive a reconnect.\n *\n * Outstanding upstream, not tied to the version we happen to be on: `sandbox.js`\n * is byte-identical from 0.7.0 through 0.9.0 (npm latest) and still unfixed on\n * `paritytech/host-rust-core` main, the repo formerly named truapi. Remove once\n * it clears the cached client on close.\n */\nfunction latchDisconnected(\n    previous: HostConnectionStatus | null,\n    next: HostConnectionStatus,\n): HostConnectionStatus {\n    return next === \"connecting\" && previous === \"disconnected\" ? \"disconnected\" : next;\n}\n\nfunction notifyLocalStatusListeners(status: HostConnectionStatus): void {\n    // Iterate a snapshot: a listener that unsubscribes itself, or re-enters\n    // `setTruApiClient`, must not mutate the set mid-loop.\n    for (const listener of [...localStatusListeners]) listener(status);\n}\n\n/**\n * Test-only: push `status` to every {@link subscribeConnectionStatus} subscriber,\n * so a product can exercise its reconnecting / offline UI. The host-side\n * counterpart of `@parity/product-sdk-signer`'s `FakeSignerProvider.emitStatus`.\n * Exposed through `@parity/product-sdk-host/testing`, not the main entry.\n */\nexport function emitConnectionStatus(status: HostConnectionStatus): void {\n    if (isProductionBuild()) {\n        console.warn(\n            \"[product-sdk] emitConnectionStatus() was called in a production build. This is a test-only seam from @parity/product-sdk-host/testing; a leaked import will report a fabricated connection status to real subscribers.\",\n        );\n    }\n    notifyLocalStatusListeners(status);\n}\n\n/**\n * Subscribe to host-channel connection status. The callback fires synchronously\n * with the current status and again on every change; the returned function\n * unsubscribes. Repeats of the status you already have are suppressed.\n *\n * This is the **transport** channel. For the host's account-level connection —\n * what drives `@parity/product-sdk-signer`'s `ConnectionStatus` — use\n * `AccountsProvider.subscribeAccountConnectionStatus` instead.\n *\n * Subscribing is not passive: outside an established channel the first subscribe\n * builds the client and provider, so this can be what constructs the transport.\n *\n * Honours the `setTruApiClient` seam — an injected client is connected by\n * definition, and injecting or clearing one notifies live subscribers.\n */\nexport function subscribeConnectionStatus(\n    callback: (status: HostConnectionStatus) => void,\n): () => void {\n    let last: HostConnectionStatus | null = null;\n\n    // One wrapped callback for both sources, so `last` stays coherent: the seam\n    // and the sandbox must not each keep their own idea of what was delivered.\n    const deliver = (status: HostConnectionStatus, fromSandbox: boolean): void => {\n        const next = fromSandbox ? latchDisconnected(last, status) : status;\n        if (next === last) return;\n        last = next;\n        callback(next);\n    };\n\n    const onLocal = (status: HostConnectionStatus) => deliver(status, false);\n    localStatusListeners.add(onLocal);\n\n    if (clientOverride !== null) {\n        onLocal(\"connected\");\n        return () => void localStatusListeners.delete(onLocal);\n    }\n\n    const unsubscribeSandbox = sandboxSubscribeConnectionStatus((status) => deliver(status, true));\n    return () => {\n        localStatusListeners.delete(onLocal);\n        unsubscribeSandbox();\n    };\n}\n\n/**\n * Adapt a truapi `ObservableLike` stream into the host's callback-style\n * {@link HostSubscription} (`unsubscribe` + `onInterrupt`). `onNext` fires for\n * each item; the registered `onInterrupt` callback fires when the host ends the\n * subscription server-side — which the generated client surfaces as either\n * `complete` (a host interrupt frame) or `error` (transport close). Shared by\n * the statement-store and preimage adapters, which both expose this shape.\n */\nexport function subscribeWithInterrupt<Item, Reason = never>(\n    observable: ObservableLike<Item, Reason>,\n    onNext: (item: Item) => void,\n): TransportSubscription {\n    let interruptCallback: ((reason?: unknown) => void) | undefined;\n    const sub = observable.subscribe({\n        next: onNext,\n        error: (reason) => interruptCallback?.(reason),\n        complete: () => interruptCallback?.(),\n    });\n    return {\n        subscriptionId: sub.subscriptionId,\n        unsubscribe: () => sub.unsubscribe(),\n        onInterrupt: (callback) => {\n            interruptCallback = callback;\n            return () => {\n                if (interruptCallback === callback) interruptCallback = undefined;\n            };\n        },\n    };\n}\n\nif (import.meta.vitest) {\n    const { test, expect, afterEach } = import.meta.vitest;\n\n    afterEach(() => setTruApiClient(null));\n\n    // Environment detection and client building are covered by `@parity/truapi`'s\n    // own sandbox tests; here we only assert the local glue degrades outside a\n    // host container.\n    test(\"getClientSync returns null outside a container\", () => {\n        expect(getClientSync()).toBeNull();\n    });\n\n    test(\"getClient resolves null outside a container\", async () => {\n        expect(await getClient()).toBeNull();\n    });\n\n    test(\"setTruApiClient overrides the client and container detection\", async () => {\n        const fake = {} as TrUApiClient;\n        setTruApiClient(fake);\n        expect(getClientSync()).toBe(fake);\n        expect(await getClient()).toBe(fake);\n        expect(isCorrectEnvironment()).toBe(true);\n\n        setTruApiClient(null);\n        expect(getClientSync()).toBeNull();\n        expect(isCorrectEnvironment()).toBe(false);\n    });\n\n    test(\"setTruApiClient warns when injecting in a production build\", () => {\n        const original = process.env.NODE_ENV;\n        const warnings: string[] = [];\n        const realWarn = console.warn;\n        console.warn = (...args: unknown[]) => void warnings.push(String(args[0]));\n        try {\n            process.env.NODE_ENV = \"production\";\n            setTruApiClient({} as TrUApiClient);\n            expect(warnings).toHaveLength(1);\n            expect(warnings[0]).toContain(\"production build\");\n\n            // Clearing the override must not warn.\n            setTruApiClient(null);\n            expect(warnings).toHaveLength(1);\n        } finally {\n            console.warn = realWarn;\n            process.env.NODE_ENV = original;\n        }\n    });\n\n    test(\"subscribeConnectionStatus reports disconnected outside a container\", () => {\n        const statuses: HostConnectionStatus[] = [];\n\n        const unsubscribe = subscribeConnectionStatus((status) => statuses.push(status));\n\n        expect(statuses).toEqual([\"disconnected\"]);\n        unsubscribe();\n    });\n\n    test(\"subscribeConnectionStatus reports connected for an injected client\", () => {\n        setTruApiClient({} as TrUApiClient);\n        const statuses: HostConnectionStatus[] = [];\n\n        const unsubscribe = subscribeConnectionStatus((status) => statuses.push(status));\n\n        // The sandbox only tracks the client it built itself, so without the\n        // override branch this would report \"disconnected\" while every other\n        // accessor resolved the injected client.\n        expect(statuses).toEqual([\"connected\"]);\n        unsubscribe();\n    });\n\n    test(\"disposing the injected client notifies live subscribers\", () => {\n        setTruApiClient({} as TrUApiClient);\n        const statuses: HostConnectionStatus[] = [];\n        const unsubscribe = subscribeConnectionStatus((status) => statuses.push(status));\n\n        setTruApiClient(null);\n\n        expect(statuses).toEqual([\"connected\", \"disconnected\"]);\n        unsubscribe();\n    });\n\n    test(\"injecting a client notifies subscribers that started without one\", () => {\n        const statuses: HostConnectionStatus[] = [];\n        const unsubscribe = subscribeConnectionStatus((status) => statuses.push(status));\n\n        setTruApiClient({} as TrUApiClient);\n\n        expect(statuses).toEqual([\"disconnected\", \"connected\"]);\n        unsubscribe();\n    });\n\n    test(\"unsubscribe stops seam notifications\", () => {\n        setTruApiClient({} as TrUApiClient);\n        const statuses: HostConnectionStatus[] = [];\n        const unsubscribe = subscribeConnectionStatus((status) => statuses.push(status));\n\n        unsubscribe();\n        setTruApiClient(null);\n\n        expect(statuses).toEqual([\"connected\"]);\n        expect(localStatusListeners.size).toBe(0);\n    });\n\n    test(\"emitConnectionStatus drives transitions, including a reconnect\", () => {\n        setTruApiClient({} as TrUApiClient);\n        const statuses: HostConnectionStatus[] = [];\n        const unsubscribe = subscribeConnectionStatus((status) => statuses.push(status));\n\n        emitConnectionStatus(\"disconnected\");\n        // A seam-pushed \"connecting\" after \"disconnected\" is deliberate, so it must\n        // survive the sandbox latch — otherwise no test could drive a reconnect.\n        emitConnectionStatus(\"connecting\");\n        emitConnectionStatus(\"connected\");\n\n        expect(statuses).toEqual([\"connected\", \"disconnected\", \"connecting\", \"connected\"]);\n        unsubscribe();\n    });\n\n    test(\"repeats of the current status are suppressed\", () => {\n        setTruApiClient({} as TrUApiClient);\n        const statuses: HostConnectionStatus[] = [];\n        const unsubscribe = subscribeConnectionStatus((status) => statuses.push(status));\n\n        emitConnectionStatus(\"connected\");\n        emitConnectionStatus(\"connected\");\n\n        expect(statuses).toEqual([\"connected\"]);\n        unsubscribe();\n    });\n\n    test(\"a listener that unsubscribes itself mid-notification is safe\", () => {\n        setTruApiClient({} as TrUApiClient);\n        const statuses: HostConnectionStatus[] = [];\n        const handle: { unsubscribe?: () => void } = {};\n        handle.unsubscribe = subscribeConnectionStatus((status) => {\n            statuses.push(status);\n            handle.unsubscribe?.();\n        });\n\n        setTruApiClient(null);\n\n        expect(statuses).toEqual([\"connected\", \"disconnected\"]);\n        expect(localStatusListeners.size).toBe(0);\n    });\n\n    // The sandbox latch can't be driven through the public surface — it needs a\n    // real provider close — so the correction is pinned as a pure function.\n    test(\"latchDisconnected holds disconnected through the stale-cache connecting\", () => {\n        expect(latchDisconnected(\"disconnected\", \"connecting\")).toBe(\"disconnected\");\n    });\n\n    test(\"latchDisconnected passes every other transition through\", () => {\n        expect(latchDisconnected(null, \"disconnected\")).toBe(\"disconnected\");\n        expect(latchDisconnected(null, \"connecting\")).toBe(\"connecting\");\n        expect(latchDisconnected(\"connecting\", \"connected\")).toBe(\"connected\");\n        expect(latchDisconnected(\"connected\", \"disconnected\")).toBe(\"disconnected\");\n        // A genuine reconnect still gets through once the channel re-establishes.\n        expect(latchDisconnected(\"connected\", \"connecting\")).toBe(\"connecting\");\n    });\n\n    test(\"subscribeWithInterrupt preserves the transport subscription id\", () => {\n        const observable = {\n            subscribe: () => ({\n                subscriptionId: \"p:17\",\n                unsubscribe: () => {},\n            }),\n            [Symbol.observable]() {\n                return this;\n            },\n        } as ObservableLike<never>;\n\n        const subscription = subscribeWithInterrupt(observable, () => {});\n\n        expect(subscription.subscriptionId).toBe(\"p:17\");\n    });\n}\n"]}

package/dist/index.d.ts

@@ -5,8 +5,9 @@ import { SdkError } from '@parity/product-sdk-errors';
 export { SdkError, isSdkError } from '@parity/product-sdk-errors';
 import { Result } from '@parity/result';
 export { Result, err, ok } from '@parity/result';
-export { H as HostChainDiscovery, a as HostChainIdentifier, g as getHostChainInfo, i as isInsideContainerSync } from './chain-discovery-nLrPzb3d.js';
+export { H as HostChainDiscovery, a as HostChainIdentifier, b as HostConnectionStatus, g as getHostChainInfo, i as isInsideContainerSync, s as subscribeConnectionStatus } from './chain-discovery-BEvu7HaV.js';
 import { ResultAsync as ResultAsync$1 } from 'neverthrow';
+import '@parity/truapi/sandbox';
 
 /**
  * Public types for the host wrappers.
@@ -156,12 +157,14 @@ declare function getStatementStore(): Promise<HostStatementStore | null>;
  * chain-specific endpoints used by multiple packages.
  */
 /**
- * Bulletin Chain RPC endpoints per network environment. `paseo` (Paseo Next v2)
- * and `devnet` (public Paseo testnet) are populated today; `polkadot` and
- * `kusama` are reserved for when those Bulletin deployments go live.
+ * Bulletin Chain RPC endpoints per network environment. `paseo` (Paseo Next v2),
+ * `previewnet` (zombienet, a step ahead of paseo), and `devnet` (public Paseo
+ * testnet) are populated today; `polkadot` and `kusama` are reserved for when
+ * those Bulletin deployments go live.
  */
 declare const BULLETIN_RPCS: {
     readonly paseo: readonly ["wss://paseo-bulletin-next-rpc.polkadot.io"];
+    readonly previewnet: readonly ["wss://previewnet.substrate.dev/bulletin"];
     readonly devnet: readonly ["wss://bulletin-paseo.tservices.es:8443"];
     readonly polkadot: string[];
     readonly kusama: string[];

package/dist/index.js

@@ -1,5 +1,5 @@
-import { getClient, isCorrectEnvironment, subscribeWithInterrupt } from './chunk-GDXSV7JV.js';
-export { isCorrectEnvironment as isInsideContainerSync } from './chunk-GDXSV7JV.js';
+import { getClient, isCorrectEnvironment, subscribeWithInterrupt } from './chunk-PAKEUP2Q.js';
+export { isCorrectEnvironment as isInsideContainerSync, subscribeConnectionStatus } from './chunk-PAKEUP2Q.js';
 import { createLogger } from '@parity/product-sdk-logger';
 import { scale } from '@parity/truapi';
 import { err, ok } from '@parity/result';
@@ -68,6 +68,23 @@ function isHostError(error) {
 var log = createLogger("host:papi");
 var JSON_RPC_INTERNAL_ERROR = -32603;
 var JSON_RPC_METHOD_NOT_FOUND = -32601;
+function followOperationId(item) {
+  switch (item.tag) {
+    case "OperationBodyDone":
+    case "OperationCallDone":
+    case "OperationStorageItems":
+    case "OperationStorageDone":
+    case "OperationWaitingForContinue":
+    case "OperationInaccessible":
+    case "OperationError":
+      return item.value.operationId;
+    default:
+      return void 0;
+  }
+}
+function isTerminalOperationItem(item) {
+  return item.tag === "OperationBodyDone" || item.tag === "OperationCallDone" || item.tag === "OperationStorageDone" || item.tag === "OperationInaccessible" || item.tag === "OperationError";
+}
 var STORAGE_TYPE_MAP = {
   value: "Value",
   hash: "Hash",
@@ -174,6 +191,8 @@ function createHostPapiProvider(client, genesisHash) {
   return (onMessage) => {
     const activeFollows = /* @__PURE__ */ new Map();
     const activeBroadcasts = /* @__PURE__ */ new Set();
+    const followOperations = /* @__PURE__ */ new Map();
+    const pendingOperationStarts = /* @__PURE__ */ new Map();
     function sendJsonRpcResponse(id, result) {
       onMessage({ jsonrpc: "2.0", id, result });
     }
@@ -187,6 +206,72 @@ function createHostPapiProvider(client, genesisHash) {
         params: { subscription, result: event }
       });
     }
+    function forwardFollowItem(followSubscriptionId, item) {
+      const operationId = followOperationId(item);
+      if (operationId === void 0) {
+        sendFollowEvent(followSubscriptionId, convertFollowEventToJsonRpc(item));
+        return;
+      }
+      const operations = followOperations.get(followSubscriptionId);
+      if (!operations) return;
+      let operation = operations.get(operationId);
+      if (!operation) {
+        if ((pendingOperationStarts.get(followSubscriptionId) ?? 0) === 0) {
+          sendFollowEvent(followSubscriptionId, convertFollowEventToJsonRpc(item));
+          return;
+        }
+        operation = { announced: false, items: [] };
+        operations.set(operationId, operation);
+      }
+      if (!operation.announced) {
+        operation.items.push(item);
+        return;
+      }
+      sendFollowEvent(followSubscriptionId, convertFollowEventToJsonRpc(item));
+      if (isTerminalOperationItem(item)) {
+        operations.delete(operationId);
+      }
+    }
+    function sendOperationStartedResponse(id, followSubscriptionId, result) {
+      sendJsonRpcResponse(id, convertOperationResultToJsonRpc(result));
+      if (result.tag !== "Started") return;
+      const operations = followOperations.get(followSubscriptionId);
+      if (!operations) return;
+      const operationId = result.value.operationId;
+      let operation = operations.get(operationId);
+      if (!operation) {
+        operation = { announced: true, items: [] };
+        operations.set(operationId, operation);
+        return;
+      }
+      operation.announced = true;
+      const pendingItems = operation.items;
+      operation.items = [];
+      for (const item of pendingItems) {
+        forwardFollowItem(followSubscriptionId, item);
+      }
+    }
+    function startOperationRequest(id, followSubscriptionId) {
+      const pending = pendingOperationStarts.get(followSubscriptionId);
+      if (pending !== void 0) {
+        pendingOperationStarts.set(followSubscriptionId, pending + 1);
+      }
+      const settle = () => {
+        const outstanding = pendingOperationStarts.get(followSubscriptionId);
+        if (outstanding === void 0) return;
+        pendingOperationStarts.set(followSubscriptionId, Math.max(0, outstanding - 1));
+      };
+      return {
+        ok: (response) => {
+          settle();
+          sendOperationStartedResponse(id, followSubscriptionId, response.operation);
+        },
+        err: (error) => {
+          settle();
+          hostError(id)(error);
+        }
+      };
+    }
     const hostError = (id) => (error) => sendJsonRpcError(id, JSON_RPC_INTERNAL_ERROR, formatHostError(error));
     function handleMessage(message) {
       const { id, method } = message;
@@ -199,8 +284,10 @@ function createHostPapiProvider(client, genesisHash) {
           const forwardItem = (followSubscriptionId2, item) => {
             if (item.tag === "Stop" && activeFollows.delete(followSubscriptionId2)) {
               ref.handle?.unsubscribe();
+              followOperations.delete(followSubscriptionId2);
+              pendingOperationStarts.delete(followSubscriptionId2);
             }
-            sendFollowEvent(followSubscriptionId2, convertFollowEventToJsonRpc(item));
+            forwardFollowItem(followSubscriptionId2, item);
           };
           ref.handle = subscribeWithInterrupt(
             chain.followHeadSubscribe({ request: { genesisHash, withRuntime } }),
@@ -224,11 +311,15 @@ function createHostPapiProvider(client, genesisHash) {
             break;
           }
           ref.handle.onInterrupt(() => {
+            followOperations.delete(followSubscriptionId);
+            pendingOperationStarts.delete(followSubscriptionId);
             if (activeFollows.delete(followSubscriptionId)) {
               sendFollowEvent(followSubscriptionId, { event: "stop" });
             }
           });
           activeFollows.set(followSubscriptionId, ref.handle);
+          followOperations.set(followSubscriptionId, /* @__PURE__ */ new Map());
+          pendingOperationStarts.set(followSubscriptionId, 0);
           sendJsonRpcResponse(id, followSubscriptionId);
           for (const item of pendingItems) {
             forwardItem(followSubscriptionId, item);
@@ -242,6 +333,8 @@ function createHostPapiProvider(client, genesisHash) {
             follow.unsubscribe();
             activeFollows.delete(followSubId);
           }
+          followOperations.delete(followSubId);
+          pendingOperationStarts.delete(followSubId);
           sendJsonRpcResponse(id, null);
           break;
         }
@@ -255,13 +348,8 @@ function createHostPapiProvider(client, genesisHash) {
         }
         case "chainHead_v1_body": {
           const [followSubscriptionId, hash] = params;
-          chain.getHeadBody({ genesisHash, followSubscriptionId, hash }).match(
-            (response) => sendJsonRpcResponse(
-              id,
-              convertOperationResultToJsonRpc(response.operation)
-            ),
-            hostError(id)
-          );
+          const bodyStart = startOperationRequest(id, followSubscriptionId);
+          chain.getHeadBody({ genesisHash, followSubscriptionId, hash }).match(bodyStart.ok, bodyStart.err);
           break;
         }
         case "chainHead_v1_storage": {
@@ -270,6 +358,7 @@ function createHostPapiProvider(client, genesisHash) {
             key: item.key,
             queryType: convertStorageType(item.type)
           }));
+          const storageStart = startOperationRequest(id, followSubscriptionId);
           chain.getHeadStorage({
             genesisHash,
             followSubscriptionId,
@@ -281,30 +370,19 @@ function createHostPapiProvider(client, genesisHash) {
             // the inner Hex codec on `null`, which throws
             // (`null.startsWith`). Coerce `null` → `undefined`.
             childTrie: childTrie ?? void 0
-          }).match(
-            (response) => sendJsonRpcResponse(
-              id,
-              convertOperationResultToJsonRpc(response.operation)
-            ),
-            hostError(id)
-          );
+          }).match(storageStart.ok, storageStart.err);
           break;
         }
         case "chainHead_v1_call": {
           const [followSubscriptionId, hash, fn, callParameters] = params;
+          const callStart = startOperationRequest(id, followSubscriptionId);
           chain.callHead({
             genesisHash,
             followSubscriptionId,
             hash,
             function: fn,
             callParameters
-          }).match(
-            (response) => sendJsonRpcResponse(
-              id,
-              convertOperationResultToJsonRpc(response.operation)
-            ),
-            hostError(id)
-          );
+          }).match(callStart.ok, callStart.err);
           break;
         }
         case "chainHead_v1_unpin": {
@@ -320,7 +398,10 @@ function createHostPapiProvider(client, genesisHash) {
         }
         case "chainHead_v1_stopOperation": {
           const [followSubscriptionId, operationId] = params;
-          chain.stopHeadOperation({ genesisHash, followSubscriptionId, operationId }).match(() => sendJsonRpcResponse(id, null), hostError(id));
+          chain.stopHeadOperation({ genesisHash, followSubscriptionId, operationId }).match(() => {
+            followOperations.get(followSubscriptionId)?.delete(operationId);
+            sendJsonRpcResponse(id, null);
+          }, hostError(id));
           break;
         }
         case "chainSpec_v1_genesisHash": {
@@ -387,6 +468,8 @@ function createHostPapiProvider(client, genesisHash) {
           handle.unsubscribe();
         }
         activeFollows.clear();
+        followOperations.clear();
+        pendingOperationStarts.clear();
         for (const operationId of activeBroadcasts) {
           chain.stopTransaction({ genesisHash, operationId }).match(
             () => {
@@ -575,6 +658,7 @@ async function getStatementStore() {
 // src/chains.ts
 var BULLETIN_RPCS = {
   paseo: ["wss://paseo-bulletin-next-rpc.polkadot.io"],
+  previewnet: ["wss://previewnet.substrate.dev/bulletin"],
   devnet: ["wss://bulletin-paseo.tservices.es:8443"],
   polkadot: [],
   kusama: []
@@ -665,13 +749,18 @@ function sameRingLocation(a, b) {
 function findRingVrfKeyHandle(keys, ring) {
   return keys.find((key) => key.rings.some((candidate) => sameRingLocation(candidate, ring)))?.handle;
 }
-function deriveTxExtVersion(metadata) {
-  const versions = unifyMetadata(decAnyMetadata(metadata)).extrinsic.version;
+function selectHostTxExtVersion(versions) {
   if (versions.length === 0) {
     throw new Error("No extrinsic version found in metadata");
   }
-  const latestVersion = versions.reduce((acc, v) => Math.max(acc, v), 0);
-  return latestVersion === 4 ? 0 : latestVersion;
+  if (versions.includes(4)) {
+    return 0;
+  }
+  return versions.reduce((acc, version) => Math.max(acc, version), 0);
+}
+function deriveTxExtVersion(metadata) {
+  const versions = unifyMetadata(decAnyMetadata(metadata)).extrinsic.version;
+  return selectHostTxExtVersion(versions);
 }
 var deps = { deriveTxExtVersion };
 function toHostExtensions(signedExtensions) {