@parity/product-sdk-host 0.13.0 → 0.14.1

package/src/papi-provider.ts

@@ -6,11 +6,9 @@
  * This is a backport of `@novasamatech/host-api-wrapper`'s
  * `createPapiProvider` (`dist/papiProvider.js`) into product-sdk, with the
  * call layer swapped from the novasama `hostApi` to the
- * `@parity/truapi` client. The JSON-RPC ↔ chainHead bridge — request dispatch,
- * the `chainHead_v1_followEvent` notification synthesis, the synthetic
- * follow-subscription ids, and the operation/broadcast bookkeeping — is carried
- * over from the upstream module; only the per-method transport calls and their
- * error/response unwrapping are re-pointed at `truApi.chain.*`.
+ * `@parity/truapi` client. The JSON-RPC ↔ chainHead bridge handles request
+ * dispatch, `chainHead_v1_followEvent` notification synthesis, and operation /
+ * broadcast bookkeeping over the structured `truApi.chain.*` methods.
  *
  * **Why a bridge at all.** PAPI speaks the JSON-RPC `chainHead`/`chainSpec`/
  * `transaction` API; the host exposes the same operations as structured,
@@ -51,8 +49,7 @@ import type {
 import { createLogger } from "@parity/product-sdk-logger";
 
 import { formatHostError } from "./errors.js";
-import { subscribeWithInterrupt } from "./transport.js";
-import type { HostSubscription } from "./types.js";
+import { subscribeWithInterrupt, type TransportSubscription } from "./transport.js";
 
 const log = createLogger("host:papi");
 
@@ -195,11 +192,8 @@ export function createHostPapiProvider(
     const chain = client.chain;
 
     return (onMessage: (message: JsonRpcMessage) => void): JsonRpcConnection => {
-        const activeFollows = new Map<string, HostSubscription>();
+        const activeFollows = new Map<string, TransportSubscription>();
         const activeBroadcasts = new Set<string>();
-        let nextSubId = 0;
-
-        const getNextSubId = () => `follow_${nextSubId++}`;
 
         function sendJsonRpcResponse(id: JsonRpcRequest["id"], result: unknown): void {
             onMessage({ jsonrpc: "2.0", id, result } as JsonRpcMessage);
@@ -227,31 +221,55 @@ export function createHostPapiProvider(
             switch (method) {
                 case "chainHead_v1_follow": {
                     const [withRuntime] = params as [boolean];
-                    const syntheticSubId = getNextSubId();
                     // The Stop branch unsubscribes its own host subscription, but the
                     // handle is this call's return value — the ref breaks that
                     // chicken-and-egg. (Releasing before forwarding the Stop is just
                     // cleanup; the consumer's synchronous refollow gets a fresh wire
                     // subscription either way.)
-                    const ref: { handle?: HostSubscription } = {};
+                    const ref: { handle?: TransportSubscription } = {};
+                    const pendingItems: RemoteChainHeadFollowItem[] = [];
+                    const forwardItem = (
+                        followSubscriptionId: string,
+                        item: RemoteChainHeadFollowItem,
+                    ) => {
+                        if (item.tag === "Stop" && activeFollows.delete(followSubscriptionId)) {
+                            ref.handle?.unsubscribe();
+                        }
+                        sendFollowEvent(followSubscriptionId, convertFollowEventToJsonRpc(item));
+                    };
                     ref.handle = subscribeWithInterrupt(
                         chain.followHeadSubscribe({ request: { genesisHash, withRuntime } }),
                         (item) => {
-                            if (item.tag === "Stop" && activeFollows.delete(syntheticSubId)) {
-                                ref.handle?.unsubscribe();
+                            const followSubscriptionId = ref.handle?.subscriptionId;
+                            if (!followSubscriptionId) {
+                                pendingItems.push(item);
+                                return;
                             }
-                            sendFollowEvent(syntheticSubId, convertFollowEventToJsonRpc(item));
+                            forwardItem(followSubscriptionId, item);
                         },
                     );
+                    const followSubscriptionId = ref.handle.subscriptionId;
+                    if (!followSubscriptionId) {
+                        ref.handle.unsubscribe();
+                        sendJsonRpcError(
+                            id,
+                            JSON_RPC_INTERNAL_ERROR,
+                            "Host follow subscription did not start",
+                        );
+                        break;
+                    }
                     // A transport interrupt/close ends the stream without a Stop
                     // item; synthesize one so the consumer refollows.
                     ref.handle.onInterrupt(() => {
-                        if (activeFollows.delete(syntheticSubId)) {
-                            sendFollowEvent(syntheticSubId, { event: "stop" });
+                        if (activeFollows.delete(followSubscriptionId)) {
+                            sendFollowEvent(followSubscriptionId, { event: "stop" });
                         }
                     });
-                    activeFollows.set(syntheticSubId, ref.handle);
-                    sendJsonRpcResponse(id, syntheticSubId);
+                    activeFollows.set(followSubscriptionId, ref.handle);
+                    sendJsonRpcResponse(id, followSubscriptionId);
+                    for (const item of pendingItems) {
+                        forwardItem(followSubscriptionId, item);
+                    }
                     break;
                 }
                 case "chainHead_v1_unfollow": {
@@ -475,11 +493,15 @@ if (import.meta.vitest) {
         errors?: Record<string, unknown>;
         /** Unsubscribe spy used by the follow subscription (defaults to a fresh `vi.fn()`). */
         unsubscribe?: () => void;
+        /** Item emitted synchronously while the transport subscription starts. */
+        initialItem?: unknown;
         captureObserver?: (observer: {
             next: (i: unknown) => void;
             error: (e: unknown) => void;
             complete: () => void;
         }) => void;
+        /** Transport request id assigned to the follow subscription. */
+        subscriptionId?: string;
     }) {
         const okMatch = (value: unknown) => ({
             match: (ok: (v: unknown) => unknown, _err: (e: unknown) => unknown) => ok(value),
@@ -501,7 +523,13 @@ if (import.meta.vitest) {
                         complete: () => void;
                     }) => {
                         opts.captureObserver?.(observer);
-                        return { unsubscribe: opts.unsubscribe ?? vi.fn() };
+                        if (opts.initialItem !== undefined) {
+                            observer.next(opts.initialItem);
+                        }
+                        return {
+                            subscriptionId: opts.subscriptionId ?? "p:41",
+                            unsubscribe: opts.unsubscribe ?? vi.fn(),
+                        };
                     },
                     [Symbol.observable as symbol]() {
                         return this;
@@ -530,11 +558,14 @@ if (import.meta.vitest) {
         } as unknown as TrUApiClient;
     }
 
-    test("follow returns a synthetic id and forwards translated events", () => {
+    test("follow preserves the transport id for events and follow-up requests", () => {
         let observer:
             | { next: (i: unknown) => void; error: (e: unknown) => void; complete: () => void }
             | undefined;
+        const calls: Array<[string, unknown]> = [];
         const client = makeFakeClient({
+            subscriptionId: "p:17",
+            onCall: (method, args) => calls.push([method, args]),
             captureObserver: (o) => {
                 observer = o;
             },
@@ -545,8 +576,7 @@ if (import.meta.vitest) {
         const conn = provider((m) => messages.push(m));
 
         conn.send({ jsonrpc: "2.0", id: 1, method: "chainHead_v1_follow", params: [true] });
-        // The follow response carries the synthetic subscription id.
-        expect(messages[0]).toEqual({ jsonrpc: "2.0", id: 1, result: "follow_0" });
+        expect(messages[0]).toEqual({ jsonrpc: "2.0", id: 1, result: "p:17" });
 
         // A typed BestBlockChanged item becomes a chainHead_v1_followEvent.
         observer?.next({ tag: "BestBlockChanged", value: { bestBlockHash: "0xbeef" } });
@@ -554,10 +584,48 @@ if (import.meta.vitest) {
             jsonrpc: "2.0",
             method: "chainHead_v1_followEvent",
             params: {
-                subscription: "follow_0",
+                subscription: "p:17",
                 result: { event: "bestBlockChanged", bestBlockHash: "0xbeef" },
             },
         });
+
+        conn.send({
+            jsonrpc: "2.0",
+            id: 2,
+            method: "chainHead_v1_header",
+            params: ["p:17", "0xbeef"],
+        });
+        expect(calls).toContainEqual([
+            "getHeadHeader",
+            {
+                genesisHash: "0xfeed",
+                followSubscriptionId: "p:17",
+                hash: "0xbeef",
+            },
+        ]);
+    });
+
+    test("follow buffers an item emitted while the transport subscription starts", () => {
+        const client = makeFakeClient({
+            subscriptionId: "p:18",
+            initialItem: { tag: "BestBlockChanged", value: { bestBlockHash: "0xbeef" } },
+        });
+        const messages: JsonRpcMessage[] = [];
+        const conn = createHostPapiProvider(client, "0xfeed")((message) => messages.push(message));
+
+        conn.send({ jsonrpc: "2.0", id: 1, method: "chainHead_v1_follow", params: [true] });
+
+        expect(messages).toEqual([
+            { jsonrpc: "2.0", id: 1, result: "p:18" },
+            {
+                jsonrpc: "2.0",
+                method: "chainHead_v1_followEvent",
+                params: {
+                    subscription: "p:18",
+                    result: { event: "bestBlockChanged", bestBlockHash: "0xbeef" },
+                },
+            },
+        ]);
     });
 
     test("chainSpec_v1_properties parses the JSON-encoded properties string", () => {
@@ -628,7 +696,7 @@ if (import.meta.vitest) {
         expect(messages[1]).toEqual({
             jsonrpc: "2.0",
             method: "chainHead_v1_followEvent",
-            params: { subscription: "follow_0", result: { event: "stop" } },
+            params: { subscription: "p:41", result: { event: "stop" } },
         });
     });
 

package/src/payments.ts

@@ -5,16 +5,17 @@
  * `truApi.payment.*`.
  *
  * Exposes balance subscription, top-up, payment requests, and payment-status
- * subscription. Distinct from the CoinPayment / merchant-payments surface
- * (RFC-0017): RFC-0006 is the user-initiated balance / top-up / payment-request
- * flow.
+ * subscription. The flow is distinct from the CoinPayment / merchant-payments
+ * surface (RFC-0017) — RFC-0006 is the user-initiated balance / top-up /
+ * payment-request flow — but both operate on the same CoinPayment purses,
+ * hence the shared `CoinPaymentPurseId` (omitted = the main purse).
  *
  * @module
  */
 
 import type {
     Balance,
-    PaymentPurseId,
+    CoinPaymentPurseId,
     HexString,
     HostPaymentBalanceSubscribeItem,
     HostPaymentStatusSubscribeItem,
@@ -37,13 +38,13 @@ import type { HostSubscription } from "./types.js";
 export interface PaymentManager {
     subscribeBalance(
         callback: (balance: HostPaymentBalanceSubscribeItem) => void,
-        purse?: PaymentPurseId,
+        purse?: CoinPaymentPurseId,
     ): HostSubscription;
-    topUp(amount: Balance, source: PaymentTopUpSource, into?: PaymentPurseId): Promise<void>;
+    topUp(amount: Balance, source: PaymentTopUpSource, into?: CoinPaymentPurseId): Promise<void>;
     requestPayment(
         amount: Balance,
         destination: HexString,
-        from?: PaymentPurseId,
+        from?: CoinPaymentPurseId,
     ): Promise<{ id: string }>;
     subscribePaymentStatus(
         paymentId: string,

package/src/testing.ts

@@ -12,9 +12,10 @@
  *
  * Not modeled: the PAPI `chain` JSON-RPC surface behind `getHostProvider()` —
  * there's no chain-read fake, by design; the host owns RPC selection — and the
- * `chat` / `entropy` / `notifications` / `payment` / `permissions` /
- * `resourceAllocation` / `theme` domains. Touching an unmodeled domain throws a
- * descriptive error rather than failing with `undefined is not a function`.
+ * `chat` / `coinPayment` / `entropy` / `notifications` / `payment` /
+ * `permissions` / `resourceAllocation` / `theme` domains. Touching an unmodeled
+ * domain throws a descriptive error rather than failing with `undefined is not
+ * a function`.
  *
  * @packageDocumentation
  */
@@ -182,7 +183,16 @@ export function createFakeTruApiClient(options?: CreateFakeTruApiClientOptions):
             getAccountAlias: () =>
                 okAsync({ context: toHex(new Uint8Array([1])), alias: toHex(new Uint8Array([2])) }),
             getLegacyAccounts: () => okAsync({ accounts: legacyAccounts }),
-            createAccountProof: () => okAsync({ proof: signature }),
+            createAccountProof: () =>
+                okAsync({
+                    proof: signature,
+                    contextualAlias: {
+                        context: toHex(new Uint8Array([1])),
+                        alias: toHex(new Uint8Array([2])),
+                    },
+                    ringIndex: 0,
+                    ringRevision: 0,
+                }),
             connectionStatusSubscribe: () => inertObservable(),
         },
         signing: {
@@ -217,6 +227,7 @@ export function createFakeTruApiClient(options?: CreateFakeTruApiClientOptions):
         },
         chain: notModeled("chain"),
         chat: notModeled("chat"),
+        coinPayment: notModeled("coinPayment"),
         entropy: notModeled("entropy"),
         notifications: notModeled("notifications"),
         payment: notModeled("payment"),

package/src/transport.ts

@@ -19,6 +19,11 @@ import {
 
 import type { HostSubscription } from "./types.js";
 
+/** A {@link HostSubscription} carrying the transport-assigned subscription id. */
+export interface TransportSubscription extends HostSubscription {
+    readonly subscriptionId: string;
+}
+
 // Test-only override. When set — via `setTruApiClient`, exposed through
 // `@parity/product-sdk-host/testing` — every host accessor resolves this client
 // instead of the sandbox one. `null` in production, so the branches below are
@@ -91,7 +96,7 @@ export async function getClient(): Promise<TrUApiClient | null> {
 export function subscribeWithInterrupt<Item, Reason = never>(
     observable: ObservableLike<Item, Reason>,
     onNext: (item: Item) => void,
-): HostSubscription {
+): TransportSubscription {
     let interruptCallback: ((reason?: unknown) => void) | undefined;
     const sub = observable.subscribe({
         next: onNext,
@@ -99,6 +104,7 @@ export function subscribeWithInterrupt<Item, Reason = never>(
         complete: () => interruptCallback?.(),
     });
     return {
+        subscriptionId: sub.subscriptionId,
         unsubscribe: () => sub.unsubscribe(),
         onInterrupt: (callback) => {
             interruptCallback = callback;
@@ -156,4 +162,20 @@ if (import.meta.vitest) {
             process.env.NODE_ENV = original;
         }
     });
+
+    test("subscribeWithInterrupt preserves the transport subscription id", () => {
+        const observable = {
+            subscribe: () => ({
+                subscriptionId: "p:17",
+                unsubscribe: () => {},
+            }),
+            [Symbol.observable]() {
+                return this;
+            },
+        } as ObservableLike<never>;
+
+        const subscription = subscribeWithInterrupt(observable, () => {});
+
+        expect(subscription.subscriptionId).toBe("p:17");
+    });
 }

package/dist/chunk-3SWF5CWC.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/transport.ts"],"names":["sandboxGetClientSync","sandboxIsCorrectEnvironment"],"mappings":";;;AAyBA,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,EACgB;AAChB,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,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-3SWF5CWC.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// 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): HostSubscription {\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        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"]}