@parity/product-sdk-host 0.10.3 → 0.12.0

package/src/navigation.ts

@@ -0,0 +1,128 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Higher-level wrapper for the host's deep-link navigation.
+ *
+ * `truApi.system.navigateTo` returns a neverthrow `ResultAsync`; consumers
+ * still have to unwrap it themselves. {@link navigateTo} collapses that to a
+ * `Result<void, HostError>`-returning Promise.
+ *
+ * @module
+ */
+
+import { createLogger } from "@parity/product-sdk-logger";
+
+import { type HostError, HostUnavailableError } from "./errors.js";
+import { type Result, err } from "./result.js";
+import { getTruApi, mapHostResult } from "./truapi.js";
+
+const log = createLogger("host:navigation");
+
+/**
+ * Ask the host to navigate to a URL (deep link or external link).
+ *
+ * Calls `truApi.system.navigateTo` and unwraps the response. The host resolves
+ * the destination itself — a `dot`-suffixed deep link (e.g.
+ * `"https://search.dot"`) routes to another app/route inside the container, an
+ * `https://` URL opens externally.
+ *
+ * @param url - The URL to navigate to.
+ * @returns `ok` on success, or `err`: {@link HostUnavailableError} if the host
+ *   is unavailable, or {@link HostCallFailedError} if it denies the navigation
+ *   (`NavigateToErr::PermissionDenied`) or fails otherwise (`NavigateToErr::Unknown`).
+ *
+ * @example
+ * ```ts
+ * import { navigateTo } from "@parity/product-sdk-host";
+ *
+ * const r = await navigateTo("https://search.dot");
+ * if (!r.ok) handle(r.error);
+ * ```
+ */
+export async function navigateTo(url: string): Promise<Result<void, HostError>> {
+    const truApi = await getTruApi();
+    if (!truApi) {
+        return err(new HostUnavailableError("navigateTo: TruAPI unavailable"));
+    }
+    log.debug("navigateTo", { url });
+
+    return mapHostResult(truApi.system.navigateTo({ url }), () => undefined, "navigateTo failed");
+}
+
+if (import.meta.vitest) {
+    const { test, expect, describe, vi } = import.meta.vitest;
+
+    async function withMockedTruApi<T>(
+        bridge: { system?: { navigateTo?: (req: unknown) => unknown } } | null,
+        fn: (mod: typeof import("./navigation.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,
+            };
+        });
+        try {
+            const mod = await import("./navigation.js");
+            return await fn(mod);
+        } finally {
+            vi.doUnmock("./truapi.js");
+            vi.resetModules();
+        }
+    }
+
+    describe("navigateTo", () => {
+        test("returns err(HostUnavailableError) when TruAPI is unavailable", async () => {
+            await withMockedTruApi(null, async (mod) => {
+                const result = await mod.navigateTo("https://search.dot");
+                expect(result.ok).toBe(false);
+                if (!result.ok) {
+                    expect(result.error.name).toBe("HostUnavailableError");
+                }
+            });
+        });
+
+        test("returns ok on success", async () => {
+            await withMockedTruApi(
+                {
+                    system: {
+                        navigateTo: vi.fn().mockReturnValue({
+                            match: async (onOk: (v: unknown) => unknown) => onOk(undefined),
+                        }),
+                    },
+                },
+                async (mod) => {
+                    expect(await mod.navigateTo("https://search.dot")).toEqual({
+                        ok: true,
+                        value: undefined,
+                    });
+                },
+            );
+        });
+
+        test("wraps host errors in err(HostCallFailedError) with a diagnostic message", async () => {
+            await withMockedTruApi(
+                {
+                    system: {
+                        navigateTo: vi.fn().mockReturnValue({
+                            match: async (
+                                _onOk: (v: unknown) => unknown,
+                                onErr: (e: unknown) => unknown,
+                            ) => onErr({ tag: "PermissionDenied" }),
+                        }),
+                    },
+                },
+                async (mod) => {
+                    const result = await mod.navigateTo("https://search.dot");
+                    expect(result.ok).toBe(false);
+                    if (!result.ok) {
+                        expect(result.error.name).toBe("HostCallFailedError");
+                        expect(result.error.message).toMatch(/navigateTo failed: PermissionDenied/);
+                    }
+                },
+            );
+        });
+    });
+}

package/src/notifications.ts

@@ -1,80 +1,86 @@
 // Copyright 2026 Parity Technologies (UK) Ltd.
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Wrapper for the host's scheduled push-notification surface.
+ * Wrapper for the host's scheduled push-notification surface (RFC-0019),
+ * backed by `truApi.notifications.*`.
  *
- * Shipped flat-in-host rather than as `getTruApi().notification.*` because
- * the upstream JS `hostApi` is itself a flat object - there is no
- * `.notification` accessor to mirror. A flat `getNotificationManager()`
- * matches the singleton pattern already used by {@link getPaymentManager},
- * {@link getPreimageManager}, and {@link getHostLocalStorage}.
- *
- * Returns the shared `notificationManager` singleton from
- * `@novasamatech/host-api-wrapper` (not a fresh `createNotificationManager()`
- * instance) so callers share one wrapper + hostApi closure across the app.
- *
- * {@link PushNotificationError} is re-exported from `@novasamatech/host-api`
- * so consumers can branch on `err instanceof
- * PushNotificationError.ScheduleLimitReached` (the host's pending-notification
- * cap) without importing the novasama packages directly.
+ * `getNotificationManager()` returns a handle exposing `push(input)` (resolves
+ * to a {@link NotificationId}) and `cancel(id)`, matching the singleton
+ * pattern already used by {@link getPaymentManager}, {@link getPreimageManager},
+ * and {@link getHostLocalStorage}.
  *
  * @module
  */
 
-import { createLogger } from "@parity/product-sdk-logger";
+import type { HostPushNotificationRequest, NotificationId, TrUApiClient } from "@parity/truapi";
 
-import type { notificationManager } from "@novasamatech/host-api-wrapper";
-
-const log = createLogger("host:notifications");
+import { getClient } from "./transport.js";
+import { unwrapHostResult } from "./truapi.js";
 
 /**
  * Error variants the host raises when scheduling a push notification.
  *
- * A SCALE codec (with a `[Symbol.hasInstance]`), not a plain `Error`
- * subclass: branch with `err instanceof
- * PushNotificationError.ScheduleLimitReached` to detect the host's
- * platform-wide pending-notification cap, or `.Unknown` for everything
- * else. Re-exported from `@novasamatech/host-api` so consumers can
- * `instanceof`-branch without a direct novasama dependency.
+ * A `{ tag }` tagged union re-exported from `@parity/truapi`:
+ * `{ tag: "ScheduleLimitReached" }` (the host-wide pending-notification cap) or
+ * `{ tag: "Unknown"; value: { reason } }`. {@link NotificationManager.push} /
+ * {@link NotificationManager.cancel} reject with an `Error` whose `cause`
+ * carries this value, so branch on it — e.g.
+ * `(err as Error).cause?.tag === "ScheduleLimitReached"`.
  */
-export { PushNotificationError } from "@novasamatech/host-api";
+export type { HostPushNotificationError as PushNotificationError } from "@parity/truapi";
 
 /**
- * Host notification manager handle. Exposes `push(input)` (resolves to a
- * {@link NotificationId}) and `cancel(id)`.
- *
- * Type identical to `notificationManager` from
- * `@novasamatech/host-api-wrapper`.
+ * Host-assigned id for a scheduled notification — pass to
+ * {@link NotificationManager.cancel}. Re-exported from `@parity/truapi`.
  */
-export type NotificationManager = typeof notificationManager;
+export type { NotificationId };
 
 /**
- * Host-assigned id for a scheduled notification — pass to
- * {@link NotificationManager.cancel}. Derived from the manager's `push`
- * return type so codec changes surface here as compile errors.
+ * Push payload: `text`, an optional `deeplink`, and an optional `scheduledAt`
+ * (Unix timestamp in milliseconds; omit for immediate delivery). Re-exported
+ * from the truapi wire request type so the shape stays in lockstep with the
+ * protocol.
  */
-export type NotificationId = Awaited<ReturnType<NotificationManager["push"]>>;
+export type PushNotificationInput = HostPushNotificationRequest;
 
 /**
- * Push payload: `text`, an optional `deeplink`, and an optional
- * `scheduledAt` (omit for immediate delivery). Derived from the manager's
- * `push` parameter so the shape stays in lockstep with upstream.
+ * Host notification manager handle. Exposes `push(input)` (resolves to a
+ * {@link NotificationId}) and `cancel(id)`.
  */
-export type PushNotificationInput = Parameters<NotificationManager["push"]>[0];
+export interface NotificationManager {
+    push(input: PushNotificationInput): Promise<NotificationId>;
+    cancel(id: NotificationId): Promise<void>;
+}
+
+/** Build a {@link NotificationManager} over a TruAPI client's `notifications` domain. */
+function adaptNotificationManager(client: TrUApiClient): NotificationManager {
+    const notifications = client.notifications;
+    return {
+        async push(input) {
+            const response = await unwrapHostResult(
+                notifications.sendPushNotification(input),
+                "notification push failed",
+            );
+            return response.id;
+        },
+        async cancel(id) {
+            await unwrapHostResult(
+                notifications.cancelPushNotification({ id }),
+                "notification cancel failed",
+            );
+        },
+    };
+}
 
 /**
- * Get the host notification manager.
- *
- * Returns the shared `notificationManager` 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 notification manager, backed by `truApi.notifications.*`.
+ * Returns `null` when running outside a host container.
  *
  * @returns The notification manager, or `null` if unavailable.
  *
  * @example
  * ```ts
- * import { getNotificationManager, PushNotificationError } from "@parity/product-sdk-host";
+ * import { getNotificationManager, type PushNotificationError } from "@parity/product-sdk-host";
  *
  * const notifications = await getNotificationManager();
  * if (notifications) {
@@ -85,7 +91,8 @@ export type PushNotificationInput = Parameters<NotificationManager["push"]>[0];
  *     });
  *     // later: await notifications.cancel(id);
  *   } catch (err) {
- *     if (err instanceof PushNotificationError.ScheduleLimitReached) {
+ *     const cause = (err as Error).cause as PushNotificationError | undefined;
+ *     if (cause?.tag === "ScheduleLimitReached") {
  *       // host hit its pending-notification cap — surface to the user
  *     }
  *   }
@@ -93,31 +100,14 @@ export type PushNotificationInput = Parameters<NotificationManager["push"]>[0];
  * ```
  */
 export async function getNotificationManager(): Promise<NotificationManager | null> {
-    try {
-        const sdk = await import("@novasamatech/host-api-wrapper");
-        return sdk.notificationManager;
-    } catch (err) {
-        log.debug("getNotificationManager unavailable", err);
-        return null;
-    }
+    const client = await getClient();
+    return client ? adaptNotificationManager(client) : null;
 }
 
 if (import.meta.vitest) {
     const { test, expect } = import.meta.vitest;
 
-    test("getNotificationManager returns manager with push/cancel when SDK is available", async () => {
-        const notifications = await getNotificationManager();
-        if (notifications === null) {
-            // Acceptable: SDK couldn't load (e.g. peer dep missing in some envs).
-            return;
-        }
-        expect(typeof notifications.push).toBe("function");
-        expect(typeof notifications.cancel).toBe("function");
-    });
-
-    test("PushNotificationError is re-exported with its ScheduleLimitReached variant", async () => {
-        const { PushNotificationError } = await import("./notifications.js");
-        expect(PushNotificationError).toBeDefined();
-        expect(PushNotificationError.ScheduleLimitReached).toBeDefined();
+    test("getNotificationManager returns null outside a container", async () => {
+        expect(await getNotificationManager()).toBeNull();
     });
 }