@cardanowall/sdk-ts 0.0.0

package/dist/client/index.d.cts

@@ -0,0 +1,397 @@
+import { PoeRecord, SigEntry } from '@cardanowall/poe-standard';
+import { F as FetchImpl, A as AccountBalance, Q as QuoteInput, r as QuoteResponse, D as UploadsInput, E as UploadsResponse, l as PublishInput, p as PublishResponse, g as PublishBatchInput, h as PublishBatchResponse, k as PublishContentInput, o as PublishPrehashedInput, q as PublishSealedInput, m as PublishMerkleInput, n as PublishMerkleResponse, v as RecordsListInput, w as RecordsListResponse, R as RecordResource, c as PoeVerifyInput, C as Cip309ClientConfig, z as UploadFailureEntry } from '../types-BQMtbRCb.cjs';
+export { a as ConformanceProfile, P as PoeItemResponse, b as PoeStatus, d as PublishBatchEntry, e as PublishBatchFailureEntry, f as PublishBatchFailureError, i as PublishBatchResultEntry, j as PublishBatchSuccessEntry, s as RecordScheme, t as RecordSignature, u as RecordStatus, S as Signer, x as StorageTarget, y as SupportedHashAlg, U as UploadEntry, B as UploadSuccessEntry } from '../types-BQMtbRCb.cjs';
+import { g as VerifyReport } from '../types-CLXdbjqr.cjs';
+import '../fetch-outbound-BT5-NiYN.cjs';
+
+type OffHostSignErrorCode = 'INVALID_PUBKEY_LENGTH' | 'INVALID_SIGNATURE_LENGTH';
+declare class OffHostSignError extends Error {
+    readonly code: OffHostSignErrorCode;
+    constructor(code: OffHostSignErrorCode, message: string);
+}
+interface PrepareSigStructureArgs {
+    readonly record: PoeRecord;
+    readonly signerPubkey: Uint8Array;
+}
+interface PrepareSigStructureResult {
+    readonly sigStructureBytes: Uint8Array;
+    readonly protectedHeaderBytes: Uint8Array;
+}
+interface PrepareSigStructureHashedResult extends PrepareSigStructureResult {
+    readonly toSignHashBytes: Uint8Array;
+}
+interface AssembleCoseSign1Args {
+    readonly record: PoeRecord;
+    readonly signerPubkey: Uint8Array;
+    readonly signature: Uint8Array;
+}
+interface AssembleCoseSign1Result {
+    readonly coseSign1Bytes: Uint8Array;
+    readonly sigEntry: SigEntry;
+}
+declare function buildToSign(record: PoeRecord): Uint8Array;
+declare function prepareSigStructure(args: PrepareSigStructureArgs): PrepareSigStructureResult;
+declare function assembleCoseSign1(args: AssembleCoseSign1Args): AssembleCoseSign1Result;
+declare function prepareSigStructureHashed(args: PrepareSigStructureArgs): PrepareSigStructureHashedResult;
+declare function assembleCoseSign1Hashed(args: AssembleCoseSign1Args): AssembleCoseSign1Result;
+
+interface ResolvedConfig$2 {
+    readonly apiKey: string | undefined;
+    readonly baseUrl: string;
+    readonly fetch: FetchImpl;
+}
+declare class AccountNamespace {
+    private readonly config;
+    constructor(config: ResolvedConfig$2);
+    /**
+     * Fetch the caller's current prepaid USD balance.
+     *
+     * Returns `{ balanceUsdMicros }`, the gateway's `balance_usd_micros` field
+     * (USD micro-cents as a decimal string). The string is preserved verbatim —
+     * never parsed into a number — so no precision is lost. An account with no
+     * ledger activity yet reads `"0"`.
+     *
+     * Requires authentication: 401 (UnauthorizedError) when anonymous, 403
+     * (InsufficientScopeError) when the Bearer key lacks the `account:read`
+     * scope.
+     */
+    balance(): Promise<AccountBalance>;
+}
+
+interface ResolvedConfig$1 {
+    readonly apiKey: string | undefined;
+    readonly baseUrl: string;
+    readonly fetch: FetchImpl;
+}
+declare class PoeNamespace {
+    private readonly config;
+    constructor(config: ResolvedConfig$1);
+    /**
+     * Request an opaque price lock for an upcoming /publish call. The gateway
+     * prices the described publish from the supplied byte counts, records the
+     * lock, and returns a sealed price token: `quote_id`, the total `amount` in
+     * `currency`, and an `expires_at`. The gateway's pricing internals are
+     * deliberately NOT part of the response.
+     *
+     * `amount` is a decimal string; promote it to `BigInt` (or a decimal type)
+     * at the application boundary if you need exact arithmetic.
+     *
+     * Pass the returned `quote_id` to `publish()` (or one of the high-level
+     * `publishContent` / `publishSealed` / `publishMerkle` helpers).
+     */
+    quote(input: QuoteInput): Promise<QuoteResponse>;
+    /**
+     * Upload 1..32 binary files to a storage backend. Returns one entry per file
+     * — successful entries carry the `ar://` URI + content hash, failed entries
+     * carry an error code / detail so the caller can retry just the failed
+     * indices.
+     *
+     * Billing: free. The storage cost is part of the publish quote (POST
+     * /api/v1/poe/quote → POST /api/v1/poe/publish) and is debited once at
+     * publish time against the locked price snapshot.
+     *
+     * On HTTP-level failure (auth, rate limit, malformed request) this throws
+     * a typed `Cip309HttpError` subclass. Per-file failures inside a 200
+     * response are NOT thrown by `uploads()` itself — the response body is
+     * returned verbatim so the caller can decide how to react. The
+     * higher-level helpers (`publishSealed`, `publishMerkle`) treat any failed
+     * file as a `PartialUploadError`.
+     */
+    uploads(input: UploadsInput): Promise<UploadsResponse>;
+    /**
+     * Submit a single finalised canonical-CBOR record to Cardano. Caller is
+     * responsible for constructing the record bytes (use `publishContent` /
+     * `publishSealed` / `publishMerkle` for the assisted flows) and for
+     * acquiring a `quote_id` via `quote()` first.
+     *
+     * Returns 202 (`dedup_hit: false`) on freshly enqueued records, or 200
+     * (`dedup_hit: true`) when the same record bytes were previously submitted
+     * by this account. Dedup hits debit nothing.
+     */
+    publish(input: PublishInput): Promise<PublishResponse>;
+    /**
+     * Submit 1..50 finalised records as independent Cardano transactions.
+     * Each entry carries its own `quote_id` — request quotes ahead of time
+     * with one `quote()` call per record. Returns 200 with `results[]` —
+     * successful entries land alongside failed ones; per-record errors do NOT
+     * roll back the batch.
+     */
+    publishBatch(input: PublishBatchInput): Promise<PublishBatchResponse>;
+    /**
+     * High-level hash-only publish: hash the supplied content, build a
+     * single-item CIP-309 record, optionally sign it with the caller-supplied
+     * signer, and submit. No Arweave, no storage round-trip — anchors the
+     * digest only.
+     */
+    publishContent(input: PublishContentInput): Promise<PublishResponse>;
+    /**
+     * Hash-already-computed publish: caller already holds the digest(s) — e.g.
+     * the CLI `--hash <hex>` mode, an air-gapped offline hashing flow, or any
+     * pipeline that proxies digests from another tool. No client-side hashing.
+     */
+    publishPrehashed(input: PublishPrehashedInput): Promise<PublishResponse>;
+    /**
+     * Sealed-PoE: encrypt the supplied content to the recipient X25519 public
+     * keys (age-style sealed envelope), upload the ciphertext to Arweave via
+     * /uploads, build a CIP-309 record with the resulting `ar://` URI, sign
+     * it (optional), and submit via /publish.
+     *
+     * The sender SHOULD include their own X25519 public key in `recipients`
+     * to retain decrypt access — the SDK does NOT inject the sender silently.
+     */
+    publishSealed(input: PublishSealedInput): Promise<PublishResponse>;
+    /**
+     * Merkle batch publish: compute the RFC 9162 §2.1.1 root over N
+     * caller-supplied 32-byte leaf hashes, upload the canonical leaves-list
+     * CBOR to Arweave via /uploads, bind the root + leaf_count into
+     * `merkle[0]` of an on-chain record, optionally sign, and submit.
+     *
+     * Returns the on-chain id + tx hash + root + leaf count + the canonical
+     * `ar://<tx>` URI of the leaves-list. Anyone with that URI can later
+     * fetch the leaves-list, recompute the root, and prove inclusion of any
+     * leaf via `merkleSha2256VerifyInclusion`.
+     */
+    publishMerkle(input: PublishMerkleInput): Promise<PublishMerkleResponse>;
+}
+
+interface ResolvedConfig {
+    readonly apiKey: string | undefined;
+    readonly baseUrl: string;
+    readonly fetch: FetchImpl;
+}
+declare class RecordsNamespace {
+    private readonly config;
+    constructor(config: ResolvedConfig);
+    /**
+     * List records as a paginated `RecordsListResponse` whose `data[]` entries
+     * are the same `RecordResource` projection `get()` returns.
+     *
+     * Pass `{ sealed: true }` to restrict the page to sealed records addressed
+     * to the authenticated caller (the gateway resolves the recipient from the
+     * bearer identity); omit it to list every record the caller may read. Page
+     * with `{ cursor: previous.next_cursor }` until `has_more` is false.
+     */
+    list(input?: RecordsListInput): Promise<RecordsListResponse>;
+    /**
+     * Fetch a record by Cardano transaction hash. Returns the JSON
+     * `RecordResource` projection — same shape every `records.list` page entry
+     * carries inside `data[]`.
+     *
+     * 404 (RecordNotFoundError) on tx_hashes the indexer has not seen, OR on
+     * un-anchored rows when the caller is not their owner (oracle-safe
+     * indistinguishable response per the route's privacy invariant).
+     */
+    get(txHash: string): Promise<RecordResource>;
+    /**
+     * Run the canonical CIP-309 verifier against the record at `txHash`.
+     * Returns the same `VerifyReport` shape the standalone verifier emits —
+     * `VerifyReport` IS the wire body of this endpoint, with no transformer in
+     * between.
+     *
+     * Auth required (Bearer with `poe:read` scope, or NextAuth session
+     * cookie). Optional `verify_uris` toggles URI hash-equivalence checks;
+     * `decryption[]` drives trial-decrypt of sealed envelopes per item.
+     */
+    verify(txHash: string, input?: PoeVerifyInput): Promise<VerifyReport>;
+}
+
+declare class Cip309Client {
+    readonly poe: PoeNamespace;
+    readonly records: RecordsNamespace;
+    readonly account: AccountNamespace;
+    /**
+     * Construct a client against a CIP-309 gateway.
+     *
+     * `config.baseUrl` is required — there is no default deployment. The
+     * `config.apiKey`, when supplied, is an opaque bearer token sent verbatim as
+     * `Authorization: Bearer <apiKey>`; omit it for anonymous read-only access.
+     *
+     * PoE submissions debit the gateway's own balance model. Acquire a price lock
+     * via `client.poe.quote(...)` first; the resulting `quote_id` is consumed by
+     * the publish call.
+     */
+    constructor(config: Cip309ClientConfig);
+}
+
+declare class PublishError extends Error {
+    readonly code: 'INVALID_SIGNER_PUBKEY' | 'INVALID_SIGNER_SIGNATURE' | 'INVALID_LEAVES' | 'INVALID_DIGEST' | 'INVALID_RECIPIENT' | 'UNSUPPORTED_HASH_ALG';
+    constructor(code: PublishError['code'], message: string);
+}
+
+declare class PartialUploadError extends Error {
+    readonly response: UploadsResponse;
+    readonly failed: ReadonlyArray<UploadFailureEntry>;
+    constructor(response: UploadsResponse);
+    /** Convenience: the `idx` of every failed entry, in input order. */
+    get failedIndices(): ReadonlyArray<number>;
+}
+
+/** RFC 7807 per-field error entry. */
+interface ProblemErrorEntry {
+    /** Dotted JSON path of the offending field; empty for body-level errors. */
+    readonly field: string;
+    /** Stable lowercase-kebab (or Zod issue) code for the specific failure. */
+    readonly code: string;
+    /** Human-readable explanation of this individual field error. */
+    readonly detail: string;
+}
+/**
+ * RFC 7807 `application/problem+json` document as emitted by every CIP-309
+ * gateway `/api/v1/*` route.
+ *
+ * Canonical fields (`type`, `title`, `status`, `detail`, `code`, `trace_id`)
+ * are always present. `errors` is present on validation responses.
+ * `instance` is optional per RFC 7807 §3.1.
+ *
+ * Additional top-level fields are RFC 7807 §3.2 extension members and are
+ * preserved verbatim on `Cip309HttpError.extensions`.
+ */
+interface ProblemDetails {
+    readonly type: string;
+    readonly title: string;
+    readonly status: number;
+    readonly detail: string;
+    readonly code: string;
+    readonly trace_id: string;
+    readonly errors?: ReadonlyArray<ProblemErrorEntry>;
+    readonly instance?: string;
+    /** RFC 7807 §3.2 extension members. */
+    readonly [extension: string]: unknown;
+}
+interface Cip309HttpErrorInit {
+    /** The verbatim problem document. */
+    readonly problem: ProblemDetails;
+    /** Pre-split extension members. Computed from `problem` when omitted. */
+    readonly extensions?: Record<string, unknown>;
+    /** Value of the `X-Request-Id` response header. Falls back to `problem.trace_id`. */
+    readonly requestId?: string | undefined;
+    /** Value of the `Retry-After` response header (seconds), if present. */
+    readonly retryAfterSeconds?: number | undefined;
+}
+/**
+ * Parent class for every typed SDK HTTP error. Carries the full RFC 7807
+ * problem document plus headers (`X-Request-Id`, `Retry-After`) relevant for
+ * retry logic and log correlation.
+ *
+ * Consumers can dispatch on:
+ *   - `err.code`        — lowercase-kebab problem code
+ *   - `err.httpStatus`  — HTTP status (= `err.problem.status`)
+ *   - `instanceof <SpecificError>` — see the subclasses re-exported from
+ *     `@cardanowall/sdk-ts`
+ */
+declare class Cip309HttpError extends Error {
+    readonly problem: ProblemDetails;
+    readonly code: string;
+    readonly httpStatus: number;
+    readonly title: string;
+    readonly detail: string;
+    readonly type: string;
+    readonly traceId: string;
+    readonly instance: string | undefined;
+    readonly errors: ReadonlyArray<ProblemErrorEntry> | undefined;
+    readonly extensions: Record<string, unknown>;
+    readonly requestId: string;
+    readonly retryAfterSeconds: number | undefined;
+    constructor(init: Cip309HttpErrorInit);
+}
+
+declare class BatchEmptyError extends Cip309HttpError {
+    constructor(init: Cip309HttpErrorInit);
+}
+
+declare class BatchTooLargeError extends Cip309HttpError {
+    readonly max: number | undefined;
+    readonly got: number | undefined;
+    constructor(init: Cip309HttpErrorInit);
+}
+
+declare class ForbiddenError extends Cip309HttpError {
+    constructor(init: Cip309HttpErrorInit);
+}
+
+declare class IdempotencyConflictError extends Cip309HttpError {
+    constructor(init: Cip309HttpErrorInit);
+}
+
+declare class InvalidClientConfigError extends Error {
+    readonly code: "INVALID_CLIENT_CONFIG";
+    constructor(message: string);
+}
+
+declare class InsufficientFundsError extends Cip309HttpError {
+    readonly balanceUsdMicros: bigint | undefined;
+    readonly requiredUsdMicros: bigint | undefined;
+    readonly topUpUrl: string | undefined;
+    constructor(init: Cip309HttpErrorInit);
+}
+
+declare class InsufficientScopeError extends Cip309HttpError {
+    readonly requiredScopes: ReadonlyArray<string>;
+    readonly grantedScopes: ReadonlyArray<string>;
+    constructor(init: Cip309HttpErrorInit);
+    /** Convenience for the single-scope case; first entry of `requiredScopes`. */
+    get requiredScope(): string | undefined;
+}
+
+declare class InternalServerError extends Cip309HttpError {
+    constructor(init: Cip309HttpErrorInit);
+}
+
+declare class InvalidBodyError extends Cip309HttpError {
+    constructor(init: Cip309HttpErrorInit);
+}
+
+declare class MalformedCborError extends Cip309HttpError {
+    constructor(init: Cip309HttpErrorInit);
+}
+
+declare class NotFoundError extends Cip309HttpError {
+    constructor(init: Cip309HttpErrorInit);
+}
+
+declare class QuoteAlreadyConsumedError extends Cip309HttpError {
+    readonly quoteId: string | undefined;
+    constructor(init: Cip309HttpErrorInit);
+}
+
+declare class QuoteExpiredError extends Cip309HttpError {
+    readonly quoteId: string | undefined;
+    constructor(init: Cip309HttpErrorInit);
+}
+
+declare class QuoteNotFoundError extends Cip309HttpError {
+    readonly quoteId: string | undefined;
+    constructor(init: Cip309HttpErrorInit);
+}
+
+declare class RateLimitedError extends Cip309HttpError {
+    constructor(init: Cip309HttpErrorInit);
+}
+
+declare class RecordNotFoundError extends Cip309HttpError {
+    constructor(init: Cip309HttpErrorInit);
+}
+
+declare class ServiceUnavailableError extends Cip309HttpError {
+    constructor(init: Cip309HttpErrorInit);
+}
+
+declare class UnauthorizedError extends Cip309HttpError {
+    constructor(init: Cip309HttpErrorInit);
+}
+
+declare class ValidationFailedError extends Cip309HttpError {
+    constructor(init: Cip309HttpErrorInit);
+}
+
+interface ParseHttpErrorArgs {
+    readonly httpStatus: number;
+    readonly body: unknown;
+    /** `X-Request-Id` header from the response, when available. */
+    readonly requestId?: string | undefined;
+    /** `Retry-After` header from the response, parsed as integer seconds. */
+    readonly retryAfterSeconds?: number | undefined;
+}
+declare function parseHttpError(args: ParseHttpErrorArgs): Cip309HttpError;
+
+export { AccountBalance, AccountNamespace, type AssembleCoseSign1Args, type AssembleCoseSign1Result, BatchEmptyError, BatchTooLargeError, Cip309Client, Cip309ClientConfig, Cip309HttpError, type Cip309HttpErrorInit, FetchImpl, ForbiddenError, IdempotencyConflictError, InsufficientFundsError, InsufficientScopeError, InternalServerError, InvalidBodyError, InvalidClientConfigError, MalformedCborError, NotFoundError, OffHostSignError, type OffHostSignErrorCode, PartialUploadError, PoeNamespace, PoeVerifyInput, type PrepareSigStructureArgs, type PrepareSigStructureHashedResult, type PrepareSigStructureResult, type ProblemDetails, type ProblemErrorEntry, PublishBatchInput, PublishBatchResponse, PublishContentInput, PublishError, PublishInput, PublishMerkleInput, PublishMerkleResponse, PublishPrehashedInput, PublishResponse, PublishSealedInput, QuoteAlreadyConsumedError, QuoteExpiredError, QuoteInput, QuoteNotFoundError, QuoteResponse, RateLimitedError, RecordNotFoundError, RecordResource, RecordsListInput, RecordsListResponse, RecordsNamespace, ServiceUnavailableError, UnauthorizedError, UploadFailureEntry, UploadsInput, UploadsResponse, ValidationFailedError, assembleCoseSign1, assembleCoseSign1Hashed, buildToSign, parseHttpError, prepareSigStructure, prepareSigStructureHashed };