@parity/product-sdk-bulletin 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,555 @@
+import { TypedApi, PolkadotSigner } from 'polkadot-api';
+import { WaitFor, TxStatus } from '@parity/product-sdk-tx';
+import { Environment } from '@parity/product-sdk-chain-client';
+export { Environment } from '@parity/product-sdk-chain-client';
+
+/**
+ * Hash algorithms supported by the Bulletin Chain.
+ *
+ * Values are multihash codes as defined in the
+ * {@link https://github.com/multiformats/multicodec multicodec table}.
+ */
+declare const HashAlgorithm: {
+    /** BLAKE2b-256 — default for product-sdk and the chain SDK. */
+    readonly Blake2b256: 45600;
+    /** SHA2-256 — default for bulletin-deploy. */
+    readonly Sha2_256: 18;
+    /** Keccak-256 — Ethereum compatibility. */
+    readonly Keccak256: 27;
+};
+/** A multihash code supported by the Bulletin Chain. */
+type HashAlgorithm = (typeof HashAlgorithm)[keyof typeof HashAlgorithm];
+/**
+ * CID codecs supported by the Bulletin Chain.
+ *
+ * Values are multicodec codes.
+ */
+declare const CidCodec: {
+    /** Raw binary — default for single-chunk data. */
+    readonly Raw: 85;
+    /** DAG-PB — used for multi-chunk manifests / directory structures. */
+    readonly DagPb: 112;
+    /** DAG-CBOR — alternative DAG encoding. */
+    readonly DagCbor: 113;
+};
+/** A multicodec code supported by the Bulletin Chain. */
+type CidCodec = (typeof CidCodec)[keyof typeof CidCodec];
+/**
+ * Compute the CIDv1 (blake2b-256, raw codec) for arbitrary data.
+ * Deterministic: same input always produces the same CID.
+ */
+declare function computeCid(data: Uint8Array): string;
+/**
+ * Extract the content hash digest from a CIDv1 string and return it as a
+ * `0x`-prefixed hex string — the preimage key format used by the host API.
+ *
+ * Accepts CIDv1 with any hash algorithm supported by the Bulletin Chain
+ * (blake2b-256, sha2-256, keccak-256).
+ *
+ * @param cid - CIDv1 base32 string (as produced by {@link computeCid} or {@link hashToCid}).
+ * @returns `0x`-prefixed hex string of the 32-byte hash digest.
+ * @throws If the CID is not CIDv1 or uses an unsupported hash algorithm.
+ */
+declare function cidToPreimageKey(cid: string): `0x${string}`;
+/**
+ * Reconstruct a CIDv1 from a `0x`-prefixed hex hash stored on-chain.
+ *
+ * This is the inverse of {@link cidToPreimageKey}: given a 32-byte content hash
+ * and the CID configuration used when the data was stored, it rebuilds the
+ * original CIDv1 so you can construct IPFS gateway URLs.
+ *
+ * The Bulletin Chain supports multiple hash algorithms and codecs — pass the
+ * values that match the on-chain `TransactionInfo` to get the correct CID.
+ * When omitted, defaults match {@link computeCid} (blake2b-256, raw).
+ *
+ * @param hexHash   - `0x`-prefixed hex string of a 32-byte hash digest
+ *   (66 characters total: `"0x"` + 64 hex chars).
+ * @param hashCode  - Multihash code of the hashing algorithm (default: blake2b-256 `0xb220`).
+ *   Use {@link HashAlgorithm} for the supported values.
+ * @param codec     - Multicodec code of the CID codec (default: raw `0x55`).
+ *   Use {@link CidCodec} for the supported values.
+ * @returns Base32-lower CIDv1 string.
+ * @throws If `hexHash` is not exactly 66 characters, or if the hash/codec is unsupported.
+ *
+ * @example
+ * ```ts
+ * import { hashToCid, HashAlgorithm, CidCodec, gatewayUrl, getGateway } from "@parity/product-sdk-bulletin";
+ *
+ * // Default (blake2b-256, raw) — matches computeCid output
+ * const cid = hashToCid(onChainHash);
+ *
+ * // SHA2-256 content stored via bulletin-deploy
+ * const cid2 = hashToCid(onChainHash, HashAlgorithm.Sha2_256);
+ *
+ * // DAG-PB manifest with blake2b-256
+ * const cid3 = hashToCid(manifestHash, HashAlgorithm.Blake2b256, CidCodec.DagPb);
+ *
+ * const url = gatewayUrl(cid, getGateway("paseo"));
+ * ```
+ *
+ * @see {@link cidToPreimageKey} for the reverse direction (CID → hex hash).
+ * @see {@link computeCid} for computing a CID from raw data.
+ * @see {@link HashAlgorithm} for supported hash algorithms.
+ * @see {@link CidCodec} for supported CID codecs.
+ */
+declare function hashToCid(hexHash: `0x${string}`, hashCode?: HashAlgorithm, codec?: CidCodec): string;
+
+/** Typed API for the Bulletin Chain, derived from PAPI descriptors. */
+type BulletinApi = TypedApi<any>;
+
+/**
+ * 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.
+ */
+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.
+ */
+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. */
+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`.
+ */
+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}. */
+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.
+ */
+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. */
+interface FetchOptions {
+    /** Timeout in ms. Default: 30_000. */
+    timeoutMs?: number;
+}
+/** Options for query operations that support host lookup auto-resolution. */
+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;
+}
+
+/**
+ * Ergonomic entry point for Bulletin Chain operations.
+ *
+ * Bundles a typed Bulletin API (from chain-client) and an IPFS gateway URL
+ * so callers don't need to re-pass them on every call.
+ *
+ * Both upload and query paths use the host container APIs:
+ * - **Uploads** — the host preimage API signs and submits automatically.
+ * - **Queries** (`fetchBytes`/`fetchJson`) — uses host preimage lookup with caching.
+ *
+ * @example
+ * ```ts
+ * const bulletin = await BulletinClient.create("paseo");
+ * const result = await bulletin.upload(fileBytes);
+ * const metadata = await bulletin.fetchJson<Metadata>(result.cid);
+ * ```
+ */
+declare class BulletinClient {
+    readonly api: BulletinApi;
+    readonly gateway: string;
+    private queryStrategyPromise;
+    private constructor();
+    /** Lazily resolve and cache the query strategy for the client lifetime. */
+    private resolveQuery;
+    /** Create from an environment — resolves API via chain-client, gateway from known list. */
+    static create(env: Environment): Promise<BulletinClient>;
+    /** Create from an explicit API and gateway (custom setups, testing). */
+    static from(api: BulletinApi, gateway: string): BulletinClient;
+    /** Compute CID without uploading. Static — no instance needed. */
+    static computeCid(data: Uint8Array): string;
+    /**
+     * Reconstruct a CID from a `0x`-prefixed hex hash. Static — no instance needed.
+     *
+     * Useful for converting on-chain hashes back to CIDs for IPFS gateway lookups.
+     * Pass optional hash algorithm and codec to match the on-chain CID configuration.
+     *
+     * @see {@link hashToCid} for full documentation.
+     */
+    static hashToCid(hexHash: `0x${string}`, hashCode?: HashAlgorithm, codec?: CidCodec): string;
+    /**
+     * Upload data to the Bulletin Chain.
+     *
+     * @param data   - Raw bytes to store.
+     * @param signer - Optional signer. When omitted, uses the host preimage API.
+     * @param options - Upload options (timeout, waitFor, status callback).
+     */
+    upload(data: Uint8Array, signer?: PolkadotSigner, options?: Omit<UploadOptions, "gateway">): Promise<UploadResult>;
+    /**
+     * Upload multiple items sequentially.
+     *
+     * @param items  - Array of items to upload, each with data and a label.
+     * @param signer - Optional signer. When omitted, auto-resolved.
+     * @param options - Batch upload options (timeout, progress callback).
+     */
+    batchUpload(items: BatchUploadItem[], signer?: PolkadotSigner, options?: Omit<BatchUploadOptions, "gateway">): Promise<BatchUploadResult[]>;
+    /**
+     * Fetch raw bytes by CID.
+     *
+     * Uses host preimage lookup with caching.
+     */
+    fetchBytes(cid: string, options?: QueryOptions): Promise<Uint8Array>;
+    /**
+     * Fetch and parse JSON by CID.
+     *
+     * Auto-resolves query path (same as {@link fetchBytes}).
+     */
+    fetchJson<T>(cid: string, options?: QueryOptions): Promise<T>;
+    /** Check if a CID exists on the gateway. */
+    cidExists(cid: string): Promise<boolean>;
+    /** Build the full gateway URL for a CID. */
+    gatewayUrl(cid: string): string;
+    /**
+     * Check whether an account is authorized to store data on the Bulletin Chain.
+     *
+     * Use as a pre-flight check before {@link upload} to provide clear UX
+     * instead of letting the transaction fail mid-execution.
+     *
+     * @param address - SS58-encoded account address to check.
+     * @returns Authorization status with remaining quota.
+     *
+     * @see {@link checkAuthorization} for the standalone function equivalent.
+     */
+    checkAuthorization(address: string): Promise<AuthorizationStatus>;
+}
+
+/**
+ * Check whether an account is authorized to store data on the Bulletin Chain.
+ *
+ * Queries `TransactionStorage.Authorizations` for the given address and returns
+ * the raw authorization quota. Use this as a pre-flight check before calling
+ * {@link upload} to provide clear UX ("not authorized" / "insufficient quota")
+ * instead of letting the transaction fail mid-execution.
+ *
+ * The expiration block number is returned as-is — the chain enforces expiration
+ * at submission time, so callers can optionally compare against the current
+ * block for display purposes.
+ *
+ * @param api     - Typed Bulletin Chain API instance.
+ * @param address - SS58-encoded account address to check.
+ * @returns Authorization status with remaining quota.
+ *
+ * @example
+ * ```ts
+ * import { checkAuthorization } from "@parity/product-sdk-bulletin";
+ *
+ * const auth = await checkAuthorization(api, address);
+ * if (!auth.authorized) {
+ *     console.error("Account is not authorized for bulletin storage");
+ * } else if (auth.remainingBytes < BigInt(fileBytes.length)) {
+ *     console.error(`Insufficient quota: ${auth.remainingBytes} bytes remaining`);
+ * }
+ * ```
+ *
+ * @see {@link BulletinClient.checkAuthorization} for the client method equivalent.
+ */
+declare function checkAuthorization(api: BulletinApi, address: string): Promise<AuthorizationStatus>;
+
+/**
+ * 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);
+ *   }
+ * }
+ * ```
+ */
+declare class BulletinError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * 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.
+ */
+declare class BulletinHostUnavailableError extends BulletinError {
+    constructor(operation: "upload" | "query");
+}
+/**
+ * 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.
+ */
+declare 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);
+}
+/**
+ * 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.
+ */
+declare class BulletinLookupInterruptedError extends BulletinError {
+    /** The CID that was being looked up. */
+    readonly cid: string;
+    constructor(cid: string);
+}
+/**
+ * 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.
+ */
+declare class BulletinAuthorizationError extends BulletinError {
+    /** The address that was being checked. */
+    readonly address: string;
+    constructor(address: string, cause?: unknown);
+}
+/**
+ * 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.
+ */
+declare class BulletinGatewayUnavailableError extends BulletinError {
+    /** The environment that was requested. */
+    readonly environment: string;
+    constructor(environment: string);
+}
+/**
+ * An IPFS gateway request failed.
+ *
+ * Thrown when a fetch to the IPFS gateway returns a non-OK response.
+ */
+declare 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);
+}
+/**
+ * Invalid CID format or version.
+ *
+ * Thrown when a CID string cannot be parsed or has an unexpected version/codec.
+ */
+declare class BulletinCidError extends BulletinError {
+    /** The invalid CID string, if available. */
+    readonly cid?: string;
+    constructor(message: string, cid?: string);
+}
+
+/**
+ * Get the IPFS gateway URL for an environment.
+ * @throws {BulletinGatewayUnavailableError} If the network doesn't have a live gateway yet.
+ */
+declare function getGateway(env: Environment): string;
+/** Build the full gateway URL for a CID. */
+declare function gatewayUrl(cid: string, gateway: string): string;
+/** Check if a CID exists on the gateway (HEAD request). Returns false on any error or timeout. */
+declare function cidExists(cid: string, gateway: string, options?: FetchOptions): Promise<boolean>;
+/**
+ * Fetch raw bytes from the gateway.
+ * @throws {BulletinGatewayFetchError} If the gateway returns a non-OK response.
+ */
+declare function fetchBytes(cid: string, gateway: string, options?: FetchOptions): Promise<Uint8Array>;
+/** Fetch and parse JSON from the gateway. */
+declare function fetchJson<T>(cid: string, gateway: string, options?: FetchOptions): Promise<T>;
+
+/**
+ * Query strategy for the Bulletin Chain.
+ *
+ * The host manages the lookup via its preimage subscription API,
+ * which includes local caching and managed IPFS polling.
+ */
+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.
+ */
+declare function resolveQueryStrategy(): Promise<QueryStrategy>;
+
+/**
+ * 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.
+ */
+declare function queryBytes(cid: string, options?: QueryOptions): Promise<Uint8Array>;
+/**
+ * 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.
+ */
+declare function queryJson<T>(cid: string, options?: QueryOptions): Promise<T>;
+
+/**
+ * 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.
+ */
+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.
+ */
+declare function resolveUploadStrategy(explicitSigner?: PolkadotSigner): Promise<UploadStrategy>;
+
+/**
+ * Upload data to the Bulletin Chain.
+ *
+ * When a signer is provided, submits a `TransactionStorage.store` transaction
+ * directly. When omitted, uses the host preimage API — the host signs and
+ * submits automatically.
+ *
+ * Computes the CIDv1 (blake2b-256, raw codec) locally.
+ *
+ * @param api    - Typed Bulletin Chain API.
+ * @param data   - Raw bytes to store.
+ * @param signer - Optional signer. When omitted, uses host preimage API.
+ * @param options - Upload options (gateway, timeout, waitFor, status callback).
+ * @returns Upload result with CID and either blockHash or preimageKey.
+ */
+declare function upload(api: BulletinApi, data: Uint8Array, signer?: PolkadotSigner, options?: UploadOptions): Promise<UploadResult>;
+/**
+ * Upload multiple items sequentially to the Bulletin Chain.
+ *
+ * Bulletin Chain requires sequential transaction submission (nonce ordering).
+ * Individual failures are captured in results — the batch does not abort.
+ *
+ * Signer resolution follows the same rules as {@link upload}: when omitted,
+ * the strategy is auto-resolved once and reused for all items.
+ *
+ * @param api    - Typed Bulletin Chain API.
+ * @param items  - Array of items to upload, each with data and a label.
+ * @param signer - Optional signer. When omitted, auto-resolved.
+ * @param options - Batch upload options (gateway, timeout, progress callback).
+ * @returns Array of results, one per item, preserving input order.
+ */
+declare function batchUpload(api: BulletinApi, items: BatchUploadItem[], signer?: PolkadotSigner, options?: BatchUploadOptions): Promise<BatchUploadResult[]>;
+
+export { type AuthorizationStatus, type BatchUploadItem, type BatchUploadOptions, type BatchUploadResult, type BulletinApi, BulletinAuthorizationError, BulletinCidError, BulletinClient, BulletinError, BulletinGatewayFetchError, BulletinGatewayUnavailableError, BulletinHostUnavailableError, BulletinLookupInterruptedError, BulletinLookupTimeoutError, CidCodec, type FetchOptions, HashAlgorithm, type QueryOptions, type QueryStrategy, type UploadOptions, type UploadResult, type UploadStrategy, batchUpload, checkAuthorization, cidExists, cidToPreimageKey, computeCid, fetchBytes, fetchJson, gatewayUrl, getGateway, hashToCid, queryBytes, queryJson, resolveQueryStrategy, resolveUploadStrategy, upload };