@moneymq/sdk 0.3.1 → 0.5.0

package/dist/index.d.ts

@@ -1,3 +1,40 @@
+import { Signer } from 'x402-fetch';
+export { Signer } from 'x402-fetch';
+
+/** Payment requirements returned when payment is required (402) */
+interface PaymentRequirements {
+    scheme: string;
+    network: string;
+    max_amount_required: string;
+    resource: string;
+    description: string;
+    mime_type: string;
+    pay_to: string;
+    max_timeout_seconds: number;
+    asset: string;
+    extra?: {
+        feePayer?: string;
+        product?: string;
+    };
+}
+/** Error thrown when payment is required to access a resource */
+declare class PaymentRequiredError extends Error {
+    readonly paymentRequirements: PaymentRequirements[];
+    readonly raw: unknown;
+    constructor(message: string, paymentRequirements: PaymentRequirements[], raw: unknown);
+}
+/** Response from product access endpoint */
+interface ProductAccessResponse {
+    object: 'product_access';
+    product_id: string;
+    access_granted: boolean;
+    message: string;
+}
+/** Parameters for accessing a product with x402 payment */
+interface ProductAccessParams {
+    /** Base64-encoded X-Payment header value */
+    paymentHeader?: string;
+}
 interface Product {
     id: string;
     object: 'product';
@@ -7,6 +44,8 @@ interface Product {
     metadata?: Record<string, string>;
     created: number;
     updated: number;
+    /** URL path for accessing this product (x402 gated) */
+    accessUrl: string;
 }
 interface ProductCreateParams {
     name: string;
@@ -74,6 +113,32 @@ declare class ProductsAPI {
     delete(id: string): Promise<{
         deleted: boolean;
     }>;
+    /**
+     * Access a product - gated by x402 payment
+     *
+     * This endpoint requires payment. If no payment header is provided (or payment is invalid),
+     * throws a PaymentRequiredError with the payment requirements.
+     *
+     * @example
+     * ```ts
+     * try {
+     *   // First attempt without payment - will throw PaymentRequiredError
+     *   const access = await moneymq.catalog.products.access('surfnet-max');
+     * } catch (error) {
+     *   if (error instanceof PaymentRequiredError) {
+     *     // Get payment requirements and create payment
+     *     const requirements = error.paymentRequirements[0];
+     *     const paymentHeader = await createPayment(requirements);
+     *
+     *     // Retry with payment
+     *     const access = await moneymq.catalog.products.access('surfnet-max', {
+     *       paymentHeader,
+     *     });
+     *   }
+     * }
+     * ```
+     */
+    access(id: string, params?: ProductAccessParams): Promise<ProductAccessResponse>;
 }
 declare class PricesAPI {
     private config;
@@ -167,6 +232,60 @@ interface PaymentListParams {
     limit?: number;
     startingAfter?: string;
 }
+interface PayParams {
+    /** Amount in smallest currency unit (e.g., cents for USD) */
+    amount: number;
+    /** Currency code (e.g., 'usd', 'usdc') */
+    currency: string;
+    /** Product name for display */
+    productName: string;
+    /** Product ID for tracking */
+    productId?: string;
+    /** Optional product description */
+    description?: string;
+    /** Customer wallet address */
+    customer?: string;
+    /** Additional metadata */
+    metadata?: Record<string, string>;
+}
+interface PayResult {
+    /** Checkout session ID */
+    sessionId: string;
+    /** Payment intent ID */
+    paymentIntentId: string;
+    /** Client secret for confirming payment */
+    clientSecret: string;
+    /** Total amount in smallest currency unit */
+    amount: number;
+    /** Currency */
+    currency: string;
+    /** Status */
+    status: 'requires_confirmation' | 'succeeded' | 'failed';
+}
+interface PaymentIntent {
+    id: string;
+    object: 'payment_intent';
+    amount: number;
+    currency: string;
+    status: 'requires_payment_method' | 'requires_confirmation' | 'processing' | 'succeeded' | 'canceled';
+    customer?: string;
+    description?: string;
+    metadata: Record<string, string>;
+    clientSecret?: string;
+    created: number;
+}
+interface PaymentIntentCreateParams {
+    /** Amount in smallest currency unit */
+    amount: number;
+    /** Currency code */
+    currency: string;
+    /** Customer wallet address */
+    customer?: string;
+    /** Description */
+    description?: string;
+    /** Metadata including product info */
+    metadata?: Record<string, string>;
+}
 interface Customer {
     id: string;
     object: 'customer';
@@ -319,13 +438,41 @@ declare class WebhooksAPI {
         success: boolean;
     }>;
 }
+/**
+ * Payment Intents API - for direct payments without full checkout flow
+ * Similar to Stripe's Payment Intents API
+ */
+declare class PaymentIntentsAPI {
+    private request;
+    constructor(config: MoneyMQConfig);
+    /**
+     * Create a payment intent
+     * Use this for simple payments without the full checkout session flow
+     */
+    create(params: PaymentIntentCreateParams): Promise<PaymentIntent>;
+    /**
+     * Retrieve a payment intent
+     */
+    retrieve(id: string): Promise<PaymentIntent>;
+    /**
+     * Confirm a payment intent
+     * This triggers the actual payment (and x402 flow if required)
+     */
+    confirm(id: string): Promise<PaymentIntent>;
+    /**
+     * Cancel a payment intent
+     */
+    cancel(id: string): Promise<PaymentIntent>;
+}
 /**
  * Payment API for checkout, links, customers, and payouts
  */
 declare class PaymentAPI {
     private request;
-    /** Checkout sessions API */
+    /** Checkout sessions API - for full e-commerce flows with line items */
     readonly checkout: CheckoutAPI;
+    /** Payment intents API - for simpler direct payments */
+    readonly intents: PaymentIntentsAPI;
     /** Payment links API */
     readonly links: LinksAPI;
     /** Customers API */
@@ -335,6 +482,21 @@ declare class PaymentAPI {
     /** Webhooks API */
     readonly webhooks: WebhooksAPI;
     constructor(config: MoneyMQConfig);
+    /**
+     * Simple one-liner payment - creates a checkout session with inline product data
+     *
+     * @example
+     * ```ts
+     * const result = await moneymq.payment.pay({
+     *   amount: 999,
+     *   currency: 'usd',
+     *   productName: 'Pro Plan',
+     *   productId: 'pro-plan',
+     *   customer: 'wallet_address',
+     * });
+     * ```
+     */
+    pay(params: PayParams): Promise<PayResult>;
     /**
      * Retrieve a payment by ID
      */
@@ -348,6 +510,154 @@ declare class PaymentAPI {
     }>;
 }
 
+/**
+ * MoneyMQ server configuration returned from /config endpoint
+ */
+interface ServerConfig {
+    account: {
+        name: string;
+        description: string;
+    };
+    x402: {
+        payoutAccount: {
+            currency: string;
+            decimals: number;
+            address: string;
+            tokenAddress: string;
+        };
+        facilitator: {
+            operatorAccount: {
+                out: string;
+                in: {
+                    currency: string;
+                    decimals: number;
+                    address: string;
+                    tokenAddress: string;
+                };
+            };
+            url: string;
+        };
+        validator: {
+            network: string;
+            rpcUrl: string;
+            bindHost: string;
+            rpcPort: number;
+            wsPort: number;
+        };
+    };
+}
+/**
+ * Fetch server configuration from MoneyMQ API
+ *
+ * @param apiUrl - The MoneyMQ API URL
+ * @returns Server configuration including RPC URL
+ *
+ * @example
+ * ```typescript
+ * const config = await fetchConfig('http://localhost:8488');
+ * console.log(config.x402.validator.rpcUrl);
+ * ```
+ */
+declare function fetchConfig(apiUrl: string): Promise<ServerConfig>;
+/**
+ * Get the Solana RPC URL from server config
+ *
+ * @param apiUrl - The MoneyMQ API URL
+ * @param fallback - Fallback RPC URL if fetch fails
+ * @returns RPC URL string
+ */
+declare function getRpcUrl(apiUrl: string, fallback?: string): Promise<string>;
+
+/**
+ * Parameters for getting a signer by tag
+ */
+interface GetSignerParams {
+    /**
+     * Tag/label identifying the sandbox wallet account
+     * @example 'alice', 'bob', 'agent-1'
+     */
+    tag: string;
+}
+
+/**
+ * X402 configuration compatible with x402-fetch wrapFetchWithPayment
+ */
+interface X402ClientConfig {
+    svmConfig?: {
+        rpcUrl: string;
+    };
+}
+/**
+ * X402 API for agentic payments
+ *
+ * @example
+ * ```typescript
+ * import { wrapFetchWithPayment } from 'x402-fetch';
+ *
+ * const moneymq = new MoneyMQ({
+ *   endpoint: 'http://localhost:8488',
+ * });
+ *
+ * // Get signer for sandbox account by label
+ * const payer = await moneymq.x402.getSigner({ tag: 'alice' });
+ *
+ * // Get x402 config for the fetch wrapper
+ * const config = await moneymq.x402.getConfig();
+ *
+ * // Create the payment-enabled fetch
+ * const fetchWithPayment = wrapFetchWithPayment(
+ *   fetch,
+ *   payer,
+ *   undefined,
+ *   undefined,
+ *   config,
+ * );
+ *
+ * // Make requests that automatically handle 402 payments
+ * const response = await fetchWithPayment(url, { method: 'GET' });
+ * ```
+ */
+declare class X402API {
+    private config;
+    private serverConfig;
+    private sandboxAccounts;
+    constructor(config: MoneyMQConfig);
+    /**
+     * Fetch sandbox accounts from the server
+     */
+    private fetchSandboxAccounts;
+    /**
+     * Get a signer for a sandbox account by tag/label
+     *
+     * @param params - Parameters containing the wallet tag/label
+     * @returns A Signer that can be used directly with wrapFetchWithPayment
+     *
+     * @example
+     * ```typescript
+     * const payer = await moneymq.x402.getSigner({ tag: 'alice' });
+     * ```
+     */
+    getSigner(params: GetSignerParams): Promise<Signer>;
+    /**
+     * Get x402 configuration for use with wrapFetchWithPayment
+     *
+     * @returns Configuration object compatible with x402-fetch
+     *
+     * @example
+     * ```typescript
+     * const config = await moneymq.x402.getConfig();
+     * const fetchWithPayment = wrapFetchWithPayment(fetch, payer, undefined, undefined, config);
+     * ```
+     */
+    getConfig(): Promise<X402ClientConfig>;
+    /**
+     * Get the full server configuration
+     *
+     * @returns The complete server configuration including x402 settings
+     */
+    getServerConfig(): Promise<ServerConfig>;
+}
+
 /**
  * Configuration options for the MoneyMQ client
  *
@@ -408,6 +718,10 @@ declare class MoneyMQ {
     readonly catalog: CatalogAPI;
     /** Payment API for checkout, links, customers, and payouts */
     readonly payment: PaymentAPI;
+    /** X402 API for agentic payments */
+    readonly x402: X402API;
+    /** MoneyMQ API endpoint */
+    get endpoint(): string;
     constructor(config: MoneyMQConfig);
     /**
      * Make an authenticated request to the MoneyMQ API
@@ -415,62 +729,4 @@ declare class MoneyMQ {
     request<T>(method: 'GET' | 'POST' | 'PUT' | 'DELETE', path: string, body?: unknown): Promise<T>;
 }
 
-/**
- * MoneyMQ server configuration returned from /config endpoint
- */
-interface ServerConfig {
-    account: {
-        name: string;
-        description: string;
-    };
-    x402: {
-        payoutAccount: {
-            currency: string;
-            decimals: number;
-            address: string;
-            tokenAddress: string;
-        };
-        facilitator: {
-            operatorAccount: {
-                out: string;
-                in: {
-                    currency: string;
-                    decimals: number;
-                    address: string;
-                    tokenAddress: string;
-                };
-            };
-            url: string;
-        };
-        validator: {
-            network: string;
-            rpcUrl: string;
-            bindHost: string;
-            rpcPort: number;
-            wsPort: number;
-        };
-    };
-}
-/**
- * Fetch server configuration from MoneyMQ API
- *
- * @param apiUrl - The MoneyMQ API URL
- * @returns Server configuration including RPC URL
- *
- * @example
- * ```typescript
- * const config = await fetchConfig('http://localhost:8488');
- * console.log(config.x402.validator.rpcUrl);
- * ```
- */
-declare function fetchConfig(apiUrl: string): Promise<ServerConfig>;
-/**
- * Get the Solana RPC URL from server config
- *
- * @param apiUrl - The MoneyMQ API URL
- * @param fallback - Fallback RPC URL if fetch fails
- * @returns RPC URL string
- */
-declare function getRpcUrl(apiUrl: string, fallback?: string): Promise<string>;
-
-export { type CheckoutCreateParams, type CheckoutSession, type Customer, type CustomerCreateParams, type CustomerUpdateParams, MoneyMQ, type MoneyMQConfig, type Payment, type PaymentLink, type PaymentLinkCreateParams, type PaymentListParams, type Payout, type PayoutCreateParams, type PayoutListParams, type PayoutSettings, type PayoutSettingsUpdateParams, type Price, type PriceCreateParams, type Product, type ProductCreateParams, type ProductListParams, type ServerConfig, fetchConfig, getRpcUrl };
+export { type CheckoutCreateParams, type CheckoutSession, type Customer, type CustomerCreateParams, type CustomerUpdateParams, type GetSignerParams, MoneyMQ, type MoneyMQConfig, type PayParams, type PayResult, type Payment, type PaymentIntent, type PaymentIntentCreateParams, type PaymentLink, type PaymentLinkCreateParams, type PaymentListParams, PaymentRequiredError, type PaymentRequirements, type Payout, type PayoutCreateParams, type PayoutListParams, type PayoutSettings, type PayoutSettingsUpdateParams, type Price, type PriceCreateParams, type Product, type ProductAccessParams, type ProductAccessResponse, type ProductCreateParams, type ProductListParams, type ServerConfig, type X402ClientConfig, fetchConfig, getRpcUrl };