@parity/product-sdk-bulletin 0.1.0 → 0.2.0

package/src/query.ts

@@ -1,19 +1,33 @@
+import { CidCodec, parseCid, UnixFsDagBuilder } from "@parity/bulletin-sdk";
 import { createLogger } from "@parity/product-sdk-logger";
 
-import { resolveQueryStrategy, type QueryStrategy } from "./resolve-query.js";
+import type { QueryStrategy } from "./resolve-query.js";
+import { resolveQueryStrategy } 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.
+ * Fetch raw bytes for a CID via the host's preimage lookup.
  *
- * Uses local cache + managed IPFS polling via the host container.
+ * Container-only by design: the bulletin SDK does not retrieve content
+ * through public IPFS gateways. Inside a Polkadot Browser / Desktop
+ * container, the host's `preimageManager` provides a cached, polling-
+ * managed lookup that returns bytes when the underlying IPFS network
+ * makes them available. Outside a container, this throws
+ * {@link BulletinHostUnavailableError}.
+ *
+ * The bulletin chain stores transaction *metadata* on-chain
+ * (`chunk_root`, `content_hash`, `size`, `cid_codec`, `hashing`) — the
+ * content bytes themselves live in IPFS and are surfaced through the
+ * host's preimage subscription, never via direct gateway fetch.
+ *
+ * To prove that a CID was stored on-chain (without fetching the bytes),
+ * use `verifyOnChain` from `verify.ts`.
  *
  * @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.
+ * @param options - Query options (`lookupTimeoutMs` for host).
+ * @throws {BulletinHostUnavailableError} If running outside a container.
  */
 export async function queryBytes(cid: string, options?: QueryOptions): Promise<Uint8Array> {
     const strategy = await resolveQueryStrategy();
@@ -21,14 +35,9 @@ export async function queryBytes(cid: string, options?: QueryOptions): Promise<U
 }
 
 /**
- * Fetch and parse JSON for a CID, auto-resolving the query path.
- *
- * Delegates to {@link queryBytes} and parses the result as JSON.
+ * Fetch and parse JSON for a CID via the host's preimage lookup.
  *
- * @param cid     - CIDv1 string to fetch.
- * @param options - Query options.
- * @returns Parsed JSON value.
- * @throws {Error} If the host preimage API is unavailable.
+ * Convenience wrapper over {@link queryBytes}.
  */
 export async function queryJson<T>(cid: string, options?: QueryOptions): Promise<T> {
     const bytes = await queryBytes(cid, options);
@@ -38,45 +47,170 @@ export async function queryJson<T>(cid: string, options?: QueryOptions): Promise
 /**
  * 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.
+ * Exposed so `BulletinClient` can resolve the strategy once at
+ * construction time and reuse it across calls without re-detecting
+ * the host environment on every fetch.
+ *
+ * **Reassembly is automatic.** If `cid` carries the DAG-PB codec
+ * (`0x70`) — meaning the upload was chunked and a UnixFS manifest was
+ * created — this function recursively fetches each chunk via `strategy
+ * .lookup` and returns the concatenated bytes. Pass `noReassemble: true`
+ * to get the raw manifest bytes instead.
  *
- * @param strategy - Pre-resolved query strategy.
- * @param cid      - CIDv1 string to fetch.
- * @param options  - Query options.
- * @returns Raw bytes of the content.
+ * For raw-codec CIDs (`0x55`, single-chunk content), the bytes returned
+ * by the host are returned directly — no parsing overhead.
  */
 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);
+    log.info("query: host preimage lookup", { cid });
+    const bytes = await strategy.lookup(cid, options?.lookupTimeoutMs);
+
+    // Skip reassembly when the caller explicitly asks for raw bytes, or
+    // when the CID's codec says this is a single-block payload (raw,
+    // 0x55) — most uploads land here, so the parseCid + Promise.all
+    // overhead is worth gating on codec rather than always paying it.
+    if (options?.noReassemble) return bytes;
+    const parsed = parseCid(cid);
+    if (parsed.code !== CidCodec.DagPb) return bytes;
+
+    log.info("query: reassembling DAG-PB manifest", { cid });
+    const builder = new UnixFsDagBuilder();
+    const { chunkCids } = await builder.parse(bytes);
+
+    // Fetch chunks in parallel — the host's preimageManager caches and
+    // dedupes lookups, and order is preserved by Promise.all's input
+    // ordering, which matches the DAG-PB Links order from parse().
+    const chunks = await Promise.all(
+        chunkCids.map((c) => strategy.lookup(c.toString(), options?.lookupTimeoutMs)),
+    );
+
+    let total = 0;
+    for (const chunk of chunks) total += chunk.length;
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return out;
 }
 
 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.
+    const { beforeAll, describe, test, expect, vi } = import.meta.vitest;
+    const { calculateCid } = await import("@parity/bulletin-sdk");
 
     describe("executeQuery", () => {
         const testData = new Uint8Array([1, 2, 3]);
 
-        test("executes host-lookup strategy", async () => {
+        test("delegates to the strategy's lookup function", async () => {
             const lookup = vi.fn().mockResolvedValue(testData);
             const strategy: QueryStrategy = { kind: "host-lookup", lookup };
-            const result = await executeQuery(strategy, "bafytest");
+            // Use a real raw-codec CID so the codec check passes through
+            // without triggering reassembly.
+            const rawCid = (await calculateCid(testData)).toString();
+            const result = await executeQuery(strategy, rawCid);
             expect(result).toBe(testData);
-            expect(lookup).toHaveBeenCalledWith("bafytest", undefined);
+            expect(lookup).toHaveBeenCalledWith(rawCid, undefined);
+        });
+
+        test("forwards lookupTimeoutMs to the strategy", async () => {
+            const lookup = vi.fn().mockResolvedValue(testData);
+            const strategy: QueryStrategy = { kind: "host-lookup", lookup };
+            const rawCid = (await calculateCid(testData)).toString();
+            await executeQuery(strategy, rawCid, { lookupTimeoutMs: 5000 });
+            expect(lookup).toHaveBeenCalledWith(rawCid, 5000);
         });
 
-        test("passes lookupTimeoutMs to host-lookup", async () => {
+        test("returns raw bytes directly for raw-codec CIDs (no reassembly)", 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);
+            const rawCid = (await calculateCid(testData)).toString();
+            const result = await executeQuery(strategy, rawCid);
+            expect(result).toBe(testData);
+            // Single lookup, no recursion.
+            expect(lookup).toHaveBeenCalledTimes(1);
+        });
+
+        test("noReassemble: true short-circuits even for DAG-PB CIDs", async () => {
+            // Manufacture a DAG-PB CID; we don't need the bytes to actually
+            // be a valid manifest because we're skipping the parse step.
+            const fakeManifestBytes = new Uint8Array([10, 20, 30]);
+            const dagPbCid = (await calculateCid(fakeManifestBytes, /* dag-pb */ 0x70)).toString();
+            const lookup = vi.fn().mockResolvedValue(fakeManifestBytes);
+            const strategy: QueryStrategy = { kind: "host-lookup", lookup };
+            const result = await executeQuery(strategy, dagPbCid, { noReassemble: true });
+            expect(result).toBe(fakeManifestBytes);
+            expect(lookup).toHaveBeenCalledTimes(1);
+        });
+
+        describe("DAG-PB reassembly", () => {
+            // Build a real manifest: two raw chunks, dag-pb root.
+            const chunkA = new Uint8Array([0xaa, 0xaa, 0xaa]);
+            const chunkB = new Uint8Array([0xbb, 0xbb]);
+            let chunkACid: string;
+            let chunkBCid: string;
+            let manifestBytes: Uint8Array;
+            let manifestCid: string;
+
+            beforeAll(async () => {
+                const { UnixFsDagBuilder: Builder } = await import("@parity/bulletin-sdk");
+                chunkACid = (await calculateCid(chunkA)).toString();
+                chunkBCid = (await calculateCid(chunkB)).toString();
+                const cidA = await calculateCid(chunkA);
+                const cidB = await calculateCid(chunkB);
+                const manifest = await new Builder().build([
+                    { data: chunkA, cid: cidA, index: 0, totalChunks: 2 },
+                    { data: chunkB, cid: cidB, index: 1, totalChunks: 2 },
+                ]);
+                manifestBytes = manifest.dagBytes;
+                manifestCid = manifest.rootCid.toString();
+            });
+
+            test("recursively fetches chunks and concatenates", async () => {
+                const lookup = vi.fn(async (cid: string) => {
+                    if (cid === manifestCid) return manifestBytes;
+                    if (cid === chunkACid) return chunkA;
+                    if (cid === chunkBCid) return chunkB;
+                    throw new Error(`unexpected lookup: ${cid}`);
+                });
+                const strategy: QueryStrategy = { kind: "host-lookup", lookup };
+                const result = await executeQuery(strategy, manifestCid);
+                expect(result).toEqual(new Uint8Array([0xaa, 0xaa, 0xaa, 0xbb, 0xbb]));
+                // 1 manifest + 2 chunks = 3 lookups.
+                expect(lookup).toHaveBeenCalledTimes(3);
+            });
+
+            test("forwards lookupTimeoutMs to every chunk lookup", async () => {
+                const lookup = vi.fn(async (cid: string, _timeoutMs?: number) => {
+                    if (cid === manifestCid) return manifestBytes;
+                    if (cid === chunkACid) return chunkA;
+                    if (cid === chunkBCid) return chunkB;
+                    throw new Error("boom");
+                });
+                const strategy: QueryStrategy = { kind: "host-lookup", lookup };
+                await executeQuery(strategy, manifestCid, { lookupTimeoutMs: 7777 });
+                for (const call of lookup.mock.calls) {
+                    expect(call[1]).toBe(7777);
+                }
+            });
+
+            test("preserves chunk order from the manifest", async () => {
+                const lookup = vi.fn(async (cid: string) => {
+                    if (cid === manifestCid) return manifestBytes;
+                    if (cid === chunkACid) return chunkA;
+                    if (cid === chunkBCid) return chunkB;
+                    throw new Error("boom");
+                });
+                const strategy: QueryStrategy = { kind: "host-lookup", lookup };
+                const result = await executeQuery(strategy, manifestCid);
+                // Order matters: chunkA bytes must come before chunkB bytes
+                // even though both are fetched in parallel.
+                expect(Array.from(result.slice(0, 3))).toEqual([0xaa, 0xaa, 0xaa]);
+                expect(Array.from(result.slice(3))).toEqual([0xbb, 0xbb]);
+            });
         });
     });
 }

package/src/resolve-query.ts

@@ -1,7 +1,8 @@
+import { calculateCid } from "@parity/bulletin-sdk";
 import { getPreimageManager, type PreimageManager } from "@parity/product-sdk-host";
 import { createLogger } from "@parity/product-sdk-logger";
 
-import { cidToPreimageKey, computeCid } from "./cid.js";
+import { cidToPreimageKey } from "./cid.js";
 import {
     BulletinHostUnavailableError,
     BulletinLookupInterruptedError,
@@ -100,7 +101,7 @@ export function lookupViaHost(
 }
 
 if (import.meta.vitest) {
-    const { describe, test, expect, vi } = import.meta.vitest;
+    const { beforeAll, describe, test, expect, vi } = import.meta.vitest;
 
     // Note: resolveQueryStrategy tests require e2e testing as they
     // depend on the host container environment.
@@ -138,7 +139,12 @@ if (import.meta.vitest) {
             return { lookup, unsubscribe, cancelInterrupt, submit: vi.fn() };
         }
 
-        const testCid = computeCid(new TextEncoder().encode("test"));
+        // calculateCid is async (Web Crypto), so populate lazily.
+        let testCid: string;
+        beforeAll(async () => {
+            const cid = await calculateCid(new TextEncoder().encode("test"));
+            testCid = cid.toString();
+        });
 
         test("resolves on first non-null callback", async () => {
             const manager = createMockManager("resolve");

package/src/types.ts

@@ -1,116 +1,17 @@
-import type { TypedApi } from "polkadot-api";
-import type { TxStatus, WaitFor } from "@parity/product-sdk-tx";
+import type { BulletinTypedApi } from "@parity/bulletin-sdk";
 
-/** Typed API for the Bulletin Chain, derived from PAPI descriptors. */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type BulletinApi = TypedApi<any>;
+/** Typed API for the Bulletin Chain (re-export from upstream). */
+export type BulletinApi = BulletinTypedApi;
 
+/** Re-exported environment string from chain-client. */
 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.
+ * Returned by {@link checkAuthorization} as a pre-flight check before storing
+ * data. Consumers can use this to show "not authorized" or "insufficient quota"
+ * messages instead of letting the transaction fail mid-execution.
  */
 export interface AuthorizationStatus {
     /** Whether an authorization entry exists for this account. */
@@ -123,18 +24,26 @@ export interface AuthorizationStatus {
     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 {
+/**
+ * Options for {@link BulletinClient.fetchBytes} / {@link BulletinClient.fetchJson}.
+ */
+export interface QueryOptions {
     /**
-     * Timeout for the host preimage lookup subscription in ms.
-     * Only applies when the query resolves through the host path.
-     * Default: 30_000.
+     * Timeout for the host preimage lookup subscription, in ms.
+     * Default: 30_000. Applied per lookup — for chunked content (DAG-PB
+     * manifest CIDs), the manifest fetch and each child chunk fetch
+     * each get this budget.
      */
     lookupTimeoutMs?: number;
+    /**
+     * When `true`, return the raw bytes for the requested CID without
+     * parsing or recursing into a DAG-PB manifest. Default: `false` — the
+     * client transparently reassembles chunked content so callers don't
+     * need to know whether a CID points at a single chunk or a manifest.
+     *
+     * Set this if you want to inspect the manifest itself, e.g., to read
+     * `unixfs.fileSize()` ahead of fetching, or to drive your own chunk
+     * pipeline.
+     */
+    noReassemble?: boolean;
 }