@inflowpayai/x402-buyer 0.5.0

package/dist/index.d.ts

@@ -0,0 +1,427 @@
+import { x402Client, PaymentPolicy, ClientExtension, BeforePaymentCreationHook, AfterPaymentCreationHook, OnPaymentCreationFailureHook, OnPaymentResponseHook } from '@x402/core/client';
+import { PaymentRequired, PaymentPayload, Network, SchemeNetworkClient } from '@x402/core/types';
+import { InflowPaymentPayload, PaymentScheme, PaymentRequirements, ResourceInfo, X402BuyerSupportedResponse, InflowClientOptions, InstrumentType } from '@inflowpayai/x402';
+
+/**
+ * Status of an x402 transaction's signing flow. `'INITIATED'` means the server-side approval is still pending. Any
+ * other value indicates the approval has cleared — successful when paired with an `encodedPayload`, failed otherwise.
+ * The SDK treats values other than `'INITIATED'` opaquely so new statuses don't require client changes.
+ */
+type TransactionStatus = 'INITIATED' | (string & {});
+/**
+ * Status of a buyer-side approval. `'APPROVED'` means the server has synchronously signed; `'PENDING'` means the buyer
+ * must approve in their dashboard. Other terminal values (declined, cancelled, etc.) are surfaced verbatim and treated
+ * opaquely.
+ */
+type ApprovalStatus = 'APPROVED' | 'PENDING' | (string & {});
+/**
+ * Response body of `POST /v1/transactions/x402`. The buyer creates a transaction and Approval; this is what the server
+ * returns synchronously.
+ */
+interface X402TransactionResponse {
+    approvalId: string;
+    approvalStatus: ApprovalStatus;
+    transactionId: string;
+    amount: string;
+    currency: string;
+    resource?: ResourceInfo;
+}
+/**
+ * Response body of `GET /v1/transactions/{transactionId}/x402`. While `status === 'INITIATED'`, neither
+ * `encodedPayload` nor `paymentPayload` are populated. Once the server has signed, both appear together.
+ */
+interface X402PayloadResponse {
+    status: TransactionStatus;
+    encodedPayload?: string;
+    paymentPayload?: InflowPaymentPayload;
+}
+/**
+ * Context the buyer learned from the seller's 402 response, threaded into `prepare()` / `sign()` so the server-side
+ * `POST /v1/transactions/x402` endpoint receives the seller's exact `resource` and `x402Version`.
+ */
+interface SigningContext {
+    /** From `PaymentRequired.resource`. */
+    resource: ResourceInfo;
+    /** From `PaymentRequired.x402Version`. Should be `2`. */
+    x402Version: number;
+    /**
+     * From `PaymentRequired.extensions`. The signer dispatches handlers registered in the core extensions registry for
+     * the names it sees here.
+     */
+    extensions?: Record<string, unknown>;
+}
+/**
+ * Output of a successful signing. `encodedPayload` is the base64 string to set as the `PAYMENT-SIGNATURE` header — the
+ * SDK never re-encodes the server-produced value.
+ */
+interface EncodedPayment {
+    /** Base64-encoded `InflowPaymentPayload` (re-exported from `@inflowpayai/x402`). */
+    encodedPayload: string;
+    /** Parsed payload for inspection. */
+    paymentPayload: InflowPaymentPayload;
+    /**
+     * Server-side transaction id for correlation. Present when the InFlow-signed branch produced this payment; absent on
+     * the foundation-signed branch (no InFlow Approval was created).
+     */
+    transactionId?: string;
+}
+/** Per-call options accepted by every signing entry point. */
+interface SignOptions {
+    /**
+     * Poll cadence while approval is `'INITIATED'`. Default 5000 ms (fixed — no exponential backoff, no jitter; the
+     * polling loop is itself the retry mechanism for the approval window).
+     */
+    pollIntervalMs?: number;
+    /**
+     * Hard timeout for the full sign / `awaitPayload` call. Default 900 000 ms (15 minutes) — matches the server-side
+     * approval expiry.
+     */
+    timeoutMs?: number;
+    /** Cooperative cancellation. */
+    signal?: AbortSignal;
+    /**
+     * Caller-supplied payment identifier forwarded to the server's `remotePaymentId` field. Validated client-side via the
+     * `payment-identifier` extension rules (16–128 chars, `^[a-zA-Z0-9_-]+$`); invalid values throw
+     * {@link X402PaymentIdFormatError} before any server round trip.
+     */
+    paymentId?: string;
+}
+/** Constructor options for {@link createInflowClient}. */
+interface SignerOptions extends InflowClientOptions {
+    /**
+     * Ordered scheme preference used when picking among multiple InFlow-acceptable requirements inside
+     * {@link InflowClient.createPaymentPayload}. Default `['balance', 'exact']`.
+     */
+    prefer?: PaymentScheme[];
+    /** Reserved instrument-scheme configuration. */
+    instrument?: {
+        id?: string;
+        types?: InstrumentType[];
+    };
+    /** Default poll / timeout / paymentId values applied to every signing call. */
+    signDefaults?: SignOptions;
+}
+/**
+ * Handle returned by {@link InflowClient.prepareInflowPayment}. The transaction + approval have already been created
+ * server-side; the caller decides when to await the signed payload.
+ */
+interface PreparedPayment {
+    readonly transactionId: string;
+    readonly approvalId: string;
+    /**
+     * Poll `GET /v1/transactions/{transactionId}/x402` at `pollIntervalMs` cadence until the server has signed, the call
+     * times out, or the caller's `AbortSignal` aborts.
+     *
+     * @param options - Per-call overrides. Concurrent callers share the underlying loop; only the FIRST call's
+     *   `pollIntervalMs` / `timeoutMs` are honored.
+     * @returns The signed {@link EncodedPayment}.
+     * @throws {@link X402ApprovalFailedError} When the server moves out of `'INITIATED'` without producing an
+     *   `encodedPayload`.
+     * @throws {@link X402ApprovalTimeoutError} When wall-clock exceeds `timeoutMs` or the caller's `signal` aborts.
+     */
+    awaitPayload(options?: SignOptions): Promise<EncodedPayment>;
+    /**
+     * One-shot poll: returns the current {@link TransactionStatus} without waiting.
+     *
+     * @returns The latest status reported by the server.
+     */
+    status(): Promise<TransactionStatus>;
+    /**
+     * Best-effort cancel of the underlying server-side approval. Calls `POST /v1/approvals/{approvalId}/cancel`.
+     * **Fire-and-forget by design** — always resolves, never rejects. Use to release a `PreparedPayment` the caller no
+     * longer intends to await.
+     *
+     * @returns A promise that always resolves.
+     */
+    cancel(): Promise<void>;
+}
+/**
+ * Minimal buyer-side signer contract. Implementation detail of {@link InflowClient}; not re-exported from the package
+ * barrel.
+ *
+ * @internal
+ */
+interface Signer {
+    /** Ordered scheme preference this signer would like callers to honor. */
+    readonly prefer: readonly PaymentScheme[];
+    /**
+     * Set of extension names this signer can satisfy on the buyer side. Used to filter `accepts[]` entries whose
+     * `PaymentRequired` declares a `required: true` extension this signer cannot handle.
+     */
+    readonly extensionsHandled: ReadonlySet<string>;
+    /**
+     * Synchronous predicate: does this signer know how to sign the given requirement?
+     *
+     * @param requirement - The candidate {@link PaymentRequirements}.
+     * @returns `true` if `sign(requirement, ctx)` is expected to succeed.
+     */
+    supports(requirement: PaymentRequirements): boolean;
+    /**
+     * Single-shot signing. Produces a base64-encoded {@link InflowPaymentPayload} ready to set as the `PAYMENT-SIGNATURE`
+     * header.
+     *
+     * @param requirement - The chosen {@link PaymentRequirements}.
+     * @param context - Seller-side {@link SigningContext} (resource + `x402Version` + extensions declarations).
+     * @param options - Per-call {@link SignOptions}.
+     * @returns The signed {@link EncodedPayment}.
+     */
+    sign(requirement: PaymentRequirements, context: SigningContext, options?: SignOptions): Promise<EncodedPayment>;
+}
+/**
+ * InFlow-specific buyer signer. Adds the InFlow-server capability table, priming hooks, and a two-phase `prepare()` /
+ * `awaitPayload()` flow for callers that want to surface pending-approval UI before the protected request.
+ * Implementation detail of {@link InflowClient}; not re-exported from the package barrel.
+ *
+ * @internal
+ */
+interface InflowSigner extends Signer {
+    /**
+     * Idempotent no-op for callers that have a long-lived signer and want to assert readiness explicitly. The async
+     * factory has already primed the capability cache; `ready()` exists for ergonomics only.
+     *
+     * @returns A resolved promise.
+     */
+    ready(): Promise<void>;
+    /**
+     * Return the cached buyer capability set. 60-min TTL.
+     *
+     * @returns The {@link X402BuyerSupportedResponse}.
+     */
+    getSupported(): Promise<X402BuyerSupportedResponse>;
+    /**
+     * Force a refetch of the buyer capability table.
+     *
+     * @returns The freshly fetched {@link X402BuyerSupportedResponse}.
+     */
+    refreshSupported(): Promise<X402BuyerSupportedResponse>;
+    /**
+     * Kick off the buyer's transaction and Approval and return a handle the caller can await independently.
+     *
+     * @param requirement - The chosen {@link PaymentRequirements}.
+     * @param context - Seller-side {@link SigningContext}.
+     * @param options - Per-call {@link SignOptions}.
+     * @returns A {@link PreparedPayment} handle.
+     * @throws {@link X402PaymentIdFormatError} When `options.paymentId` is set but doesn't satisfy `validatePaymentId`.
+     */
+    prepare(requirement: PaymentRequirements, context: SigningContext, options?: SignOptions): Promise<PreparedPayment>;
+}
+
+/**
+ * Subclass of `@x402/core`'s `x402Client` that adds the InFlow MPC signing branch and the two-phase
+ * {@link InflowClient.prepareInflowPayment} flow. Construct via {@link createInflowClient}.
+ */
+declare class InflowClient extends x402Client {
+    /**
+     * The InFlow-signed branch of the routing decision. Kept private — callers compose by passing the {@link InflowClient}
+     * to `x402HTTPClient` (and to `registerExactEvmScheme` / `registerExactSvmScheme` for foundation-signed networks).
+     */
+    private readonly inflowSigner;
+    /**
+     * Ordered scheme preference used when picking among multiple InFlow-acceptable requirements. Sourced from the InFlow
+     * signer at construction so the buyer's intent (`prefer: ['balance', 'exact']` by default) survives across the
+     * override.
+     */
+    private readonly preferOrder;
+    /**
+     * Construct via {@link createInflowClient}. The factory primes the buyer capability cache before resolving, so the
+     * routing decision in {@link InflowClient.createPaymentPayload} is synchronous against in-memory data. The constructor
+     * is exported only so the class is referenceable for `instanceof` checks, generic constraints, and return types.
+     *
+     * @param inflowSigner - Primed InFlow signer carrying the buyer capability cache, MPC signing flow, and prefer order.
+     * @internal
+     */
+    constructor(inflowSigner: InflowSigner);
+    /**
+     * Routing override. InFlow signs when the buyer capability cache covers a requirement (preferred-scheme order);
+     * otherwise the foundation signs and any registered extension handlers are folded into `payload.extensions`. A
+     * `required: true` extension whose handler returns `null` throws.
+     */
+    createPaymentPayload(paymentRequired: PaymentRequired): Promise<PaymentPayload>;
+    /**
+     * Two-phase signing flow for callers that want to surface pending- approval UI before the protected request is
+     * replayed. Forwarded to the InFlow signer's `prepare()`; returns a {@link PreparedPayment} the caller can
+     * `awaitPayload()` or `cancel()` independently.
+     *
+     * Has no foundation equivalent — `x402Client.createPaymentPayload` is one-shot. The handle is InFlow-specific and
+     * only applies to requirements InFlow can sign.
+     *
+     * @param requirement - The chosen `PaymentRequirements` (re-exported from `@inflowpayai/x402`) — must match an entry
+     *   in the InFlow buyer capability cache.
+     * @param context - Seller-side {@link SigningContext}.
+     * @param options - Per-call {@link SignOptions}.
+     * @returns A {@link PreparedPayment} handle.
+     * @throws {@link X402AdapterRoutingError} When the requirement is not in the InFlow buyer capability cache
+     *   (foundation-signed requirements have no two-phase flow).
+     */
+    prepareInflowPayment(requirement: PaymentRequirements, context: SigningContext, options?: SignOptions): Promise<PreparedPayment>;
+    register(network: Network, schemeNetworkClient: SchemeNetworkClient): this;
+    registerV1(network: string, schemeNetworkClient: SchemeNetworkClient): this;
+    registerPolicy(policy: PaymentPolicy): this;
+    registerExtension(extension: ClientExtension): this;
+    onBeforePaymentCreation(hook: BeforePaymentCreationHook): this;
+    onAfterPaymentCreation(hook: AfterPaymentCreationHook): this;
+    onPaymentCreationFailure(hook: OnPaymentCreationFailureHook): this;
+    onPaymentResponse(hook: OnPaymentResponseHook): this;
+    /**
+     * Pick the buyer's preferred `accepts[]` entry the InFlow signer can handle. Walks {@link InflowClient.preferOrder}
+     * and returns the first entry whose `(scheme, network)` is in the InFlow capability cache; returns `null` when no
+     * entry matches (the foundation branch takes over).
+     */
+    private pickInflowMatch;
+}
+/**
+ * Async factory for {@link InflowClient}. Constructs the InFlow signer (which primes the buyer-supported cache) and
+ * attaches it to a fresh `InflowClient` instance.
+ *
+ * Foundation-managed scheme registrations (`registerExactEvmScheme(client, …)`, `registerExactSvmScheme(client, …)`)
+ * are applied to the returned instance by the caller after this factory resolves.
+ *
+ * @param options - {@link SignerOptions}.
+ * @returns A primed {@link InflowClient} ready for `x402HTTPClient` and any further foundation scheme registrations.
+ */
+declare function createInflowClient(options: SignerOptions): Promise<InflowClient>;
+
+/**
+ * Normalize a secp256k1 secret to viem's `0x`-prefixed 32-byte hex form. Accepts `0x`-prefixed hex, bare hex, or an
+ * InFlow Java seed (`BigInteger.toByteArray()` output — two's-complement, so 33 bytes with a leading sign byte for
+ * high-bit-set secrets, or short when leading zero bytes were dropped). Both edges renormalize to 32 bytes.
+ *
+ * @example
+ *
+ * ```ts
+ * import { privateKeyToAccount } from 'viem/accounts';
+ * import { parseEvmPrivateKey } from '@inflowpayai/x402-buyer';
+ *
+ * const account = privateKeyToAccount(parseEvmPrivateKey(process.env.EVM_PRIVATE_KEY!));
+ * ```
+ *
+ * @throws {@link X402InvalidEvmKeyError} On non-hex input or a payload that doesn't reduce to exactly 32 bytes.
+ */
+declare function parseEvmPrivateKey(value: string): `0x${string}`;
+
+/**
+ * Decode a Solana secret into the 64-byte Ed25519 form expected by `@solana/kit`'s `createKeyPairSignerFromBytes`.
+ * Auto-detects between a JSON byte array (`[...]`, as written by `solana-keygen`) and base58 (as emitted by InFlow's
+ * `SolanaClient.Account.getSeed()` and by Phantom's exported secret).
+ *
+ * @example
+ *
+ * ```ts
+ * import { createKeyPairSignerFromBytes } from '@solana/kit';
+ * import { decodeSolanaSecret } from '@inflowpayai/x402-buyer';
+ *
+ * const bytes = decodeSolanaSecret(process.env.SOLANA_PRIVATE_KEY!);
+ * const signer = await createKeyPairSignerFromBytes(bytes);
+ * ```
+ *
+ * @throws {@link X402InvalidSolanaKeyError} On empty input, unparseable payloads, or anything that doesn't decode to
+ *   exactly 64 bytes.
+ */
+declare function decodeSolanaSecret(value: string): Uint8Array;
+
+/**
+ * Thrown by `awaitPayload` when the server moves the approval out of `'INITIATED'` without producing an
+ * `encodedPayload` — the server has decided not to sign (insufficient funds, user-rejected, internal error, etc.). The
+ * terminal `status` string is surfaced verbatim so callers can branch on it without the SDK having to enumerate every
+ * server-side failure state.
+ */
+declare class X402ApprovalFailedError extends Error {
+    /** The approval id the server returned from `POST /v1/transactions/x402`. */
+    readonly approvalId: string;
+    /** Terminal status reported by the server. */
+    readonly status: TransactionStatus;
+    /**
+     * @param approvalId - Server-issued approval id.
+     * @param status - Terminal status string from the polling response.
+     */
+    constructor(approvalId: string, status: TransactionStatus);
+}
+/**
+ * Thrown by `awaitPayload` when `cancel()` is called on the same `PreparedPayment`. The cancel is fire-and-forget
+ * against the server; the SDK exits the polling loop immediately and never returns the partially-fetched state to the
+ * caller.
+ */
+declare class X402ApprovalCancelledError extends Error {
+    /** The approval id the server returned from `POST /v1/transactions/x402`. */
+    readonly approvalId: string;
+    constructor(approvalId: string);
+}
+/**
+ * Thrown by `awaitPayload` when wall-clock exceeds `timeoutMs` or the caller's `signal` aborts before the server has
+ * signed.
+ */
+declare class X402ApprovalTimeoutError extends Error {
+    /** The approval id the server returned from `POST /v1/transactions/x402`. */
+    readonly approvalId: string;
+    /** Effective timeout in milliseconds. */
+    readonly timeoutMs: number;
+    /**
+     * @param approvalId - Server-issued approval id.
+     * @param timeoutMs - The configured timeout that elapsed.
+     */
+    constructor(approvalId: string, timeoutMs: number);
+}
+/**
+ * Thrown by `prepare()` / `sign()` when `SignOptions.paymentId` does not satisfy the `payment-identifier` extension's
+ * format rules (16–128 chars, `^[a-zA-Z0-9_-]+$`). Surfaced client-side before any server round trip.
+ */
+declare class X402PaymentIdFormatError extends Error {
+    /** The offending input. */
+    readonly input: string;
+    /** @param input - The {@link SignOptions.paymentId} value that failed validation. */
+    constructor(input: string);
+}
+/**
+ * Thrown by {@link InflowClient.prepareInflowPayment} when the caller asks the two-phase flow for a requirement the
+ * InFlow signer cannot sign. The two-phase flow only exists for InFlow-signed requirements; foundation-signed schemes
+ * have no equivalent.
+ */
+declare class X402AdapterRoutingError extends Error {
+    /** Scheme of the requirement the adapter could not route. */
+    readonly scheme: string;
+    /** Network of the requirement the adapter could not route. */
+    readonly network: string;
+    /**
+     * @param scheme - Scheme of the offending requirement.
+     * @param network - Network of the offending requirement.
+     */
+    constructor(scheme: string, network: string);
+}
+/**
+ * Thrown by `parseEvmPrivateKey` when the input cannot be normalized to a 32-byte secp256k1 secret. The accepted input
+ * forms are `0x`-prefixed hex, bare hex, and InFlow's Java `Hex.encodeHexString(BigInteger.toByteArray())` seed
+ * (including the 33-byte sign-byte and sub-32-byte leading-zero-stripped shapes).
+ *
+ * The raw input is intentionally **not** preserved on the error: a decoding failure can be the user pasting a real key
+ * in the wrong encoding (e.g. a Solana base58 secret into the EVM decoder), so the offending value is treated as
+ * potential cryptographic material. Use {@link X402InvalidEvmKeyError.reason} for diagnostics; never log the input.
+ */
+declare class X402InvalidEvmKeyError extends Error {
+    /** Why the input failed validation. Never contains key bytes. */
+    readonly reason: string;
+    /**
+     * @param reason - Short explanation appended to the error message. Must not contain the raw input — produce a length
+     *   / shape description instead (e.g. `'expected 32 bytes, got 31'`).
+     */
+    constructor(reason: string);
+}
+/**
+ * Thrown by `decodeSolanaSecret` when the input cannot be decoded to a 64-byte Ed25519 secret key. Accepted input forms
+ * are a base58 string (matches InFlow's `SolanaClient.Account.getSeed()` and Phantom's export) or a JSON byte array
+ * (matches `solana-keygen`'s output file).
+ *
+ * The raw input is intentionally **not** preserved on the error: a decoding failure can be the user pasting a real key
+ * in the wrong encoding (e.g. a base58 secret with one character mistyped), so the offending value is treated as
+ * potential cryptographic material. Use {@link X402InvalidSolanaKeyError.reason} for diagnostics; never log the input.
+ */
+declare class X402InvalidSolanaKeyError extends Error {
+    /** Why the input failed validation. Never contains key bytes. */
+    readonly reason: string;
+    /**
+     * @param reason - Short explanation appended to the error message. Must not contain the raw input — produce a length
+     *   / shape description instead (e.g. `'expected 64 bytes, got 32'`).
+     */
+    constructor(reason: string);
+}
+
+export { type ApprovalStatus, type EncodedPayment, InflowClient, type PreparedPayment, type SignOptions, type SignerOptions, type SigningContext, type TransactionStatus, X402AdapterRoutingError, X402ApprovalCancelledError, X402ApprovalFailedError, X402ApprovalTimeoutError, X402InvalidEvmKeyError, X402InvalidSolanaKeyError, type X402PayloadResponse, X402PaymentIdFormatError, type X402TransactionResponse, createInflowClient, decodeSolanaSecret, parseEvmPrivateKey };