@parity/product-sdk-host 0.16.0 → 0.18.0

package/src/transport.ts

@@ -3,18 +3,21 @@
 /**
  * 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
  */
 
 import type { ObservableLike, TrUApiClient } from "@parity/truapi";
 import {
+    type ConnectionStatus,
     getClientSync as sandboxGetClientSync,
     isCorrectEnvironment as sandboxIsCorrectEnvironment,
+    subscribeConnectionStatus as sandboxSubscribeConnectionStatus,
 } from "@parity/truapi/sandbox";
 
 import type { HostSubscription } from "./types.js";
@@ -30,6 +33,11 @@ export interface TransportSubscription extends HostSubscription {
 // no-ops there.
 let clientOverride: TrUApiClient | null = null;
 
+// Status subscribers registered here rather than only in the sandbox, so that
+// flipping the test seam is an *event*. The sandbox tracks only the client it
+// built itself, so it cannot know an injected client appeared or went away.
+const localStatusListeners = new Set<(status: HostConnectionStatus) => void>();
+
 function isProductionBuild(): boolean {
     try {
         // Must stay a plain `process.env.NODE_ENV` member expression: bundlers
@@ -51,6 +59,9 @@ function isProductionBuild(): boolean {
  * 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.
  */
 export function setTruApiClient(client: TrUApiClient | null): void {
     if (client !== null && isProductionBuild()) {
@@ -58,7 +69,11 @@ export function setTruApiClient(client: TrUApiClient | null): void {
             "[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");
+    }
 }
 
 /**
@@ -85,6 +100,103 @@ export async function getClient(): Promise<TrUApiClient | null> {
     return getClientSync();
 }
 
+/**
+ * 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.
+ */
+export type HostConnectionStatus = ConnectionStatus;
+
+/**
+ * Correct one defect in the sandbox's status signal: `@parity/truapi` never clears
+ * its cached client when the pipe closes, so a subscriber arriving after a
+ * disconnect re-derives `"connecting"` from the dead client — and because the
+ * sandbox fans every change out to all listeners, that rewrites everyone's state
+ * with no way back. Hold `"disconnected"` until a real `"connected"` arrives.
+ *
+ * Applies to sandbox-sourced statuses only. A status pushed by the test seam is
+ * deliberate and passes through, so a fake host can still drive a reconnect.
+ *
+ * Outstanding upstream, not tied to the version we happen to be on: `sandbox.js`
+ * is byte-identical from 0.7.0 through 0.9.0 (npm latest) and still unfixed on
+ * `paritytech/host-rust-core` main, the repo formerly named truapi. Remove once
+ * it clears the cached client on close.
+ */
+function latchDisconnected(
+    previous: HostConnectionStatus | null,
+    next: HostConnectionStatus,
+): HostConnectionStatus {
+    return next === "connecting" && previous === "disconnected" ? "disconnected" : next;
+}
+
+function notifyLocalStatusListeners(status: HostConnectionStatus): void {
+    // Iterate a snapshot: a listener that unsubscribes itself, or re-enters
+    // `setTruApiClient`, must not mutate the set mid-loop.
+    for (const listener of [...localStatusListeners]) listener(status);
+}
+
+/**
+ * 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.
+ */
+export function emitConnectionStatus(status: HostConnectionStatus): void {
+    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);
+}
+
+/**
+ * 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.
+ */
+export function subscribeConnectionStatus(
+    callback: (status: HostConnectionStatus) => void,
+): () => void {
+    let last: HostConnectionStatus | null = null;
+
+    // One wrapped callback for both sources, so `last` stays coherent: the seam
+    // and the sandbox must not each keep their own idea of what was delivered.
+    const deliver = (status: HostConnectionStatus, fromSandbox: boolean): void => {
+        const next = fromSandbox ? latchDisconnected(last, status) : status;
+        if (next === last) return;
+        last = next;
+        callback(next);
+    };
+
+    const onLocal = (status: HostConnectionStatus) => deliver(status, false);
+    localStatusListeners.add(onLocal);
+
+    if (clientOverride !== null) {
+        onLocal("connected");
+        return () => void localStatusListeners.delete(onLocal);
+    }
+
+    const unsubscribeSandbox = sandboxSubscribeConnectionStatus((status) => deliver(status, true));
+    return () => {
+        localStatusListeners.delete(onLocal);
+        unsubscribeSandbox();
+    };
+}
+
 /**
  * Adapt a truapi `ObservableLike` stream into the host's callback-style
  * {@link HostSubscription} (`unsubscribe` + `onInterrupt`). `onNext` fires for
@@ -163,6 +275,118 @@ if (import.meta.vitest) {
         }
     });
 
+    test("subscribeConnectionStatus reports disconnected outside a container", () => {
+        const statuses: HostConnectionStatus[] = [];
+
+        const unsubscribe = subscribeConnectionStatus((status) => statuses.push(status));
+
+        expect(statuses).toEqual(["disconnected"]);
+        unsubscribe();
+    });
+
+    test("subscribeConnectionStatus reports connected for an injected client", () => {
+        setTruApiClient({} as TrUApiClient);
+        const statuses: HostConnectionStatus[] = [];
+
+        const unsubscribe = subscribeConnectionStatus((status) => statuses.push(status));
+
+        // The sandbox only tracks the client it built itself, so without the
+        // override branch this would report "disconnected" while every other
+        // accessor resolved the injected client.
+        expect(statuses).toEqual(["connected"]);
+        unsubscribe();
+    });
+
+    test("disposing the injected client notifies live subscribers", () => {
+        setTruApiClient({} as TrUApiClient);
+        const statuses: HostConnectionStatus[] = [];
+        const unsubscribe = subscribeConnectionStatus((status) => statuses.push(status));
+
+        setTruApiClient(null);
+
+        expect(statuses).toEqual(["connected", "disconnected"]);
+        unsubscribe();
+    });
+
+    test("injecting a client notifies subscribers that started without one", () => {
+        const statuses: HostConnectionStatus[] = [];
+        const unsubscribe = subscribeConnectionStatus((status) => statuses.push(status));
+
+        setTruApiClient({} as TrUApiClient);
+
+        expect(statuses).toEqual(["disconnected", "connected"]);
+        unsubscribe();
+    });
+
+    test("unsubscribe stops seam notifications", () => {
+        setTruApiClient({} as TrUApiClient);
+        const statuses: HostConnectionStatus[] = [];
+        const unsubscribe = subscribeConnectionStatus((status) => statuses.push(status));
+
+        unsubscribe();
+        setTruApiClient(null);
+
+        expect(statuses).toEqual(["connected"]);
+        expect(localStatusListeners.size).toBe(0);
+    });
+
+    test("emitConnectionStatus drives transitions, including a reconnect", () => {
+        setTruApiClient({} as TrUApiClient);
+        const statuses: HostConnectionStatus[] = [];
+        const unsubscribe = subscribeConnectionStatus((status) => statuses.push(status));
+
+        emitConnectionStatus("disconnected");
+        // A seam-pushed "connecting" after "disconnected" is deliberate, so it must
+        // survive the sandbox latch — otherwise no test could drive a reconnect.
+        emitConnectionStatus("connecting");
+        emitConnectionStatus("connected");
+
+        expect(statuses).toEqual(["connected", "disconnected", "connecting", "connected"]);
+        unsubscribe();
+    });
+
+    test("repeats of the current status are suppressed", () => {
+        setTruApiClient({} as TrUApiClient);
+        const statuses: HostConnectionStatus[] = [];
+        const unsubscribe = subscribeConnectionStatus((status) => statuses.push(status));
+
+        emitConnectionStatus("connected");
+        emitConnectionStatus("connected");
+
+        expect(statuses).toEqual(["connected"]);
+        unsubscribe();
+    });
+
+    test("a listener that unsubscribes itself mid-notification is safe", () => {
+        setTruApiClient({} as TrUApiClient);
+        const statuses: HostConnectionStatus[] = [];
+        const handle: { unsubscribe?: () => void } = {};
+        handle.unsubscribe = subscribeConnectionStatus((status) => {
+            statuses.push(status);
+            handle.unsubscribe?.();
+        });
+
+        setTruApiClient(null);
+
+        expect(statuses).toEqual(["connected", "disconnected"]);
+        expect(localStatusListeners.size).toBe(0);
+    });
+
+    // The sandbox latch can't be driven through the public surface — it needs a
+    // real provider close — so the correction is pinned as a pure function.
+    test("latchDisconnected holds disconnected through the stale-cache connecting", () => {
+        expect(latchDisconnected("disconnected", "connecting")).toBe("disconnected");
+    });
+
+    test("latchDisconnected passes every other transition through", () => {
+        expect(latchDisconnected(null, "disconnected")).toBe("disconnected");
+        expect(latchDisconnected(null, "connecting")).toBe("connecting");
+        expect(latchDisconnected("connecting", "connected")).toBe("connected");
+        expect(latchDisconnected("connected", "disconnected")).toBe("disconnected");
+        // A genuine reconnect still gets through once the channel re-establishes.
+        expect(latchDisconnected("connected", "connecting")).toBe("connecting");
+    });
+
     test("subscribeWithInterrupt preserves the transport subscription id", () => {
         const observable = {
             subscribe: () => ({

package/src/truapi.ts

@@ -28,6 +28,7 @@ import {
     type HostError,
     type HostErrorPayload,
     HostCallFailedError,
+    HostResponseDecodeError,
     HostUnavailableError,
     formatHostError,
 } from "./errors.js";
@@ -37,6 +38,66 @@ import type { HostSubscription, Statement, StatementProof } from "./types.js";
 
 const log = createLogger("host");
 
+/**
+ * `result.match(onOk, onErr)`, but a decode-time rejection is routed through
+ * `onDecode` instead of rejecting the returned promise.
+ *
+ * The truapi client decodes each response inside the value it resolves, and
+ * wraps the whole call with `ResultAsync.fromSafePromise`, which installs no
+ * rejection handler. So when the host's reply doesn't match the client's codec
+ * — a protocol-version skew, or a channel that closed mid-call — the resulting
+ * rejection escapes the `Result` channel entirely and `.match` never sees it,
+ * surfacing as a raw `RangeError` rather than reaching `onErr`. Catching the
+ * `.match` promise re-homes that rejection as a typed
+ * {@link HostResponseDecodeError} that names the call. Both
+ * {@link unwrapHostResult} and {@link mapHostResult} route through here, so
+ * every boundary — throwing and Result-returning — is covered, not just the
+ * accounts adapter.
+ */
+async function matchGuarded<T, E, A, B>(
+    result: ResultAsync<T, E>,
+    label: string,
+    onOk: (value: T) => A,
+    onErr: (error: E) => B,
+    onDecode: (error: HostResponseDecodeError) => B,
+): Promise<A | B> {
+    // `.match` rejects for two reasons: the underlying `ResultAsync` rejected (a
+    // decode failure — what we want to catch), or `onOk`/`onErr` themselves threw
+    // (e.g. `unwrapHostResult`'s err path deliberately throws). Wrap the handler
+    // throws in a sentinel so the `catch` can tell them apart and only re-home a
+    // genuine underlying rejection; a handler throw is rethrown unchanged.
+    try {
+        return await result.match(
+            (value) => {
+                try {
+                    return onOk(value);
+                } catch (thrown) {
+                    throw new HandlerThrow(thrown);
+                }
+            },
+            (error) => {
+                try {
+                    return onErr(error);
+                } catch (thrown) {
+                    throw new HandlerThrow(thrown);
+                }
+            },
+        );
+    } catch (cause) {
+        if (cause instanceof HandlerThrow) throw cause.thrown;
+        return onDecode(
+            cause instanceof HostResponseDecodeError
+                ? cause
+                : new HostResponseDecodeError(label, cause),
+        );
+    }
+}
+
+/** Marks a throw that came from a caller's `onOk`/`onErr`, not the underlying `ResultAsync`. */
+class HandlerThrow {
+    constructor(readonly thrown: unknown) {}
+}
+
 /**
  * Await a host `ResultAsync`, returning its Ok value or throwing a diagnostic
  * `Error` built from the host's error payload (preserved as `cause`).
@@ -49,11 +110,18 @@ const log = createLogger("host");
  * throw convention. The flat public operations use {@link mapHostResult} instead.
  */
 export function unwrapHostResult<T, E>(result: ResultAsync<T, E>, label: string): Promise<T> {
-    return result.match(
+    return matchGuarded(
+        result,
+        label,
         (value) => value,
         (error: E) => {
             throw new Error(`${label}: ${formatHostError(error)}`, { cause: error });
         },
+        // A response the client can't decode would otherwise reject with a raw
+        // `RangeError`; throw it as a typed, named error instead.
+        (decodeError) => {
+            throw decodeError;
+        },
     );
 }
 
@@ -69,9 +137,15 @@ export function mapHostResult<T, U>(
     map: (value: T) => U,
     label: string,
 ): Promise<Result<U, HostError>> {
-    return result.match(
+    // A response the client can't decode would otherwise reject this promise
+    // with a raw `RangeError`; return it as a typed err instead, matching the
+    // `Result` contract these flat public operations advertise.
+    return matchGuarded<T, HostErrorPayload, Result<U, HostError>, Result<U, HostError>>(
+        result,
+        label,
         (value) => ok(map(value)),
         (error) => err(new HostCallFailedError(label, error)),
+        (decodeError) => err(decodeError),
     );
 }
 
@@ -271,7 +345,7 @@ export interface ResultAsync<T, E> {
 // ─────────────────────────────────────────────────────────────────────────────
 
 if (import.meta.vitest) {
-    const { test, expect } = import.meta.vitest;
+    const { test, expect, describe } = import.meta.vitest;
 
     test("getTruApi returns null outside a container", async () => {
         const api = await getTruApi();
@@ -310,4 +384,66 @@ if (import.meta.vitest) {
     test("createProofAuthorized is callable", () => {
         expect(typeof createProofAuthorized).toBe("function");
     });
+
+    // The decode boundary these two helpers share. The truapi client's real
+    // `ResultAsync` *rejects* its underlying promise on a decode failure, which
+    // `.match` surfaces as a rejected promise — modelled here by a fake whose
+    // `.match` rejects. Ok and typed-err doubles mirror neverthrow's `.match`.
+    const okLike = <T>(value: T): ResultAsync<T, never> => ({
+        match: async (onOk) => onOk(value),
+    });
+    const errLike = <E>(error: E): ResultAsync<never, E> => ({
+        match: async (_onOk, onErr) => onErr(error),
+    });
+    const rejectLike = (cause: unknown): ResultAsync<never, never> => ({
+        match: () => Promise.reject(cause),
+    });
+
+    describe("mapHostResult decode boundary", () => {
+        test("a decode rejection becomes err(HostResponseDecodeError) naming the call", async () => {
+            const cause = new RangeError("Offset is outside the bounds of the DataView");
+            const result = await mapHostResult(rejectLike(cause), (v) => v, "createRingVRFProof");
+            expect(result.ok).toBe(false);
+            if (!result.ok) {
+                expect(result.error).toBeInstanceOf(HostResponseDecodeError);
+                expect((result.error as HostResponseDecodeError).call).toBe("createRingVRFProof");
+                expect((result.error as HostResponseDecodeError).cause).toBe(cause);
+            }
+        });
+
+        test("an ok value maps through", async () => {
+            const result = await mapHostResult(okLike(41), (v: number) => v + 1, "getUserId");
+            expect(result.ok && result.value).toBe(42);
+        });
+
+        test("a typed host err becomes HostCallFailedError, not a decode error", async () => {
+            const result = await mapHostResult(errLike({ tag: "Denied" }), (v) => v, "getUserId");
+            expect(result.ok).toBe(false);
+            if (!result.ok) {
+                expect(result.error).toBeInstanceOf(HostCallFailedError);
+                expect(result.error).not.toBeInstanceOf(HostResponseDecodeError);
+            }
+        });
+    });
+
+    describe("unwrapHostResult decode boundary", () => {
+        test("a decode rejection throws HostResponseDecodeError naming the call", async () => {
+            const cause = new RangeError("Offset is outside the bounds of the DataView");
+            await expect(unwrapHostResult(rejectLike(cause), "signVrf")).rejects.toMatchObject({
+                name: "HostResponseDecodeError",
+                call: "signVrf",
+                cause,
+            });
+        });
+
+        test("an ok value passes through", async () => {
+            expect(await unwrapHostResult(okLike("hi"), "getUserId")).toBe("hi");
+        });
+
+        test("a typed host err still throws a diagnostic Error, not a decode error", async () => {
+            await expect(
+                unwrapHostResult(errLike({ tag: "Denied" }), "getUserId"),
+            ).rejects.not.toBeInstanceOf(HostResponseDecodeError);
+        });
+    });
 }

package/dist/chunk-GDXSV7JV.js

@@ -1,50 +0,0 @@
-import { isCorrectEnvironment as isCorrectEnvironment$1, getClientSync as getClientSync$1 } from '@parity/truapi/sandbox';
-
-// src/transport.ts
-var clientOverride = null;
-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."
-    );
-  }
-  clientOverride = client;
-}
-function getClientSync() {
-  return clientOverride ?? getClientSync$1();
-}
-function isCorrectEnvironment() {
-  return clientOverride !== null || isCorrectEnvironment$1();
-}
-async function getClient() {
-  return getClientSync();
-}
-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 { getClient, isCorrectEnvironment, setTruApiClient, subscribeWithInterrupt };
-//# sourceMappingURL=chunk-GDXSV7JV.js.map
-//# sourceMappingURL=chunk-GDXSV7JV.js.map

package/dist/chunk-GDXSV7JV.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/transport.ts"],"names":["sandboxGetClientSync","sandboxIsCorrectEnvironment"],"mappings":";;;AA8BA,IAAI,cAAA,GAAsC,IAAA;AAE1C,SAAS,iBAAA,GAA6B;AAClC,EAAA,IAAI;AAIA,IAAA,OAAO,OAAA,CAAQ,IAAI,QAAA,KAAa,YAAA;AAAA,EACpC,CAAA,CAAA,MAAQ;AAEJ,IAAA,OAAO,KAAA;AAAA,EACX;AACJ;AAYO,SAAS,gBAAgB,MAAA,EAAmC;AAC/D,EAAA,IAAI,MAAA,KAAW,IAAA,IAAQ,iBAAA,EAAkB,EAAG;AACxC,IAAA,OAAA,CAAQ,IAAA;AAAA,MACJ;AAAA,KACJ;AAAA,EACJ;AACA,EAAA,cAAA,GAAiB,MAAA;AACrB;AAMO,SAAS,aAAA,GAAqC;AACjD,EAAA,OAAO,kBAAkBA,eAAA,EAAqB;AAClD;AAMO,SAAS,oBAAA,GAAgC;AAC5C,EAAA,OAAO,cAAA,KAAmB,QAAQC,sBAAA,EAA4B;AAClE;AAMA,eAAsB,SAAA,GAA0C;AAC5D,EAAA,OAAO,aAAA,EAAc;AACzB;AAUO,SAAS,sBAAA,CACZ,YACA,MAAA,EACqB;AACrB,EAAA,IAAI,iBAAA;AACJ,EAAA,MAAM,GAAA,GAAM,WAAW,SAAA,CAAU;AAAA,IAC7B,IAAA,EAAM,MAAA;AAAA,IACN,KAAA,EAAO,CAAC,MAAA,KAAW,iBAAA,GAAoB,MAAM,CAAA;AAAA,IAC7C,QAAA,EAAU,MAAM,iBAAA;AAAoB,GACvC,CAAA;AACD,EAAA,OAAO;AAAA,IACH,gBAAgB,GAAA,CAAI,cAAA;AAAA,IACpB,WAAA,EAAa,MAAM,GAAA,CAAI,WAAA,EAAY;AAAA,IACnC,WAAA,EAAa,CAAC,QAAA,KAAa;AACvB,MAAA,iBAAA,GAAoB,QAAA;AACpB,MAAA,OAAO,MAAM;AACT,QAAA,IAAI,iBAAA,KAAsB,UAAU,iBAAA,GAAoB,MAAA;AAAA,MAC5D,CAAA;AAAA,IACJ;AAAA,GACJ;AACJ","file":"chunk-GDXSV7JV.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 and the lazily-built, cached client come from\n * `@parity/truapi/sandbox`; this module layers the product-sdk-specific glue on\n * top — an async {@link getClient} accessor and {@link subscribeWithInterrupt},\n * which 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    getClientSync as sandboxGetClientSync,\n    isCorrectEnvironment as sandboxIsCorrectEnvironment,\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\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 */\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    clientOverride = client;\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 * 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(\"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"]}