@parity/product-sdk-bulletin 0.1.0

package/src/resolve-query.ts

@@ -0,0 +1,192 @@
+import { getPreimageManager, type PreimageManager } from "@parity/product-sdk-host";
+import { createLogger } from "@parity/product-sdk-logger";
+
+import { cidToPreimageKey, computeCid } from "./cid.js";
+import {
+    BulletinHostUnavailableError,
+    BulletinLookupInterruptedError,
+    BulletinLookupTimeoutError,
+} from "./errors.js";
+
+const log = createLogger("bulletin");
+
+const DEFAULT_LOOKUP_TIMEOUT_MS = 30_000;
+
+/**
+ * Query strategy for the Bulletin Chain.
+ *
+ * The host manages the lookup via its preimage subscription API,
+ * which includes local caching and managed IPFS polling.
+ */
+export interface QueryStrategy {
+    kind: "host-lookup";
+    lookup: (cid: string, timeoutMs?: number) => Promise<Uint8Array>;
+}
+
+/**
+ * Determine the query strategy for the Bulletin Chain.
+ *
+ * Uses the host preimage lookup API which caches results and manages
+ * IPFS polling automatically.
+ *
+ * @returns The resolved query strategy.
+ * @throws {BulletinHostUnavailableError} If the host preimage manager is unavailable.
+ */
+export async function resolveQueryStrategy(): Promise<QueryStrategy> {
+    const preimageManager = await getPreimageManager();
+    if (preimageManager) {
+        log.info("using host preimage lookup for bulletin queries");
+        return {
+            kind: "host-lookup",
+            lookup: (cid, timeoutMs) => lookupViaHost(preimageManager, cid, timeoutMs),
+        };
+    }
+
+    throw new BulletinHostUnavailableError("query");
+}
+
+/**
+ * Wrap `preimageManager.lookup` (subscription-based) into a one-shot Promise.
+ *
+ * Converts the CID to a hex preimage key, subscribes, and resolves on the
+ * first non-null callback. Rejects on timeout or if the host interrupts the
+ * subscription (e.g. after repeated failures). Always unsubscribes on settlement.
+ *
+ * @param manager   - The product-sdk preimage manager.
+ * @param cid       - CIDv1 string to look up.
+ * @param timeoutMs - Maximum wait time. Default: 30_000ms.
+ * @returns The raw bytes of the preimage.
+ */
+export function lookupViaHost(
+    manager: PreimageManager,
+    cid: string,
+    timeoutMs: number = DEFAULT_LOOKUP_TIMEOUT_MS,
+): Promise<Uint8Array> {
+    const key = cidToPreimageKey(cid);
+
+    return new Promise<Uint8Array>((resolve, reject) => {
+        const cleanup = () => {
+            cancelInterrupt();
+            sub.unsubscribe();
+        };
+
+        const settle = (fn: () => void) => {
+            if (timer === null) return;
+            clearTimeout(timer);
+            timer = null;
+            cleanup();
+            fn();
+        };
+
+        let timer: ReturnType<typeof setTimeout> | null = setTimeout(() => {
+            settle(() => {
+                reject(new BulletinLookupTimeoutError(cid, timeoutMs));
+            });
+        }, timeoutMs);
+
+        const sub = manager.lookup(key, (preimage) => {
+            if (preimage !== null) {
+                settle(() => resolve(preimage));
+            }
+            // null means "not found yet" — host will keep polling
+        });
+
+        const cancelInterrupt = sub.onInterrupt(() => {
+            settle(() => {
+                reject(new BulletinLookupInterruptedError(cid));
+            });
+        });
+    });
+}
+
+if (import.meta.vitest) {
+    const { describe, test, expect, vi } = import.meta.vitest;
+
+    // Note: resolveQueryStrategy tests require e2e testing as they
+    // depend on the host container environment.
+
+    describe("lookupViaHost", () => {
+        function createMockManager(
+            behavior: "resolve" | "null-then-resolve" | "hang" | "interrupt",
+        ) {
+            const unsubscribe = vi.fn();
+            const cancelInterrupt = vi.fn();
+            let interruptCb: VoidFunction | undefined;
+
+            const lookup = vi.fn((_key: string, callback: (p: Uint8Array | null) => void) => {
+                const data = new Uint8Array([10, 20, 30]);
+                queueMicrotask(() => {
+                    if (behavior === "resolve") {
+                        callback(data);
+                    } else if (behavior === "null-then-resolve") {
+                        callback(null);
+                        queueMicrotask(() => callback(data));
+                    } else if (behavior === "interrupt") {
+                        interruptCb?.();
+                    }
+                    // "hang" does nothing
+                });
+                return {
+                    unsubscribe,
+                    onInterrupt: (cb: VoidFunction) => {
+                        interruptCb = cb;
+                        return cancelInterrupt;
+                    },
+                };
+            });
+
+            return { lookup, unsubscribe, cancelInterrupt, submit: vi.fn() };
+        }
+
+        const testCid = computeCid(new TextEncoder().encode("test"));
+
+        test("resolves on first non-null callback", async () => {
+            const manager = createMockManager("resolve");
+            const result = await lookupViaHost(manager, testCid);
+            expect(result).toEqual(new Uint8Array([10, 20, 30]));
+        });
+
+        test("ignores null callbacks and resolves on subsequent data", async () => {
+            const manager = createMockManager("null-then-resolve");
+            const result = await lookupViaHost(manager, testCid);
+            expect(result).toEqual(new Uint8Array([10, 20, 30]));
+        });
+
+        test("rejects with BulletinLookupTimeoutError on timeout", async () => {
+            const { BulletinLookupTimeoutError } = await import("./errors.js");
+            const manager = createMockManager("hang");
+            const err = await lookupViaHost(manager, testCid, 50).catch((e) => e);
+            expect(err).toBeInstanceOf(BulletinLookupTimeoutError);
+            expect(err.cid).toBe(testCid);
+            expect(err.timeoutMs).toBe(50);
+        });
+
+        test("rejects with BulletinLookupInterruptedError on interrupt", async () => {
+            const { BulletinLookupInterruptedError } = await import("./errors.js");
+            const manager = createMockManager("interrupt");
+            const err = await lookupViaHost(manager, testCid).catch((e) => e);
+            expect(err).toBeInstanceOf(BulletinLookupInterruptedError);
+            expect(err.cid).toBe(testCid);
+        });
+
+        test("calls unsubscribe and cancelInterrupt on resolution", async () => {
+            const manager = createMockManager("resolve");
+            await lookupViaHost(manager, testCid);
+            expect(manager.unsubscribe).toHaveBeenCalledOnce();
+            expect(manager.cancelInterrupt).toHaveBeenCalledOnce();
+        });
+
+        test("calls unsubscribe on interrupt", async () => {
+            const manager = createMockManager("interrupt");
+            await lookupViaHost(manager, testCid).catch(() => {});
+            expect(manager.unsubscribe).toHaveBeenCalledOnce();
+        });
+
+        test("passes correct hex key to manager", async () => {
+            const expectedKey = cidToPreimageKey(testCid);
+            const manager = createMockManager("resolve");
+            await lookupViaHost(manager, testCid);
+            expect(manager.lookup).toHaveBeenCalledWith(expectedKey, expect.any(Function));
+        });
+    });
+}

package/src/resolve-signer.ts

@@ -0,0 +1,66 @@
+import { getPreimageManager } from "@parity/product-sdk-host";
+import { createLogger } from "@parity/product-sdk-logger";
+import type { PolkadotSigner } from "polkadot-api";
+
+import { BulletinHostUnavailableError } from "./errors.js";
+
+const log = createLogger("bulletin");
+
+/**
+ * Discriminated union describing how data will be uploaded to the Bulletin Chain.
+ *
+ * - `"preimage"` — the host handles signing and chain submission via its preimage API.
+ * - `"signer"`   — a `TransactionStorage.store` transaction is signed and submitted directly.
+ */
+export type UploadStrategy =
+    | { kind: "preimage"; submit: (data: Uint8Array) => Promise<string> }
+    | { kind: "signer"; signer: PolkadotSigner };
+
+/**
+ * Determine the upload strategy for the Bulletin Chain.
+ *
+ * Resolution order:
+ * 1. If an explicit signer is provided, use it directly.
+ * 2. Otherwise, use the host preimage API (the SDK is designed to run inside a container).
+ *
+ * @param explicitSigner - Optional signer provided by the caller. When present,
+ *                         skips host auto-detection entirely.
+ * @returns The resolved upload strategy.
+ * @throws {Error} If no signer is provided and the host preimage API is unavailable.
+ */
+export async function resolveUploadStrategy(
+    explicitSigner?: PolkadotSigner,
+): Promise<UploadStrategy> {
+    if (explicitSigner) {
+        log.debug("using explicit signer provided by caller");
+        return { kind: "signer", signer: explicitSigner };
+    }
+
+    // Use the host preimage API (inside container)
+    const preimageManager = await getPreimageManager();
+    if (preimageManager) {
+        log.info("using host preimage API for bulletin upload");
+        return { kind: "preimage", submit: (data) => preimageManager.submit(data) };
+    }
+
+    throw new BulletinHostUnavailableError("upload");
+}
+
+if (import.meta.vitest) {
+    const { describe, test, expect, vi } = import.meta.vitest;
+
+    describe("resolveUploadStrategy", () => {
+        test("returns explicit signer when provided", async () => {
+            const signer = { publicKey: new Uint8Array(32) } as PolkadotSigner;
+            const strategy = await resolveUploadStrategy(signer);
+            expect(strategy.kind).toBe("signer");
+            if (strategy.kind === "signer") {
+                expect(strategy.signer).toBe(signer);
+            }
+        });
+
+        // Note: Tests for host preimage manager integration require e2e testing
+        // as they depend on the actual host container environment.
+        // The explicit signer path above validates the core logic.
+    });
+}

package/src/types.ts

@@ -0,0 +1,140 @@
+import type { TypedApi } from "polkadot-api";
+import type { TxStatus, WaitFor } from "@parity/product-sdk-tx";
+
+/** Typed API for the Bulletin Chain, derived from PAPI descriptors. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type BulletinApi = TypedApi<any>;
+
+export type { Environment } from "@parity/product-sdk-chain-client";
+
+/**
+ * Options for {@link upload}.
+ *
+ * Note: `waitFor`, `timeoutMs`, and `onStatus` only apply to the **transaction**
+ * upload path (when an explicit signer is used or the dev signer fallback is active).
+ * The preimage path delegates to the host which controls its own submission
+ * lifecycle — these options are ignored in that case.
+ */
+export interface UploadOptions {
+    /** IPFS gateway base URL (e.g., from `getGateway("paseo")`). If provided, result includes gatewayUrl. */
+    gateway?: string;
+    /** When to resolve: `"best-block"` (default) or `"finalized"`. Transaction path only. */
+    waitFor?: WaitFor;
+    /** Timeout in ms. Default: 300_000 (5 min). Transaction path only. */
+    timeoutMs?: number;
+    /** Lifecycle status callback for UI progress. Transaction path only. */
+    onStatus?: (status: TxStatus) => void;
+}
+
+/** Fields common to all upload results. */
+interface UploadResultBase {
+    /** CIDv1 string (blake2b-256, raw codec). */
+    cid: string;
+    /** Gateway URL. Present only if `gateway` was provided in options. */
+    gatewayUrl?: string;
+}
+
+/**
+ * Result of a successful upload to the Bulletin Chain.
+ *
+ * Discriminated on `kind`:
+ * - `"transaction"` — uploaded via a signed `TransactionStorage.store` extrinsic.
+ * - `"preimage"` — uploaded via the host preimage API (no user signing).
+ *
+ * Use `result.kind` to narrow the type and access path-specific fields.
+ */
+export type UploadResult =
+    | (UploadResultBase & {
+          /** Upload was performed via a signed transaction. */
+          kind: "transaction";
+          /** Block hash where the store transaction was included. */
+          blockHash: string;
+      })
+    | (UploadResultBase & {
+          /** Upload was performed via the host preimage API. */
+          kind: "preimage";
+          /** Hex key returned by the host preimage API. */
+          preimageKey: string;
+      });
+
+/** A single item in a batch upload. */
+export interface BatchUploadItem {
+    /** Raw bytes to upload. */
+    data: Uint8Array;
+    /** Label for progress tracking (e.g., filename). */
+    label: string;
+}
+
+/** Fields common to all batch upload results. */
+interface BatchUploadResultBase {
+    label: string;
+    cid: string;
+    gatewayUrl?: string;
+}
+
+/**
+ * Result for one item in a batch upload.
+ *
+ * Discriminated on `kind` (upload path) and `success` (outcome).
+ * Use `result.success` to check for errors, then `result.kind` to access
+ * path-specific fields like `blockHash` or `preimageKey`.
+ */
+export type BatchUploadResult =
+    | (BatchUploadResultBase & {
+          kind: "transaction";
+          success: true;
+          /** Block hash where the store transaction was included. */
+          blockHash: string;
+      })
+    | (BatchUploadResultBase & {
+          kind: "preimage";
+          success: true;
+          /** Hex key returned by the host preimage API. */
+          preimageKey: string;
+      })
+    | (BatchUploadResultBase & {
+          kind: "transaction" | "preimage";
+          success: false;
+          /** Error message describing the failure. */
+          error: string;
+      });
+
+/** Options for {@link batchUpload}. */
+export interface BatchUploadOptions extends UploadOptions {
+    /** Called after each item completes (success or failure). */
+    onProgress?: (completed: number, total: number, current: BatchUploadResult) => void;
+}
+
+/**
+ * Authorization status for a Bulletin Chain account.
+ *
+ * Returned by {@link checkAuthorization} to enable pre-flight checks before
+ * uploading. Consumers can use this to show "not authorized" or "insufficient
+ * quota" messages instead of letting the transaction fail.
+ */
+export interface AuthorizationStatus {
+    /** Whether an authorization entry exists for this account. */
+    authorized: boolean;
+    /** Remaining transactions allowed. 0 if not authorized. */
+    remainingTransactions: number;
+    /** Remaining bytes allowed. 0n if not authorized. */
+    remainingBytes: bigint;
+    /** Block number when the authorization expires. 0 if not authorized. */
+    expiration: number;
+}
+
+/** Options for gateway fetch operations. */
+export interface FetchOptions {
+    /** Timeout in ms. Default: 30_000. */
+    timeoutMs?: number;
+}
+
+/** Options for query operations that support host lookup auto-resolution. */
+export interface QueryOptions extends FetchOptions {
+    /**
+     * Timeout for the host preimage lookup subscription in ms.
+     * Only applies when the query resolves through the host path.
+     * Default: 30_000.
+     */
+    lookupTimeoutMs?: number;
+}