@parity/product-sdk-cloud-storage 0.5.0

package/dist/index.d.ts

@@ -0,0 +1,600 @@
+import { BulletinTypedApi, AsyncBulletinClient, ClientConfig, StoreBuilder, AuthCallBuilder, CallBuilder } from '@parity/bulletin-sdk';
+export { AsyncBulletinClient, AuthCallBuilder, AuthorizationScope, BulletinClientInterface, BulletinError, BulletinPreparer, BulletinTypedApi, CID, CallBuilder, Chunk, ChunkDetails, ChunkProgressEvent, ChunkStatus, ChunkedStoreResult, ChunkerConfig, ClientConfig, DEFAULT_CHUNKER_CONFIG, DEFAULT_CLIENT_CONFIG, DEFAULT_STORE_OPTIONS, DagManifest, ErrorCode, MAX_CHUNK_SIZE, MAX_FILE_SIZE, MockBulletinClient, MockClientConfig, MockOperation, ProgressCallback, ProgressEvent, StoreBuilder, StoreOptions, StoreResult, SubmitFn, TransactionReceipt, TransactionStatusEvent, TxStatus, WaitFor, calculateCid, cidFromBytes, cidToBytes, convertCid, estimateAuthorization, getContentHash, parseCid, reassembleChunks, resolveClientConfig, validateChunkSize } from '@parity/bulletin-sdk';
+import { PolkadotSigner } from 'polkadot-api';
+import { paseo_bulletin } from '@parity/product-sdk-descriptors/paseo-bulletin';
+import { WaitFor, TxStatus } from '@parity/product-sdk-tx';
+export { Environment } from '@parity/product-sdk-chain-client';
+
+/**
+ * Known Cloud Storage networks.
+ *
+ * Each environment pairs its genesis hash with a per-environment PAPI descriptor.
+ */
+
+interface CloudStorageNetwork {
+    /** Genesis hash of the underlying chain on this environment. */
+    genesisHash: `0x${string}`;
+    /** PAPI descriptor for typed API access. */
+    descriptor: typeof paseo_bulletin;
+}
+/**
+ * Cloud Storage network presets.
+ *
+ * Use these with {@link CloudStorageClient.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.
+ */
+declare const CloudStorageNetworks: {
+    readonly paseo: {
+        readonly genesisHash: "0x8cfe6717dc4becfda2e13c488a1e2061ff2dfee96e7d031157f72d36716c0a22";
+        readonly descriptor: any;
+    };
+};
+/** Network keys with built-in presets in {@link CloudStorageNetworks}. */
+type CloudStorageEnvironment = keyof typeof CloudStorageNetworks;
+
+/** Typed API for the Cloud Storage (re-export from upstream BulletinTypedApi). */
+type CloudStorageApi = BulletinTypedApi;
+
+/** //TODO: Come back to this (code docs might need update)
+ * Authorization status for a Cloud Storage account.
+ *
+ * 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.
+ */
+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 {@link CloudStorageClient.fetchBytes} / {@link CloudStorageClient.fetchJson}.
+ */
+interface QueryOptions {
+    /**
+     * 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;
+}
+
+/** A single matched entry from `TransactionStorage.Transactions`. */
+interface ChainStoredEntry {
+    /** Block number where the transaction was included. */
+    block: number;
+    /** Index of the entry within the block's transactions array. */
+    index: number;
+    /** Size of the stored data in bytes (from chain metadata). */
+    size: number;
+    /** Number of chunks (1 for unchunked data, >1 for chunked + manifest). */
+    blockChunks: number;
+}
+/**
+ * Verification options for {@link verifyStored}.
+ */
+interface VerifyStoredOptions {
+    /**
+     * Block number to look up. Pass the `blockNumber` returned from a prior
+     * `store(...).send()` for an O(1) lookup.
+     *
+     * If omitted, throws — full-chain scans are not supported because
+     * `RetentionPeriod` can be many days of blocks. Use `getEntries()` on
+     * `api.query.TransactionStorage.Transactions` directly if you need that.
+     */
+    block: number;
+    /**
+     * Optional: index within the block. When provided, narrows verification
+     * to that exact slot. Useful when re-checking a known `(block, index)`
+     * tuple from an earlier receipt.
+     */
+    index?: number;
+}
+/**
+ * Verify that a CID is recorded in the cloud storage (bulletin chain's `Transactions` storage)
+ * at the given block.
+ *
+ * Returns the matched entry (with block + index) when the CID's content
+ * hash and hashing algorithm both match a `Transactions[block]` entry.
+ * Returns `null` when no match is found at that block.
+ *
+ * @param api     - Typed Cloud Storage API instance.
+ * @param cid     - CIDv1 string to look up.
+ * @param options - Verification target (block number, optional index).
+ *
+ * @example
+ * ```ts
+ * const receipt = await client.store(data).send();
+ * if (receipt.blockNumber !== undefined) {
+ *   const entry = await verifyStored(client.api, receipt.cid!.toString(), {
+ *     block: receipt.blockNumber,
+ *     index: receipt.extrinsicIndex,
+ *   });
+ *   if (!entry) console.warn("CID not found in expected block — chain reorg?");
+ * }
+ * ```
+ */
+declare function verifyStored(api: CloudStorageApi, cid: string, options: VerifyStoredOptions): Promise<ChainStoredEntry | null>;
+
+/**
+ * Options for {@link CloudStorageClient.create}.
+ *
+ * One of two construction shapes is supported:
+ *
+ * - **Environment shorthand** — pass an `environment` string keyed by
+ *   {@link CloudStorageNetworks}. Wires up the chain-client automatically.
+ * - **Explicit network** — pass `genesisHash` and `descriptor` directly
+ *   (e.g., spread from a {@link CloudStorageNetworks} entry, or supply custom
+ *   values for a private chain).
+ */
+type CreateCloudStorageClientOptions = (CreateCloudStorageClientCommon & {
+    environment: CloudStorageEnvironment;
+}) | (CreateCloudStorageClientCommon & {
+    genesisHash: `0x${string}`;
+    descriptor: (typeof CloudStorageNetworks)[CloudStorageEnvironment]["descriptor"];
+});
+interface CreateCloudStorageClientCommon {
+    /** Signer for transaction submission. Required — every store needs a signer. */
+    signer: PolkadotSigner;
+    /** Optional config forwarded to the upstream client. */
+    config?: Partial<ClientConfig>;
+}
+/**
+ * Ergonomic entry point for Cloud Storage operations.
+ *
+ * Wraps the upstream `@parity/bulletin-sdk` client (which handles
+ * chunking, DAG-PB manifests, CID calculation, and progress events) and adds:
+ *
+ * - **Network presets** via {@link CloudStorageClient.create} and {@link CloudStorageNetworks}.
+ * - **Read helpers** ({@link fetchBytes}, {@link fetchJson}) routed through
+ *   the host's preimage subscription — upstream is upload-only and the SDK
+ *   is container-only by design (no public-gateway fetches).
+ * - **Pre-flight authorization check** ({@link checkAuthorization}) for
+ *   friendlier UX before submitting a store.
+ *
+ * For uploads, mirror upstream's fluent builders:
+ *
+ * ```ts
+ * const client = await CloudStorageClient.create({ environment: "paseo", signer });
+ * const result = await client.store(data).send();
+ * ```
+ *
+ * For chunked uploads with progress:
+ *
+ * ```ts
+ * const result = await client
+ *   .store(largeFile)
+ *   .withChunkSize(1 << 20)
+ *   .withCallback((evt) => console.log(evt))
+ *   .send();
+ * ```
+ */
+declare class CloudStorageClient {
+    /** Underlying upstream client — exposed for power users. */
+    readonly inner: AsyncBulletinClient;
+    /** Typed CloudStorage API. */
+    readonly api: CloudStorageApi;
+    /** Lazy-resolved host-preimage query strategy, cached for the client lifetime. */
+    private queryStrategyPromise;
+    /** Constructed via {@link create} or {@link from}. */
+    private constructor();
+    /** Resolve and cache the host query strategy on first use. */
+    private resolveQuery;
+    /**
+     * Create a client from an environment shorthand or an explicit network.
+     *
+     * Environment form uses our `getChainAPI(env)` to resolve the typed API.
+     * Explicit form skips the environment lookup and lets you pass any
+     * genesis/descriptor combo.
+     *
+     * @example
+     * ```ts
+     * // Shorthand
+     * const client = await CloudStorageClient.create({ environment: "paseo", signer });
+     *
+     * // Explicit (custom network)
+     * const client = await CloudStorageClient.create({
+     *   ...CloudStorageNetworks.paseo,
+     *   signer,
+     *   config: { defaultChunkSize: 1 << 20 },
+     * });
+     * ```
+     */
+    static create(options: CreateCloudStorageClientOptions): Promise<CloudStorageClient>;
+    /**
+     * Construct from a pre-built `AsyncBulletinClient` and PAPI typed API.
+     *
+     * Use this when you already own the connection lifecycle (BYOD setups,
+     * tests). The caller is responsible for calling `papiClient.destroy()`
+     * — this client's {@link destroy} only tears down the upstream's
+     * `onDestroy` hook.
+     */
+    static from(inner: AsyncBulletinClient, api: CloudStorageApi): CloudStorageClient;
+    /** Build a store transaction. See upstream `StoreBuilder` for chained options. */
+    store(data: Uint8Array): StoreBuilder;
+    /** Authorize an account to store data on the chain (sudo required on most networks). */
+    authorizeAccount(who: string, transactions: number, bytes: bigint): AuthCallBuilder;
+    /** Authorize content storage by hash (anyone can store; no fees). */
+    authorizePreimage(contentHash: Uint8Array, maxSize: bigint): AuthCallBuilder;
+    /** Renew a stored transaction by block + index. */
+    renew(block: number, index: number): CallBuilder;
+    /** Estimate the authorization (transactions + bytes) needed for `dataSize`. */
+    estimateAuthorization(dataSize: number): {
+        transactions: number;
+        bytes: number;
+    };
+    /**
+     * Fetch raw bytes for a CID via the host's preimage lookup.
+     *
+     * Container-only — outside a Polkadot Browser / Desktop host this
+     * throws {@link CloudStorageHostUnavailableError}. The chain stores
+     * content metadata (`content_hash`, size, codec) but the bytes
+     * themselves are surfaced through the host's preimage subscription.
+     *
+     * Use {@link verifyStored} if you only need to confirm a CID was
+     * recorded on-chain (no byte fetch).
+     */
+    fetchBytes(cid: string, options?: QueryOptions): Promise<Uint8Array>;
+    /** Fetch and parse JSON for a CID. */
+    fetchJson<T>(cid: string, options?: QueryOptions): Promise<T>;
+    /** Pre-flight: check whether `address` can store via Cloud Storage. */
+    checkAuthorization(address: string): Promise<AuthorizationStatus>;
+    /**
+     * Verify that a CID was recorded on-chain at the given block.
+     *
+     * Common pattern: pass `blockNumber` (and optionally `extrinsicIndex`)
+     * from a `store(...).send()` receipt to confirm the upload landed.
+     * See {@link verifyStored} for details.
+     */
+    verifyStored(cid: string, options: VerifyStoredOptions): Promise<ChainStoredEntry | null>;
+    /** Tear down the underlying connection. */
+    destroy(): Promise<void>;
+}
+
+/**
+ * Check whether an account is authorized to store data in Cloud Storage.
+ *
+ * Queries `TransactionStorage.Authorizations` for the given address and returns
+ * the raw authorization quota. Use this as a pre-flight check before calling
+ * {@link CloudStorageClient.store} 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 Cloud Storage API instance.
+ * @param address - SS58-encoded account address to check.
+ * @returns Authorization status with remaining quota.
+ *
+ * @example
+ * ```ts
+ * import { checkAuthorization } from "@parity/product-sdk-cloud-storage";
+ *
+ * const auth = await checkAuthorization(api, address);
+ * if (!auth.authorized) {
+ *     console.error("Account is not authorized for cloud storage");
+ * } else if (auth.remainingBytes < BigInt(fileBytes.length)) {
+ *     console.error(`Insufficient quota: ${auth.remainingBytes} bytes remaining`);
+ * }
+ * ```
+ *
+ * @see {@link CloudStorageClient.checkAuthorization} for the client method equivalent.
+ */
+declare function checkAuthorization(api: CloudStorageApi, address: string): Promise<AuthorizationStatus>;
+/**
+ * Options for {@link authorizeAccount}.
+ */
+interface AuthorizeAccountOptions {
+    /**
+     * Wrap the extrinsic in `Sudo.sudo(...)` before submission. Default: `false`.
+     *
+     * Use `true` on networks where granting cloud storage authorization
+     * requires sudo permissions (most production / managed test networks).
+     * Use `false` (default) when the account self-authorizes — typical for
+     * local development chains.
+     */
+    viaSudo?: boolean;
+    /** When to resolve: `"best-block"` (default) or `"finalized"`. */
+    waitFor?: WaitFor;
+    /** Timeout in ms. Default: 300_000 (5 min). */
+    timeoutMs?: number;
+    /** Lifecycle status callback for UI progress. */
+    onStatus?: (status: TxStatus) => void;
+}
+/**
+ * Grant an account authorization to store data in Cloud Storage.
+ *
+ * Submits a `TransactionStorage.authorize_account` extrinsic, optionally
+ * wrapped in `Sudo.sudo(...)` for networks that require sudo to grant
+ * authorization. Mirrors the call shape of {@link CloudStorageClient.store} — top-level
+ * function, takes an explicit signer, returns a block hash on success.
+ *
+ * Pair with {@link checkAuthorization} for a typical "check, grant if
+ * insufficient, then upload" flow.
+ *
+ * ## Additive semantics — call once per authorization need
+ *
+ * `authorize_account` is **additive** within an unexpired authorization window
+ * for `AuthorizationScope::Account` (see `pallet-bulletin-transaction-storage`,
+ * `fn authorize`). Each successful call **adds** to the existing
+ * `transactions_allowance` and `bytes_allowance` rather than overwriting them.
+ *
+ * Implications for callers:
+ *
+ * - Calling this function twice with `(100, 1MB)` while the previous
+ *   authorization is still active leaves the account with quota for `200`
+ *   transactions and `2MB` — likely unintended.
+ * - **This function does NOT use `withRetry`.** Retrying a successful-but-
+ *   acknowledgment-lost submission would double-grant the quota. Callers
+ *   needing retry should wrap this function and use {@link checkAuthorization}
+ *   to verify the post-state before retrying.
+ * - To "reset" a quota, let the existing authorization expire
+ *   (`AuthorizationPeriod` blocks). The next call after expiry creates a fresh
+ *   authorization rather than adding.
+ *
+ * Note: `AuthorizationScope::Preimage` uses `set` semantics in the same
+ * pallet. This helper is for account-scope authorization only.
+ *
+ * @param api          - Typed Cloud Storage API instance.
+ * @param who          - SS58-encoded account to authorize.
+ * @param transactions - Number of transactions to **add** to the account's allowance.
+ * @param bytes        - Byte budget to **add** to the account's allowance.
+ * @param signer       - Signer for the extrinsic. On `viaSudo: true` this must be the sudo key.
+ * @param options      - Optional `viaSudo` flag plus standard submission controls.
+ * @returns Block hash where the extrinsic was included.
+ * @throws {ProductCloudStorageError} If `viaSudo: true` is requested but the chain has no `Sudo` pallet.
+ *
+ * @example Direct (account self-authorizes — local dev)
+ * ```ts
+ * import { authorizeAccount } from "@parity/product-sdk-cloud-storage";
+ *
+ * await authorizeAccount(api, address, 100, 100n * 1024n * 1024n, signer);
+ * ```
+ *
+ * @example Sudo-wrapped (managed test network)
+ * ```ts
+ * await authorizeAccount(api, userAddress, 100, 1_000_000n, sudoSigner, {
+ *     viaSudo: true,
+ * });
+ * ```
+ *
+ * @see {@link checkAuthorization} for the read counterpart.
+ * @see {@link CloudStorageClient.authorizeAccount} for the client method equivalent.
+ */
+declare function authorizeAccount(api: CloudStorageApi, who: string, transactions: number, bytes: bigint, signer: PolkadotSigner, options?: AuthorizeAccountOptions): Promise<{
+    blockHash: string;
+}>;
+
+/**
+ * Build a `PolkadotSigner` whose underlying signer is resolved on every call.
+ *
+ * `AsyncBulletinClient` takes a fixed `PolkadotSigner` at construction, but
+ * apps often build the Cloud Storage 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.
+ */
+declare function createLazySigner(getSigner: () => PolkadotSigner | null, onMissing?: string): PolkadotSigner;
+
+/**
+ * Query strategy for Cloud Storage retrieval.
+ *
+ * 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 Cloud Storage retrieval.
+ *
+ * Uses the host preimage lookup API which caches results and manages
+ * IPFS polling automatically.
+ *
+ * @returns The resolved query strategy.
+ * @throws {CloudStorageHostUnavailableError} If the host preimage manager is unavailable.
+ */
+declare function resolveQueryStrategy(): Promise<QueryStrategy>;
+
+/**
+ * Fetch raw bytes for a CID via the host's preimage lookup.
+ *
+ * Container-only by design: the Cloud Storage 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 CloudStorageHostUnavailableError}.
+ *
+ * The underlying 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 `verifyStored` from `verify.ts`.
+ *
+ * @param cid     - CIDv1 string to fetch.
+ * @param options - Query options (`lookupTimeoutMs` for host).
+ * @throws {CloudStorageHostUnavailableError} If running outside a container.
+ */
+declare function queryBytes(cid: string, options?: QueryOptions): Promise<Uint8Array>;
+/**
+ * Fetch and parse JSON for a CID via the host's preimage lookup.
+ *
+ * Convenience wrapper over {@link queryBytes}.
+ */
+declare function queryJson<T>(cid: string, options?: QueryOptions): Promise<T>;
+/**
+ * Execute a query using a pre-resolved strategy.
+ *
+ * Exposed so `CloudStorageClient` 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.
+ *
+ * For raw-codec CIDs (`0x55`, single-chunk content), the bytes returned
+ * by the host are returned directly — no parsing overhead.
+ */
+declare function executeQuery(strategy: QueryStrategy, cid: string, options?: QueryOptions): Promise<Uint8Array>;
+
+/**
+ * Hash algorithms supported by Cloud Storage.
+ *
+ * Values are multihash codes from the multicodec table.
+ */
+declare const HashAlgorithm: {
+    /** BLAKE2b-256 — chain default. */
+    readonly Blake2b256: 45600;
+    /** SHA2-256. */
+    readonly Sha2_256: 18;
+    /** Keccak-256 — Ethereum compatibility. */
+    readonly Keccak256: 27;
+};
+type HashAlgorithm = (typeof HashAlgorithm)[keyof typeof HashAlgorithm];
+/**
+ * CID codecs supported by Cloud Storage.
+ */
+declare const CidCodec: {
+    /** Raw binary — default for single-chunk data. */
+    readonly Raw: 85;
+    /** DAG-PB — used for multi-chunk manifests / IPFS UnixFS. */
+    readonly DagPb: 112;
+    /** DAG-CBOR — alternative DAG encoding. */
+    readonly DagCbor: 113;
+};
+type CidCodec = (typeof CidCodec)[keyof typeof CidCodec];
+/**
+ * Reconstruct a CIDv1 from a `0x`-prefixed 32-byte hex hash.
+ *
+ * Useful when reading on-chain `TransactionInfo.content_hash` and you need
+ * the CID to look up content via an IPFS gateway.
+ *
+ * @param hexHash  - 66-char `0x`-prefixed hex of a 32-byte digest.
+ * @param hashCode - Multihash code (default: blake2b-256).
+ * @param codec    - Multicodec code (default: raw).
+ */
+declare function hashToCid(hexHash: `0x${string}`, hashCode?: HashAlgorithm, codec?: CidCodec): string;
+/**
+ * Extract the 32-byte content hash digest from a CIDv1 and return it as a
+ * `0x`-prefixed hex string.
+ *
+ * Useful for matching a CID against on-chain `TransactionInfo.content_hash`.
+ */
+declare function cidToPreimageKey(cid: string): `0x${string}`;
+
+/**
+ * Cloud Storage error types.
+ *
+ * Two error families coexist:
+ *
+ * 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`, `verifyStored`).
+ *
+ * Catch upstream errors with `instanceof BulletinError`. Catch our read-side
+ * errors with `instanceof ProductCloudStorageError` (or the specific subclass).
+ */
+
+/**
+ * Base class for read-side errors raised by `@parity/product-sdk-cloud-storage`.
+ *
+ * Distinct from upstream `BulletinError` which covers upload/store failures.
+ */
+declare class ProductCloudStorageError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * The host preimage API is unavailable.
+ *
+ * Thrown when cloud storage operations require the host container but it's not
+ * available. This typically means the SDK is running outside Polkadot
+ * Browser / Desktop. The Cloud Storage SDK is container-only by design — see
+ * the README for the rationale.
+ */
+declare class CloudStorageHostUnavailableError extends ProductCloudStorageError {
+    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 CloudStorageLookupTimeoutError extends ProductCloudStorageError {
+    /** 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 CloudStorageLookupInterruptedError extends ProductCloudStorageError {
+    /** The CID that was being looked up. */
+    readonly cid: string;
+    constructor(cid: string);
+}
+/**
+ * Invalid CID format or version.
+ */
+declare class CloudStorageCidError extends ProductCloudStorageError {
+    /** The invalid CID string, if available. */
+    readonly cid?: string;
+    constructor(message: string, 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 in Cloud Storage.
+ */
+declare class CloudStorageAuthorizationError extends ProductCloudStorageError {
+    /** The address that was being checked. */
+    readonly address: string;
+    constructor(address: string, cause?: unknown);
+}
+
+export { type AuthorizationStatus, type AuthorizeAccountOptions, type ChainStoredEntry, CidCodec, type CloudStorageApi, CloudStorageAuthorizationError, CloudStorageCidError, CloudStorageClient, type CloudStorageEnvironment, CloudStorageHostUnavailableError, CloudStorageLookupInterruptedError, CloudStorageLookupTimeoutError, type CloudStorageNetwork, CloudStorageNetworks, type CreateCloudStorageClientOptions, HashAlgorithm, ProductCloudStorageError, type QueryOptions, type QueryStrategy, type VerifyStoredOptions, authorizeAccount, checkAuthorization, cidToPreimageKey, createLazySigner, executeQuery, hashToCid, queryBytes, queryJson, resolveQueryStrategy, verifyStored };