@w3payments/common

Foundation package providing shared types, utilities, and theming system for the W3 Payments Platform. This package serves as the core dependency for all other W3 Payments packages.

Installation

npm install @w3payments/common

Key Features

• Complete TypeScript definitions for payment processing
• W3Appearance theming system (Stripe Elements-inspired)
• Currency and network registries with metadata
• QR code generation utilities for payment links
• Icon management system for currencies and exchanges
• Payment method services for resolution and filtering

🎨 W3Appearance Theming System

The centerpiece of this package is the W3Appearance API - a comprehensive theming system that provides consistent styling across all W3 Payments components.

Core Concept

The theming system uses 16 carefully chosen variables that cover all essential styling needs:

interface W3Appearance {
  variables?: {
    // Colors (8 variables)
    primary?: string;          // Brand color, buttons, highlights
    background?: string;       // Main background color
    text?: string;            // Primary text color
    textSecondary?: string;   // Secondary text, labels, hints
    danger?: string;          // Error states, warnings
    success?: string;         // Success states, confirmations
    warning?: string;         // Warning states, cautions
    border?: string;          // Borders, dividers, outlines
    
    // Typography (5 variables)
    fontFamily?: string;       // Base font family
    fontSizeBase?: string;     // Standard text size (14px)
    fontSizeSmall?: string;    // Small text size (12px)  
    fontSizeLarge?: string;    // Large text size (32px)
    fontWeightNormal?: string; // Normal font weight (400)
    
    // Layout (3 variables)
    spacingUnit?: string;      // Base spacing unit (4px)
    borderRadius?: string;     // Standard border radius (8px)
    buttonRadius?: string;     // Button border radius (6px)
  };
}

Built-in Themes

Default Theme (Light)

import { getThemeVariables } from '@w3payments/common';

const defaultVars = getThemeVariables('default');
// Returns CSS variables for light theme with blue primary (#2563eb)

Night Theme (Dark)

const nightVars = getThemeVariables('night');
// Returns CSS variables for dark theme with blue accent (#0085FF)

Using the Theming System

With Built-in Themes

import { W3PaymentWidget } from '@w3payments/react';

// Use built-in theme
<W3PaymentWidget theme="night" />

With Custom Theme

import type { W3Appearance } from '@w3payments/common';

const customTheme: W3Appearance = {
  variables: {
    primary: '#ff6b35',        // Orange brand color
    background: '#f8f9fa',     // Light gray background  
    borderRadius: '12px',      // Rounded corners
    fontFamily: 'SF Pro Display, system-ui, sans-serif'
  }
};

<W3PaymentWidget appearance={customTheme} />

With CSS Variables (Advanced)

import { getThemeVariables } from '@w3payments/common';

// Convert W3Appearance to CSS variables
const cssVars = getThemeVariables(customTheme);
// Returns: { '--w3-primary': '#ff6b35', '--w3-background': '#f8f9fa', ... }

// Apply to element
element.style.setProperty('--w3-primary', '#your-color');

Theme Conversion Utility

The getThemeVariables function converts W3Appearance objects to CSS custom properties:

import { getThemeVariables } from '@w3payments/common';

// Convert appearance to CSS variables
const appearance = { variables: { primary: '#ff6b35' } };
const cssVars = getThemeVariables(appearance);

console.log(cssVars);
// Output: { '--w3-primary': '#ff6b35', '--w3-background': '#ffffff', ... }

💰 Payment Types

Core Payment Interfaces

import type {
  PaymentIntent,
  PaymentResult,
  CryptoDestination,
  PaymentMethod
} from '@w3payments/common';

// Create payment intent
const intent: PaymentIntent = {
  amount: '100.00',
  currency: 'USD',
  destinations: [{
    address: '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa',
    networkId: 'bitcoin',
    symbol: 'BTC'
  }]
};

Payment Method Types

import type {
  FiatPaymentMethod,
  CryptoPaymentMethod,
  BasePaymentMethod
} from '@w3payments/common';

// Strongly typed payment methods
const fiatMethod: FiatPaymentMethod = {
  id: 'ach',
  type: 'fiat',
  name: 'Bank Transfer',
  currency: 'USD'
};

const cryptoMethod: CryptoPaymentMethod = {
  id: 'bitcoin',
  type: 'crypto', 
  name: 'Bitcoin',
  currency: 'BTC',
  networkId: 'bitcoin'
};

🌍 Currency and Network Data

Currency Registry

import { CURRENCIES, currencyService } from '@w3payments/common';

// Access currency metadata
const bitcoin = CURRENCIES.BTC;
console.log(bitcoin.name);        // "Bitcoin"
console.log(bitcoin.symbol);      // "BTC"
console.log(bitcoin.decimals);    // 8

// Use currency service
const usdcData = currencyService.getCurrency('USDC');
const cryptoCurrencies = currencyService.getCryptoCurrencies();

Network Registry

import { NETWORKS, networkService } from '@w3payments/common';

// Access network metadata
const ethereum = NETWORKS.ethereum;
console.log(ethereum.name);       // "Ethereum"
console.log(ethereum.chainId);    // 1
console.log(ethereum.symbol);     // "ETH"

// Use network service
const solanaNetwork = networkService.getNetwork('solana');
const evmNetworks = networkService.getEvmNetworks();

🎯 Payment Method Services

Payment Method Resolution

import { PaymentMethodService, paymentMethodService } from '@w3payments/common';

// Initialize service
const pmService = new PaymentMethodService();

// Resolve available payment methods
const methods = await pmService.getAvailablePaymentMethods({
  targetCurrency: 'USDC',
  targetNetwork: 'ethereum',
  amount: '100.00'
});

// Filter methods
const filteredMethods = pmService.filterPaymentMethods(methods, {
  exchangeFilter: ['coinbase', 'kraken'],
  walletFilter: ['BTC', 'ETH']
});

Payment Method Categories

import { paymentMethodService } from '@w3payments/common';

// Get methods by category
const fiatMethods = paymentMethodService.getFiatMethods();
const cryptoMethods = paymentMethodService.getCryptoMethods();
const exchangeMethods = paymentMethodService.getExchangeMethods();

🎨 Icon Utilities

Currency Icons

import { getCurrencyIcon } from '@w3payments/common';

// Get currency icon URL
const bitcoinIcon = getCurrencyIcon('BTC');
const ethereumIcon = getCurrencyIcon('ETH');

// Icons are optimized SVGs from trusted sources

Exchange Icons

import { getExchangeIcon, getFiatIcon } from '@w3payments/common';

// Exchange platform icons
const coinbaseIcon = getExchangeIcon('coinbase');
const krakenIcon = getExchangeIcon('kraken');

// Fiat currency icons
const usdIcon = getFiatIcon('USD');
const eurIcon = getFiatIcon('EUR');

🔗 QR Code Generation

import { generateQRCode } from '@w3payments/common';

// Generate QR code for payment
const qrDataUrl = await generateQRCode('bitcoin:1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa?amount=0.001');

// Use in React component
<img src={qrDataUrl} alt="Payment QR Code" />

📱 Vendor Adapter Types

Adapter Interface

import type { VendorAdapter, CheckoutSession } from '@w3payments/common';

// Implement custom adapter
class CustomAdapter implements VendorAdapter {
  async createSession(options: CreatePaymentOptions): Promise<CheckoutSession> {
    // Implementation
  }
  
  async getSessionStatus(sessionId: string): Promise<PaymentResult> {
    // Implementation  
  }
}

🔧 Environment Configuration

import type { Environment, PaymentConfig } from '@w3payments/common';

// Environment-specific configuration
const config: PaymentConfig = {
  environment: 'sandbox', // or 'production'
  vendors: {
    meshpay: {
      clientId: 'your-client-id',
      clientSecret: 'your-secret'
    }
  }
};

📚 Complete Type Exports

// Import all types from single source
import type {
  // Core payment types
  PaymentIntent,
  PaymentResult,
  PaymentStatus,
  CryptoDestination,
  
  // Payment method types  
  PaymentMethod,
  FiatPaymentMethod,
  CryptoPaymentMethod,
  
  // Configuration types
  PaymentConfig,
  PaymentClientOptions,
  CreatePaymentOptions,
  
  // Theming types
  W3Appearance,
  
  // Vendor types
  VendorAdapter,
  CheckoutSession,
  
  // Data types
  Currency,
  Network,
  Environment
} from '@w3payments/common';

🎯 Why Use This Package?

1. Type Safety - Complete TypeScript definitions prevent runtime errors
2. Consistent Theming - W3Appearance ensures visual consistency across frameworks
3. Rich Metadata - Currency and network registries provide complete context
4. Framework Agnostic - Works with React, Vue, Angular, vanilla JS
5. Production Ready - Used by all W3 Payments components

🔗 Related Packages

• @w3payments/core - Payment orchestration engine (uses this package)
• @w3payments/react - React components with W3Appearance integration
• @w3payments/adapters - Vendor integrations (uses types from this package)

📄 License

Proprietary - All rights reserved

💡 Pro Tip: Start with the W3Appearance theming system for consistent branding, then leverage the payment method services for dynamic payment options based on your specific requirements.