@relai-fi/x402 0.6.5 → 0.6.7

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-export { B as BridgePluginConfig, D as DynamicPrice, j as FeedbackPluginConfig, F as FreeTierPluginConfig, M as MppServerHandler, b as PaymentInfo, g as PluginContext, h as PluginResult, P as ProtectOptions, R as Relai, d as RelaiIntegritasFlow, e as RelaiIntegritasOptions, f as RelaiPlugin, a as RelaiServerConfig, i as ScorePluginConfig, S as SettleResult, k as SolanaFeedbackPluginConfig, c as StripePayTo, R as default, s as stripePayTo } from './server-DaySqG5H.js';
+export { B as BridgePluginConfig, D as DynamicPrice, j as FeedbackPluginConfig, F as FreeTierPluginConfig, M as MppServerHandler, b as PaymentInfo, g as PluginContext, h as PluginResult, P as ProtectOptions, R as Relai, d as RelaiIntegritasFlow, e as RelaiIntegritasOptions, f as RelaiPlugin, a as RelaiServerConfig, i as ScorePluginConfig, S as SettleResult, k as SolanaFeedbackPluginConfig, c as StripePayTo, R as default, s as stripePayTo } from './server-D9ZfrFFx.js';
 export { MppHandler, RelayWebSocketFactory, RelayWebSocketLike, X402Client, X402ClientConfig, X402FetchInit, X402IntegritasConfig, X402IntegritasFlow, X402NetworkSelectionMode, X402RelayWsConfig, X402RelayWsError, X402RelayWsResponse, X402RequestOptions, default as createX402Client } from './client.js';
 export { RelayFeedbackConfig, submitRelayFeedback } from './relay-feedback.js';
-export { A as AcceptsExtra, B as BASE_MAINNET_NETWORK, C as CAIP2_TO_NETWORK, b as CHAIN_IDS, E as EXPLORER_TX_URL, l as EvmWallet, N as NETWORK_CAIP2, e as NETWORK_LABELS, d as NETWORK_TOKENS, c as NetworkToken, P as PaymentAccept, o as PaymentRequired, R as RELAI_FACILITATOR_URL, h as RELAI_NETWORKS, a as RelaiNetwork, m as ResourceInfo, S as SOLANA_MAINNET_NETWORK, k as SolanaWallet, U as USDC_ADDRESSES, g as USDC_BASE, f as USDC_SOLANA, W as WalletSet, j as isEvm, i as isSolana, n as normalizeNetwork, r as resolveToken } from './types-Y9ni5XwY.js';
+export { A as AcceptsExtra, B as BASE_MAINNET_NETWORK, C as CAIP2_TO_NETWORK, b as CHAIN_IDS, E as EXPLORER_TX_URL, l as EvmWallet, N as NETWORK_CAIP2, e as NETWORK_LABELS, d as NETWORK_TOKENS, c as NetworkToken, P as PaymentAccept, o as PaymentRequired, a as RELAI_FACILITATOR_URL, i as RELAI_NETWORKS, R as RelaiNetwork, m as ResourceInfo, f as SOLANA_MAINNET_NETWORK, S as SolanaWallet, U as USDC_ADDRESSES, h as USDC_BASE, g as USDC_SOLANA, W as WalletSet, k as isEvm, j as isSolana, n as normalizeNetwork, r as resolveToken } from './types-DjEveKgt.js';
 export { BridgeBalances, BridgeQuoteResult, BridgeResult } from './management.js';
 export { NETWORK_V1_TO_V2, NETWORK_V2_TO_V1, convertPayloadToVersion, convertV1ToV2, convertV2ToV1, detectPayloadVersion, formatUsd, fromAtomicUnits, isEvmNetwork, isSolanaNetwork, networkV1ToV2, networkV2ToV1, normalizePaymentHeader, toAtomicUnits } from './utils/index.js';
 export { charge as evmChargeMethod } from './mpp/evm-method.js';
@@ -15,32 +15,96 @@ import 'viem';
 /**
  * Payment Code API — BLIK-style x402 payment codes
  *
- * generatePaymentCode() — sign EIP-3009 authorization and register on SKALE L3
- * redeemPaymentCode()   — redeem a code (payee calls this, triggers Base L2 settlement)
- * getPaymentCode()      — check code status
+ * createPrivateKeySigner()    — create a signer from a raw private key (for agents/bots)
+ * generatePaymentCode()       — sign EIP-3009 authorization and register on SKALE L3
+ * generatePaymentCodesBatch() — register up to 20 codes in one call (agent budget)
+ * redeemPaymentCode()         — redeem a code (payee calls this, triggers Base L2 settlement)
+ * getPaymentCode()            — check code status
+ * cancelPaymentCode()         — cancel/revoke a code before redemption
  */
+type PaymentCodeNetwork = "base" | "base-sepolia" | "skale-base" | "skale-base-sepolia";
+interface NetworkConfig {
+    chainId: number;
+    usdc: string;
+    /** EIP-712 domain name of the USDC contract on this network */
+    domainName: string;
+    rpc: string;
+    settlementNetwork: string;
+}
+declare const NETWORK_CONFIGS: Record<PaymentCodeNetwork, NetworkConfig>;
+interface PaymentCodeSigner {
+    getAddress(): Promise<string>;
+    signTypedData(domain: object, types: object, value: object): Promise<string>;
+}
+/**
+ * Create an EIP-712 signer from a raw private key.
+ * Intended for agents/bots running server-side with a custodial wallet.
+ *
+ * @example
+ * const signer = createPrivateKeySigner(process.env.AGENT_PRIVATE_KEY!);
+ * const { code } = await generatePaymentCode(config, { signer, value: 1_000_000n });
+ */
+declare function createPrivateKeySigner(privateKey: string): PaymentCodeSigner;
 interface PaymentCodeConfig {
+    /** RelAI facilitator base URL (default: https://relai.fi/facilitator) */
     facilitatorUrl?: string;
 }
 interface GeneratePaymentCodeParams {
-    /** EIP-3009 signer — must implement signTypedData */
-    signer: {
-        getAddress(): Promise<string>;
-        signTypedData(domain: object, types: object, value: object): Promise<string>;
-    };
-    /** Payee wallet address */
-    to: string;
-    /** Amount in USDC micro-units (6 decimals), e.g. 1000 = $0.001 */
+    /** EIP-3009 signer — use createPrivateKeySigner() for agents */
+    signer: PaymentCodeSigner;
+    /** Settlement network (default: "base-sepolia") */
+    network?: PaymentCodeNetwork;
+    /** Amount in USDC micro-units (6 decimals), e.g. 1_000_000 = $1.00 */
     value: string | bigint;
-    /** USDC contract address on Base L2 (defaults to Base mainnet USDC) */
+    /** TTL in seconds (default: 86400 = 24 h) */
+    ttl?: number;
+    /** Optional message shown to the recipient when they claim */
+    description?: string;
+    /**
+     * Lock the code to a specific payee address — only that address can redeem it.
+     * Useful for agent-to-agent payments or scheduled disbursements.
+     */
+    payee?: string;
+    /** Override the USDC contract address */
     usdcContract?: string;
-    /** TTL in seconds (default: 120) */
+}
+interface BatchCodeItem {
+    /** Amount in USDC micro-units */
+    value: string | bigint;
+    /** TTL in seconds (default: 86400) */
     ttl?: number;
 }
+interface GeneratePaymentCodesBatchParams {
+    signer: PaymentCodeSigner;
+    /** Settlement network (default: "base-sepolia") */
+    network?: PaymentCodeNetwork;
+    /** Up to 20 codes to register */
+    codes: BatchCodeItem[];
+    /** Lock all codes to a specific payee */
+    payee?: string;
+    /** Override the USDC contract address */
+    usdcContract?: string;
+    /** RelAI auth token (required — batch endpoint is authenticated) */
+    authToken: string;
+}
 interface PaymentCode {
     code: string;
     validBefore: number;
     expiresIn: number;
+    relayerAddress: string;
+    settlementNetwork: string;
+    locked: boolean;
+    description?: string | null;
+}
+interface BatchPaymentCodesResult {
+    registered: number;
+    codes: Pick<PaymentCode, "code" | "validBefore" | "expiresIn" | "locked">[];
+    failed: {
+        index: number;
+        error: string;
+    }[];
+    relayerAddress: string;
+    settlementNetwork: string;
 }
 interface RedeemResult {
     success: boolean;
@@ -48,9 +112,17 @@ interface RedeemResult {
     l3TxHash: string;
     l2TxHash: string;
     explorerUrl: string;
+    settlementNetwork: string;
+    private: boolean;
     amount: string;
     from: string;
-    to: string;
+    payee: string;
+    /** Amount returned as change (µUSDC), present when invoiceAmount < code value */
+    change?: string;
+    /** How the change was returned: 'code' = new payment code, 'wallet' = sent to from address */
+    changeMode?: 'code' | 'wallet';
+    /** New payment code for the change amount (present when changeMode === 'code') */
+    changeCode?: string;
 }
 interface CodeStatus {
     code: string;
@@ -61,31 +133,220 @@ interface CodeStatus {
     redeemed: boolean;
     expired: boolean;
     redeemable: boolean;
+    settlementNetwork: string | null;
+    description: string | null;
 }
 /**
- * Generate a BLIK-style x402 payment code backed by EIP-3009.
+ * Generate a BLIK-style x402 payment code backed by an EIP-3009 authorization.
+ * The facilitator registers it on SKALE L3 — no gas cost for the payer.
+ * The `to` address (settler/relayer) is fetched automatically from the facilitator.
+ *
+ * @example Agent usage (Node.js / server-side):
+ * ```ts
+ * import { createPrivateKeySigner, generatePaymentCode } from '@relai-fi/x402';
+ *
+ * const signer = createPrivateKeySigner(process.env.AGENT_PRIVATE_KEY!);
+ * const { code } = await generatePaymentCode(
+ *   { facilitatorUrl: 'https://relai.fi/facilitator' },
+ *   { signer, value: 1_000_000n, ttl: 3600, description: 'coffee' },
+ * );
+ * // code = "X7K9P2AB" — share with the payee, e.g. via SMS / email / QR
+ * ```
+ */
+declare function generatePaymentCode(config: PaymentCodeConfig, params: GeneratePaymentCodeParams): Promise<PaymentCode>;
+/**
+ * Generate multiple payment codes in one call — agent budget allocation pattern.
+ * Each code is independently signed. Max 20 codes per call.
+ * Requires a valid RelAI `authToken`.
  *
  * @example
- * const { code } = await generatePaymentCode(config, {
- *   signer: walletClient,
- *   to: "0xMerchant...",
- *   value: "1000",  // $0.001 USDC
- *   ttl: 120,
+ * ```ts
+ * const { codes } = await generatePaymentCodesBatch(config, {
+ *   signer,
+ *   authToken: process.env.RELAI_API_KEY!,
+ *   codes: Array(10).fill({ value: 1_000_000n, ttl: 3600 }),  // 10 × $1.00
  * });
- * // code = "X7K9P2AB"
+ * // codes[0].code = "X7K9P2AB", codes[1].code = "B3R5N7QA", …
+ * ```
  */
-declare function generatePaymentCode(config: PaymentCodeConfig, params: GeneratePaymentCodeParams): Promise<PaymentCode>;
+declare function generatePaymentCodesBatch(config: PaymentCodeConfig, params: GeneratePaymentCodesBatchParams): Promise<BatchPaymentCodesResult>;
 /**
- * Redeem a payment code. Triggers Base L2 settlement via relayer.
+ * Redeem a payment code. Triggers USDC settlement on Base L2 or SKALE.
+ * No wallet connection needed on the payee side — just provide a destination address.
  *
  * @example
- * const result = await redeemPaymentCode(config, "X7K9P2AB");
- * // result.l2TxHash = "0x..."
+ * ```ts
+ * const result = await redeemPaymentCode(config, "X7K9P2AB", "0xYourWallet...");
+ * console.log(result.explorerUrl); // https://sepolia.basescan.org/tx/0x...
+ * ```
  */
-declare function redeemPaymentCode(config: PaymentCodeConfig, code: string): Promise<RedeemResult>;
+declare function redeemPaymentCode(config: PaymentCodeConfig, code: string, 
+/** Address to receive the USDC (required unless code was registered with a locked payee) */
+payee?: string): Promise<RedeemResult>;
 /**
- * Get the status of a payment code.
+ * Get the current status of a payment code.
  */
 declare function getPaymentCode(config: PaymentCodeConfig, code: string): Promise<CodeStatus>;
+/**
+ * Cancel a payment code before it is redeemed.
+ * Soft-cancels immediately (relayer will refuse to settle);
+ * also attempts a hard-cancel on SKALE L3 to mark it used on-chain.
+ */
+declare function cancelPaymentCode(config: PaymentCodeConfig, code: string): Promise<{
+    success: boolean;
+    l3TxHash: string | null;
+}>;
+
+/**
+ * Payment Request API — Merchant-initiated x402 payment codes
+ *
+ * Flow (reverse of payment-codes):
+ *   1. Merchant calls createPayRequest() → gets a short code
+ *   2. Merchant shares the code with the buyer (QR, link, message)
+ *   3. Buyer calls getPayRequest() → sees amount, merchant, description
+ *   4. Buyer calls payPayRequest() with their signer → USDC sent directly to merchant
+ *
+ * createPayRequest()  — merchant creates a payment request (no signature needed)
+ * getPayRequest()     — buyer reads request details (amount, merchant, description)
+ * payPayRequest()     — buyer signs EIP-3009 and submits payment
+ */
+
+interface PaymentRequestConfig {
+    /** RelAI facilitator base URL (default: https://relai.fi/facilitator) */
+    facilitatorUrl?: string;
+}
+interface CreatePayRequestParams {
+    /** Merchant wallet address — receives the USDC */
+    to: string;
+    /** Amount in USDC micro-units (6 decimals), e.g. 1_000_000 = $1.00 */
+    amount: number | bigint;
+    /** Settlement network (default: "base-sepolia") */
+    network?: PaymentCodeNetwork;
+    /** Payment description shown to the buyer, e.g. "Coffee ☕" */
+    description?: string;
+    /** Code TTL in seconds (min 60, max 86400, default 3600) */
+    ttlSeconds?: number;
+}
+interface PayRequest {
+    /** 8-character alphanumeric code, e.g. "X7K9P2AB" */
+    code: string;
+    /** Unix timestamp when the request expires */
+    validUntil: number;
+    /** Address the buyer must use as EIP-3009 `to` (settler/relayer, NOT merchant directly) */
+    toAddress: string;
+    /** USDC contract on the settlement network */
+    usdcContract: string;
+}
+interface PayRequestInfo {
+    code: string;
+    /** Merchant wallet address */
+    to: string;
+    /** EIP-3009 `to` address (settler/relayer) */
+    toAddress: string;
+    amount: number;
+    network: string;
+    usdcContract: string;
+    description: string | null;
+    validUntil: number;
+    expiresIn: number;
+    status: "pending" | "processing" | "paid";
+    payable: boolean;
+}
+interface PayRequestResult {
+    success: boolean;
+    code: string;
+    payTxHash: string | null;
+    explorerUrl?: string;
+    network?: string;
+    private?: boolean;
+    amount?: string;
+    /** Merchant address that received the USDC */
+    to?: string;
+}
+/**
+ * Create a payment request — merchant/seller side.
+ * No signing required. Returns a short code to share with the buyer.
+ *
+ * @example Merchant/agent creates a $5 invoice:
+ * ```ts
+ * const req = await createPayRequest(config, {
+ *   to:          '0xMerchantWallet...',
+ *   amount:      5_000_000,   // $5.00 USDC
+ *   network:     'base-sepolia',
+ *   description: 'Order #1234 — 2× coffee',
+ *   ttlSeconds:  900,         // 15 minutes
+ * });
+ * // req.code = "X7K9P2AB" — share via QR / link / message
+ * // link: https://relai.fi/pay#X7K9P2AB
+ * ```
+ */
+declare function createPayRequest(config: PaymentRequestConfig, params: CreatePayRequestParams): Promise<PayRequest>;
+/**
+ * Get the status and details of a payment request — buyer side.
+ *
+ * @example
+ * ```ts
+ * const info = await getPayRequest(config, 'X7K9P2AB');
+ * console.log(`Pay $${info.amount / 1e6} to ${info.to}`);
+ * console.log('Description:', info.description);
+ * console.log('Payable:', info.payable);
+ * ```
+ */
+declare function getPayRequest(config: PaymentRequestConfig, code: string): Promise<PayRequestInfo>;
+/**
+ * Pay a payment request — buyer side.
+ * Signs an EIP-3009 authorization and submits it to the facilitator,
+ * which executes the on-chain transfer to the merchant.
+ *
+ * @example Buyer pays using a private key (agent):
+ * ```ts
+ * import { createPrivateKeySigner } from '@relai-fi/x402';
+ *
+ * const signer = createPrivateKeySigner(process.env.BUYER_PRIVATE_KEY!);
+ * const result = await payPayRequest(config, 'X7K9P2AB', signer);
+ * console.log('Paid! Explorer:', result.explorerUrl);
+ * ```
+ */
+declare function payPayRequest(config: PaymentRequestConfig, code: string, signer: PaymentCodeSigner): Promise<PayRequestResult>;
+/**
+ * Pay a merchant's payment request using a pre-generated payment code.
+ * The buyer already holds a BLIK-style code (created via generatePaymentCode) —
+ * instead of signing on the spot, they redeem that code and USDC goes to the merchant.
+ *
+ * The payment code must have enough value to cover the request amount.
+ * If the code was created without a locked payee, the merchant address is set at redemption time.
+ *
+ * @example
+ * ```ts
+ * // Merchant shares their invoice code: "SHOP1234"
+ * // Buyer has a pre-generated payment code: "MYBLIK78"
+ * const result = await payPayRequestWithCode(config, 'SHOP1234', 'MYBLIK78');
+ * console.log('Paid! Explorer:', result.explorerUrl);
+ * ```
+ */
+interface PayPayRequestWithCodeOptions {
+    /**
+     * How to return the change when the payment code value exceeds the invoice amount.
+     * - `'code'` (default) — relayer pays the merchant, then generates a new payment
+     *    code for the remainder and returns it as `result.changeCode`. Works even when
+     *    the buyer has no wallet (pure code-based flow).
+     * - `'wallet'` — uses `settler.settleExact()` on-chain: merchant receives exact
+     *    invoice amount, surplus is returned atomically to the buyer's wallet (`from`).
+     *    Requires the payment code was created with `to = settler` (atomic mode).
+     *
+     * Set `allowOverpayment: false` to throw instead of handling the difference.
+     */
+    returnChange?: 'code' | 'wallet';
+    /**
+     * If false, throws when code value ≠ invoice amount (strict match).
+     * Default: true — difference is handled per `returnChange`.
+     */
+    allowOverpayment?: boolean;
+}
+declare function payPayRequestWithCode(config: PaymentRequestConfig, 
+/** The merchant's payment request code */
+requestCode: string, 
+/** The buyer's pre-generated BLIK-style payment code */
+paymentCode: string, options?: PayPayRequestWithCodeOptions): Promise<RedeemResult>;
 
-export { type CodeStatus, type GeneratePaymentCodeParams, type PaymentCode, type PaymentCodeConfig, type RedeemResult, generatePaymentCode, getPaymentCode, redeemPaymentCode };
+export { type BatchCodeItem, type BatchPaymentCodesResult, type CodeStatus, type CreatePayRequestParams, type GeneratePaymentCodeParams, type GeneratePaymentCodesBatchParams, NETWORK_CONFIGS, type NetworkConfig, type PayPayRequestWithCodeOptions, type PayRequest, type PayRequestInfo, type PayRequestResult, type PaymentCode, type PaymentCodeConfig, type PaymentCodeNetwork, type PaymentCodeSigner, type PaymentRequestConfig, type RedeemResult, cancelPaymentCode, createPayRequest, createPrivateKeySigner, generatePaymentCode, generatePaymentCodesBatch, getPayRequest, getPaymentCode, payPayRequest, payPayRequestWithCode, redeemPaymentCode };