@w3payments/react 0.0.1

package/README.md

@@ -0,0 +1,488 @@
+# W3 Payments React
+
+React components for crypto onramping and payments. Currently focused on fiat-to-crypto and crypto-to-crypto onramp flows with MeshPay integration.
+
+## Install
+
+```bash
+npm install @w3payments/react @w3payments/core @w3payments/common
+```
+
+## Quick Start
+
+### 1. Backend Setup (Required)
+
+The widget requires a secure backend to create payment sessions. Create an Express server:
+
+```typescript
+// server.ts
+import express from 'express';
+import cors from 'cors';
+import { W3Payments } from '@w3payments/core';
+import type { CreatePaymentOptions } from '@w3payments/common';
+
+const app = express();
+app.use(cors());
+app.use(express.json());
+
+// Initialize W3Payments with your credentials
+const w3payments = new W3Payments({
+  config: {
+    environment: 'sandbox', // or 'production'
+    meshpay: {
+      clientId: process.env.MESH_CLIENT_ID!,
+      clientSecret: process.env.MESH_CLIENT_SECRET!,
+    },
+  },
+});
+
+await w3payments.initialize();
+
+// Create payment endpoint
+app.post('/api/payments/create', async (req, res) => {
+  try {
+    // Validate request body matches expected CreatePaymentOptions type
+    const paymentOptions: CreatePaymentOptions = req.body;
+    const session = await w3payments.paymentIntents.create(paymentOptions);
+    res.json(session);
+  } catch (error) {
+    res.status(500).json({ 
+      error: error instanceof Error ? error.message : 'Payment creation failed' 
+    });
+  }
+});
+
+// Payment status endpoint  
+app.get('/api/payments/:sessionId', async (req, res) => {
+  try {
+    const { sessionId } = req.params;
+    const { vendorId } = req.query;
+    
+    if (!vendorId || typeof vendorId !== 'string') {
+      return res.status(400).json({ error: 'vendorId is required' });
+    }
+    
+    const status = await w3payments.paymentIntents.retrieve(sessionId, vendorId);
+    res.json(status);
+  } catch (error) {
+    res.status(500).json({ 
+      error: error instanceof Error ? error.message : 'Status retrieval failed' 
+    });
+  }
+});
+
+app.listen(3001);
+```
+
+**Credentials**: MeshPay credentials are provided by the W3 Payments team during onboarding.
+
+### 2. React Integration
+
+Add the payment widget to your React app:
+
+```tsx
+import { W3PaymentsProvider, W3PaymentWidget } from '@w3payments/react';
+
+export function PaymentPage() {
+  return (
+    <div style={{ width: '400px', height: '600px' }}>
+      <W3PaymentsProvider
+        endpoint="http://localhost:3001/api/payments"
+        environment="sandbox"
+      >
+        <W3PaymentWidget
+          title="Fund Wallet"
+          targetCurrency="USDC"
+          targetNetwork="solana"
+          destinations={[{
+            address: "your_wallet_or_contract_address",
+            networkId: "solana",
+            symbol: "USDC"
+          }]}
+          onComplete={(result) => {
+            console.log('Payment completed:', result.transactionId);
+            // Update UI, redirect, etc.
+          }}
+          onError={(error) => {
+            console.error('Payment failed:', error.message);
+            // Show error to user
+          }}
+        />
+      </W3PaymentsProvider>
+    </div>
+  );
+}
+```
+
+## Configuration
+
+### Required Props
+
+**destinations** - Where payments will be sent:
+```tsx
+destinations={[{
+  address: "contract_or_wallet_address",
+  networkId: "solana",     // bitcoin, ethereum, solana, polygon, etc.
+  symbol: "USDC"           // Currency symbol
+}]}
+```
+
+### Payment Method Filtering
+
+Control which payment options are available:
+
+```tsx
+// Show specific wallet currencies
+walletFilter={['BTC', 'ETH', 'USDC']}
+
+// Show specific exchanges
+exchangeFilter={['coinbase', 'kraken', 'binance']}
+
+// Show fiat payment methods  
+fiatFilter={['ACH']}
+
+// Target specific currency (auto-converts if needed)
+targetCurrency="USDC"
+targetNetwork="solana"
+```
+
+### Event Handling
+
+```tsx
+<W3PaymentWidget
+  onInitiate={(data) => {
+    // User clicked payment button - log for analytics
+    console.log(`Starting ${data.currency} payment for ${data.amount}`);
+  }}
+  
+  onComplete={(data) => {
+    // Payment successful - update your app state
+    updateUserBalance(data.amount);
+    redirectToSuccess();
+  }}
+  
+  onError={(error) => {
+    // Payment failed - show user-friendly error
+    showErrorMessage(error.message);
+  }}
+/>
+```
+
+## Use Cases
+
+### Crypto Onramping (Coming Soon with IronPay)
+```tsx
+// Buy crypto with fiat (ACH, bank transfer) - IronPay integration in progress
+<W3PaymentWidget
+  title="Buy Crypto"
+  targetCurrency="USDC"
+  targetNetwork="solana"
+  fiatFilter={['ACH']}  // Will be available with IronPay
+  destinations={[{ address: userWallet, networkId: "solana", symbol: "USDC" }]}
+/>
+```
+
+### Crypto-to-Crypto Transfers (Available Now)
+```tsx
+// Transfer between different cryptocurrencies
+<W3PaymentWidget
+  title="Fund Wallet"
+  targetCurrency="USDC"
+  targetNetwork="solana"
+  walletFilter={['BTC', 'ETH']}  // Pay with BTC/ETH, receive USDC
+  destinations={[{ address: userWallet, networkId: "solana", symbol: "USDC" }]}
+/>
+```
+
+### Coming Soon
+
+```tsx
+// Auto-Converting Payments - COMING SOON
+<W3PaymentWidget
+  title="Pay with Any Currency"
+  targetCurrency="ETH"
+  autoConvert={true}  // Not yet available
+  destinations={[{ address: receiverWallet, networkId: "ethereum", symbol: "ETH" }]}
+/>
+
+// Staking with Auto-Yield - COMING SOON
+<W3PaymentWidget
+  title="Stake & Earn"
+  autoYield={true}  // Not yet available
+  destinations={[{ address: stakingContract, networkId: "solana", symbol: "USDC" }]}
+/>
+
+// Crypto Offramping - COMING SOON  
+<W3PaymentWidget
+  title="Cash Out"
+  targetCurrency="USD"  // Fiat offramp not yet available
+  destinations={[{ address: bankAccount, networkId: "fiat", symbol: "USD" }]}
+/>
+```
+
+## Current Features
+
+### MeshPay Integration
+Secure crypto-to-crypto transfers and exchange integrations through MeshPay's infrastructure.
+
+### Multi-Currency Support
+Support for major cryptocurrencies (BTC, ETH, USDC, SOL) across multiple networks (Bitcoin, Ethereum, Solana).
+
+### Smart Payment Routing
+Automatically routes payments through the most efficient available methods based on your target currency and network.
+
+## Planned Features (Coming Soon)
+
+### IronPay Integration
+Fiat-to-crypto onramping with ACH bank transfers and direct USD purchasing (integration in progress).
+
+### Auto Conversion
+Automatic currency conversions between any supported payment methods and target currencies at optimal rates.
+
+### Auto Yield
+Automatic routing through yield-generating opportunities (staking, lending pools) while maintaining the same user experience.
+
+### Cross-Chain Support
+Seamless payments across Bitcoin, Ethereum, Solana, Polygon with automatic bridging.
+
+### Crypto Offramping
+Direct crypto-to-fiat conversions with bank account deposits.
+
+## Customization
+
+### Widget Branding
+
+Customize the widget appearance with props:
+
+```tsx
+<W3PaymentWidget
+  title="Your Brand Name"
+  subtitle="CHOOSE PAYMENT METHOD"
+  logo="/your-logo.png"
+  showAmount={false}  // Hide amount section
+  showHeader={false}  // Hide header with title/logo
+  // ... other props
+/>
+```
+
+### Theme Customization
+
+Use the **W3Appearance API** for consistent theming across all components:
+
+#### Built-in Themes
+
+```tsx
+import { W3PaymentWidget } from '@w3payments/react';
+
+// Default light theme
+<W3PaymentWidget theme="default" />
+
+// Dark theme
+<W3PaymentWidget theme="night" />
+```
+
+#### Custom Themes
+
+```tsx
+import type { W3Appearance } from '@w3payments/common';
+
+const customTheme: W3Appearance = {
+  variables: {
+    // Brand colors
+    primary: '#ff6b35',           // Orange brand color
+    background: '#f8f9fa',        // Light gray background
+    text: '#2d3748',             // Dark text
+    textSecondary: '#718096',     // Muted text
+    
+    // Status colors
+    success: '#38a169',          // Green
+    danger: '#e53e3e',           // Red
+    warning: '#dd6b20',          // Orange
+    border: '#e2e8f0',           // Light border
+    
+    // Typography
+    fontFamily: 'Inter, system-ui, sans-serif',
+    fontSizeBase: '14px',
+    fontSizeSmall: '12px',
+    fontSizeLarge: '28px',
+    fontWeightNormal: '500',
+    
+    // Layout
+    spacingUnit: '6px',          // Increased spacing
+    borderRadius: '12px',        // More rounded
+    buttonRadius: '8px'          // Button radius
+  }
+};
+
+<W3PaymentWidget appearance={customTheme} />
+```
+
+#### Dark Theme Example
+
+```tsx
+const darkTheme: W3Appearance = {
+  variables: {
+    primary: '#0085FF',          // Blue accent
+    background: '#1a202c',       // Dark background
+    text: '#f7fafc',            // Light text
+    textSecondary: '#a0aec0',   // Muted light text
+    success: '#48bb78',         // Bright green
+    danger: '#f56565',          // Bright red
+    warning: '#ed8936',         // Bright orange
+    border: '#4a5568',          // Dark border
+    fontFamily: 'SF Pro Display, system-ui, sans-serif'
+  }
+};
+
+<W3PaymentWidget appearance={darkTheme} />
+```
+
+#### Theming with Context
+
+Apply themes globally using the provider:
+
+```tsx
+<W3PaymentsProvider 
+  endpoint="http://localhost:3001/api/payments"
+  environment="sandbox"
+  appearance={customTheme}  // Applied to all widgets
+>
+  <W3PaymentWidget amount="100.00" />
+  <W3PaymentWidget amount="50.00" />  {/* Both use customTheme */}
+</W3PaymentsProvider>
+```
+
+### Advanced Theming
+
+#### Responsive Themes
+
+```tsx
+const useResponsiveTheme = () => {
+  const [theme, setTheme] = useState<W3Appearance>({
+    variables: {
+      primary: '#2563eb',
+      spacingUnit: window.innerWidth < 768 ? '3px' : '4px',
+      fontSizeBase: window.innerWidth < 768 ? '13px' : '14px',
+      borderRadius: window.innerWidth < 768 ? '6px' : '8px'
+    }
+  });
+  
+  useEffect(() => {
+    const handleResize = () => {
+      setTheme(prev => ({
+        variables: {
+          ...prev.variables,
+          spacingUnit: window.innerWidth < 768 ? '3px' : '4px',
+          fontSizeBase: window.innerWidth < 768 ? '13px' : '14px',
+          borderRadius: window.innerWidth < 768 ? '6px' : '8px'
+        }
+      }));
+    };
+    
+    window.addEventListener('resize', handleResize);
+    return () => window.removeEventListener('resize', handleResize);
+  }, []);
+  
+  return theme;
+};
+
+// Usage
+function PaymentPage() {
+  const responsiveTheme = useResponsiveTheme();
+  
+  return (
+    <W3PaymentWidget appearance={responsiveTheme} />
+  );
+}
+```
+
+#### Brand Integration
+
+```tsx
+// Extract colors from your design system
+const brandTheme: W3Appearance = {
+  variables: {
+    // Use your brand colors
+    primary: 'var(--brand-primary, #2563eb)',
+    background: 'var(--surface-primary, #ffffff)',
+    text: 'var(--text-primary, #1a1a1a)',
+    textSecondary: 'var(--text-secondary, #6b7280)',
+    
+    // Match your typography
+    fontFamily: 'var(--font-family, Inter, sans-serif)',
+    fontSizeBase: 'var(--text-sm, 14px)',
+    
+    // Match your spacing scale  
+    spacingUnit: 'var(--spacing-1, 4px)',
+    borderRadius: 'var(--radius-md, 8px)'
+  }
+};
+
+<W3PaymentWidget appearance={brandTheme} />
+```
+
+### Advanced CSS Customization
+
+For specific styling needs beyond the W3Appearance API:
+
+```css
+/* Target widget container */
+[data-w3-payment-widget] {
+  /* Widget-level customization */
+  min-height: 500px;
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
+}
+
+/* Customize payment buttons */
+[data-w3-payment-widget] button {
+  transition: all 0.2s ease;
+}
+
+[data-w3-payment-widget] button:hover {
+  transform: translateY(-1px);
+}
+
+/* Amount input styling */
+[data-w3-payment-widget] input[type="number"] {
+  letter-spacing: 0.05em;
+}
+```
+
+**Note:** The W3Appearance API handles all standard theming needs. CSS overrides should only be used for specific animations or layout adjustments not covered by the design system.
+
+## How It Works
+
+1. **Payment Initiation**: User selects amount and payment method
+2. **Secure Session**: Widget calls your backend to create payment session
+3. **Smart Routing**: W3Payments optimizes vendor selection, conversions, and yield
+4. **User Flow**: User completes payment in vendor's secure interface
+5. **Auto Processing**: Auto conversions, bridging, and yield optimization happen automatically
+6. **Completion**: Widget receives result and calls your success/error handlers
+
+The widget abstracts all complexity - multi-vendor routing, currency conversions, cross-chain bridging, and yield optimization happen seamlessly behind the scenes.
+
+## Roadmap
+
+**Current**: Onramping, basic payments, MeshPay integration  
+**Coming Soon**: Offramping, auto-yield optimization, additional vendor integrations  
+**Future**: Advanced DeFi integrations, institutional-grade APIs, white-label solutions
+
+## Framework Support
+
+This is the React implementation. Other frameworks coming soon:
+- `@w3payments/vue` - Vue 3 components
+- `@w3payments/angular` - Angular components  
+- `@w3payments/nextjs` - Next.js integration
+
+Full SDK and REST API also in development for non-JavaScript environments.
+
+## Development
+
+Test the widget with Storybook:
+
+```bash
+cd packages/react
+npm run storybook
+```
+
+Make sure your backend server is running for end-to-end payment testing.

package/dist/appearance.d.ts

@@ -0,0 +1,30 @@
+/**
+ * W3 Payment Widget Appearance Configuration
+ *
+ * Following Stripe's appearance API pattern for simple but complete theming.
+ * This file belongs in the React package as it's UI-specific.
+ */
+export 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;
+    };
+}
+declare const BUILT_IN_THEMES: Record<string, Required<W3Appearance['variables']>>;
+export declare const getThemeVariables: (themeName?: string, appearance?: W3Appearance) => Record<string, string>;
+export { BUILT_IN_THEMES };
+//# sourceMappingURL=appearance.d.ts.map

package/dist/appearance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"appearance.d.ts","sourceRoot":"","sources":["../src/appearance.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,EAAE;QAEV,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,MAAM,CAAC,EAAE,MAAM,CAAC;QAGhB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAG1B,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,CAAC;CACH;AAqBD,QAAA,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC,CAWxE,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAC5B,YAAW,MAAkB,EAC7B,aAAa,YAAY,KACxB,MAAM,CAAC,MAAM,EAAE,MAAM,CAUvB,CAAC;AAEF,OAAO,EAAE,eAAe,EAAE,CAAC"}

package/dist/assets/3.svg

@@ -0,0 +1 @@
+<svg width="24" height="23.5" viewBox="0 0 48 47" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M43.9654 0H3.55466C1.75037 0 0.28833 1.46203 0.28833 3.26633V43.677C0.28833 45.4813 1.75037 46.9434 3.55466 46.9434H43.9654C45.7697 46.9434 47.2317 45.4813 47.2317 43.677V3.26633C47.2317 1.46203 45.7697 0 43.9654 0ZM39.785 30.1883C39.785 35.0097 35.8638 38.9309 31.0425 38.9309H10.8906C9.77276 38.9309 8.86468 38.0248 8.86468 36.905C8.86468 35.7852 9.77078 34.8791 10.8906 34.8791H31.0425C33.6302 34.8791 35.7352 32.7741 35.7352 30.1864C35.7352 27.5986 33.6302 25.4936 31.0425 25.4936H23.0419C21.9241 25.4936 21.016 24.5875 21.016 23.4677C21.016 22.348 21.9221 21.4419 23.0419 21.4419H31.0425C33.6302 21.4419 35.7352 19.3368 35.7352 16.7491C35.7352 14.1614 33.6302 12.0563 31.0425 12.0563H10.8906C9.77276 12.0563 8.86468 11.1502 8.86468 10.0305C8.86468 8.9107 9.77078 8.00459 10.8906 8.00459H31.0425C35.8638 8.00459 39.785 11.9258 39.785 16.7471C39.785 19.4437 38.5564 21.8593 36.6315 23.4638C38.5564 25.0683 39.785 27.4839 39.785 30.1804V30.1883Z" fill="white" class="group-hover:fill-[#FF3223]"></path></svg>

package/dist/assets/io.svg

@@ -0,0 +1 @@
+<svg width="14.5" height="11" viewBox="0 0 29 22" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M15.4597 5.22243C16.6803 3.79799 16.2708 4.07496 18.1384 2.86616C18.6825 2.60897 18.8744 2.06096 18.7141 1.47535C18.5539 0.889747 17.9129 0.632558 17.4658 0.816549C15.6714 1.691 14.8523 2.698 14.2608 3.44781C13.9066 3.87515 13.7939 4.52802 14.1144 5.00283C14.4349 5.47963 15.0422 5.58844 15.4597 5.22243Z" fill="white"></path><path d="M28.2084 10.9678C28.1055 10.3169 27.4586 10.123 27.0412 10.2694C26.6257 10.4158 26.3685 10.8926 26.3685 11.4782C26.3685 12.687 26.1449 13.969 25.7275 15.1759C25.0232 17.0811 23.5176 19.0575 22.4295 19.3127C22.3979 19.2395 22.3346 18.9467 22.3346 18.5807C22.3346 16.8239 23.3594 13.4547 25.9194 9.97664C26.2716 9.53744 26.2083 8.84302 25.7908 8.43943C25.407 8.03584 24.7996 8.10904 24.4455 8.58583C23.8401 9.41082 23.306 10.2398 22.8351 11.0588C22.8054 11.0747 22.7777 11.0925 22.748 11.1122C15.7702 15.9831 12.1241 19.2791 9.72427 19.2791C9.72427 19.1683 9.75592 18.9863 9.97948 18.3631L13.3091 9.72143C13.5327 9.17144 13.3091 8.51263 12.8284 8.29303C12.3476 8.03584 11.7719 8.29303 11.58 8.84302L8.09012 17.8863C7.44912 19.5343 7.99318 21.5107 9.72229 21.5107C12.1221 21.5107 15.3706 18.9506 21.0862 14.8969C20.6391 16.2442 20.4096 17.4985 20.4096 18.5827C20.4096 19.9003 20.9536 21.5127 22.3623 21.5127C24.1863 21.5127 26.5228 18.8042 27.516 15.9831C27.7395 15.3242 28.0126 14.1708 28.0759 13.6782C28.1392 13.1856 28.3054 11.6207 28.2025 10.9698L28.2084 10.9678Z" fill="white"></path><path d="M1.16597 19.376C0.576406 19.376 0.0996094 19.8528 0.0996094 20.4423C0.0996094 21.0319 0.576406 21.5087 1.16597 21.5087C1.75553 21.5087 2.23232 21.0319 2.23232 20.4423C2.23232 19.8528 1.75553 19.376 1.16597 19.376Z" fill="white"></path></svg>