@agentkv/client 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,584 @@
+import { Signer, UsageBlock } from '@agentx402-ai/core';
+export { AgentKVError, Signer, SpendCapError, UsageBlock } from '@agentx402-ai/core';
+
+/** Request passed to `topoffPayer` when the client needs an account-key top-off. */
+interface TopoffPayerRequest {
+    /** `${endpoint}/account/deposit` — the ONLY URL a hook should ever pay. */
+    depositUrl: string;
+    /** The `ak_…` bearer that must authorize the deposit (`Authorization: Bearer <ak>`). */
+    accountKey: string;
+    /** Requested top-off in USD (= `prepay.topoff`, >= $1 — the server minimum). */
+    amountUsd: number;
+    /** Hard payment ceiling in atomic USDC units (1e6 = $1) the hook MUST enforce (e.g. awal `--max-amount`). */
+    maxAmountAtomic: number;
+}
+/**
+ * Request handed to `opInlinePayer`: the WHOLE encrypted account-key `set`/`get`
+ * op, ready to send as-is. The hook drives its OWN 402→pay→retry (e.g. via
+ * `awal x402 pay`) and returns the final response — the client never sees the
+ * intermediate 402 on this path.
+ */
+interface OpInlineRequest {
+    /** `${endpoint}/kv/<digest>` — the ONLY URL a hook should ever request. */
+    url: string;
+    method: "POST" | "GET";
+    /** Ciphertext JSON body (POST only; omitted on GET). */
+    body?: string;
+    /** Full request headers: bearer `Authorization`, `Idempotency-Key`, `content-type` (POST). */
+    headers: Record<string, string>;
+    /** Hard payment ceiling in atomic USDC units (1e6 = $1) the hook MUST enforce (e.g. awal `--max-amount`). */
+    maxAmountAtomic: number;
+}
+/** Final response from `opInlinePayer`, after its own 402→pay→retry has settled. */
+interface OpInlineResponse {
+    status: number;
+    body: string;
+    headers: Record<string, string>;
+}
+interface AgentKVCommon {
+    endpoint: string;
+    network?: string;
+    /** Per-paying-call USD cap; throws SpendCapError if exceeded. */
+    maxSpendUsd?: number;
+    /**
+     * Cumulative USD cap across this client instance. **Best-effort**: the running
+     * total is a plain in-memory counter, so concurrent paying calls can race
+     * (both pass `assertSpend` before either `recordSpend`s) and modestly overshoot
+     * the cap. It is a guardrail, not a hard ledger — serialize paying calls if you
+     * need a strict bound.
+     */
+    maxSessionSpendUsd?: number;
+    /**
+     * Bounded internal retries on TRANSIENT failures (a thrown fetch / lost
+     * response, or a 5xx). Default 2 (3 attempts total). Retries reuse the op's
+     * stable Idempotency-Key (and pinned EIP-3009 nonce on paid ops) so a
+     * processed-but-unacked request dedupes server-side instead of double-charging.
+     * Kept small so a re-sent paid authorization stays within validBefore. Set 0 to disable.
+     */
+    retries?: number;
+    /** Per-attempt request timeout in ms (aborts a hung-open connection so an op can't wedge forever). Default 30000. Pass 0 to disable. */
+    timeoutMs?: number;
+    /** Injectable `fetch` for proxies / instrumentation / testing. Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+    /** Opt-in Discounted Prepay. When set, the client keeps a credit balance topped up. */
+    prepay?: {
+        /** Top off when the tracked balance (USD) falls below this. */
+        watermark: number;
+        /** Top-off amount in USD (>= 1). */
+        topoff: number;
+        /** Opt-in background top-off instead of synchronous single-shot. Default false. */
+        async?: boolean;
+    };
+    /**
+     * ACCOUNT-KEY MODE ONLY: pays a prepaid-credit top-off to
+     * `${endpoint}/account/deposit` on this client's behalf (a managed account has
+     * no signing wallet). Called single-flight when the tracked balance falls below
+     * `prepay.watermark`, and as a fallback when an op hits an insufficient-credits
+     * 402. Resolve only once the deposit has SETTLED; a rejection surfaces as
+     * `account_topoff_failed` (fatal on the hard-402 path, swallowed on the
+     * proactive path). REQUIRED alongside `prepay` in account-key mode; rejected
+     * (`invalid_config`) in wallet mode or without `prepay` (it could never fire).
+     */
+    topoffPayer?: (req: TopoffPayerRequest) => Promise<void>;
+    /**
+     * ACCOUNT-KEY MODE ONLY: routes a WHOLE `set`/`get` op through an external inline
+     * x402 transport (e.g. `awal x402 pay`) instead of the stage-1 deposit top-off —
+     * opt-in, pay-per-op, no `prepay` required. Called on a hard 402 (insufficient
+     * credits): the client hands the hook the complete encrypted request
+     * (`{url, method, body, headers}`, already bearer-authenticated and
+     * Idempotency-Keyed) and the hook drives its OWN 402→pay→retry, returning the
+     * final `{status, body, headers}` for the client to parse/decrypt as usual.
+     *
+     * Mutually exclusive with `topoffPayer` PER OP: when BOTH are configured,
+     * `topoffPayer` (deposit top-off) always takes precedence and `opInlinePayer`
+     * is used only when `topoffPayer` is absent — see client/README.md. Rejected
+     * (`invalid_config`) in wallet mode (a signing wallet pays its own challenges).
+     */
+    opInlinePayer?: (req: OpInlineRequest) => Promise<OpInlineResponse>;
+}
+/**
+ * Construct with one of four auth shapes:
+ *  - `{ privateKey }` — a raw wallet key (HKDF-derives the AES key from the KEY BYTES;
+ *    wallet signs).
+ *  - `{ signer, encryptionKey }` — a wallet signer + an explicit AES key.
+ *  - `{ signer }` — a wallet signer; the AES key is SIGN-TO-DERIVED (HKDF over the wallet's
+ *    signature of a fixed message).
+ *  - `{ accountKey, encryptionKey }` — account-key mode: a managed account with
+ *    NO signing wallet. Auth is an opaque `ak_…` bearer token (server hashes it to
+ *    name storage + debits prepaid credits — no x402/EIP-712). There is no wallet
+ *    to derive an AES key from, so an explicit `encryptionKey` is REQUIRED.
+ *
+ * ⚠️ Encryption-key stability — the shapes are NOT interchangeable for the same wallet:
+ *  - `{ privateKey: k }` and `{ signer: accountFrom(k) }` (sign-to-derive) derive DIFFERENT
+ *    encryption keys (raw key bytes vs a signature over them). Switching a wallet between
+ *    these two shapes changes the value/key-name/blind-index keys, so previously written
+ *    data becomes unreadable AND unlisted (its lookup digests no longer match) with no error
+ *    — reads simply return null. To move between them, or to use a KMS/hardware/MPC signer,
+ *    pin an explicit `encryptionKey` so the AES key never depends on the signer shape.
+ *  - Sign-to-derive requires a DETERMINISTIC signer whose signTypedData returns the standard
+ *    65-byte ECDSA form. Non-deterministic (some MPC/threshold) or alternate-encoding
+ *    signers (EIP-2098 compact, ERC-1271/6492 smart accounts) either rotate the key per call
+ *    or are rejected — those MUST pass an explicit `encryptionKey`.
+ *  - The sign-to-derive signature IS secret-grade material: whoever obtains it can derive all
+ *    of this wallet's AgentKV keys. Treat it like a private key (do not log / expose it).
+ */
+type AgentKVOptions = AgentKVCommon & ({
+    privateKey: `0x${string}`;
+} | {
+    signer: Signer;
+    encryptionKey: Uint8Array | `0x${string}`;
+} | {
+    signer: Signer;
+} | {
+    accountKey: string;
+    encryptionKey: Uint8Array | `0x${string}`;
+});
+/** Per-write options. */
+interface SetOptions {
+    /** Time-to-live in days (server default 90). */
+    ttlDays?: number;
+    /** If true, reads do not extend expiry (server default false). */
+    strictTtl?: boolean;
+    /**
+     * Stable key identifying this logical write, reused across retries so a
+     * retried set() (after a crash/timeout) is exactly-once: the server hits its
+     * idempotency record instead of charging again. Defaults to a fresh value
+     * (each call is a distinct write).
+     */
+    idempotencyKey?: string;
+}
+/** Per-read options. */
+interface GetOptions {
+    /**
+     * Stable key making a retried get() exactly-once: the same key hits the
+     * server's read idempotency record (credit path) and pins the EIP-3009 nonce
+     * (paid path) instead of charging again. Defaults to a fresh value per call
+     * (each get() is a distinct, separately-charged read).
+     */
+    idempotencyKey?: string;
+}
+/** Result of a successful write. */
+interface SetResult {
+    ok: true;
+    expires_at: string;
+    /** Machine-readable usage envelope for this write. Absent only if the server predates it. */
+    usage?: UsageBlock;
+}
+/** Result of a successful delete. */
+interface DeleteResult {
+    ok: true;
+}
+/** Result of a successful credit deposit. */
+interface DepositResult {
+    credits_added: number;
+    balance: number;
+}
+/** Standard AgentKV error response body. */
+interface ErrorBody {
+    error: string;
+    code: string;
+    hint?: string;
+}
+
+/**
+ * Mint a fresh account key: `ak_` followed by the hex of AK_RANDOM_BYTES
+ * cryptographically-random bytes. This is the bearer secret — knowing it IS the
+ * capability to read/write the account. Persist it securely (e.g. a keystore);
+ * the worker stores only its hash, so a lost key is unrecoverable.
+ */
+declare function generateAccountKey(): string;
+/** True iff `s` is a string in the canonical `ak_<64 lowercase hex>` shape. */
+declare function isAccountKeyFormat(s: unknown): s is string;
+
+/**
+ * All keys derived from one per-wallet `ikm` with domain-separated HKDF labels — so the
+ * value key, the key-name key, and the blind-index MAC key are independent.
+ */
+interface KeyMaterial {
+    value: Uint8Array;
+    keyName: Uint8Array;
+    mac: Uint8Array;
+}
+declare function deriveKeyMaterial(ikm: Uint8Array): KeyMaterial;
+/**
+ * Blind-index digest for a key NAME: `scheme_tag ‖ HMAC-SHA256(macKey, NFC(name))`,
+ * url-safe-base64. Deterministic and per-wallet (macKey is per-wallet), so the server
+ * looks up by an opaque token it cannot invert or correlate across wallets. NFC is the
+ * frozen normalization (case-sensitive, whitespace-preserving). Used by set/get/delete/list
+ * to look a value up under an opaque per-wallet token the server cannot invert.
+ */
+declare function hashKey(macKey: Uint8Array, name: string): string;
+/**
+ * Encrypt plaintext with AES-256-GCM, emitting the versioned self-describing envelope
+ * `base64( magic ‖ ver ‖ suite ‖ kdf_id ‖ IV ‖ ct+tag )`. The header (and, when `aad` is
+ * supplied, the key's digest) is bound into the AAD.
+ */
+declare function encrypt(key: Uint8Array, plaintext: string, aad?: string): Promise<string>;
+/**
+ * Decrypt a value produced by encrypt(). Requires the versioned envelope (magic + known
+ * ver/suite/kdf) and verifies the AAD-bound header (and, when `aad` is supplied, the key's
+ * digest — so a value the server serves for the WRONG key fails the tag instead of decrypting).
+ */
+declare function decrypt(key: Uint8Array, packed: string, aad?: string): Promise<string>;
+
+declare const VERSION = "0.1.0";
+
+/** USD value of one prepaid credit ($1 mints 10,000 credits). */
+declare const CREDIT_VALUE_USD = 0.0001;
+declare const ACCOUNT_READ_USD = 0.0003;
+declare const ACCOUNT_WRITE_USD = 0.0005;
+/**
+ * Built-in ceiling on a SERVER-QUOTED per-op price when no `maxSpendUsd` is configured.
+ * The advertised op price is ~$0.005; without this, a compromised or spoofed worker could
+ * answer a routine read with a 402 challenge for the wallet's entire balance and the client
+ * would sign the EIP-3009 authorization (the default config has no per-op cap). Callers who
+ * legitimately need a pricier op opt in explicitly via `maxSpendUsd`.
+ */
+declare const DEFAULT_MAX_OP_USD = 0.05;
+declare class AgentKV {
+    /**
+     * The signing wallet. `undefined` in account-key mode (a managed account has no
+     * wallet that can sign) — the `ak_…` bearer token is the identity instead.
+     */
+    readonly signer?: Signer;
+    /**
+     * The wallet address, the per-wallet namespace. In account-key mode there is no
+     * wallet, so this is the zero address (a documented sentinel: the account key —
+     * not an address — is the identity; the server names storage by the key's hash).
+     */
+    /** The wallet address (its namespace) in wallet/signer mode; `undefined` in account-key mode. */
+    readonly address: `0x${string}` | undefined;
+    /** The raw `ak_…` bearer token in account-key mode; `undefined` otherwise. */
+    readonly accountKey?: string;
+    readonly endpoint: string;
+    readonly network: string;
+    readonly maxSpendUsd?: number;
+    readonly maxSessionSpendUsd?: number;
+    /** Bounded internal retries on transient failures (network error / 5xx). */
+    readonly maxRetries: number;
+    private readonly timeoutMs?;
+    private readonly fetchImpl?;
+    private _ikm?;
+    private _km?;
+    private _kmPromise?;
+    private sessionSpentUsd;
+    private readonly prepay?;
+    /** Top-off amount in atomic USDC units (1e6), computed once in the constructor. */
+    private readonly topoffAtomic;
+    /** Account-key top-off hook (account-key mode only; validated in the constructor). */
+    private readonly topoffPayer?;
+    /**
+     * Account-key inline x402 transport hook (account-key mode only; validated in
+     * the constructor). Mutually exclusive with `topoffPayer` PER OP — `topoffPayer`
+     * always takes precedence when both are configured (see the call sites in
+     * set()/get(), which gate on `!this.topoffPayer`).
+     */
+    private readonly opInlinePayer?;
+    /** Last-known credit balance as an EXACT integer credit count (never USD floats). */
+    private knownCredits?;
+    /** Synchronous single-flight guard: at most one in-flight top-off at a time. */
+    private topoffInFlight;
+    /**
+     * The in-flight SYNCHRONOUS top-off deposit (account mode), published so a concurrent op
+     * that hits a hard 402 but can't claim the single-flight can await it and retry.
+     */
+    private topoffPromise;
+    /** Cached last `PAYMENT-REQUIRED` header — the template for a proactive single-shot. */
+    private challengeTemplate?;
+    constructor(opts: AgentKVOptions);
+    /**
+     * Resolve (and memoize) the AES key. Async only for the sign-to-derive shape
+     * (`{signer}` with no encryptionKey): the key is `HKDF` over a fixed-message
+     * signature, which is stable ONLY for deterministic ECDSA signers (local keys /
+     * RFC-6979). Non-deterministic signers (some MPC/threshold backends) would
+     * derive a different key each run and fail to decrypt — those must pass an
+     * explicit `encryptionKey`.
+     */
+    private getKeyMaterial;
+    /**
+     * Decrypt a value envelope with the current value key, binding the key's blind-index
+     * digest into the AAD so a value the server serves for the wrong key fails the auth tag.
+     */
+    private decryptValue;
+    private assertSpend;
+    private recordSpend;
+    /**
+     * Reject a SERVER-QUOTED per-op price above a sane ceiling in the DEFAULT (cap-less) config.
+     * When `maxSpendUsd` is set, `assertSpend` already bounds the op price; when it is NOT set,
+     * a compromised or spoofed worker could otherwise answer a routine $0.005 read with a 402
+     * challenge for the wallet's whole balance and the client would sign the EIP-3009
+     * authorization. Callers who genuinely need a pricier op opt in via `maxSpendUsd`.
+     */
+    private assertOpPriceCeiling;
+    /**
+     * The effective per-op ceiling (USD) for an inline-payer op: the caller's `maxSpendUsd`
+     * when set (they opted into that bound), else the built-in default ceiling. Handed to the
+     * hook as its hard `maxAmountAtomic`, and pre-reserved against the session cap before paying.
+     */
+    private inlineOpCeilingUsd;
+    /**
+     * The on-chain settlement txHash from a response's PAYMENT-RESPONSE header, or ""
+     * when the server served the op from existing credits (so the attached top-off
+     * authorization was NEVER settled — it just expires) or the header is absent. The
+     * worker emits PAYMENT-RESPONSE = base64(JSON `{ success, payer, amount, txHash }`)
+     * on any paid 200, with `txHash: ""` on the credit hot path. A proactive single-shot
+     * top-off must only count toward session spend when this is non-empty — otherwise no
+     * USDC moved and recording it inflates sessionSpentUsd, prematurely tripping the cap.
+     *
+     * Accepted trade-off: in a doubly-rare crash window (the server's settle mined on-chain
+     * but its ledger row was lost, AND the response was lost so the client retries), the
+     * worker's already-used-authorization recovery returns success with txHash "" even
+     * though USDC did move. The client then under-counts that top-off by one, making the
+     * local session cap marginally lenient — no funds are lost (the amount is still minted
+     * as credits). This is unavoidable (the worker cannot distinguish that case from a
+     * plain credit-served op) and far cheaper than the systematic L3 over-count it replaces.
+     */
+    private settledTxHash;
+    /**
+     * Issue a request with bounded internal retry on TRANSIENT failures only: a
+     * thrown fetch (network error / lost response) or a 5xx. `build()` is re-invoked
+     * per attempt so the credit path can re-sign identity with a FRESH nonce each
+     * time, while the op's stable Idempotency-Key (and pinned EIP-3009 nonce on paid
+     * ops) makes a retry of an already-processed request dedupe server-side — so a
+     * lost response that the server already charged is recovered without a second
+     * charge. NOT retried: any 2xx/4xx (incl. the 402 credit->pay handoff, 401, 404)
+     * — those are returned as-is for the caller's normal handling. The bound is kept
+     * small so a re-sent paid authorization cannot outlive its validBefore.
+     *
+     * The retry MECHANICS (transient-status detection, backoff,
+     * Retry-After honoring) were extracted to `@agentx402-ai/core`'s `fetchWithRetry`
+     * as a pure function parameterized by `maxRetries` — this method is now a
+     * thin delegating wrapper so every existing `this.fetchWithRetry(...)` call
+     * site above is unchanged.
+     */
+    private fetchWithRetry;
+    /**
+     * Update prepay tracking from any server response. Reads the exact integer
+     * credit balance (`X-AgentKV-Credits-Remaining`) and caches the most recent
+     * `PAYMENT-REQUIRED` challenge as the proactive single-shot template (so a
+     * top-off needs no preflight request). Safe to call when prepay is disabled.
+     */
+    private trackBalance;
+    /** Watermark (USD) expressed in EXACT integer credits (1 credit = CREDIT_VALUE_USD = $0.0001,
+     *  so $1 = 10,000 credits — matching the worker's mint rate). */
+    private watermarkCredits;
+    /**
+     * Synchronous single-flight claim for a proactive top-off. CRITICAL: there is
+     * NO `await` between the watermark check and setting `topoffInFlight = true`,
+     * and this must be called at the very top of set/get before any await.
+     * Otherwise two concurrent ops both pass the check and each fire a separate
+     * top-off with distinct fresh nonces the server can't dedupe (double charge).
+     * Returns true for exactly one concurrent op below the watermark; the caller
+     * MUST clear `topoffInFlight` in a `finally`. Losers take the identity path.
+     */
+    private tryClaimTopoff;
+    /**
+     * Single-flight claim at a hard 402 (insufficient credits). Unlike
+     * `tryClaimTopoff` this ignores the watermark — a 402 already proves credits
+     * are short — but still claims the flag synchronously so concurrent 402s don't
+     * each fire a top-off. Returns true only if the flag was free; the caller MUST
+     * clear it in a `finally`. In `async` mode we leave the 402 to be paid at the
+     * op price (the background deposit replenishes credits separately).
+     */
+    private tryClaimTopoffOnFault;
+    /**
+     * Run a synchronous account-mode top-off while PUBLISHING its in-flight promise, so a
+     * concurrent op that hits a hard 402 (and can't claim the single-flight) can await THIS
+     * deposit and retry rather than surfacing the 402. The caller holds the single-flight claim.
+     */
+    private runSharedTopoff;
+    /**
+     * Detached async top-off (opt-in via `prepay.async`). When below the watermark
+     * and no top-off is in flight, fire a deposit WITHOUT awaiting it in the op
+     * path. Documented races: the balance read is point-in-time so the trigger can
+     * be stale, and a deposit settling between an op's read and this check can make
+     * the top-off redundant; the single-flight flag bounds these to at most one
+     * outstanding deposit, but cannot serialize against an op already past its own
+     * check. Use the (default) synchronous single-shot for exactly-bounded spend.
+     *
+     * Account-key mode: there is no signing wallet, so the detached
+     * deposit is dispatched through `runAccountTopoff()` (the `topoffPayer` hook)
+     * instead of `runDeposit` (which throws `no_signer` in account mode). Wallet
+     * mode is completely unchanged below.
+     */
+    private maybeAsyncTopoff;
+    /**
+     * Whether a top-off of `prepay.topoff` fits under the cumulative SESSION cap.
+     * Top-offs are deliberately NOT gated on the per-op `maxSpendUsd` (which bounds
+     * individual pay-per-op charges); when over the session cap we downgrade to
+     * pay-per-op rather than throwing.
+     */
+    private topoffFitsSessionCap;
+    /**
+     * Single source of truth for BOTH the EIP-712-signed pathname (`path`) and the
+     * URL to fetch (`url`), so they can never diverge — a divergence silently
+     * breaks identity auth: the worker verifies over the RECEIVED path and
+     * recovers a phantom address if it differs from what the client signed.
+     * `base` is the un-prefixed pathname; the fetched/signed path is `/v1` + `base`
+     * (list-keys overrides it to `/v1/kv`). `query` is appended to `url`
+     * ONLY — EIP-712 binds the pathname, never the query string.
+     */
+    private route;
+    private kvRoute;
+    /**
+     * Per-op auth headers. In account-key mode this is the `Authorization: Bearer
+     * ak_…` header (server hashes it to name storage + debit credits); in wallet
+     * mode it is the EIP-712 identity signature. Used by every op so the same call
+     * site picks the right scheme. Async to share the signature of `identityHeaders`.
+     */
+    private authHeaders;
+    /**
+     * The signing wallet, asserted present. Every x402 path (set/get top-off + 402
+     * fallback, deposit) is gated behind `!this.accountKey` and so always has a
+     * signer; this narrows the optional type at those call sites (and fails loudly
+     * if that invariant is ever broken).
+     */
+    private requireSigner;
+    /** EIP-712 identity headers with the deployment host bound into the signature (prevents cross-deployment signature replay). */
+    private identityHeaders;
+    /**
+     * Shared money/transport orchestrator behind set() and getInternal() — the single copy of
+     * the flow both share: account-key (bearer) mode with proactive + hard-402 top-off and the
+     * inline-payer path; wallet mode with the proactive single-shot, credit path, and 402
+     * pay-and-retry — including the single-flight top-off accounting and settled-txHash spend
+     * gating. Per-op differences (method/body, credit cost, 404 handling, success/inline
+     * parsing) come from `spec`. The CALLER must claim the single-flight top-off SYNCHRONOUSLY
+     * (before any await) and pass it in `flight`; it may be re-claimed here on a cold-start hard
+     * 402, and the caller's `finally` releases it.
+     */
+    private performOp;
+    /**
+     * Write an encrypted value. The value is JSON-stringified and AES-256-GCM
+     * encrypted client-side; the server only ever stores ciphertext. `null` and
+     * `undefined` are rejected (`invalid_value`) so a `null` from get() unambiguously
+     * means "missing key" — use delete() to remove a key. Tries the credit path first
+     * (EIP-712 identity signature); if credits are insufficient the server returns a 402
+     * x402 challenge and the client pays. A stable Idempotency-Key is reused across that
+     * retry so the write is exactly-once.
+     */
+    set(key: string, value: unknown, opts?: SetOptions): Promise<SetResult>;
+    /**
+     * Read and decrypt a value. Tries the credit path first (EIP-712 identity);
+     * if credits are insufficient the server returns a 402 x402 challenge and the
+     * client pays, then retries. Returns null if the key is missing or expired (404);
+     * stored values are never null (set rejects it), so null unambiguously means absent.
+     */
+    get<T = unknown>(key: string, opts?: GetOptions): Promise<T | null>;
+    /**
+     * Like `get`, but ALSO surfaces the machine-readable usage envelope the server
+     * attaches to a paid read's success body — a separate, additive
+     * accessor so `get()` keeps its narrower `T | null` signature (no existing
+     * caller breaks). `usage` is absent when the key was missing/expired (404 —
+     * the read op itself is never charged on a miss, see the DO's 404-before-charge
+     * precheck — though a proactive top-off, if one was triggered for this call,
+     * is a separate deposit charge and can still happen alongside a miss) or when
+     * talking to a server that predates the usage envelope.
+     */
+    getWithUsage<T = unknown>(key: string, opts?: GetOptions): Promise<{
+        value: T | null;
+        usage?: UsageBlock;
+    }>;
+    /**
+     * Shared implementation behind `get`/`getWithUsage`. Tries the credit path
+     * first (EIP-712 identity); if credits are insufficient the server returns a
+     * 402 x402 challenge and the client pays, then retries. `value` is null if
+     * the key is missing or expired (404); stored values are never null (set
+     * rejects it), so null unambiguously means absent.
+     */
+    private getInternal;
+    /**
+     * Delete a key. Free operation. Authenticated with the account-key bearer in
+     * account mode, else an EIP-712 identity signature (fresh nonce + timestamp).
+     * The digest is computed from the local key material either way.
+     */
+    delete(key: string): Promise<DeleteResult>;
+    /**
+     * List the wallet's keys. The server returns opaque per-wallet digests plus each key's
+     * ENCRYPTED name; this decrypts the names locally and returns them — the server never
+     * sees a plaintext key name. Free (EIP-712 identity signed). Paginated: pass the returned
+     * `cursor` to fetch the next page; `cursor` is null once exhausted.
+     */
+    listKeys(opts?: {
+        cursor?: string | null;
+        limit?: number;
+    }): Promise<{
+        keys: string[];
+        cursor: string | null;
+    }>;
+    /**
+     * Read the pre-paid credit balance. Free. Account-key bearer in account mode,
+     * else an EIP-712 identity signature.
+     */
+    balance(): Promise<number>;
+    /**
+     * Buy credits with an x402 payment. `amountUsd` must be at least $1; any
+     * amount is accepted (no fixed tiers). This settles on-chain once via the
+     * facilitator; the returned credits are then spendable by set/get with no
+     * further payment.
+     */
+    deposit(amountUsd: number, opts?: {
+        idempotencyKey?: string;
+        expectedPayTo?: string;
+    }): Promise<DepositResult>;
+    /**
+     * Account-key top-off: delegate payment of `${endpoint}/account/deposit` to the
+     * configured `topoffPayer` (a managed account has no signing wallet to sign an
+     * x402 payment). The caller must hold the single-flight claim and have checked
+     * `topoffFitsSessionCap()`. On resolve (= the deposit SETTLED) the top-off is
+     * recorded against the session budget only — top-offs are credit purchases, not
+     * per-op charges, so the per-op cap is deliberately not consulted (mirrors the
+     * wallet-mode top-off budget rules). A rejection is wrapped as
+     * `account_topoff_failed`; the ak_ bearer is never included in the message.
+     */
+    /**
+     * `amountUsd` generalizes this beyond the fixed `prepay.topoff` amount
+     * so `deposit()` can reuse it for a caller-chosen amount. OMITTED (the no-arg
+     * call from the proactive/hard-402/async paths above), it defaults to
+     * `prepay.topoff` and its precomputed `topoffAtomic` ceiling — BYTE-FOR-BYTE the
+     * stage-1 behavior. An EXPLICIT `amountUsd` (from `deposit()`, which may be
+     * called with no `prepay` configured at all) is validated here the same way
+     * `runDeposit` validates its wallet-mode amount, since it never passed through
+     * the constructor's `prepay.topoff` guard.
+     */
+    private runAccountTopoff;
+    private runDeposit;
+    /**
+     * Fund an ACCOUNT-KEY namespace — "payer funds, bearer owns". A CALLER-supplied
+     * `signer` pays via x402 to add prepaid credits to THIS client's account (the
+     * one named by its `ak_…` bearer). The payer and the owner are deliberately
+     * DECOUPLED: the payer wallet signs the on-chain EIP-3009 authorization, while
+     * the bearer — not the payer's address — owns the credited namespace. This is the
+     * SDK counterpart of the server's `/account/deposit` route.
+     *
+     * Account-key mode ONLY. In WALLET mode the paying wallet IS the namespace, so
+     * use `deposit()` instead — calling this throws `wrong_mode` before any network.
+     *
+     * `signer` is the PAYER: a viem account (must expose `address` + `signTypedData`)
+     * or a raw `0x` private key (built into a viem account internally, mirroring the
+     * constructor). `amountUsd` must be a whole number of dollars >= $1. UNLIKE
+     * `deposit()` (which IS gated by both spend caps and counts toward session spend),
+     * this explicit funding call is NOT gated by `maxSpendUsd`/`maxSessionSpendUsd` and
+     * does not count toward session spend — the payer is an EXTERNAL wallet, not this
+     * client's tracked budget. The local encryption key is never touched (funding does not encrypt).
+     */
+    fundAccount(signer: Signer | `0x${string}`, amountUsd: number, opts?: {
+        idempotencyKey?: string;
+        expectedPayTo?: string;
+    }): Promise<DepositResult>;
+    /** Shared by `asError` (a real `Response`) and the `opInlinePayer` path (a plain `{status,body}`). */
+    private errorFromBody;
+    private asError;
+    /**
+     * The settled amount (USD) from an `opInlinePayer` response's PAYMENT-RESPONSE
+     * header — the inline-path mirror of `settledTxHash()` above, but reading a
+     * plain `Record<string,string>` (the hook's own headers, not a `Response`) and
+     * returning the `amount` field instead of the `txHash`. Case-insensitive header
+     * lookup: an external transport (e.g. awal) is not guaranteed to preserve the
+     * worker's exact `PAYMENT-RESPONSE` casing. Returns `undefined` when the header
+     * is absent/unparsable OR the op settled nothing (served from existing credits,
+     * `txHash: ""`) — callers fall back to the credit-equivalent op price.
+     */
+    private inlineSettledAmountUsd;
+}
+
+export { ACCOUNT_READ_USD, ACCOUNT_WRITE_USD, AgentKV, type AgentKVOptions, CREDIT_VALUE_USD, DEFAULT_MAX_OP_USD, type DeleteResult, type DepositResult, type ErrorBody, type GetOptions, type KeyMaterial, type OpInlineRequest, type OpInlineResponse, type SetOptions, type SetResult, type TopoffPayerRequest, VERSION, decrypt, deriveKeyMaterial, encrypt, generateAccountKey, hashKey, isAccountKeyFormat };