@w3payments/common 1.1.0

package/dist/index.d.ts

@@ -0,0 +1,641 @@
+/**
+ * Apply theme to container element
+ */
+export declare function applyTheme(themeInput: W3ThemeInput, container: HTMLElement): void;
+
+/**
+ * Currency Types
+ *
+ * Clean currency type definitions using discriminated unions.
+ */
+/**
+ * Base currency properties shared by all currencies
+ */
+export declare type BaseCurrency = {
+    /** Currency code (e.g., 'BTC', 'USD', 'USDC') */
+    code: string;
+    /** Display name (e.g., 'Bitcoin', 'US Dollar') */
+    name: string;
+    /** Currency symbol for display (e.g., '₿', '$') */
+    symbol: string;
+    /** Number of decimal places */
+    decimals: number;
+    /** Icon URL */
+    iconUrl?: string;
+    /** Description */
+    description?: string;
+    /** Whether actively supported */
+    isActive?: boolean;
+};
+
+/**
+ * Payment Method Types
+ *
+ * Minimal payment method definitions for current support:
+ * - Fiat: ACH only
+ * - Crypto: Wallet and Exchange (with network + currency)
+ */
+/**
+ * Base payment method properties shared by all methods
+ */
+export declare type BasePaymentMethod = {
+    /** Unique identifier (e.g., 'ach-meshpay', 'wallet-usdc-eth-ironpay') */
+    id: string;
+    /** Display name (e.g., 'ACH via MeshPay', 'USDC Wallet (Ethereum) via IronPay') */
+    name: string;
+    /** Vendor that provides this payment method */
+    vendorId: string;
+    /** Description of the payment method */
+    description?: string;
+    /** Supported currency codes */
+    supportedCurrencies: string[];
+    /** Supported regions (if empty, assume all regions supported) */
+    regions?: string[];
+    /** Fee structure (if undefined, no fees) */
+    fees?: {
+        percentage?: number;
+        fixed?: number;
+        currency?: string;
+    };
+    /** Transaction limits (if undefined, no limits) */
+    limits?: {
+        min?: number;
+        max?: number;
+        currency?: string;
+    };
+    /** Processing time (if undefined, assume instant) */
+    processingTime?: string;
+    /** Whether this method is currently active */
+    isActive: boolean;
+};
+
+/**
+ * Checkout session created by vendor adapter
+ */
+export declare interface CheckoutSession {
+    /** Unique session identifier */
+    id: string;
+    /** Checkout URL for client to open (optional - some vendors use tokens instead) */
+    url?: string;
+    /** Session expiration timestamp (optional) */
+    expiresAt?: string;
+    /** Additional vendor-specific metadata */
+    metadata?: Record<string, any>;
+}
+
+export declare type CreatePaymentOptions = {
+    /** Unique payment intent ID */
+    id: string;
+    /** Amount in base currency units */
+    amount: number;
+    /** Currency code */
+    currency: string;
+    /** Customer ID */
+    customerId: string;
+    /** Destination addresses for crypto payments */
+    destinations: Array<{
+        address: string;
+        networkId: string;
+        symbol: string;
+    }>;
+    /** Optional vendor preference (if not provided, core will select best) */
+    preferredVendor?: string;
+    /** Optional metadata */
+    metadata?: Record<string, any>;
+};
+
+/**
+ * Cryptocurrency variant
+ */
+export declare type CryptoCurrency = BaseCurrency & {
+    type: 'crypto';
+    /** Network this currency runs on */
+    network: string;
+    /** Contract address for tokens */
+    contractAddress?: string;
+    /** Whether this is a stablecoin */
+    isStablecoin?: boolean;
+};
+
+/**
+ * Crypto destination for payments
+ */
+export declare interface CryptoDestination {
+    /** Blockchain network ID */
+    networkId: string;
+    /** Token symbol */
+    symbol: string;
+    /** Destination address */
+    address: string;
+    /** Optional amount for this destination */
+    amount?: number;
+    /** Optional percentage split for this destination */
+    percentage?: number;
+}
+
+/**
+ * Crypto payment method - wallet and exchange with network + currency
+ */
+export declare type CryptoPaymentMethod = BasePaymentMethod & {
+    type: 'crypto';
+    method: 'wallet' | 'exchange';
+    /** Blockchain network (e.g., 'ethereum', 'solana', 'bitcoin') */
+    network: string;
+    /** Specific currency/token (e.g., 'USDC', 'BTC', 'ETH') */
+    currency: string;
+};
+
+/**
+ * W3 Payments Theme System
+ *
+ * Stripe-style appearance API for simple, powerful theming
+ * Framework-agnostic - works with React, Vue, vanilla JS, etc.
+ */
+/**
+ * CSS properties type (framework-agnostic)
+ * Simple record of CSS properties - allows any property name and value
+ */
+export declare interface CSSStyleProperties {
+    [property: string]: string | number | undefined;
+}
+
+export declare const CURRENCIES: Record<string, Currency>;
+
+/**
+ * Currency union type - can be either crypto or fiat
+ */
+export declare type Currency = CryptoCurrency | FiatCurrency;
+
+/**
+ * Currency service for managing currency registration and lookup
+ */
+declare class CurrencyService {
+    private static instance;
+    private currencies;
+    private supportedCurrencies;
+    private constructor();
+    static getInstance(): CurrencyService;
+    /**
+     * Register a new currency
+     */
+    register(currency: Currency): void;
+    /**
+     * Register multiple currencies
+     */
+    registerMany(currencies: Currency[]): void;
+    /**
+     * Get currency by code
+     */
+    getCurrency(code: string): Currency | undefined;
+    /**
+     * Get all registered currencies
+     */
+    getAllCurrencies(): Currency[];
+    /**
+     * Check if currency exists
+     */
+    hasCurrency(code: string): boolean;
+    /**
+     * Get currency icon URL
+     */
+    getCurrencyIcon(code: string): string;
+    /**
+     * Get cryptocurrencies only
+     */
+    getCryptoCurrencies(): CryptoCurrency[];
+    /**
+     * Get fiat currencies only
+     */
+    getFiatCurrencies(): FiatCurrency[];
+    /**
+     * Get stablecoins only
+     */
+    getStablecoins(): CryptoCurrency[];
+    /**
+     * Get currencies by network
+     */
+    getCurrenciesByNetwork(networkId: string): CryptoCurrency[];
+    /**
+     * Search currencies by code or name
+     */
+    searchCurrencies(query: string): Currency[];
+    /**
+     * Add currency to supported list for environment
+     */
+    addSupportedCurrency(code: string, environment: Environment): void;
+    /**
+     * Get supported currencies for environment
+     */
+    getSupportedCurrencies(environment: Environment): string[];
+    /**
+     * Check if currency is supported in environment
+     */
+    isCurrencySupported(code: string, environment: Environment): boolean;
+    /**
+     * Clear all currencies (useful for testing)
+     */
+    clear(): void;
+}
+
+/**
+ * Default currency service instance
+ */
+export declare const currencyService: CurrencyService;
+
+/**
+ * Environment Types
+ *
+ * Common environment definitions used across services.
+ */
+/**
+ * Application environment types
+ */
+export declare type Environment = 'sandbox' | 'production';
+
+/**
+ * Fiat currency variant
+ */
+export declare type FiatCurrency = BaseCurrency & {
+    type: 'fiat';
+    /** ISO country code */
+    countryCode: string;
+};
+
+/**
+ * Fiat payment method - ACH only for now
+ */
+export declare type FiatPaymentMethod = BasePaymentMethod & {
+    type: 'fiat';
+    method: 'ach';
+};
+
+export declare function getCurrencyIcon(code: string): string | undefined;
+
+export declare function getExchangeIcon(exchange: string): string | undefined;
+
+export declare function getFiatIcon(method: string): string | undefined;
+
+/**
+ * Network Types
+ *
+ * Blockchain network definitions for crypto currencies.
+ */
+/**
+ * Blockchain network definition
+ */
+export declare type Network = {
+    /** Network identifier (e.g., 'ethereum', 'bitcoin') */
+    id: string;
+    /** Display name (e.g., 'Ethereum', 'Bitcoin') */
+    name: string;
+    /** Network symbol (e.g., 'ETH', 'BTC') */
+    symbol: string;
+    /** Whether this is a testnet */
+    isTestnet?: boolean;
+    /** Chain ID for EVM networks */
+    chainId?: number;
+};
+
+export declare const NETWORKS: Record<string, Network>;
+
+/**
+ * Network service for managing blockchain network registration and lookup
+ */
+declare class NetworkService {
+    private static instance;
+    private networks;
+    private constructor();
+    static getInstance(): NetworkService;
+    /**
+     * Register a new network
+     */
+    register(network: Network): void;
+    /**
+     * Register multiple networks
+     */
+    registerMany(networks: Network[]): void;
+    /**
+     * Get network by ID
+     */
+    getNetwork(id: string): Network | undefined;
+    /**
+     * Get all registered networks
+     */
+    getAllNetworks(): Network[];
+    /**
+     * Check if network exists
+     */
+    hasNetwork(id: string): boolean;
+    /**
+     * Get mainnet networks only
+     */
+    getMainnetNetworks(): Network[];
+    /**
+     * Get testnet networks only
+     */
+    getTestnetNetworks(): Network[];
+    /**
+     * Clear all networks (useful for testing)
+     */
+    clear(): void;
+}
+
+/**
+ * Default network service instance
+ */
+export declare const networkService: NetworkService;
+
+export declare type PaymentClientOptions = {
+    /** Payment configuration - adapters auto-discovered from config keys */
+    config: PaymentConfig;
+    /** Optional environment override */
+    environment?: 'sandbox' | 'production';
+    /** Optional timeout settings */
+    timeout?: {
+        /** Timeout for payment creation (ms) */
+        create?: number;
+        /** Timeout for payment confirmation (ms) */
+        confirm?: number;
+        /** Timeout for status checks (ms) */
+        status?: number;
+    };
+};
+
+/**
+ * Vendor Configuration Types
+ *
+ * Generic vendor configuration interface that adapters can extend
+ * for their specific needs while maintaining vendor-agnostic core types.
+ */
+/**
+ * Payment system configuration
+ */
+export declare interface PaymentConfig {
+    /** Global environment and vendor-specific configurations */
+    [key: string]: any;
+}
+
+/**
+ * Payment intent - represents the intent to collect a payment
+ */
+export declare interface PaymentIntent {
+    /** Unique payment intent ID */
+    id: string;
+    /** Payment amount in the smallest currency unit */
+    amount: number;
+    /** Currency code */
+    currency: string;
+    /** Crypto destinations for the payment */
+    destinations: CryptoDestination[];
+    /** Customer ID */
+    customerId: string;
+    /** Payment method ID to use */
+    paymentMethodId?: string;
+    /** Order/transaction ID */
+    orderId?: string;
+    /** Return URL after payment */
+    returnUrl?: string;
+    /** Additional metadata */
+    metadata?: Record<string, any>;
+}
+
+/**
+ * Payment method union type
+ */
+export declare type PaymentMethod = FiatPaymentMethod | CryptoPaymentMethod;
+
+/**
+ * Payment method service for managing payment method registration and lookup
+ */
+export declare class PaymentMethodService {
+    private static instance;
+    private paymentMethods;
+    private constructor();
+    static getInstance(): PaymentMethodService;
+    /**
+     * Register a new payment method
+     */
+    register(method: PaymentMethod): void;
+    /**
+     * Register multiple payment methods
+     */
+    registerMany(methods: PaymentMethod[]): void;
+    /**
+     * Get payment method by ID
+     */
+    getPaymentMethod(id: string): PaymentMethod | undefined;
+    /**
+     * Get all registered payment methods
+     */
+    getAllPaymentMethods(): PaymentMethod[];
+    /**
+     * Check if payment method exists
+     */
+    hasPaymentMethod(id: string): boolean;
+    /**
+     * Get payment methods by vendor
+     */
+    getByVendor(vendorId: string): PaymentMethod[];
+    /**
+     * Get payment methods by method type (ach, wallet, exchange)
+     */
+    getByMethod(methodType: string): PaymentMethod[];
+    /**
+     * Get payment methods by type (fiat or crypto)
+     */
+    getByType(type: 'fiat' | 'crypto'): PaymentMethod[];
+    /**
+     * Get fiat payment methods only
+     */
+    getFiatPaymentMethods(): FiatPaymentMethod[];
+    /**
+     * Get crypto payment methods only
+     */
+    getCryptoPaymentMethods(): CryptoPaymentMethod[];
+    /**
+     * Get payment methods by currency
+     */
+    getByCurrency(currencyCode: string): PaymentMethod[];
+    /**
+     * Get crypto payment methods by network
+     */
+    getByNetwork(networkId: string): CryptoPaymentMethod[];
+    /**
+     * Get crypto payment methods by network and currency combination
+     */
+    getByNetworkAndCurrency(networkId: string, currencyCode: string): CryptoPaymentMethod[];
+    /**
+     * Get payment methods by region
+     */
+    getByRegion(region: string): PaymentMethod[];
+    /**
+     * Get active payment methods only
+     */
+    getActive(): PaymentMethod[];
+    /**
+     * Get available payment methods for currency and region
+     */
+    getAvailableFor(currencyCode: string, region?: string): PaymentMethod[];
+    /**
+     * Search payment methods by name or description
+     */
+    searchPaymentMethods(query: string): PaymentMethod[];
+    /**
+     * Get wallet payment methods with optional currency and target filters
+     */
+    getWalletMethods(filters?: {
+        currencies?: string[];
+        targetCurrency?: string;
+        targetNetwork?: string;
+    }): CryptoPaymentMethod[];
+    /**
+     * Get exchange payment methods with optional exchange and target filters
+     */
+    getExchangeMethods(filters?: {
+        exchanges?: string[];
+        targetCurrency?: string;
+    }): CryptoPaymentMethod[];
+    /**
+     * Get fiat payment methods with optional method type filter
+     */
+    getFiatMethods(filters?: {
+        methods?: string[];
+    }): FiatPaymentMethod[];
+    /**
+     * Get simple display options from filter values
+     */
+    getDisplayOptions(filters?: {
+        walletFilter?: string[];
+        exchangeFilter?: string[];
+        fiatFilter?: string[];
+        targetCurrency?: string;
+        targetNetwork?: string;
+    }): Array<{
+        id: string;
+        displayName: string;
+        method: string;
+    }>;
+    /**
+     * Clear all payment methods (useful for testing)
+     */
+    clear(): void;
+}
+
+/**
+ * Default payment method service instance
+ */
+export declare const paymentMethodService: PaymentMethodService;
+
+/**
+ * Payment result from vendor
+ */
+export declare interface PaymentResult {
+    /** Payment ID from vendor */
+    id: string;
+    /** Payment status */
+    status: PaymentStatus;
+    /** Payment URL if applicable */
+    url?: string;
+    /** Additional result data */
+    data?: Record<string, any>;
+}
+
+/**
+ * Payment Types
+ *
+ * Core payment-related types for payment processing.
+ */
+/**
+ * Payment status types
+ */
+export declare type PaymentStatus = 'pending' | 'processing' | 'completed' | 'failed' | 'cancelled';
+
+/**
+ * Standard vendor adapter interface
+ */
+export declare interface VendorAdapter {
+    /** Unique adapter identifier */
+    readonly id: string;
+    /** Human-readable adapter name */
+    readonly name: string;
+    /**
+     * Initialize the adapter with configuration
+     */
+    initialize(config: PaymentConfig): Promise<void>;
+    /**
+     * Register onramp payment methods this adapter supports
+     */
+    registerOnrampMethods(paymentMethodService: PaymentMethodService): void;
+    /**
+     * Create checkout session for onramp payment
+     */
+    createCheckoutSession(intent: PaymentIntent): Promise<CheckoutSession>;
+    /**
+     * Open checkout UI for client-side payment flow (optional)
+     * Uses session data returned from createCheckoutSession
+     */
+    openCheckout?(session: CheckoutSession): Promise<PaymentResult>;
+    /**
+     * Get payment status
+     */
+    getPaymentStatus(sessionId: string): Promise<PaymentResult>;
+}
+
+/**
+ * Complete theme configuration (Stripe-style)
+ */
+export declare interface W3Theme {
+    /** Named theme preset */
+    theme?: 'light' | 'dark' | string;
+    /** Design token overrides */
+    variables?: W3ThemeVariables;
+    /** Component-level style rules */
+    rules?: W3ThemeRules;
+}
+
+/**
+ * Theme input - can be just a string for named themes or full config
+ */
+export declare type W3ThemeInput = string | W3Theme;
+
+/**
+ * Component-level style overrides
+ * Record of CSS selectors to style properties
+ */
+export declare type W3ThemeRules = Record<string, CSSStyleProperties>;
+
+/**
+ * Design token variables for common customizations
+ */
+export declare interface W3ThemeVariables {
+    /** Primary brand color */
+    colorPrimary?: string;
+    /** Primary color on hover/focus */
+    colorPrimaryHover?: string;
+    /** Light variant of primary color */
+    colorPrimaryLight?: string;
+    /** Background color */
+    colorBackground?: string;
+    /** Primary text color */
+    colorText?: string;
+    /** Secondary/muted text color */
+    colorTextMuted?: string;
+    /** Border color */
+    colorBorder?: string;
+    /** Light border color */
+    colorBorderLight?: string;
+    /** Error/danger color */
+    colorDanger?: string;
+    /** Success color */
+    colorSuccess?: string;
+    /** Font family */
+    fontFamily?: string;
+    /** Base font size */
+    fontSize?: string;
+    /** Border radius */
+    borderRadius?: string;
+    /** Base spacing unit */
+    spacing?: string;
+}
+
+export { }