@parity/product-sdk-bulletin 0.1.0 → 0.2.0

package/src/errors.ts

@@ -1,33 +1,42 @@
 /**
- * Base class for all Bulletin Chain errors.
+ * Bulletin error types.
  *
- * Use `instanceof BulletinError` to catch any bulletin-related error.
+ * Two error families coexist:
  *
- * @example
- * ```ts
- * try {
- *   await bulletin.upload(data);
- * } catch (e) {
- *   if (e instanceof BulletinError) {
- *     console.error("Bulletin operation failed:", e.message);
- *   }
- * }
- * ```
+ * 1. **Upstream SDK errors** — `BulletinError` and `ErrorCode` from
+ *    `@parity/bulletin-sdk` cover upload/store/authorization failures
+ *    surfaced by `AsyncBulletinClient`. Each carries `code`, `retryable`,
+ *    and `recoveryHint`.
+ * 2. **Read-side errors** declared here — host preimage availability /
+ *    lookup timeouts / interrupts, plus CID format problems, surfaced by
+ *    our retrieval helpers (`fetchBytes`, `fetchJson`, `verifyOnChain`).
+ *
+ * Catch upstream errors with `instanceof BulletinError`. Catch our read-side
+ * errors with `instanceof ProductBulletinError` (or the specific subclass).
+ */
+export { BulletinError, ErrorCode } from "@parity/bulletin-sdk";
+
+/**
+ * Base class for read-side errors raised by `@parity/product-sdk-bulletin`.
+ *
+ * Distinct from upstream `BulletinError` which covers upload/store failures.
  */
-export class BulletinError extends Error {
+export class ProductBulletinError extends Error {
     constructor(message: string, options?: ErrorOptions) {
         super(message, options);
-        this.name = "BulletinError";
+        this.name = "ProductBulletinError";
     }
 }
 
 /**
  * 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.
+ * Thrown when bulletin operations require the host container but it's not
+ * available. This typically means the SDK is running outside Polkadot
+ * Browser / Desktop. The bulletin SDK is container-only by design — see
+ * the README for the rationale.
  */
-export class BulletinHostUnavailableError extends BulletinError {
+export class BulletinHostUnavailableError extends ProductBulletinError {
     constructor(operation: "upload" | "query") {
         super(
             `Host preimage API unavailable for ${operation}. Ensure you are running inside a host container (Polkadot Browser / Desktop).`,
@@ -39,10 +48,10 @@ export class BulletinHostUnavailableError extends BulletinError {
 /**
  * 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.
+ * 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 {
+export class BulletinLookupTimeoutError extends ProductBulletinError {
     /** The CID that was being looked up. */
     readonly cid: string;
     /** The timeout duration in milliseconds. */
@@ -59,10 +68,10 @@ export class BulletinLookupTimeoutError extends BulletinError {
 /**
  * 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.
+ * The host terminated the lookup subscription, typically after repeated
+ * failures or when the host determines the content is unavailable.
  */
-export class BulletinLookupInterruptedError extends BulletinError {
+export class BulletinLookupInterruptedError extends ProductBulletinError {
     /** The CID that was being looked up. */
     readonly cid: string;
 
@@ -73,13 +82,27 @@ export class BulletinLookupInterruptedError extends BulletinError {
     }
 }
 
+/**
+ * Invalid CID format or version.
+ */
+export class BulletinCidError extends ProductBulletinError {
+    /** The invalid CID string, if available. */
+    readonly cid?: string;
+
+    constructor(message: string, cid?: string) {
+        super(message);
+        this.name = "BulletinCidError";
+        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 {
+export class BulletinAuthorizationError extends ProductBulletinError {
     /** The address that was being checked. */
     readonly address: string;
 
@@ -90,146 +113,50 @@ export class BulletinAuthorizationError extends BulletinError {
     }
 }
 
-/**
- * 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");
+    describe("ProductBulletinError hierarchy", () => {
+        test("ProductBulletinError extends Error", () => {
+            const err = new ProductBulletinError("test");
             expect(err).toBeInstanceOf(Error);
-            expect(err).toBeInstanceOf(BulletinError);
-            expect(err.name).toBe("BulletinError");
+            expect(err.name).toBe("ProductBulletinError");
+        });
+
+        test("BulletinCidError", () => {
+            const err = new BulletinCidError("bad", "Qmabc");
+            expect(err).toBeInstanceOf(ProductBulletinError);
+            expect(err.cid).toBe("Qmabc");
         });
 
         test("BulletinHostUnavailableError", () => {
-            const err = new BulletinHostUnavailableError("upload");
-            expect(err).toBeInstanceOf(BulletinError);
-            expect(err.name).toBe("BulletinHostUnavailableError");
-            expect(err.message).toContain("upload");
+            const err = new BulletinHostUnavailableError("query");
+            expect(err).toBeInstanceOf(ProductBulletinError);
+            expect(err.message).toContain("query");
             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).toBeInstanceOf(ProductBulletinError);
             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).toBeInstanceOf(ProductBulletinError);
             expect(err.cid).toBe("bafyabc123");
             expect(err.message).toContain("interrupted");
         });
 
-        test("BulletinAuthorizationError with cause", () => {
-            const cause = new Error("RPC timeout");
+        test("BulletinAuthorizationError carries cause", () => {
+            const cause = new Error("RPC down");
             const err = new BulletinAuthorizationError("5GrwvaEF...", cause);
-            expect(err).toBeInstanceOf(BulletinError);
-            expect(err.name).toBe("BulletinAuthorizationError");
+            expect(err).toBeInstanceOf(ProductBulletinError);
             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/index.ts

@@ -1,38 +1,103 @@
+/**
+ * @parity/product-sdk-bulletin — Upload and retrieve content on the Polkadot Bulletin Chain.
+ *
+ * Wraps `@parity/bulletin-sdk` (chunking, DAG-PB manifests, CID calculation,
+ * progress events) and adds:
+ *
+ * - **Network presets** via {@link BulletinChain}
+ * - **Read helpers** ({@link BulletinClient.fetchBytes} / {@link BulletinClient.fetchJson})
+ * - **Authorization pre-flight** via {@link checkAuthorization}
+ *
+ * @packageDocumentation
+ */
+
 export { BulletinClient } from "./client.js";
-export { checkAuthorization } from "./authorization.js";
+export type { CreateBulletinClientOptions } from "./client.js";
+export { BulletinChain } from "./networks.js";
+export type { BulletinEnvironment, BulletinNetwork } from "./networks.js";
+export { authorizeAccount, checkAuthorization } from "./authorization.js";
+export type { AuthorizeAccountOptions } from "./authorization.js";
+export { createLazySigner } from "./lazy-signer.js";
+export { executeQuery, queryBytes, queryJson } from "./query.js";
+export { resolveQueryStrategy } from "./resolve-query.js";
+export type { QueryStrategy } from "./resolve-query.js";
+export { verifyOnChain } from "./verify.js";
+export type { ChainStoredEntry, VerifyOnChainOptions } from "./verify.js";
 export {
-    computeCid,
     cidToPreimageKey,
     hashToCid,
     HashAlgorithm,
     CidCodec,
 } from "./cid.js";
+
+// Errors — both upstream `BulletinError` and our read-side errors
 export {
     BulletinError,
-    BulletinHostUnavailableError,
-    BulletinLookupTimeoutError,
-    BulletinLookupInterruptedError,
+    ErrorCode,
+    ProductBulletinError,
     BulletinAuthorizationError,
-    BulletinGatewayUnavailableError,
-    BulletinGatewayFetchError,
     BulletinCidError,
+    BulletinHostUnavailableError,
+    BulletinLookupInterruptedError,
+    BulletinLookupTimeoutError,
 } 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";
+
+// Types
 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";
+
+// Re-exports from upstream SDK — surface for power users + so consumers
+// don't need a separate `@parity/bulletin-sdk` import.
+export {
+    AsyncBulletinClient,
+    BulletinPreparer,
+    AuthCallBuilder,
+    CallBuilder,
+    StoreBuilder,
+    MockBulletinClient,
+    AuthorizationScope,
+    ChunkStatus,
+    TxStatus,
+    WaitFor,
+    MAX_CHUNK_SIZE,
+    MAX_FILE_SIZE,
+    DEFAULT_CHUNKER_CONFIG,
+    DEFAULT_CLIENT_CONFIG,
+    DEFAULT_STORE_OPTIONS,
+    calculateCid,
+    cidFromBytes,
+    cidToBytes,
+    convertCid,
+    estimateAuthorization,
+    getContentHash,
+    parseCid,
+    reassembleChunks,
+    resolveClientConfig,
+    validateChunkSize,
+    CID,
+} from "@parity/bulletin-sdk";
+
+export type {
+    BulletinClientInterface,
+    BulletinTypedApi,
+    Chunk,
+    ChunkDetails,
+    ChunkProgressEvent,
+    ChunkedStoreResult,
+    ChunkerConfig,
+    ClientConfig,
+    DagManifest,
+    MockClientConfig,
+    MockOperation,
+    ProgressCallback,
+    ProgressEvent,
+    StoreOptions,
+    StoreResult,
+    SubmitFn,
+    TransactionReceipt,
+    TransactionStatusEvent,
+} from "@parity/bulletin-sdk";

package/src/lazy-signer.ts

@@ -0,0 +1,113 @@
+import type { PolkadotSigner } from "polkadot-api";
+
+/**
+ * Build a `PolkadotSigner` whose underlying signer is resolved on every call.
+ *
+ * `AsyncBulletinClient` takes a fixed `PolkadotSigner` at construction, but
+ * apps often build the bulletin client before any account is selected. This
+ * wrapper defers signer resolution: each call to `signTx` / `signBytes`
+ * invokes `getSigner()` and forwards to the result. If the getter returns
+ * `null`, calls throw with a clear message.
+ *
+ * The `publicKey` field is *also* resolved lazily — accessing it before a
+ * signer is available throws. This means callers that read `publicKey`
+ * eagerly will fail fast with the same error rather than seeing a stale
+ * key from a previously-selected account.
+ *
+ * Account changes between calls are picked up automatically: each sign
+ * resolves the current signer.
+ */
+export function createLazySigner(
+    getSigner: () => PolkadotSigner | null,
+    onMissing = "No signer available — connect a wallet and select an account first.",
+): PolkadotSigner {
+    const resolve = (): PolkadotSigner => {
+        const inner = getSigner();
+        if (!inner) throw new Error(onMissing);
+        return inner;
+    };
+
+    // `async` on the methods is deliberate: it converts a "no signer" throw
+    // from `resolve()` into a rejected Promise. PolkadotSigner.signTx /
+    // signBytes are typed as returning Promises, and consumers expect a
+    // rejection rather than a synchronous escape on the failure path.
+    const lazy: PolkadotSigner = {
+        get publicKey() {
+            return resolve().publicKey;
+        },
+        signTx: async (...args: Parameters<PolkadotSigner["signTx"]>) => resolve().signTx(...args),
+        signBytes: async (...args: Parameters<PolkadotSigner["signBytes"]>) =>
+            resolve().signBytes(...args),
+    };
+    return lazy;
+}
+
+if (import.meta.vitest) {
+    const { describe, test, expect, vi } = import.meta.vitest;
+
+    function makeMockSigner(label: string): PolkadotSigner {
+        return {
+            publicKey: new TextEncoder().encode(label),
+            signTx: vi.fn().mockResolvedValue(new Uint8Array([1])),
+            signBytes: vi.fn().mockResolvedValue(new Uint8Array([2])),
+        };
+    }
+
+    describe("createLazySigner", () => {
+        test("publicKey throws when getter returns null", () => {
+            const lazy = createLazySigner(() => null);
+            expect(() => lazy.publicKey).toThrow("No signer available");
+        });
+
+        test("publicKey resolves through getter when signer is available", () => {
+            const inner = makeMockSigner("alice");
+            const lazy = createLazySigner(() => inner);
+            expect(lazy.publicKey).toBe(inner.publicKey);
+        });
+
+        test("signTx throws when getter returns null", async () => {
+            const lazy = createLazySigner(() => null);
+            await expect(lazy.signTx(new Uint8Array(), {}, new Uint8Array(), 0)).rejects.toThrow(
+                "No signer available",
+            );
+        });
+
+        test("signTx forwards to current signer", async () => {
+            const inner = makeMockSigner("alice");
+            const lazy = createLazySigner(() => inner);
+            const callData = new Uint8Array([0xaa, 0xbb]);
+            const signedExtensions = {};
+            const metadata = new Uint8Array([0xcc]);
+            const atBlock = 42;
+            const result = await lazy.signTx(callData, signedExtensions, metadata, atBlock);
+            expect(inner.signTx).toHaveBeenCalledWith(
+                callData,
+                signedExtensions,
+                metadata,
+                atBlock,
+            );
+            expect(result).toEqual(new Uint8Array([1]));
+        });
+
+        test("signBytes forwards to current signer", async () => {
+            const inner = makeMockSigner("bob");
+            const lazy = createLazySigner(() => inner);
+            const result = await lazy.signBytes(new Uint8Array([9]));
+            expect(inner.signBytes).toHaveBeenCalledWith(new Uint8Array([9]));
+            expect(result).toEqual(new Uint8Array([2]));
+        });
+
+        test("picks up account changes between calls", () => {
+            let active: PolkadotSigner | null = makeMockSigner("first");
+            const lazy = createLazySigner(() => active);
+            expect(lazy.publicKey).toEqual(new TextEncoder().encode("first"));
+            active = makeMockSigner("second");
+            expect(lazy.publicKey).toEqual(new TextEncoder().encode("second"));
+        });
+
+        test("custom error message", () => {
+            const lazy = createLazySigner(() => null, "select an account first");
+            expect(() => lazy.publicKey).toThrow("select an account first");
+        });
+    });
+}

package/src/networks.ts

@@ -0,0 +1,49 @@
+/**
+ * Known Bulletin Chain networks.
+ *
+ * Pairs each environment with the genesis hash and the PAPI descriptor needed
+ * to construct an `AsyncBulletinClient`. Re-uses the descriptor exported by
+ * `@parity/product-sdk-descriptors/bulletin` — the bulletin descriptor is the
+ * same across all environments today, so the difference between entries is
+ * the genesis hash (and, downstream, the chain RPC URL).
+ */
+import { bulletin as bulletinDescriptor } from "@parity/product-sdk-descriptors/bulletin";
+
+export interface BulletinNetwork {
+    /** Genesis hash of the bulletin chain on this environment. */
+    genesisHash: `0x${string}`;
+    /** PAPI descriptor for typed API access. */
+    descriptor: typeof bulletinDescriptor;
+}
+
+/**
+ * Bulletin Chain network presets.
+ *
+ * Use these with {@link BulletinClient.create} when you want to be explicit
+ * about the network rather than passing an environment string. Reads go
+ * through the host's preimage subscription (container-only); no gateway
+ * URL is configured per network.
+ */
+export const BulletinChain = {
+    paseo: {
+        genesisHash: "0x744960c32e3a3df5440e1ecd4d34096f1ce2230d7016a5ada8a765d5a622b4ea",
+        descriptor: bulletinDescriptor,
+    },
+} as const satisfies Record<string, BulletinNetwork>;
+
+/** Network keys with built-in presets in {@link BulletinChain}. */
+export type BulletinEnvironment = keyof typeof BulletinChain;
+
+if (import.meta.vitest) {
+    const { describe, test, expect } = import.meta.vitest;
+
+    describe("BulletinChain", () => {
+        test("paseo has a valid genesis hash", () => {
+            expect(BulletinChain.paseo.genesisHash).toMatch(/^0x[a-f0-9]{64}$/);
+        });
+
+        test("paseo descriptor has matching genesis", () => {
+            expect(BulletinChain.paseo.descriptor.genesis).toBe(BulletinChain.paseo.genesisHash);
+        });
+    });
+}