@mixrpay/merchant-sdk 0.2.0 → 0.3.0

package/dist/index.d.mts

@@ -0,0 +1,289 @@
+import { V as VerifyReceiptOptions, P as PaymentReceipt } from './types-jelXkTp9.mjs';
+export { M as MixrPayOptions, a as MixrPayPaymentResult, b as PaymentMethod, c as PriceContext } from './types-jelXkTp9.mjs';
+
+/**
+ * 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>;
+
+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;
+}
+/**
+ * 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;
+
+/**
+ * MixrPay Widget Custom Element Type Declarations
+ * 
+ * These types enable TypeScript support for MixrPay widget custom elements
+ * in JSX/TSX files.
+ * 
+ * Usage in your app:
+ * ```typescript
+ * // Option 1: Import for side effects (recommended)
+ * import '@mixrpay/merchant-sdk/widget-elements';
+ * 
+ * // Option 2: Reference directly
+ * /// <reference types="@mixrpay/merchant-sdk/widget-elements" />
+ * ```
+ * 
+ * Now these work without TypeScript errors:
+ * ```tsx
+ * <mixr-balance data-theme="dark" />
+ * <mixr-wallet />
+ * ```
+ */
+
+// =============================================================================
+// Widget Attribute Types
+// =============================================================================
+
+interface MixrWidgetAttributes {
+  /** Theme for the widget - 'dark' or 'light' */
+  'data-theme'?: 'dark' | 'light';
+  /** Additional class names */
+  class?: string;
+  className?: string;
+}
+
+interface MixrBalanceAttributes extends MixrWidgetAttributes {
+  // Balance-specific attributes (currently none beyond base)
+}
+
+interface MixrWalletAttributes extends MixrWidgetAttributes {
+  // Wallet-specific attributes (currently none beyond base)
+}
+
+// =============================================================================
+// Global State Types
+// =============================================================================
+
+/**
+ * State object returned by window.Mixr.getState()
+ */
+interface MixrState {
+  /** User's balance in minor units (bigint) */
+  balance: bigint;
+  /** User's balance in USD */
+  balanceUsd: number;
+  /** Currency code (e.g., 'USD') */
+  currency: string;
+  /** Whether the user is authenticated */
+  isAuthenticated: boolean;
+  /** Whether the user has completed onboarding */
+  isOnboarded: boolean;
+  /** User's wallet address (null if not authenticated) */
+  walletAddress: string | null;
+  /** Whether the widget is loading */
+  loading: boolean;
+  /** Error message if any */
+  error: string | null;
+}
+
+// =============================================================================
+// Global API Types
+// =============================================================================
+
+/**
+ * MixrPay global API available on window.Mixr
+ */
+interface MixrAPI {
+  /** Initialize the widget (called automatically on load) */
+  init(): void;
+  
+  /** 
+   * Open the wallet popup
+   * @param tab - Optional tab to open: 'add_funds', 'send', 'receive', 'sessions'
+   */
+  openWallet(tab?: 'add_funds' | 'send' | 'receive' | 'sessions'): void;
+  
+  /** Get current widget state */
+  getState(): MixrState;
+  
+  /** Refresh user balance and state */
+  refresh(): Promise<void>;
+  
+  /**
+   * Programmatically charge a user
+   * @param feature - Feature slug to charge for
+   * @param priceUsd - Price in USD as string (e.g., "0.25")
+   * @param element - The element that triggered the charge (for UI feedback)
+   */
+  charge(feature: string, priceUsd: string, element: HTMLElement): Promise<void>;
+}
+
+// =============================================================================
+// Event Detail Types
+// =============================================================================
+
+interface MixrChargeSuccessDetail {
+  /** The feature that was charged */
+  feature: string;
+  /** The price that was charged */
+  price: string;
+  /** Unique charge ID */
+  chargeId?: string;
+}
+
+interface MixrChargeErrorDetail {
+  /** Error message */
+  error: string;
+  /** The feature that failed to charge */
+  feature?: string;
+}
+
+interface MixrLowBalanceDetail {
+  /** Current balance */
+  balance: number;
+  /** Required amount */
+  required: number;
+}
+
+interface MixrStateUpdatedDetail extends MixrState {}
+
+interface MixrFundingDetail {
+  /** Amount funded */
+  amount: number;
+  /** Transaction hash if available */
+  txHash?: string;
+}
+
+interface MixrTransactionDetail {
+  /** Transaction hash */
+  txHash: string;
+  /** Amount transferred */
+  amount: number;
+}
+
+// =============================================================================
+// Custom Events Map
+// =============================================================================
+
+/**
+ * MixrPay custom events that can be listened to via addEventListener
+ * 
+ * @example
+ * ```typescript
+ * window.addEventListener('mixr:charge-success', (e) => {
+ *   console.log('Charged:', e.detail.feature, e.detail.price);
+ * });
+ * ```
+ */
+interface MixrEventMap {
+  'mixr:charge-success': CustomEvent<MixrChargeSuccessDetail>;
+  'mixr:charge-error': CustomEvent<MixrChargeErrorDetail>;
+  'mixr:low-balance': CustomEvent<MixrLowBalanceDetail>;
+  'mixr:state-updated': CustomEvent<MixrStateUpdatedDetail>;
+  'mixr:funding': CustomEvent<MixrFundingDetail>;
+  'mixr:transaction': CustomEvent<MixrTransactionDetail>;
+}
+
+// =============================================================================
+// Global Augmentations
+// =============================================================================
+
+declare global {
+  interface Window {
+    /** MixrPay global API */
+    Mixr: MixrAPI;
+  }
+
+  interface WindowEventMap extends MixrEventMap {}
+
+  namespace JSX {
+    interface IntrinsicElements {
+      /**
+       * MixrPay balance display component
+       * 
+       * @example
+       * ```tsx
+       * <mixr-balance data-theme="dark" />
+       * ```
+       */
+      'mixr-balance': React.DetailedHTMLProps<
+        React.HTMLAttributes<HTMLElement> & MixrBalanceAttributes,
+        HTMLElement
+      >;
+      
+      /**
+       * MixrPay wallet widget component
+       * 
+       * @example
+       * ```tsx
+       * <mixr-wallet data-theme="dark" />
+       * ```
+       */
+      'mixr-wallet': React.DetailedHTMLProps<
+        React.HTMLAttributes<HTMLElement> & MixrWalletAttributes,
+        HTMLElement
+      >;
+    }
+  }
+}
+
+export { PaymentReceipt, type SessionGrant, verifyPaymentReceipt, verifySessionWebhook };

package/dist/index.d.ts

@@ -0,0 +1,289 @@
+import { V as VerifyReceiptOptions, P as PaymentReceipt } from './types-jelXkTp9.js';
+export { M as MixrPayOptions, a as MixrPayPaymentResult, b as PaymentMethod, c as PriceContext } from './types-jelXkTp9.js';
+
+/**
+ * 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>;
+
+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;
+}
+/**
+ * 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;
+
+/**
+ * MixrPay Widget Custom Element Type Declarations
+ * 
+ * These types enable TypeScript support for MixrPay widget custom elements
+ * in JSX/TSX files.
+ * 
+ * Usage in your app:
+ * ```typescript
+ * // Option 1: Import for side effects (recommended)
+ * import '@mixrpay/merchant-sdk/widget-elements';
+ * 
+ * // Option 2: Reference directly
+ * /// <reference types="@mixrpay/merchant-sdk/widget-elements" />
+ * ```
+ * 
+ * Now these work without TypeScript errors:
+ * ```tsx
+ * <mixr-balance data-theme="dark" />
+ * <mixr-wallet />
+ * ```
+ */
+
+// =============================================================================
+// Widget Attribute Types
+// =============================================================================
+
+interface MixrWidgetAttributes {
+  /** Theme for the widget - 'dark' or 'light' */
+  'data-theme'?: 'dark' | 'light';
+  /** Additional class names */
+  class?: string;
+  className?: string;
+}
+
+interface MixrBalanceAttributes extends MixrWidgetAttributes {
+  // Balance-specific attributes (currently none beyond base)
+}
+
+interface MixrWalletAttributes extends MixrWidgetAttributes {
+  // Wallet-specific attributes (currently none beyond base)
+}
+
+// =============================================================================
+// Global State Types
+// =============================================================================
+
+/**
+ * State object returned by window.Mixr.getState()
+ */
+interface MixrState {
+  /** User's balance in minor units (bigint) */
+  balance: bigint;
+  /** User's balance in USD */
+  balanceUsd: number;
+  /** Currency code (e.g., 'USD') */
+  currency: string;
+  /** Whether the user is authenticated */
+  isAuthenticated: boolean;
+  /** Whether the user has completed onboarding */
+  isOnboarded: boolean;
+  /** User's wallet address (null if not authenticated) */
+  walletAddress: string | null;
+  /** Whether the widget is loading */
+  loading: boolean;
+  /** Error message if any */
+  error: string | null;
+}
+
+// =============================================================================
+// Global API Types
+// =============================================================================
+
+/**
+ * MixrPay global API available on window.Mixr
+ */
+interface MixrAPI {
+  /** Initialize the widget (called automatically on load) */
+  init(): void;
+  
+  /** 
+   * Open the wallet popup
+   * @param tab - Optional tab to open: 'add_funds', 'send', 'receive', 'sessions'
+   */
+  openWallet(tab?: 'add_funds' | 'send' | 'receive' | 'sessions'): void;
+  
+  /** Get current widget state */
+  getState(): MixrState;
+  
+  /** Refresh user balance and state */
+  refresh(): Promise<void>;
+  
+  /**
+   * Programmatically charge a user
+   * @param feature - Feature slug to charge for
+   * @param priceUsd - Price in USD as string (e.g., "0.25")
+   * @param element - The element that triggered the charge (for UI feedback)
+   */
+  charge(feature: string, priceUsd: string, element: HTMLElement): Promise<void>;
+}
+
+// =============================================================================
+// Event Detail Types
+// =============================================================================
+
+interface MixrChargeSuccessDetail {
+  /** The feature that was charged */
+  feature: string;
+  /** The price that was charged */
+  price: string;
+  /** Unique charge ID */
+  chargeId?: string;
+}
+
+interface MixrChargeErrorDetail {
+  /** Error message */
+  error: string;
+  /** The feature that failed to charge */
+  feature?: string;
+}
+
+interface MixrLowBalanceDetail {
+  /** Current balance */
+  balance: number;
+  /** Required amount */
+  required: number;
+}
+
+interface MixrStateUpdatedDetail extends MixrState {}
+
+interface MixrFundingDetail {
+  /** Amount funded */
+  amount: number;
+  /** Transaction hash if available */
+  txHash?: string;
+}
+
+interface MixrTransactionDetail {
+  /** Transaction hash */
+  txHash: string;
+  /** Amount transferred */
+  amount: number;
+}
+
+// =============================================================================
+// Custom Events Map
+// =============================================================================
+
+/**
+ * MixrPay custom events that can be listened to via addEventListener
+ * 
+ * @example
+ * ```typescript
+ * window.addEventListener('mixr:charge-success', (e) => {
+ *   console.log('Charged:', e.detail.feature, e.detail.price);
+ * });
+ * ```
+ */
+interface MixrEventMap {
+  'mixr:charge-success': CustomEvent<MixrChargeSuccessDetail>;
+  'mixr:charge-error': CustomEvent<MixrChargeErrorDetail>;
+  'mixr:low-balance': CustomEvent<MixrLowBalanceDetail>;
+  'mixr:state-updated': CustomEvent<MixrStateUpdatedDetail>;
+  'mixr:funding': CustomEvent<MixrFundingDetail>;
+  'mixr:transaction': CustomEvent<MixrTransactionDetail>;
+}
+
+// =============================================================================
+// Global Augmentations
+// =============================================================================
+
+declare global {
+  interface Window {
+    /** MixrPay global API */
+    Mixr: MixrAPI;
+  }
+
+  interface WindowEventMap extends MixrEventMap {}
+
+  namespace JSX {
+    interface IntrinsicElements {
+      /**
+       * MixrPay balance display component
+       * 
+       * @example
+       * ```tsx
+       * <mixr-balance data-theme="dark" />
+       * ```
+       */
+      'mixr-balance': React.DetailedHTMLProps<
+        React.HTMLAttributes<HTMLElement> & MixrBalanceAttributes,
+        HTMLElement
+      >;
+      
+      /**
+       * MixrPay wallet widget component
+       * 
+       * @example
+       * ```tsx
+       * <mixr-wallet data-theme="dark" />
+       * ```
+       */
+      'mixr-wallet': React.DetailedHTMLProps<
+        React.HTMLAttributes<HTMLElement> & MixrWalletAttributes,
+        HTMLElement
+      >;
+    }
+  }
+}
+
+export { PaymentReceipt, type SessionGrant, verifyPaymentReceipt, verifySessionWebhook };