@parity/product-sdk-bulletin 0.1.0

package/src/errors.ts

@@ -0,0 +1,235 @@
+/**
+ * Base class for all Bulletin Chain errors.
+ *
+ * Use `instanceof BulletinError` to catch any bulletin-related error.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await bulletin.upload(data);
+ * } catch (e) {
+ *   if (e instanceof BulletinError) {
+ *     console.error("Bulletin operation failed:", e.message);
+ *   }
+ * }
+ * ```
+ */
+export class BulletinError extends Error {
+    constructor(message: string, options?: ErrorOptions) {
+        super(message, options);
+        this.name = "BulletinError";
+    }
+}
+
+/**
+ * The host preimage API is unavailable.
+ *
+ * Thrown when bulletin operations require the host container but it's not available.
+ * This typically means the SDK is running outside of Polkadot Browser/Desktop.
+ */
+export class BulletinHostUnavailableError extends BulletinError {
+    constructor(operation: "upload" | "query") {
+        super(
+            `Host preimage API unavailable for ${operation}. Ensure you are running inside a host container (Polkadot Browser / Desktop).`,
+        );
+        this.name = "BulletinHostUnavailableError";
+    }
+}
+
+/**
+ * The host preimage lookup timed out.
+ *
+ * The host was unable to retrieve the requested content within the timeout period.
+ * The content may still become available later.
+ */
+export class BulletinLookupTimeoutError extends BulletinError {
+    /** The CID that was being looked up. */
+    readonly cid: string;
+    /** The timeout duration in milliseconds. */
+    readonly timeoutMs: number;
+
+    constructor(cid: string, timeoutMs: number) {
+        super(`Host preimage lookup timed out after ${timeoutMs}ms for CID: ${cid}`);
+        this.name = "BulletinLookupTimeoutError";
+        this.cid = cid;
+        this.timeoutMs = timeoutMs;
+    }
+}
+
+/**
+ * The host interrupted the preimage lookup.
+ *
+ * The host terminated the lookup subscription, typically after repeated failures
+ * or when the host determines the content is unavailable.
+ */
+export class BulletinLookupInterruptedError extends BulletinError {
+    /** The CID that was being looked up. */
+    readonly cid: string;
+
+    constructor(cid: string) {
+        super(`Host preimage lookup was interrupted for CID: ${cid}`);
+        this.name = "BulletinLookupInterruptedError";
+        this.cid = cid;
+    }
+}
+
+/**
+ * Failed to check authorization status for an account.
+ *
+ * Wraps RPC or query errors that occur when checking if an account
+ * is authorized to store data on the Bulletin Chain.
+ */
+export class BulletinAuthorizationError extends BulletinError {
+    /** The address that was being checked. */
+    readonly address: string;
+
+    constructor(address: string, cause?: unknown) {
+        super(`Failed to check authorization for ${address}`, { cause });
+        this.name = "BulletinAuthorizationError";
+        this.address = address;
+    }
+}
+
+/**
+ * The IPFS gateway for the specified environment is not available.
+ *
+ * Thrown when attempting to use gateway features for a network that
+ * doesn't have a live bulletin gateway yet.
+ */
+export class BulletinGatewayUnavailableError extends BulletinError {
+    /** The environment that was requested. */
+    readonly environment: string;
+
+    constructor(environment: string) {
+        super(`Bulletin gateway for "${environment}" is not yet available`);
+        this.name = "BulletinGatewayUnavailableError";
+        this.environment = environment;
+    }
+}
+
+/**
+ * An IPFS gateway request failed.
+ *
+ * Thrown when a fetch to the IPFS gateway returns a non-OK response.
+ */
+export class BulletinGatewayFetchError extends BulletinError {
+    /** The CID that was being fetched. */
+    readonly cid: string;
+    /** The HTTP status code returned by the gateway. */
+    readonly status: number;
+    /** The HTTP status text returned by the gateway. */
+    readonly statusText: string;
+
+    constructor(cid: string, status: number, statusText: string) {
+        super(`Gateway fetch failed for ${cid}: ${status} ${statusText}`);
+        this.name = "BulletinGatewayFetchError";
+        this.cid = cid;
+        this.status = status;
+        this.statusText = statusText;
+    }
+}
+
+/**
+ * Invalid CID format or version.
+ *
+ * Thrown when a CID string cannot be parsed or has an unexpected version/codec.
+ */
+export class BulletinCidError extends BulletinError {
+    /** The invalid CID string, if available. */
+    readonly cid?: string;
+
+    constructor(message: string, cid?: string) {
+        super(message);
+        this.name = "BulletinCidError";
+        this.cid = cid;
+    }
+}
+
+if (import.meta.vitest) {
+    const { describe, test, expect } = import.meta.vitest;
+
+    describe("BulletinError hierarchy", () => {
+        test("BulletinError is instanceof Error", () => {
+            const err = new BulletinError("test");
+            expect(err).toBeInstanceOf(Error);
+            expect(err).toBeInstanceOf(BulletinError);
+            expect(err.name).toBe("BulletinError");
+        });
+
+        test("BulletinHostUnavailableError", () => {
+            const err = new BulletinHostUnavailableError("upload");
+            expect(err).toBeInstanceOf(BulletinError);
+            expect(err.name).toBe("BulletinHostUnavailableError");
+            expect(err.message).toContain("upload");
+            expect(err.message).toContain("Host preimage API unavailable");
+        });
+
+        test("BulletinLookupTimeoutError", () => {
+            const err = new BulletinLookupTimeoutError("bafyabc123", 30000);
+            expect(err).toBeInstanceOf(BulletinError);
+            expect(err.name).toBe("BulletinLookupTimeoutError");
+            expect(err.cid).toBe("bafyabc123");
+            expect(err.timeoutMs).toBe(30000);
+            expect(err.message).toContain("30000ms");
+            expect(err.message).toContain("bafyabc123");
+        });
+
+        test("BulletinLookupInterruptedError", () => {
+            const err = new BulletinLookupInterruptedError("bafyabc123");
+            expect(err).toBeInstanceOf(BulletinError);
+            expect(err.name).toBe("BulletinLookupInterruptedError");
+            expect(err.cid).toBe("bafyabc123");
+            expect(err.message).toContain("interrupted");
+        });
+
+        test("BulletinAuthorizationError with cause", () => {
+            const cause = new Error("RPC timeout");
+            const err = new BulletinAuthorizationError("5GrwvaEF...", cause);
+            expect(err).toBeInstanceOf(BulletinError);
+            expect(err.name).toBe("BulletinAuthorizationError");
+            expect(err.address).toBe("5GrwvaEF...");
+            expect(err.cause).toBe(cause);
+        });
+
+        test("BulletinGatewayUnavailableError", () => {
+            const err = new BulletinGatewayUnavailableError("polkadot");
+            expect(err).toBeInstanceOf(BulletinError);
+            expect(err.name).toBe("BulletinGatewayUnavailableError");
+            expect(err.environment).toBe("polkadot");
+            expect(err.message).toContain("polkadot");
+        });
+
+        test("BulletinGatewayFetchError", () => {
+            const err = new BulletinGatewayFetchError("bafyabc", 404, "Not Found");
+            expect(err).toBeInstanceOf(BulletinError);
+            expect(err.name).toBe("BulletinGatewayFetchError");
+            expect(err.cid).toBe("bafyabc");
+            expect(err.status).toBe(404);
+            expect(err.statusText).toBe("Not Found");
+            expect(err.message).toContain("404");
+        });
+
+        test("BulletinCidError", () => {
+            const err = new BulletinCidError("Expected CIDv1, got CIDv0", "Qmabc");
+            expect(err).toBeInstanceOf(BulletinError);
+            expect(err.name).toBe("BulletinCidError");
+            expect(err.cid).toBe("Qmabc");
+        });
+
+        test("all errors can be caught with BulletinError", () => {
+            const errors = [
+                new BulletinHostUnavailableError("query"),
+                new BulletinLookupTimeoutError("cid", 1000),
+                new BulletinLookupInterruptedError("cid"),
+                new BulletinAuthorizationError("addr"),
+                new BulletinGatewayUnavailableError("env"),
+                new BulletinGatewayFetchError("cid", 500, "Error"),
+                new BulletinCidError("bad cid"),
+            ];
+
+            for (const err of errors) {
+                expect(err).toBeInstanceOf(BulletinError);
+            }
+        });
+    });
+}

package/src/gateway.ts

@@ -0,0 +1,209 @@
+import { BulletinGatewayFetchError, BulletinGatewayUnavailableError } from "./errors.js";
+import type { Environment, FetchOptions } from "./types.js";
+
+/** Add entries here as bulletin gateways go live on each network. */
+const GATEWAYS: Partial<Record<Environment, string>> = {
+    paseo: "https://paseo-ipfs.polkadot.io/ipfs/",
+};
+
+const DEFAULT_FETCH_TIMEOUT_MS = 30_000;
+
+/**
+ * Get the IPFS gateway URL for an environment.
+ * @throws {BulletinGatewayUnavailableError} If the network doesn't have a live gateway yet.
+ */
+export function getGateway(env: Environment): string {
+    const gw = GATEWAYS[env];
+    if (!gw) {
+        throw new BulletinGatewayUnavailableError(env);
+    }
+    return gw;
+}
+
+/** Build the full gateway URL for a CID. */
+export function gatewayUrl(cid: string, gateway: string): string {
+    return `${gateway}${cid}`;
+}
+
+/** Check if a CID exists on the gateway (HEAD request). Returns false on any error or timeout. */
+export async function cidExists(
+    cid: string,
+    gateway: string,
+    options?: FetchOptions,
+): Promise<boolean> {
+    const timeoutMs = options?.timeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(gatewayUrl(cid, gateway), {
+            method: "HEAD",
+            signal: controller.signal,
+        });
+        return response.ok;
+    } catch {
+        return false;
+    } finally {
+        clearTimeout(timer);
+    }
+}
+
+/**
+ * Fetch raw bytes from the gateway.
+ * @throws {BulletinGatewayFetchError} If the gateway returns a non-OK response.
+ */
+export async function fetchBytes(
+    cid: string,
+    gateway: string,
+    options?: FetchOptions,
+): Promise<Uint8Array> {
+    const timeoutMs = options?.timeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+    try {
+        const response = await fetch(gatewayUrl(cid, gateway), { signal: controller.signal });
+        if (!response.ok) {
+            throw new BulletinGatewayFetchError(cid, response.status, response.statusText);
+        }
+        return new Uint8Array(await response.arrayBuffer());
+    } finally {
+        clearTimeout(timer);
+    }
+}
+
+/** Fetch and parse JSON from the gateway. */
+export async function fetchJson<T>(
+    cid: string,
+    gateway: string,
+    options?: FetchOptions,
+): Promise<T> {
+    const bytes = await fetchBytes(cid, gateway, options);
+    return JSON.parse(new TextDecoder().decode(bytes)) as T;
+}
+
+if (import.meta.vitest) {
+    const { describe, test, expect, vi, afterEach } = import.meta.vitest;
+
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+
+    describe("getGateway", () => {
+        test("returns known URL for paseo", () => {
+            const gw = getGateway("paseo");
+            expect(gw).toMatch(/^https:\/\//);
+            expect(gw).toMatch(/\/ipfs\/$/);
+        });
+
+        test("throws BulletinGatewayUnavailableError for environments without a live gateway", () => {
+            expect(() => getGateway("polkadot")).toThrow(BulletinGatewayUnavailableError);
+            expect(() => getGateway("kusama")).toThrow(BulletinGatewayUnavailableError);
+        });
+    });
+
+    describe("gatewayUrl", () => {
+        test("concatenates gateway and CID", () => {
+            expect(gatewayUrl("bafyabc", "https://gw.example/ipfs/")).toBe(
+                "https://gw.example/ipfs/bafyabc",
+            );
+        });
+    });
+
+    describe("cidExists", () => {
+        test("returns true for 200 response", async () => {
+            vi.stubGlobal("fetch", vi.fn().mockResolvedValue({ ok: true }));
+            expect(await cidExists("bafyabc", "https://gw/ipfs/")).toBe(true);
+        });
+
+        test("returns false for 404 response", async () => {
+            vi.stubGlobal("fetch", vi.fn().mockResolvedValue({ ok: false, status: 404 }));
+            expect(await cidExists("bafyabc", "https://gw/ipfs/")).toBe(false);
+        });
+
+        test("returns false on network error", async () => {
+            vi.stubGlobal("fetch", vi.fn().mockRejectedValue(new Error("network")));
+            expect(await cidExists("bafyabc", "https://gw/ipfs/")).toBe(false);
+        });
+
+        test("returns false on timeout", async () => {
+            vi.stubGlobal(
+                "fetch",
+                vi.fn().mockImplementation(
+                    (_url: string, init: { signal: AbortSignal }) =>
+                        new Promise((_resolve, reject) => {
+                            init.signal.addEventListener("abort", () =>
+                                reject(new DOMException("aborted", "AbortError")),
+                            );
+                        }),
+                ),
+            );
+            expect(await cidExists("bafyabc", "https://gw/ipfs/", { timeoutMs: 10 })).toBe(false);
+        });
+    });
+
+    describe("fetchBytes", () => {
+        test("returns bytes from response", async () => {
+            const payload = new Uint8Array([1, 2, 3]);
+            vi.stubGlobal(
+                "fetch",
+                vi.fn().mockResolvedValue({
+                    ok: true,
+                    arrayBuffer: () => Promise.resolve(payload.buffer),
+                }),
+            );
+            const result = await fetchBytes("bafyabc", "https://gw/ipfs/");
+            expect(result).toEqual(payload);
+        });
+
+        test("throws BulletinGatewayFetchError on non-ok response", async () => {
+            vi.stubGlobal(
+                "fetch",
+                vi.fn().mockResolvedValue({
+                    ok: false,
+                    status: 500,
+                    statusText: "Internal Server Error",
+                }),
+            );
+            const err = await fetchBytes("bafyabc", "https://gw/ipfs/").catch((e) => e);
+            expect(err).toBeInstanceOf(BulletinGatewayFetchError);
+            expect(err.cid).toBe("bafyabc");
+            expect(err.status).toBe(500);
+        });
+
+        test("throws on timeout", async () => {
+            vi.stubGlobal(
+                "fetch",
+                vi.fn().mockImplementation(
+                    (_url: string, init: { signal: AbortSignal }) =>
+                        new Promise((_resolve, reject) => {
+                            init.signal.addEventListener("abort", () =>
+                                reject(new DOMException("aborted", "AbortError")),
+                            );
+                        }),
+                ),
+            );
+            await expect(
+                fetchBytes("bafyabc", "https://gw/ipfs/", { timeoutMs: 10 }),
+            ).rejects.toThrow();
+        });
+    });
+
+    describe("fetchJson", () => {
+        test("parses JSON from response", async () => {
+            const obj = { name: "test", value: 42 };
+            const bytes = new TextEncoder().encode(JSON.stringify(obj));
+            vi.stubGlobal(
+                "fetch",
+                vi.fn().mockResolvedValue({
+                    ok: true,
+                    arrayBuffer: () => Promise.resolve(bytes.buffer),
+                }),
+            );
+            const result = await fetchJson<{ name: string; value: number }>(
+                "bafyabc",
+                "https://gw/ipfs/",
+            );
+            expect(result).toEqual(obj);
+        });
+    });
+}

package/src/index.ts

@@ -0,0 +1,38 @@
+export { BulletinClient } from "./client.js";
+export { checkAuthorization } from "./authorization.js";
+export {
+    computeCid,
+    cidToPreimageKey,
+    hashToCid,
+    HashAlgorithm,
+    CidCodec,
+} from "./cid.js";
+export {
+    BulletinError,
+    BulletinHostUnavailableError,
+    BulletinLookupTimeoutError,
+    BulletinLookupInterruptedError,
+    BulletinAuthorizationError,
+    BulletinGatewayUnavailableError,
+    BulletinGatewayFetchError,
+    BulletinCidError,
+} from "./errors.js";
+export { getGateway, gatewayUrl, cidExists, fetchBytes, fetchJson } from "./gateway.js";
+export { resolveQueryStrategy } from "./resolve-query.js";
+export { queryBytes, queryJson } from "./query.js";
+export { resolveUploadStrategy } from "./resolve-signer.js";
+export { upload, batchUpload } from "./upload.js";
+export type {
+    AuthorizationStatus,
+    BulletinApi,
+    Environment,
+    UploadOptions,
+    UploadResult,
+    BatchUploadItem,
+    BatchUploadResult,
+    BatchUploadOptions,
+    FetchOptions,
+    QueryOptions,
+} from "./types.js";
+export type { UploadStrategy } from "./resolve-signer.js";
+export type { QueryStrategy } from "./resolve-query.js";

package/src/query.ts

@@ -0,0 +1,82 @@
+import { createLogger } from "@parity/product-sdk-logger";
+
+import { resolveQueryStrategy, type QueryStrategy } from "./resolve-query.js";
+import type { QueryOptions } from "./types.js";
+
+const log = createLogger("bulletin");
+
+/**
+ * Fetch raw bytes for a CID using the host preimage lookup.
+ *
+ * Uses local cache + managed IPFS polling via the host container.
+ *
+ * @param cid     - CIDv1 string to fetch.
+ * @param options - Query options (lookupTimeoutMs for host).
+ * @returns Raw bytes of the content.
+ * @throws {Error} If the host preimage API is unavailable.
+ */
+export async function queryBytes(cid: string, options?: QueryOptions): Promise<Uint8Array> {
+    const strategy = await resolveQueryStrategy();
+    return executeQuery(strategy, cid, options);
+}
+
+/**
+ * Fetch and parse JSON for a CID, auto-resolving the query path.
+ *
+ * Delegates to {@link queryBytes} and parses the result as JSON.
+ *
+ * @param cid     - CIDv1 string to fetch.
+ * @param options - Query options.
+ * @returns Parsed JSON value.
+ * @throws {Error} If the host preimage API is unavailable.
+ */
+export async function queryJson<T>(cid: string, options?: QueryOptions): Promise<T> {
+    const bytes = await queryBytes(cid, options);
+    return JSON.parse(new TextDecoder().decode(bytes)) as T;
+}
+
+/**
+ * Execute a query using a pre-resolved strategy.
+ *
+ * Exposed so that {@link BulletinClient} can resolve the strategy once and
+ * reuse it across multiple calls without re-detecting the environment.
+ *
+ * @param strategy - Pre-resolved query strategy.
+ * @param cid      - CIDv1 string to fetch.
+ * @param options  - Query options.
+ * @returns Raw bytes of the content.
+ */
+export async function executeQuery(
+    strategy: QueryStrategy,
+    cid: string,
+    options?: QueryOptions,
+): Promise<Uint8Array> {
+    log.info("querying via host preimage lookup", { cid });
+    return strategy.lookup(cid, options?.lookupTimeoutMs);
+}
+
+if (import.meta.vitest) {
+    const { describe, test, expect, vi } = import.meta.vitest;
+
+    // Note: queryBytes and queryJson tests require e2e testing as they
+    // depend on the host container environment for strategy resolution.
+
+    describe("executeQuery", () => {
+        const testData = new Uint8Array([1, 2, 3]);
+
+        test("executes host-lookup strategy", async () => {
+            const lookup = vi.fn().mockResolvedValue(testData);
+            const strategy: QueryStrategy = { kind: "host-lookup", lookup };
+            const result = await executeQuery(strategy, "bafytest");
+            expect(result).toBe(testData);
+            expect(lookup).toHaveBeenCalledWith("bafytest", undefined);
+        });
+
+        test("passes lookupTimeoutMs to host-lookup", async () => {
+            const lookup = vi.fn().mockResolvedValue(testData);
+            const strategy: QueryStrategy = { kind: "host-lookup", lookup };
+            await executeQuery(strategy, "bafytest", { lookupTimeoutMs: 5000 });
+            expect(lookup).toHaveBeenCalledWith("bafytest", 5000);
+        });
+    });
+}