@parity/product-sdk-host 0.12.0 → 0.14.0

package/src/errors.ts

@@ -17,38 +17,44 @@
  *
  * @module
  */
-import type { GenericError } from "@parity/truapi";
+import type { SdkError } from "@parity/product-sdk-errors";
+import type { scale } from "@parity/truapi";
 
 /**
- * The structured error payload `@parity/truapi` surfaces on the `Err` channel of
- * a host call, once unwrapped from the versioned wire envelope. Every host error
- * union is built from these:
- *
- * - the catch-all {@link GenericError} (`{ reason }`),
- * - a unit tagged variant (`{ tag }`), or
- * - a tagged variant carrying a reason (`{ tag, value: { reason } }`).
- *
- * `GenericError` is imported from `@parity/truapi`; the `{ tag }` members are a
- * deliberate widening of truapi's per-domain named variants (the formatter is
- * tag-agnostic). truapi has no umbrella error union to import today — once it
- * exports a canonical tagged-error union from codegen, replace these local
- * members with that import so the type is protocol-sourced rather than
- * hand-widened.
+ * What a `Domain`-tagged call error carries. Widened from truapi's per-domain
+ * `Versioned*Error` types (all `{ tag: "V1", value: <domain error> }` today)
+ * so one payload type covers every call.
+ */
+type VersionedDomainError = { tag: string; value?: unknown };
+
+/**
+ * The error a host call puts on its `Err` channel — truapi's canonical
+ * {@link scale.CallErrorValue} envelope. `Denied` / `Unsupported` /
+ * `MalformedFrame` / `HostFailure` are transport-level failures; `Domain`
+ * wraps the actual per-domain error in a versioned envelope, which
+ * {@link formatHostError} digs through when rendering.
  *
- * This is the *payload* the host public API carries inside a
- * {@link HostCallFailedError} on the `err` channel of its `Result` returns — not
- * the error type consumers branch on.
+ * This is the payload {@link HostCallFailedError} carries — not the error
+ * type consumers branch on.
  */
-export type HostErrorPayload =
-    | GenericError
-    | { tag: string; value?: undefined }
-    | { tag: string; value: { reason: string } };
-
-/** Narrow an unknown `Err`-channel value to a {@link HostErrorPayload}. */
-function isHostErrorPayload(error: unknown): error is HostErrorPayload {
-    if (error == null || typeof error !== "object") return false;
-    const obj = error as Record<string, unknown>;
-    return typeof obj.reason === "string" || typeof obj.tag === "string";
+export type HostErrorPayload = scale.CallErrorValue<VersionedDomainError>;
+
+/** Narrow to a tagged-union member: `{ tag, value? }`. */
+function isTagged(value: unknown): value is { tag: string; value?: unknown } {
+    return (
+        value != null &&
+        typeof value === "object" &&
+        typeof (value as { tag?: unknown }).tag === "string"
+    );
+}
+
+/** Narrow to a reason-carrying payload — truapi's `GenericError` shape. */
+function hasReason(value: unknown): value is { reason: string } {
+    return (
+        value != null &&
+        typeof value === "object" &&
+        typeof (value as { reason?: unknown }).reason === "string"
+    );
 }
 
 /**
@@ -66,16 +72,20 @@ export function formatHostError(error: unknown): string {
     if (error instanceof Error) return error.message;
     if (typeof error === "string") return error;
 
-    if (isHostErrorPayload(error)) {
-        if ("tag" in error) {
-            // Tagged variant carrying a reason: { tag, value: { reason } }
-            if (error.value != null && typeof error.value.reason === "string") {
-                return `${error.tag}: ${error.value.reason}`;
-            }
-            // Unit tagged variant, e.g. { tag: "Full" } / { tag: "PermissionDenied" }
-            return error.tag;
+    if (isTagged(error)) {
+        // `Domain` carries the real error inside a versioned envelope — unwrap it.
+        if (error.tag === "Domain" && isTagged(error.value) && error.value.value !== undefined) {
+            return formatHostError(error.value.value);
+        }
+        // Tagged variant carrying a reason: { tag, value: { reason } }
+        if (hasReason(error.value)) {
+            return `${error.tag}: ${error.value.reason}`;
         }
-        // GenericError: { reason }
+        // Unit tagged variant, e.g. { tag: "Denied" } / { tag: "PermissionDenied" }
+        return error.tag;
+    }
+    // GenericError: { reason }
+    if (hasReason(error)) {
         return error.reason;
     }
 
@@ -93,9 +103,13 @@ export function formatHostError(error: unknown): string {
 
 /**
  * Base class for all host errors. Use `instanceof HostError` (or {@link isHostError})
- * to catch any host-related failure.
+ * to catch any host-related failure. Implements the cross-package
+ * {@link SdkError} marker so `isSdkError(e)` also recognizes it.
  */
-export class HostError extends Error {
+export class HostError extends Error implements SdkError {
+    readonly isSdkError = true as const;
+    readonly source = "host";
+
     constructor(message: string, options?: ErrorOptions) {
         super(message, options);
         this.name = "HostError";
@@ -156,7 +170,13 @@ if (import.meta.vitest) {
         });
 
         test("HostCallFailedError renders payload and preserves it", () => {
-            const payload = { tag: "PermissionDenied", value: { reason: "user said no" } };
+            const payload: HostErrorPayload = {
+                tag: "Domain",
+                value: {
+                    tag: "V1",
+                    value: { tag: "PermissionDenied", value: { reason: "user said no" } },
+                },
+            };
             const e = new HostCallFailedError("requestPermission failed", payload);
             expect(e).toBeInstanceOf(HostError);
             expect(e.payload).toBe(payload);
@@ -164,14 +184,17 @@ if (import.meta.vitest) {
             expect(e.message).toBe("requestPermission failed: PermissionDenied: user said no");
         });
 
-        test("HostCallFailedError renders a GenericError payload", () => {
-            const e = new HostCallFailedError("submit failed", { reason: "timeout" });
+        test("HostCallFailedError renders a Domain-wrapped GenericError payload", () => {
+            const e = new HostCallFailedError("submit failed", {
+                tag: "Domain",
+                value: { tag: "V1", value: { reason: "timeout" } },
+            });
             expect(e.message).toBe("submit failed: timeout");
         });
 
         test("isHostError narrows host errors only", () => {
             expect(isHostError(new HostUnavailableError())).toBe(true);
-            expect(isHostError(new HostCallFailedError("x", { reason: "y" }))).toBe(true);
+            expect(isHostError(new HostCallFailedError("x", { tag: "Denied" }))).toBe(true);
             expect(isHostError(new Error("plain"))).toBe(false);
             expect(isHostError("string")).toBe(false);
         });
@@ -189,6 +212,24 @@ if (import.meta.vitest) {
             expect(formatHostError({ tag: "Full" })).toBe("Full");
         });
 
+        test("unwraps the CallError Domain envelope to the domain error", () => {
+            // { tag: "Domain", value: { tag: "V1", value: <domain error> } }
+            expect(
+                formatHostError({
+                    tag: "Domain",
+                    value: { tag: "V1", value: { tag: "PermissionDenied" } },
+                }),
+            ).toBe("PermissionDenied");
+            expect(
+                formatHostError({ tag: "Domain", value: { tag: "V1", value: { reason: "boom" } } }),
+            ).toBe("boom");
+            // Transport-level CallError variants render as-is.
+            expect(formatHostError({ tag: "Denied" })).toBe("Denied");
+            expect(formatHostError({ tag: "HostFailure", value: { reason: "crashed" } })).toBe(
+                "HostFailure: crashed",
+            );
+        });
+
         test("falls back for non-host-error input", () => {
             expect(formatHostError(new Error("plain"))).toBe("plain");
             expect(formatHostError("string err")).toBe("string err");

package/src/index.ts

@@ -56,6 +56,7 @@ export type {
 // Result type + typed host errors (the throw→Result boundary)
 export { ok, err } from "./result.js";
 export type { Result } from "./result.js";
+export { type SdkError, isSdkError } from "@parity/product-sdk-errors";
 export {
     HostError,
     HostUnavailableError,
@@ -72,7 +73,9 @@ export type {
     HostAccount,
     ProductAccount,
     ContextualAlias,
+    ProductProofContext,
     RingLocation,
+    RingVRFProof,
 } from "./accounts.js";
 
 // Higher-level permission wrappers

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/result.ts

@@ -1,56 +1,13 @@
 // Copyright 2026 Parity Technologies (UK) Ltd.
 // SPDX-License-Identifier: Apache-2.0
 /**
- * A lightweight tagged `Result` type for the host public API.
+ * Re-export of the shared `Result` primitive from `@parity/result`.
  *
  * 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.
+ * consumers get typed errors on the `err` channel. The type is now owned by the
+ * zero-dependency `@parity/result` leaf so every package shares one
+ * definition; this module stays as the host-internal import path.
  *
  * @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" });
-        });
-    });
-}
+export { type Result, ok, err } from "@parity/result";