@catena/sdk 0.0.0-bootstrap.0 → 0.1.0

package/dist/client.d.mts

@@ -0,0 +1,3 @@
+import { t as InvalidKeyError } from "./keypair-BjMJtI3-.mjs";
+import { A as IntentResult, B as Policy, C as COUNTERPARTY_RULE_MODES, D as ExtensibleString, E as Counterparty, F as OnchainNetworkInput, G as X402Resource, H as SendMethod, I as POLICY_CAPABILITIES, J as X402SignedReceipt, K as AppInfo, L as POLICY_OVERRIDE_CAPABILITIES, M as MppChallenge, N as MppResource, O as INTENT_ACTION_TYPES, P as OnchainAssetInput, R as POLICY_RULE_ACTIONS, S as COUNTERPARTY_ACTIONS, T as CounterpartiesResponse, U as X402Authorization, V as SEND_METHODS, W as X402PaymentRequirements, _ as AccountDepositAddressResponse, a as IntentSubmitError, b as AccountsResponse, c as ACCOUNT_AGGREGATION_SCOPES, d as ACCOUNT_TRANSACTION_MOVEMENT_STATUSES, f as ACCOUNT_TRANSACTION_STATUSES, g as AccountDepositAddressParams, h as AccountBalanceResponse, i as FetchLike, j as MppAction, k as IntentAction, l as ACCOUNT_DEPOSIT_ADDRESS_SOURCES, m as ACTOR_AGGREGATION_SCOPES, n as CatenaClient, o as TimeoutError, p as ACCOUNT_TRANSACTION_TYPES, q as X402SignedOffer, r as CatenaClientOptions, s as createCatenaClient, t as ApiError, u as ACCOUNT_TRANSACTION_METHODS, v as AccountTransactionsParams, w as CounterpartiesParams, x as Agent, y as AccountTransactionsResponse, z as POLICY_RULE_TYPES } from "./client-Cm2wNUuB.mjs";
+export { ACCOUNT_AGGREGATION_SCOPES, ACCOUNT_DEPOSIT_ADDRESS_SOURCES, ACCOUNT_TRANSACTION_METHODS, ACCOUNT_TRANSACTION_MOVEMENT_STATUSES, ACCOUNT_TRANSACTION_STATUSES, ACCOUNT_TRANSACTION_TYPES, ACTOR_AGGREGATION_SCOPES, type AccountBalanceResponse, type AccountDepositAddressParams, type AccountDepositAddressResponse, type AccountTransactionsParams, type AccountTransactionsResponse, type AccountsResponse, type Agent, ApiError, type AppInfo, COUNTERPARTY_ACTIONS, COUNTERPARTY_RULE_MODES, type CatenaClient, CatenaClientOptions, type CounterpartiesParams, type CounterpartiesResponse, type Counterparty, type ExtensibleString, FetchLike, INTENT_ACTION_TYPES, type IntentAction, type IntentResult, IntentSubmitError, InvalidKeyError, type MppAction, type MppChallenge, type MppResource, type OnchainAssetInput, type OnchainNetworkInput, POLICY_CAPABILITIES, POLICY_OVERRIDE_CAPABILITIES, POLICY_RULE_ACTIONS, POLICY_RULE_TYPES, type Policy, SEND_METHODS, type SendMethod, TimeoutError, type X402Authorization, type X402PaymentRequirements, type X402Resource, type X402SignedOffer, type X402SignedReceipt, createCatenaClient };

package/dist/client.mjs

@@ -0,0 +1,3 @@
+import { InvalidKeyError } from "./keypair.mjs";
+import { _ as POLICY_RULE_ACTIONS, a as ACCOUNT_AGGREGATION_SCOPES, c as ACCOUNT_TRANSACTION_MOVEMENT_STATUSES, d as ACTOR_AGGREGATION_SCOPES, f as COUNTERPARTY_ACTIONS, g as POLICY_OVERRIDE_CAPABILITIES, h as POLICY_CAPABILITIES, i as createCatenaClient, l as ACCOUNT_TRANSACTION_STATUSES, m as INTENT_ACTION_TYPES, n as IntentSubmitError, o as ACCOUNT_DEPOSIT_ADDRESS_SOURCES, p as COUNTERPARTY_RULE_MODES, r as TimeoutError, s as ACCOUNT_TRANSACTION_METHODS, t as ApiError, u as ACCOUNT_TRANSACTION_TYPES, v as POLICY_RULE_TYPES, y as SEND_METHODS } from "./client-CHZMO00P.mjs";
+export { ACCOUNT_AGGREGATION_SCOPES, ACCOUNT_DEPOSIT_ADDRESS_SOURCES, ACCOUNT_TRANSACTION_METHODS, ACCOUNT_TRANSACTION_MOVEMENT_STATUSES, ACCOUNT_TRANSACTION_STATUSES, ACCOUNT_TRANSACTION_TYPES, ACTOR_AGGREGATION_SCOPES, ApiError, COUNTERPARTY_ACTIONS, COUNTERPARTY_RULE_MODES, INTENT_ACTION_TYPES, IntentSubmitError, InvalidKeyError, POLICY_CAPABILITIES, POLICY_OVERRIDE_CAPABILITIES, POLICY_RULE_ACTIONS, POLICY_RULE_TYPES, SEND_METHODS, TimeoutError, createCatenaClient };

package/dist/keypair-BjMJtI3-.d.mts

@@ -0,0 +1,35 @@
+//#region src/keypair.d.ts
+interface P256Keypair {
+  algorithm: "p256";
+  privateKeyHex: string;
+  publicKeyHex: string;
+}
+/**
+ * The supplied value is not a usable P-256 key.
+ */
+declare class InvalidKeyError extends Error {
+  constructor(message: string);
+}
+/**
+ * Generate a fresh agent credential. Feed `privateKeyHex` to
+ * `createCatenaClient`; the public half (or its thumbprint) is what gets
+ * registered with Catena when the agent is linked. The SDK never persists
+ * keys — storage is the caller's responsibility.
+ */
+declare function generateP256Keypair(): P256Keypair;
+/**
+ * Derive the full keypair from the private scalar alone, so a corrupt key
+ * throws at construction instead of surfacing as bank-side invalid_signature
+ * 401s — and a mismatched pair cannot exist at all.
+ */
+declare function p256KeypairFromPrivateKeyHex(privateKeyHex: string): P256Keypair;
+declare function p256PointFromCompressedHex(publicKeyHex: string): Buffer | null;
+/**
+ * RFC 7638 JWK thumbprint of a P-256 public key — the stable id the API
+ * knows a linked credential by. Throws {@link InvalidKeyError} when the
+ * input is not a valid P-256 point.
+ */
+declare function computeP256PublicKeyThumbprint(publicKeyHex: string): string;
+declare function p256PublicKeyThumbprintFromPoint(point: Buffer): string;
+//#endregion
+export { p256KeypairFromPrivateKeyHex as a, generateP256Keypair as i, P256Keypair as n, p256PointFromCompressedHex as o, computeP256PublicKeyThumbprint as r, p256PublicKeyThumbprintFromPoint as s, InvalidKeyError as t };

package/dist/keypair.d.mts

@@ -0,0 +1,2 @@
+import { a as p256KeypairFromPrivateKeyHex, i as generateP256Keypair, n as P256Keypair, o as p256PointFromCompressedHex, r as computeP256PublicKeyThumbprint, s as p256PublicKeyThumbprintFromPoint, t as InvalidKeyError } from "./keypair-BjMJtI3-.mjs";
+export { InvalidKeyError, P256Keypair, computeP256PublicKeyThumbprint, generateP256Keypair, p256KeypairFromPrivateKeyHex, p256PointFromCompressedHex, p256PublicKeyThumbprintFromPoint };

package/dist/keypair.mjs

@@ -0,0 +1,50 @@
+import { ECDH, createECDH, createHash } from "node:crypto";
+//#region src/keypair.ts
+var InvalidKeyError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "InvalidKeyError";
+	}
+};
+function generateP256Keypair() {
+	const ecdh = createECDH("prime256v1");
+	ecdh.generateKeys();
+	return p256KeypairFromPrivateKeyHex(ecdh.getPrivateKey().toString("hex").padStart(64, "0"));
+}
+const PRIVATE_KEY_HEX = /^[0-9a-f]{64}$/i;
+function p256KeypairFromPrivateKeyHex(privateKeyHex) {
+	if (!PRIVATE_KEY_HEX.test(privateKeyHex)) throw new InvalidKeyError("P-256 private key must be 64 hex characters");
+	const normalized = privateKeyHex.toLowerCase();
+	const ecdh = createECDH("prime256v1");
+	try {
+		ecdh.setPrivateKey(Buffer.from(normalized, "hex"));
+	} catch {
+		throw new InvalidKeyError("value is not a valid P-256 private key (scalar out of range)");
+	}
+	return {
+		algorithm: "p256",
+		privateKeyHex: normalized,
+		publicKeyHex: ecdh.getPublicKey("hex", "compressed")
+	};
+}
+function p256PointFromCompressedHex(publicKeyHex) {
+	try {
+		const uncompressed = ECDH.convertKey(publicKeyHex, "prime256v1", "hex", "hex", "uncompressed");
+		const point = Buffer.isBuffer(uncompressed) ? uncompressed : Buffer.from(uncompressed, "hex");
+		return point.length === 65 ? point : null;
+	} catch {
+		return null;
+	}
+}
+function computeP256PublicKeyThumbprint(publicKeyHex) {
+	const point = p256PointFromCompressedHex(publicKeyHex);
+	if (point === null) throw new InvalidKeyError("value is not a valid P-256 public key");
+	return p256PublicKeyThumbprintFromPoint(point);
+}
+function p256PublicKeyThumbprintFromPoint(point) {
+	const x = point.subarray(1, 33).toString("base64url");
+	const y = point.subarray(33, 65).toString("base64url");
+	return createHash("sha256").update(`{"crv":"P-256","kty":"EC","x":"${x}","y":"${y}"}`, "utf8").digest("base64url");
+}
+//#endregion
+export { InvalidKeyError, computeP256PublicKeyThumbprint, generateP256Keypair, p256KeypairFromPrivateKeyHex, p256PointFromCompressedHex, p256PublicKeyThumbprintFromPoint };

package/dist/mpp.d.mts

@@ -0,0 +1,315 @@
+import { A as IntentResult, i as FetchLike, n as CatenaClient } from "./client-Cm2wNUuB.mjs";
+import { Method, z } from "mppx";
+//#region src/mpp.d.ts
+declare const evmCharge: {
+  readonly name: "evm";
+  readonly intent: "charge";
+  readonly schema: {
+    credential: {
+      payload: z.ZodMiniObject<{
+        type: z.ZodMiniLiteral<"authorization">;
+        from: z.ZodMiniString<string>;
+        to: z.ZodMiniString<string>;
+        value: z.ZodMiniString<string>;
+        validAfter: z.ZodMiniString<string>;
+        validBefore: z.ZodMiniString<string>;
+        nonce: z.ZodMiniString<string>;
+        signature: z.ZodMiniString<string>;
+      }, z.core.$strip>;
+    };
+    request: z.ZodMiniObject<{
+      amount: z.ZodMiniString<string>;
+      currency: z.ZodMiniString<string>;
+      description: z.ZodMiniOptional<z.ZodMiniString<string>>;
+      externalId: z.ZodMiniOptional<z.ZodMiniString<string>>;
+      recipient: z.ZodMiniString<string>;
+      methodDetails: z.ZodMiniObject<{
+        chainId: z.ZodMiniNumber<number>;
+        credentialTypes: z.ZodMiniArray<z.ZodMiniLiteral<"authorization">>;
+        decimals: z.ZodMiniLiteral<6>;
+        permit2Address: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        splits: z.ZodMiniOptional<z.ZodMiniNever>;
+      }, z.core.$strip>;
+    }, z.core.$strip>;
+  };
+};
+declare const usdcCharge: {
+  readonly name: "usdc";
+  readonly intent: "charge";
+  readonly schema: {
+    credential: {
+      payload: z.ZodMiniObject<{
+        type: z.ZodMiniLiteral<"authorization">;
+        from: z.ZodMiniString<string>;
+        to: z.ZodMiniString<string>;
+        value: z.ZodMiniString<string>;
+        validAfter: z.ZodMiniString<string>;
+        validBefore: z.ZodMiniString<string>;
+        nonce: z.ZodMiniString<string>;
+        signature: z.ZodMiniString<string>;
+      }, z.core.$strip>;
+    };
+    request: z.ZodMiniObject<{
+      amount: z.ZodMiniString<string>;
+      currency: z.ZodMiniString<string>;
+      description: z.ZodMiniOptional<z.ZodMiniString<string>>;
+      externalId: z.ZodMiniOptional<z.ZodMiniString<string>>;
+      recipient: z.ZodMiniString<string>;
+      methodDetails: z.ZodMiniObject<{
+        type: z.ZodMiniLiteral<"evm">;
+        evm: z.ZodMiniObject<{
+          chainId: z.ZodMiniNumber<number>;
+          credentialTypes: z.ZodMiniOptional<z.ZodMiniArray<z.ZodMiniLiteral<"authorization">>>;
+          decimals: z.ZodMiniLiteral<6>;
+          permit2Address: z.ZodMiniOptional<z.ZodMiniString<string>>;
+          splits: z.ZodMiniOptional<z.ZodMiniNever>;
+        }, z.core.$strip>;
+      }, z.core.$strip>;
+    }, z.core.$strip>;
+  };
+};
+/**
+ * Parameters shared by both Catena MPP charge methods.
+ */
+interface CatenaMppParameters {
+  /**
+   * A linked Catena SDK client used to submit the payment intent.
+   */
+  readonly client: CatenaClient;
+  /**
+   * Catena account whose wallet will authorize the charge.
+   */
+  readonly accountId: string;
+  /**
+   * Price ceiling in atomic USDC units (6 decimals). Challenges asking for
+   * more are refused before any intent is created.
+   */
+  readonly maxAtomicAmount?: bigint;
+}
+/**
+ * Catena-backed `evm/charge` mppx client method.
+ */
+type CatenaEvmChargeMethod = Method.Client<typeof evmCharge>;
+/**
+ * Catena-backed `usdc/charge` mppx client method.
+ */
+type CatenaUsdcChargeMethod = Method.Client<typeof usdcCharge>;
+/**
+ * Both Catena methods registered by the factory.
+ */
+type CatenaMppMethods = readonly [CatenaEvmChargeMethod, CatenaUsdcChargeMethod];
+/**
+ * Callable Catena MPP factory, with the conventional charge alias.
+ */
+interface CatenaMppFactory {
+  (parameters: CatenaMppParameters): CatenaMppMethods;
+  charge(parameters: CatenaMppParameters): CatenaMppMethods;
+}
+/**
+ * Status of a Catena MPP intent that did not yield a usable credential.
+ */
+type MppPaymentStatus = IntentResult["status"];
+/**
+ * A Catena MPP intent completed without a usable credential or stopped in a
+ * non-completed state. Inspect `status` to choose a recovery path and
+ * `intentId` to reconcile the payment with `client.getIntent(intentId)`.
+ */
+declare class MppPaymentError extends Error {
+  readonly intentId: string;
+  readonly status: MppPaymentStatus;
+  readonly reasons: readonly string[];
+  readonly expiresAt: string | null;
+  constructor(message: string, details: {
+    readonly intentId: string;
+    readonly status: MppPaymentStatus;
+    readonly reasons: readonly string[];
+    readonly expiresAt: string | null;
+  });
+}
+/**
+ * Credential-free record of an MPP payment completed by the managed fetch
+ * wrapper.
+ */
+interface MppPaymentReceipt {
+  /**
+   * Catena intent that completed the payment.
+   */
+  readonly intentId: string;
+  /**
+   * Validated MPP method selected from the seller's challenge.
+   */
+  readonly method: "evm" | "usdc";
+  /**
+   * Paid amount in atomic USDC units (6 decimals).
+   */
+  readonly atomicAmount: string;
+  /**
+   * CAIP-2 network on which the payment was authorized.
+   */
+  readonly network: "eip155:8453" | "eip155:84532";
+  /**
+   * EVM address that received the payment authorization.
+   */
+  readonly recipient: string;
+  /**
+   * Canonical final URL of the resource that was paid.
+   */
+  readonly resourceUrl: string;
+}
+/**
+ * Base error for managed MPP negotiation failures. `intentId` is present only
+ * after Catena created an intent; `reasons` carries server recovery detail
+ * without exposing the payment credential.
+ */
+declare class MppFetchPaymentError extends Error {
+  /**
+   * Catena intent to reconcile, when one was created.
+   */
+  readonly intentId: string | undefined;
+  /**
+   * Stable recovery detail returned by Catena.
+   */
+  readonly reasons: readonly string[];
+  constructor(message: string, details?: {
+    readonly intentId?: string;
+    readonly reasons?: readonly string[];
+    readonly cause?: unknown;
+  });
+}
+/**
+ * None of the offered MPP networks can be funded by the selected account.
+ */
+declare class MppNetworkMismatchError extends MppFetchPaymentError {
+  /**
+   * Account that needs a wallet on one of the required networks.
+   */
+  readonly accountId: string;
+  /**
+   * Offered networks that Catena reported as mismatches.
+   */
+  readonly requiredNetworks: readonly ("eip155:8453" | "eip155:84532")[];
+  constructor(accountId: string, requiredNetworks: readonly ("eip155:8453" | "eip155:84532")[], reasons: readonly string[]);
+}
+/**
+ * The selected MPP recipient is not saved as a usable Catena counterparty
+ * rail.
+ */
+declare class MppCounterpartyNotFoundError extends MppFetchPaymentError {
+  /**
+   * Recipient address that must be added.
+   */
+  readonly recipient: string;
+  /**
+   * Network on which the recipient was offered.
+   */
+  readonly network: "eip155:8453" | "eip155:84532";
+  constructor(recipient: string, network: "eip155:8453" | "eip155:84532", reasons: readonly string[]);
+}
+/**
+ * The MPP payment is parked for human approval. Retry the original request
+ * after approval so a fresh challenge can consume the grant.
+ */
+declare class MppApprovalPendingError extends MppFetchPaymentError {
+  /**
+   * Time at which the pending approval expires, when supplied by Catena.
+   */
+  readonly expiresAt: string | null;
+  constructor(intentId: string, reasons: readonly string[], expiresAt: string | null);
+}
+/**
+ * Catena terminally blocked or failed the selected MPP payment.
+ */
+declare class MppPaymentDeclinedError extends MppFetchPaymentError {
+  /**
+   * Terminal intent disposition.
+   */
+  readonly status: "blocked" | "failed";
+  constructor(intentId: string, status: "blocked" | "failed", reasons: readonly string[]);
+}
+/**
+ * Submission failed where Catena may already have acted. Reconcile the intent
+ * before authorizing another payment.
+ */
+declare class MppSubmitInterruptedError extends MppFetchPaymentError {
+  /**
+   * Validated MPP method whose submission became ambiguous.
+   */
+  readonly method: "evm" | "usdc";
+  /**
+   * Potentially paid amount in atomic USDC units.
+   */
+  readonly atomicAmount: string;
+  /**
+   * Network on which submission may have occurred.
+   */
+  readonly network: "eip155:8453" | "eip155:84532";
+  /**
+   * Recipient whose payment may have been submitted.
+   */
+  readonly recipient: string;
+  /**
+   * Canonical resource URL bound to the ambiguous intent.
+   */
+  readonly resourceUrl: string;
+  constructor(intentId: string, terms: {
+    readonly method: "evm" | "usdc";
+    readonly atomicAmount: string;
+    readonly network: "eip155:8453" | "eip155:84532";
+    readonly recipient: string;
+  }, resourceUrl: string, cause: unknown);
+}
+/**
+ * Payment completed but `onPayment` or the single paid retry failed. The
+ * credential-free receipt identifies the settled intent for reconciliation.
+ */
+declare class MppRetryFailedError extends MppFetchPaymentError {
+  /**
+   * Completed payment that must not be paid a second time.
+   */
+  readonly receipt: MppPaymentReceipt;
+  constructor(receipt: MppPaymentReceipt, cause: unknown);
+}
+/**
+ * Options for the managed MPP fetch wrapper.
+ */
+interface MppFetchOptions {
+  /**
+   * Catena account whose wallet authorizes payments.
+   */
+  readonly accountId: string;
+  /**
+   * Custom fetch transport, defaulting to `globalThis.fetch`.
+   */
+  readonly baseFetch?: FetchLike;
+  /**
+   * Maximum acceptable price in atomic USDC units (6 decimals).
+   */
+  readonly maxAtomicAmount?: bigint;
+  /**
+   * Called once after payment completes and before the paid retry. The receipt
+   * deliberately excludes the MPP credential.
+   */
+  readonly onPayment?: (receipt: MppPaymentReceipt) => void | Promise<void>;
+}
+/**
+ * Create Catena-backed mppx charge methods for native USDC on Base and Base
+ * Sepolia. Pass the returned tuple directly in `Mppx.create({ methods: [...]
+ * })`.
+ */
+declare const catena: CatenaMppFactory;
+/**
+ * Wrap `fetch` with one managed MPP payment attempt. Ordinary responses and
+ * 402s without a decodable MPP challenge pass through unchanged. For a
+ * supported challenge, the wrapper binds the payment to the final same-origin
+ * resource URL, submits one Catena intent at a time, calls `onPayment`, and
+ * retries the original request exactly once through the configured Fetch
+ * transport with Mppx's credential transport.
+ *
+ * Stream and consumed `Request` bodies are rejected before payment because
+ * they cannot be replayed safely. Once an intent completes, continuation
+ * failures throw `MppRetryFailedError`; do not run the payment loop again
+ * without first reconciling that receipt's intent.
+ */
+declare function wrapFetchWithMppPayment(client: CatenaClient, options: MppFetchOptions): FetchLike;
+//#endregion
+export { CatenaEvmChargeMethod, CatenaMppFactory, CatenaMppMethods, CatenaMppParameters, CatenaUsdcChargeMethod, MppApprovalPendingError, MppCounterpartyNotFoundError, MppFetchOptions, MppFetchPaymentError, MppNetworkMismatchError, MppPaymentDeclinedError, MppPaymentError, MppPaymentReceipt, MppPaymentStatus, MppRetryFailedError, MppSubmitInterruptedError, catena, wrapFetchWithMppPayment };