@mixrpay/merchant-sdk 0.1.1 → 0.3.0

package/dist/index.d.mts

@@ -1,49 +1,5 @@
-import { V as VerifyOptions, X as X402PaymentResult, a as VerifyReceiptOptions, P as PaymentReceipt } from './types-BJNy6Hhb.mjs';
-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.mjs';
-export { default as expressX402 } from './middleware/express.mjs';
-export { createPaymentRequired, withX402 } from './middleware/nextjs.mjs';
-export { x402 as fastifyX402, x402Plugin } from './middleware/fastify.mjs';
-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;
-}>;
+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
@@ -88,115 +44,7 @@ declare function parseX402Payment(paymentHeader: string, chainId?: number): Prom
  * ```
  */
 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;
@@ -213,50 +61,6 @@ interface SessionGrant {
     /** 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.
  *
@@ -272,20 +76,214 @@ declare class ChargesClient {
  * ```
  */
 declare function verifySessionWebhook(payload: string, signature: string, secret: string): boolean;
+
 /**
- * Parse a session.granted webhook payload.
+ * 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 />
+ * ```
  */
-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 };
+// =============================================================================
+// 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 };