@mixrpay/merchant-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,291 @@
+import { V as VerifyOptions, X as X402PaymentResult, a as VerifyReceiptOptions, P as PaymentReceipt } from './types-BJNy6Hhb.js';
+export { E as EIP712Domain, e as PriceContext, R as ReceiptMode, S as SkipContext, T as TransferWithAuthorizationMessage, b as X402Options, d as X402PaymentPayload, c as X402PaymentRequired } from './types-BJNy6Hhb.js';
+export { default as expressX402 } from './middleware/express.js';
+export { createPaymentRequired, withX402 } from './middleware/nextjs.js';
+export { x402 as fastifyX402, x402Plugin } from './middleware/fastify.js';
+import 'express';
+import 'next/server';
+import 'fastify';
+
+/**
+ * MixrPay Merchant SDK - Payment Verification
+ */
+
+/**
+ * Verify an X-PAYMENT header and optionally settle the payment.
+ *
+ * @param paymentHeader - The X-PAYMENT header value (base64 encoded JSON)
+ * @param options - Verification options
+ * @returns Payment verification result
+ *
+ * @example
+ * ```typescript
+ * const result = await verifyX402Payment(req.headers['x-payment'], {
+ *   expectedAmount: 50000n, // 0.05 USDC
+ *   expectedRecipient: '0x...',
+ * });
+ *
+ * if (result.valid) {
+ *   console.log(`Payment from ${result.payer}: $${result.amount}`);
+ * }
+ * ```
+ */
+declare function verifyX402Payment(paymentHeader: string, options: VerifyOptions): Promise<X402PaymentResult>;
+/**
+ * Parse and validate an X-PAYMENT header without settlement.
+ * Useful for checking if a payment is structurally valid before processing.
+ */
+declare function parseX402Payment(paymentHeader: string, chainId?: number): Promise<{
+    valid: boolean;
+    error?: string;
+    payer?: string;
+    recipient?: string;
+    amount?: number;
+    amountMinor?: bigint;
+    expiresAt?: Date;
+}>;
+
+/**
+ * MixrPay Merchant SDK - Payment Receipt Verification
+ *
+ * Verify JWT payment receipts issued by MixrPay after successful x402 payments.
+ *
+ * @example
+ * ```typescript
+ * import { verifyPaymentReceipt } from '@mixrpay/merchant-sdk';
+ *
+ * const receipt = req.headers['x-payment-receipt'];
+ * const payment = await verifyPaymentReceipt(receipt);
+ *
+ * console.log(`Payment received: $${payment.amountUsd} from ${payment.payer}`);
+ * console.log(`Transaction: ${payment.txHash}`);
+ * ```
+ */
+
+/**
+ * Verify a JWT payment receipt from MixrPay.
+ *
+ * This function:
+ * 1. Fetches the JWKS from MixrPay (cached for 1 hour)
+ * 2. Verifies the JWT signature using RS256
+ * 3. Validates standard JWT claims (exp, iat)
+ * 4. Returns the typed payment receipt
+ *
+ * @param receipt - The JWT receipt string from X-Payment-Receipt header
+ * @param options - Optional configuration (custom JWKS URL, issuer validation)
+ * @returns Verified payment receipt
+ * @throws Error if verification fails
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const payment = await verifyPaymentReceipt(receipt);
+ *
+ * // With custom JWKS URL (for testing or self-hosted)
+ * const payment = await verifyPaymentReceipt(receipt, {
+ *   jwksUrl: 'https://your-mixrpay.com/.well-known/jwks'
+ * });
+ * ```
+ */
+declare function verifyPaymentReceipt(receipt: string, options?: VerifyReceiptOptions): Promise<PaymentReceipt>;
+/**
+ * Parse a JWT payment receipt without verification.
+ *
+ * WARNING: This does NOT verify the signature. Use only for debugging
+ * or when you've already verified the receipt elsewhere.
+ *
+ * @param receipt - The JWT receipt string
+ * @returns Decoded payload (unverified)
+ */
+declare function parsePaymentReceipt(receipt: string): PaymentReceipt;
+/**
+ * Check if a receipt is expired.
+ *
+ * @param receipt - The JWT receipt string or parsed PaymentReceipt
+ * @returns true if expired, false otherwise
+ */
+declare function isReceiptExpired(receipt: string | PaymentReceipt): boolean;
+/**
+ * Clear the JWKS cache.
+ * Useful for testing or when keys have rotated.
+ */
+declare function clearJWKSCache(): void;
+/**
+ * Get the default JWKS URL.
+ */
+declare function getDefaultJWKSUrl(): string;
+
+/**
+ * MixrPay Merchant SDK - Utilities
+ */
+
+declare const USDC_CONTRACTS: Record<number, `0x${string}`>;
+declare const DEFAULT_FACILITATOR = "https://x402.org/facilitator";
+/**
+ * Convert USD dollars to USDC minor units (6 decimals)
+ */
+declare function usdToMinor(usd: number): bigint;
+/**
+ * Convert USDC minor units to USD dollars
+ */
+declare function minorToUsd(minor: bigint): number;
+/**
+ * Generate a random nonce for x402 payments
+ */
+declare function generateNonce(): `0x${string}`;
+/**
+ * Check if an address is valid
+ */
+declare function isValidAddress(address: string): address is `0x${string}`;
+/**
+ * Normalize an address to lowercase checksum format
+ */
+declare function normalizeAddress(address: string): `0x${string}`;
+
+/**
+ * MixrPay Charges Module
+ *
+ * Create and manage charges using session signers.
+ * Session signers allow you to charge user wallets without
+ * requiring approval for each transaction.
+ */
+interface CreateChargeParams {
+    /** Session key ID granted by the user */
+    sessionId: string;
+    /** Amount to charge in USD (e.g., 0.05 for 5 cents) */
+    amountUsd: number;
+    /** Unique reference for idempotency (e.g., "order_123") */
+    reference: string;
+    /** Optional metadata */
+    metadata?: Record<string, unknown>;
+}
+interface Charge {
+    /** Unique charge ID */
+    id: string;
+    /** Current status */
+    status: 'pending' | 'submitted' | 'confirmed' | 'failed';
+    /** Amount in USD */
+    amountUsd: number;
+    /** Formatted USDC amount */
+    amountUsdc: string;
+    /** Transaction hash (if submitted) */
+    txHash?: string;
+    /** Block explorer URL */
+    explorerUrl?: string;
+    /** From wallet address */
+    fromAddress: string;
+    /** To wallet address */
+    toAddress: string;
+    /** Your reference */
+    reference: string;
+    /** When the charge was created */
+    createdAt: string;
+    /** When the charge was confirmed */
+    confirmedAt?: string;
+    /** Session name */
+    sessionName?: string;
+    /** User wallet address */
+    userWallet?: string;
+    /** Error message if failed */
+    error?: string;
+}
+interface CreateChargeResult {
+    success: boolean;
+    charge?: Charge;
+    /** True if this is a replay of an existing charge */
+    idempotentReplay?: boolean;
+    error?: string;
+    details?: string;
+}
+interface SessionGrant {
+    /** Session key ID */
+    sessionId: string;
+    /** User's wallet address */
+    userWallet: string;
+    /** Your merchant wallet address */
+    merchantWallet: string;
+    /** Spending limits */
+    limits: {
+        maxTotalUsd?: number;
+        maxPerTxUsd?: number;
+        expiresAt: string;
+    };
+    /** When the session was granted */
+    grantedAt: string;
+}
+interface ChargesClientOptions {
+    /** Your API key */
+    apiKey: string;
+    /** MixrPay API base URL */
+    baseUrl?: string;
+}
+declare class ChargesClient {
+    private apiKey;
+    private baseUrl;
+    constructor(options: ChargesClientOptions);
+    /**
+     * Create a new charge.
+     *
+     * @example
+     * ```typescript
+     * const result = await charges.create({
+     *   sessionId: 'sk_xxx',
+     *   amountUsd: 0.05,
+     *   reference: 'image_gen_123',
+     *   metadata: { feature: 'image_generation' }
+     * });
+     *
+     * if (result.success) {
+     *   console.log(`Charged ${result.charge.amountUsdc}`);
+     *   console.log(`TX: ${result.charge.explorerUrl}`);
+     * }
+     * ```
+     */
+    create(params: CreateChargeParams): Promise<CreateChargeResult>;
+    /**
+     * Get a charge by ID.
+     *
+     * @example
+     * ```typescript
+     * const charge = await charges.get('chg_xxx');
+     * console.log(charge.status); // 'confirmed'
+     * ```
+     */
+    get(chargeId: string): Promise<Charge | null>;
+    /**
+     * Get a charge by transaction hash.
+     */
+    getByTxHash(txHash: string): Promise<Charge | null>;
+}
+/**
+ * Verify a session.granted webhook signature.
+ *
+ * @example
+ * ```typescript
+ * const payload = req.body;
+ * const signature = req.headers['x-mixrpay-signature'];
+ *
+ * if (verifySessionWebhook(JSON.stringify(payload), signature, webhookSecret)) {
+ *   const grant = parseSessionGrant(payload);
+ *   console.log(`User ${grant.userWallet} granted access`);
+ * }
+ * ```
+ */
+declare function verifySessionWebhook(payload: string, signature: string, secret: string): boolean;
+/**
+ * Parse a session.granted webhook payload.
+ */
+declare function parseSessionGrant(payload: {
+    event: string;
+    session_id: string;
+    user_wallet: string;
+    merchant_wallet: string;
+    limits: {
+        max_total_usd?: number;
+        max_per_tx_usd?: number;
+        expires_at: string;
+    };
+    granted_at: string;
+}): SessionGrant;
+
+export { type Charge, ChargesClient, type ChargesClientOptions, type CreateChargeParams, type CreateChargeResult, DEFAULT_FACILITATOR, PaymentReceipt, type SessionGrant, USDC_CONTRACTS, VerifyOptions, VerifyReceiptOptions, X402PaymentResult, clearJWKSCache, generateNonce, getDefaultJWKSUrl, isReceiptExpired, isValidAddress, minorToUsd, normalizeAddress, parsePaymentReceipt, parseSessionGrant, parseX402Payment, usdToMinor, verifyPaymentReceipt, verifySessionWebhook, verifyX402Payment };