@w3payments/common 1.2.0 → 1.3.0

package/README.md

@@ -0,0 +1,375 @@
+# @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
+
+```bash
+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:
+
+```typescript
+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)
+```typescript
+import { getThemeVariables } from '@w3payments/common';
+
+const defaultVars = getThemeVariables('default');
+// Returns CSS variables for light theme with blue primary (#2563eb)
+```
+
+#### Night Theme (Dark)  
+```typescript
+const nightVars = getThemeVariables('night');
+// Returns CSS variables for dark theme with blue accent (#0085FF)
+```
+
+### Using the Theming System
+
+#### With Built-in Themes
+```typescript
+import { W3PaymentWidget } from '@w3payments/react';
+
+// Use built-in theme
+<W3PaymentWidget theme="night" />
+```
+
+#### With Custom Theme
+```typescript
+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)
+```typescript
+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:
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+// 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](../core/)** - Payment orchestration engine (uses this package)
+- **[@w3payments/react](../react/)** - React components with W3Appearance integration
+- **[@w3payments/adapters](../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.

package/dist/index.d.ts

@@ -1,8 +1,3 @@
-/**
- * Apply theme to container element
- */
-export declare function applyTheme(themeInput: W3ThemeInput, container: HTMLElement): void;
-
 /**
  * Currency Types
  *
@@ -150,20 +145,6 @@ export declare type CryptoPaymentMethod = BasePaymentMethod & {
     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>;
 
 /**
@@ -323,6 +304,8 @@ export declare function getExchangeIcon(exchange: string): string | undefined;
 
 export declare function getFiatIcon(method: string): string | undefined;
 
+export declare const getThemeVariables: (themeName?: string, appearance?: W3Appearance) => Record<string, string>;
+
 /**
  * Network Types
  *
@@ -666,60 +649,29 @@ export declare interface VendorAdapter {
 }
 
 /**
- * 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;
+ * W3 Payment Widget Appearance Configuration
+ *
+ * Following Stripe's appearance API pattern for simple but complete theming.
+ */
+export declare interface W3Appearance {
+    variables?: {
+        primary?: string;
+        background?: string;
+        text?: string;
+        textSecondary?: string;
+        danger?: string;
+        success?: string;
+        warning?: string;
+        border?: string;
+        fontFamily?: string;
+        fontSizeBase?: string;
+        fontSizeSmall?: string;
+        fontSizeLarge?: string;
+        fontWeightNormal?: string;
+        spacingUnit?: string;
+        borderRadius?: string;
+        buttonRadius?: string;
+    };
 }
 
 export { }

package/dist/index.js

@@ -1,5 +1,44 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const defaultTheme = {
+  primary: "#2563eb",
+  background: "#ffffff",
+  text: "#000000",
+  textSecondary: "#6b7280",
+  danger: "#dc2626",
+  success: "#16a34a",
+  warning: "#ca8a04",
+  border: "#e5e7eb",
+  fontFamily: "Inter, system-ui, sans-serif",
+  fontSizeBase: "14px",
+  fontSizeSmall: "12px",
+  fontSizeLarge: "32px",
+  fontWeightNormal: "400",
+  spacingUnit: "4px",
+  borderRadius: "8px",
+  buttonRadius: "6px"
+};
+const BUILT_IN_THEMES = {
+  default: defaultTheme,
+  night: {
+    ...defaultTheme,
+    primary: "#0085FF",
+    background: "#14171D",
+    text: "#C9CED8",
+    textSecondary: "#8C99AD",
+    danger: "#F23154",
+    border: "#2B3039"
+  }
+};
+const getThemeVariables = (themeName = "default", appearance) => {
+  const baseTheme = BUILT_IN_THEMES[themeName] || BUILT_IN_THEMES.default;
+  const finalVariables = { ...baseTheme, ...appearance?.variables };
+  const cssVars = {};
+  Object.entries(finalVariables).forEach(([key, value]) => {
+    cssVars[`--w3-${key}`] = value;
+  });
+  return cssVars;
+};
 class PaymentMethodService {
   static instance;
   paymentMethods = /* @__PURE__ */ new Map();
@@ -470,78 +509,6 @@ function truncateToCurrencyDecimals(value, currency) {
   const truncatedDecimal = parts[1].substring(0, currency.decimals);
   return truncatedDecimal.length > 0 ? `${parts[0]}.${truncatedDecimal}` : parts[0];
 }
-function camelToKebab(str) {
-  return str.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
-}
-function getDefaultVariables() {
-  return {
-    colorPrimary: "#6366f1",
-    colorPrimaryHover: "#4f46e5",
-    colorPrimaryLight: "#e0e7ff",
-    colorBackground: "#ffffff",
-    colorText: "#1f2937",
-    colorTextMuted: "#6b7280",
-    colorBorder: "#e5e7eb",
-    colorBorderLight: "#f3f4f6",
-    colorDanger: "#ef4444",
-    colorSuccess: "#10b981",
-    fontFamily: "system-ui, -apple-system, sans-serif",
-    fontSize: "1rem",
-    borderRadius: "0.5rem",
-    spacing: "1rem"
-  };
-}
-function getThemePreset(themeName) {
-  const defaults = getDefaultVariables();
-  switch (themeName) {
-    case "dark":
-      return {
-        ...defaults,
-        colorPrimary: "#6366f1",
-        colorPrimaryHover: "#7c3aed",
-        colorPrimaryLight: "#1e1b4b",
-        colorBackground: "#111827",
-        colorText: "#f9fafb",
-        colorTextMuted: "#9ca3af",
-        colorBorder: "#374151",
-        colorBorderLight: "#4b5563"
-      };
-    case "light":
-    default:
-      return defaults;
-  }
-}
-function applyTheme(themeInput, container) {
-  const theme = typeof themeInput === "string" ? { theme: themeInput } : themeInput;
-  const baseVariables = getThemePreset(theme.theme ?? "light");
-  const finalVariables = { ...baseVariables, ...theme.variables };
-  Object.entries(finalVariables).forEach(([key, value]) => {
-    if (value !== void 0) {
-      const cssVar = `--${camelToKebab(key)}`;
-      container.style.setProperty(cssVar, value);
-    }
-  });
-  if (theme.theme) {
-    container.setAttribute("data-theme", theme.theme);
-  }
-  if (theme.rules) {
-    applyComponentRules(theme.rules);
-  }
-}
-function applyComponentRules(rules) {
-  const styleId = "w3-theme-rules";
-  let styleElement = document.getElementById(styleId);
-  if (!styleElement) {
-    styleElement = document.createElement("style");
-    styleElement.id = styleId;
-    document.head.appendChild(styleElement);
-  }
-  const css = Object.entries(rules).map(([selector, styles]) => {
-    const cssProperties = Object.entries(styles).map(([prop, value]) => `${camelToKebab(prop)}: ${value};`).join(" ");
-    return `.w3-widget ${selector} { ${cssProperties} }`;
-  }).join("\n");
-  styleElement.textContent = css;
-}
 function getDefaultExportFromCjs(x) {
   return x && x.__esModule && Object.prototype.hasOwnProperty.call(x, "default") ? x["default"] : x;
 }
@@ -2879,7 +2846,6 @@ function getFiatIcon(method) {
 exports.CURRENCIES = CURRENCIES;
 exports.NETWORKS = NETWORKS;
 exports.PaymentMethodService = PaymentMethodService;
-exports.applyTheme = applyTheme;
 exports.copyToClipboard = copyToClipboard;
 exports.currencyService = currencyService;
 exports.formatCurrencyDisplay = formatCurrencyDisplay;
@@ -2893,6 +2859,7 @@ exports.generateQRCodeSVG = generateQRCodeSVG;
 exports.getCurrencyIcon = getCurrencyIcon;
 exports.getExchangeIcon = getExchangeIcon;
 exports.getFiatIcon = getFiatIcon;
+exports.getThemeVariables = getThemeVariables;
 exports.networkService = networkService;
 exports.paymentMethodService = paymentMethodService;
 exports.truncateToCurrencyDecimals = truncateToCurrencyDecimals;