@parity/product-sdk-host 0.11.0 → 0.12.0

package/src/payments.ts

@@ -1,61 +1,91 @@
 // Copyright 2026 Parity Technologies (UK) Ltd.
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Wrapper for the host's payment manager (RFC-0006).
+ * Wrapper for the host's payment manager (RFC-0006), backed by
+ * `truApi.payment.*`.
  *
- * Shipped flat-in-host rather than as `getTruApi().payment.*` because the
- * upstream JS `hostApi` is itself a flat object - there is no `.payment`
- * accessor to mirror. A flat `getPaymentManager()` matches the singleton
- * pattern already used by {@link getPreimageManager},
- * {@link getHostLocalStorage}, and {@link getAccountsProvider}.
- *
- * Returns the shared `paymentManager` singleton from
- * `@novasamatech/host-api-wrapper` (not a fresh `createPaymentManager()`
- * instance) so callers share one wrapper + hostApi closure across the app.
- *
- * Distinct from the CoinPayment / merchant-payments surface tracked under
- * `@parity/product-sdk-merchant-payments` (RFC-0017). RFC-0006 is the
- * user-initiated balance / top-up / payment-request flow; RFC-0017 is the
- * merchant-initiated checkout flow.
+ * 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.
  *
  * @module
  */
 
-import { createLogger } from "@parity/product-sdk-logger";
-
 import type {
-    PaymentBalance as NovasamaPaymentBalance,
-    PaymentStatus as NovasamaPaymentStatus,
-    TopUpSource as NovasamaTopUpSource,
-    paymentManager,
-} from "@novasamatech/host-api-wrapper";
-
-const log = createLogger("host:payments");
-
-/** Available balance for the user's payment account. Re-exported from `@novasamatech/host-api-wrapper`. */
-export type PaymentBalance = NovasamaPaymentBalance;
+    Balance,
+    PaymentPurseId,
+    HexString,
+    HostPaymentBalanceSubscribeItem,
+    HostPaymentStatusSubscribeItem,
+    PaymentTopUpSource,
+    TrUApiClient,
+} from "@parity/truapi";
 
-/** Status of an in-flight payment request. Re-exported from `@novasamatech/host-api-wrapper`. */
-export type PaymentStatus = NovasamaPaymentStatus;
-
-/** Source for {@link PaymentManager.topUp}. Re-exported from `@novasamatech/host-api-wrapper`. */
-export type TopUpSource = NovasamaTopUpSource;
+import { getClient, subscribeWithInterrupt } from "./transport.js";
+import { unwrapHostResult } from "./truapi.js";
+import type { HostSubscription } from "./types.js";
 
 /**
  * Payment manager handle. Exposes balance subscription, top-up, payment
- * requests, and payment status subscription.
+ * requests, and payment-status subscription.
  *
- * Type identical to `paymentManager` from `@novasamatech/host-api-wrapper`.
+ * The balance / status / top-up-source shapes are `@parity/truapi`'s
+ * `HostPaymentBalanceSubscribeItem`, `HostPaymentStatusSubscribeItem`, and
+ * `PaymentTopUpSource` — used directly rather than re-aliased.
  */
-export type PaymentManager = typeof paymentManager;
+export interface PaymentManager {
+    subscribeBalance(
+        callback: (balance: HostPaymentBalanceSubscribeItem) => void,
+        purse?: PaymentPurseId,
+    ): HostSubscription;
+    topUp(amount: Balance, source: PaymentTopUpSource, into?: PaymentPurseId): Promise<void>;
+    requestPayment(
+        amount: Balance,
+        destination: HexString,
+        from?: PaymentPurseId,
+    ): Promise<{ id: string }>;
+    subscribePaymentStatus(
+        paymentId: string,
+        callback: (status: HostPaymentStatusSubscribeItem) => void,
+    ): HostSubscription;
+}
+
+/** Build a {@link PaymentManager} over a TruAPI client's `payment` domain. */
+function adaptPaymentManager(client: TrUApiClient): PaymentManager {
+    const payment = client.payment;
+    return {
+        subscribeBalance(callback, purse) {
+            return subscribeWithInterrupt(
+                payment.balanceSubscribe({ request: { purse } }),
+                callback,
+            );
+        },
+        topUp(amount, source, into) {
+            return unwrapHostResult(
+                payment.topUp({ into, amount, source }),
+                "payment topUp failed",
+            );
+        },
+        async requestPayment(amount, destination, from) {
+            const response = await unwrapHostResult(
+                payment.request({ from, amount, destination }),
+                "payment requestPayment failed",
+            );
+            return { id: response.id };
+        },
+        subscribePaymentStatus(paymentId, callback) {
+            return subscribeWithInterrupt(
+                payment.statusSubscribe({ request: { paymentId } }),
+                callback,
+            );
+        },
+    };
+}
 
 /**
- * Get the host payment manager.
- *
- * Returns the shared `paymentManager` singleton from
- * `@novasamatech/host-api-wrapper`, or `null` if the package is unavailable
- * (running outside a host container or the optional peer dep isn't
- * installed).
+ * Get the host payment manager, backed by `truApi.payment.*`. Returns `null`
+ * when running outside a host container.
  *
  * @returns The payment manager, or `null` if unavailable.
  *
@@ -66,35 +96,21 @@ export type PaymentManager = typeof paymentManager;
  * const payments = await getPaymentManager();
  * if (payments) {
  *   const sub = payments.subscribeBalance((b) => { ... });
- *   await payments.topUp(1_000_000n, { type: "productAccount", derivationIndex: 0 });
- *   const destination = new Uint8Array(32);
- *   const { id } = await payments.requestPayment(500n, destination);
+ *   await payments.topUp(1_000_000n, { tag: "ProductAccount", value: { derivationIndex: 0 } });
+ *   const { id } = await payments.requestPayment(500n, "0x…");
  *   sub.unsubscribe();
  * }
  * ```
  */
 export async function getPaymentManager(): Promise<PaymentManager | null> {
-    try {
-        const sdk = await import("@novasamatech/host-api-wrapper");
-        return sdk.paymentManager;
-    } catch (err) {
-        log.debug("getPaymentManager unavailable", err);
-        return null;
-    }
+    const client = await getClient();
+    return client ? adaptPaymentManager(client) : null;
 }
 
 if (import.meta.vitest) {
     const { test, expect } = import.meta.vitest;
 
-    test("getPaymentManager returns manager with full RFC-0006 surface when SDK is available", async () => {
-        const payments = await getPaymentManager();
-        if (payments === null) {
-            // Acceptable: SDK couldn't load (e.g. peer dep missing in some envs).
-            return;
-        }
-        expect(typeof payments.subscribeBalance).toBe("function");
-        expect(typeof payments.topUp).toBe("function");
-        expect(typeof payments.requestPayment).toBe("function");
-        expect(typeof payments.subscribePaymentStatus).toBe("function");
+    test("getPaymentManager returns null outside a container", async () => {
+        expect(await getPaymentManager()).toBeNull();
     });
 }

package/src/permissions.ts

@@ -3,71 +3,68 @@
 /**
  * Higher-level wrappers for the host's single-permission flows.
  *
- * `hostApi.permission` / `hostApi.devicePermission` take a versioned
- * envelope (`enumValue("v1", ...)`) and return a neverthrow `ResultAsync`
- * of an unwrapped versioned response. Consumers rebuild that wrap/unwrap
- * dance every time. {@link requestPermission} and
- * {@link requestDevicePermission} collapse it to one-liners that match the
- * shape of {@link requestResourceAllocation} (throws on error, returns
- * the unwrapped payload on success).
+ * `truApi.permissions.requestRemotePermission` / `requestDevicePermission`
+ * return a neverthrow `ResultAsync` of a `{ granted }` response.
+ * {@link requestPermission} and {@link requestDevicePermission} collapse that
+ * to one-liners returning a `Result<boolean, HostError>` — the granted flag on
+ * success, a typed {@link HostError} on the `err` channel.
  *
  * @module
  */
 
+import type { HostDevicePermissionRequest } from "@parity/truapi";
 import { createLogger } from "@parity/product-sdk-logger";
 
-import type { CodecType } from "@novasamatech/host-api";
-import type { DevicePermission as DevicePermissionCodec } from "@novasamatech/host-api";
-
-import { enumValue, formatHostError, getTruApi, type RemotePermission } from "./truapi.js";
+import { type HostError, HostUnavailableError } from "./errors.js";
+import { type Result, err } from "./result.js";
+import { getTruApi, mapHostResult, type RemotePermission } from "./truapi.js";
 
 const log = createLogger("host:permissions");
 
 /**
  * Device permission the dapp can ask the host to grant via
- * {@link requestDevicePermission}.
- *
- * Derived from the upstream codec so variant renames surface as compile
- * errors, not runtime failures.
+ * {@link requestDevicePermission}. A string union (`"Camera"`, `"Microphone"`,
+ * …) re-exported from `@parity/truapi`.
  */
-export type DevicePermissionKind = CodecType<typeof DevicePermissionCodec>;
+export type DevicePermissionKind = HostDevicePermissionRequest;
 
 /**
- * Alias of {@link RemotePermission} matching the upstream
- * `@novasamatech/host-api-wrapper` name. Use either freely.
+ * Legacy alias of {@link RemotePermission}, kept for back-compat with code that
+ * used the older name. Use either freely.
  */
 export type RemotePermissionItem = RemotePermission;
 
 /**
  * Request a single remote permission from the host.
  *
- * Builds the `v1` envelope, calls `hostApi.permission`, unwraps the response,
- * and returns the host's boolean granted/denied outcome.
+ * Calls `truApi.permissions.requestRemotePermission` and returns the host's
+ * boolean granted/denied outcome.
  *
  * @param permission - The remote permission to request.
- * @returns `true` if the host granted the permission, `false` if denied.
- * @throws If the host is unavailable or the request fails.
+ * @returns `ok(true)` if the host granted the permission, `ok(false)` if denied,
+ *   or `err(HostUnavailableError | HostCallFailedError)`.
  *
  * @example
  * ```ts
- * const granted = await requestPermission({ tag: "ChainSubmit", value: undefined });
- * if (!granted) {
+ * const r = await requestPermission({ tag: "ChainSubmit", value: undefined });
+ * if (!r.ok || !r.value) {
  *   tellUserToReconnect();
  * }
  * ```
  */
-export async function requestPermission(permission: RemotePermission): Promise<boolean> {
+export async function requestPermission(
+    permission: RemotePermission,
+): Promise<Result<boolean, HostError>> {
     const truApi = await getTruApi();
     if (!truApi) {
-        throw new Error("requestPermission: TruAPI unavailable");
+        return err(new HostUnavailableError("requestPermission: TruAPI unavailable"));
     }
     log.debug("requestPermission", { tag: permission.tag });
 
-    return await truApi.permission(enumValue("v1", permission)).match(
-        (envelope: { tag: "v1"; value: boolean }) => envelope.value,
-        (err: unknown) => {
-            throw new Error(`requestPermission failed: ${formatHostError(err)}`, { cause: err });
-        },
+    return mapHostResult(
+        truApi.permissions.requestRemotePermission({ permission }),
+        (response) => response.granted,
+        "requestPermission failed",
     );
 }
 
@@ -75,56 +72,57 @@ export async function requestPermission(permission: RemotePermission): Promise<b
  * Request a single device permission (camera, microphone, etc.) from the
  * host.
  *
- * Builds the `v1` envelope, calls `hostApi.devicePermission`, unwraps the
- * response, and returns the host's boolean granted/denied outcome.
+ * Calls `truApi.permissions.requestDevicePermission` and returns the host's
+ * boolean granted/denied outcome.
  *
  * @param permission - The device permission to request.
- * @returns `true` if the host granted the permission, `false` if denied.
- * @throws If the host is unavailable or the request fails.
+ * @returns `ok(true)` if the host granted the permission, `ok(false)` if denied,
+ *   or `err(HostUnavailableError | HostCallFailedError)`.
  *
  * @example
  * ```ts
- * const granted = await requestDevicePermission("Camera");
- * if (!granted) {
+ * const r = await requestDevicePermission("Camera");
+ * if (!r.ok || !r.value) {
  *   showCameraDeniedMessage();
  * }
  * ```
  */
-export async function requestDevicePermission(permission: DevicePermissionKind): Promise<boolean> {
+export async function requestDevicePermission(
+    permission: DevicePermissionKind,
+): Promise<Result<boolean, HostError>> {
     const truApi = await getTruApi();
     if (!truApi) {
-        throw new Error("requestDevicePermission: TruAPI unavailable");
+        return err(new HostUnavailableError("requestDevicePermission: TruAPI unavailable"));
     }
     log.debug("requestDevicePermission", { permission });
 
-    return await truApi.devicePermission(enumValue("v1", permission)).match(
-        (envelope: { tag: "v1"; value: boolean }) => envelope.value,
-        (err: unknown) => {
-            throw new Error(`requestDevicePermission failed: ${formatHostError(err)}`, {
-                cause: err,
-            });
-        },
+    return mapHostResult(
+        truApi.permissions.requestDevicePermission(permission),
+        (response) => response.granted,
+        "requestDevicePermission failed",
     );
 }
 
 if (import.meta.vitest) {
     const { test, expect, describe, vi } = import.meta.vitest;
 
+    function okAsync<T>(value: T) {
+        return { match: async (onOk: (v: T) => unknown) => onOk(value) };
+    }
+    function errAsync<E>(error: E) {
+        return {
+            match: async (_onOk: (v: unknown) => unknown, onErr: (e: E) => unknown) => onErr(error),
+        };
+    }
+
     async function withMockedTruApi<T>(
-        bridge: {
-            permission?: (req: unknown) => unknown;
-            devicePermission?: (req: unknown) => unknown;
-        } | null,
+        client: unknown,
         fn: (mod: typeof import("./permissions.js")) => Promise<T>,
     ): Promise<T> {
         vi.resetModules();
         vi.doMock("./truapi.js", async (importOriginal) => {
             const original = await importOriginal<typeof import("./truapi.js")>();
-            return {
-                ...original,
-                getTruApi: async () => bridge,
-                enumValue: (version: string, value: unknown) => ({ tag: version, value }),
-            };
+            return { ...original, getTruApi: async () => client };
         });
         try {
             const mod = await import("./permissions.js");
@@ -136,97 +134,101 @@ if (import.meta.vitest) {
     }
 
     describe("requestPermission", () => {
-        test("throws when TruAPI is unavailable", async () => {
+        test("returns err(HostUnavailableError) when TruAPI is unavailable", async () => {
             await withMockedTruApi(null, async (mod) => {
-                await expect(
-                    mod.requestPermission({ tag: "ChainSubmit", value: undefined }),
-                ).rejects.toThrow(/TruAPI unavailable/);
+                const result = await mod.requestPermission({
+                    tag: "ChainSubmit",
+                    value: undefined,
+                });
+                expect(result.ok).toBe(false);
+                if (!result.ok) {
+                    expect(result.error.name).toBe("HostUnavailableError");
+                }
             });
         });
 
-        test("unwraps the v1 boolean outcome", async () => {
+        test("returns ok with the granted flag", async () => {
             await withMockedTruApi(
                 {
-                    permission: vi.fn().mockReturnValue({
-                        match: async (onOk: (v: unknown) => unknown) =>
-                            onOk({ tag: "v1", value: true }),
-                    }),
+                    permissions: {
+                        requestRemotePermission: vi.fn(() => okAsync({ granted: true })),
+                    },
                 },
                 async (mod) => {
-                    const granted = await mod.requestPermission({
+                    const result = await mod.requestPermission({
                         tag: "ChainSubmit",
                         value: undefined,
                     });
-                    expect(granted).toBe(true);
+                    expect(result).toEqual({ ok: true, value: true });
                 },
             );
         });
 
-        test("wraps host errors with a diagnostic message", async () => {
+        test("wraps host errors in err(HostCallFailedError) with a diagnostic message", async () => {
             await withMockedTruApi(
                 {
-                    permission: vi.fn().mockReturnValue({
-                        match: async (
-                            _onOk: (v: unknown) => unknown,
-                            onErr: (e: unknown) => unknown,
-                        ) =>
-                            onErr({
-                                tag: "v1",
-                                value: { name: "GenericError", message: "boom" },
-                            }),
-                    }),
+                    permissions: {
+                        requestRemotePermission: vi.fn(() => errAsync({ reason: "boom" })),
+                    },
                 },
                 async (mod) => {
-                    await expect(
-                        mod.requestPermission({ tag: "ChainSubmit", value: undefined }),
-                    ).rejects.toThrow(/requestPermission failed: GenericError: boom/);
+                    const result = await mod.requestPermission({
+                        tag: "ChainSubmit",
+                        value: undefined,
+                    });
+                    expect(result.ok).toBe(false);
+                    if (!result.ok) {
+                        expect(result.error.name).toBe("HostCallFailedError");
+                        expect(result.error.message).toMatch(/requestPermission failed: boom/);
+                    }
                 },
             );
         });
     });
 
     describe("requestDevicePermission", () => {
-        test("throws when TruAPI is unavailable", async () => {
+        test("returns err(HostUnavailableError) when TruAPI is unavailable", async () => {
             await withMockedTruApi(null, async (mod) => {
-                await expect(mod.requestDevicePermission("Camera")).rejects.toThrow(
-                    /TruAPI unavailable/,
-                );
+                const result = await mod.requestDevicePermission("Camera");
+                expect(result.ok).toBe(false);
+                if (!result.ok) {
+                    expect(result.error.name).toBe("HostUnavailableError");
+                }
             });
         });
 
-        test("unwraps the v1 boolean outcome", async () => {
+        test("returns ok with the granted flag", async () => {
             await withMockedTruApi(
                 {
-                    devicePermission: vi.fn().mockReturnValue({
-                        match: async (onOk: (v: unknown) => unknown) =>
-                            onOk({ tag: "v1", value: true }),
-                    }),
+                    permissions: {
+                        requestDevicePermission: vi.fn(() => okAsync({ granted: true })),
+                    },
                 },
                 async (mod) => {
-                    const granted = await mod.requestDevicePermission("Camera");
-                    expect(granted).toBe(true);
+                    expect(await mod.requestDevicePermission("Camera")).toEqual({
+                        ok: true,
+                        value: true,
+                    });
                 },
             );
         });
 
-        test("wraps host errors with a diagnostic message", async () => {
+        test("wraps host errors in err(HostCallFailedError) with a diagnostic message", async () => {
             await withMockedTruApi(
                 {
-                    devicePermission: vi.fn().mockReturnValue({
-                        match: async (
-                            _onOk: (v: unknown) => unknown,
-                            onErr: (e: unknown) => unknown,
-                        ) =>
-                            onErr({
-                                tag: "v1",
-                                value: { name: "GenericError", message: "boom" },
-                            }),
-                    }),
+                    permissions: {
+                        requestDevicePermission: vi.fn(() => errAsync({ reason: "boom" })),
+                    },
                 },
                 async (mod) => {
-                    await expect(mod.requestDevicePermission("Camera")).rejects.toThrow(
-                        /requestDevicePermission failed: GenericError: boom/,
-                    );
+                    const result = await mod.requestDevicePermission("Camera");
+                    expect(result.ok).toBe(false);
+                    if (!result.ok) {
+                        expect(result.error.name).toBe("HostCallFailedError");
+                        expect(result.error.message).toMatch(
+                            /requestDevicePermission failed: boom/,
+                        );
+                    }
                 },
             );
         });

package/src/result.ts

@@ -0,0 +1,56 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * A lightweight tagged `Result` type for the host public API.
+ *
+ * Host functions return `Promise<Result<T, HostError>>` rather than throwing, so
+ * consumers get typed errors on the `err` channel instead of opaque thrown
+ * `Error`s. The shape is intentionally identical to the one
+ * `@parity/product-sdk-signer` exposes (`{ ok: true; value } | { ok: false; error }`),
+ * so the two layers compose with no adapter — host's `Result` flows straight into
+ * the signer's pattern matching.
+ *
+ * NOTE: host owns its own copy because the dependency edge runs `signer → host`,
+ * so host cannot import the signer's definition. If a third package ever needs
+ * this shape, extract it into a shared `@parity/product-sdk-result` package and
+ * have both depend on that instead of duplicating.
+ *
+ * @module
+ */
+
+/** A value that is either a success (`ok`) carrying `T`, or a failure (`err`) carrying `E`. */
+export type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };
+
+/** Create a successful {@link Result}. */
+export function ok<T>(value: T): Result<T, never> {
+    return { ok: true, value };
+}
+
+/** Create a failed {@link Result}. */
+export function err<E>(error: E): Result<never, E> {
+    return { ok: false, error };
+}
+
+if (import.meta.vitest) {
+    const { test, expect, describe } = import.meta.vitest;
+
+    describe("ok", () => {
+        test("produces an ok result with value", () => {
+            const result = ok(42);
+            expect(result.ok).toBe(true);
+            expect(result).toEqual({ ok: true, value: 42 });
+        });
+
+        test("works with null value", () => {
+            expect(ok(null)).toEqual({ ok: true, value: null });
+        });
+    });
+
+    describe("err", () => {
+        test("produces an error result", () => {
+            const result = err("boom");
+            expect(result.ok).toBe(false);
+            expect(result).toEqual({ ok: false, error: "boom" });
+        });
+    });
+}