swiftshopr-payments 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 SwiftShopr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,339 @@
+# swiftshopr-payments
+
+Official Node.js SDK for SwiftShopr Payments API. Accept USDC payments with zero chargebacks, instant settlement, and lower fees than card networks.
+
+## Features
+
+- **Zero Dependencies** - Uses native `fetch` (Node.js 18+)
+- **TypeScript Support** - Full type definitions included
+- **Automatic Retries** - Exponential backoff for failed requests
+- **Idempotency** - Safe retries for payment operations
+- **Webhook Verification** - HMAC signature validation
+
+## Installation
+
+```bash
+npm install swiftshopr-payments
+```
+
+## Quick Start
+
+```javascript
+const { SwiftShoprClient } = require('swiftshopr-payments');
+
+const client = new SwiftShoprClient({
+  apiKey: 'sk_live_your_api_key',
+});
+
+// Create an onramp session (Add Funds)
+const session = await client.payments.createSession({
+  amount: 25.00,
+  orderId: 'ORDER-123',
+  storeId: 'STORE001',
+});
+
+console.log('Redirect user to:', session.onrampUrl);
+```
+
+## Payment Flows
+
+### Two-Button Pattern
+
+SwiftShopr supports two payment methods:
+
+| Button | Method | When to Use | Fees |
+|--------|--------|-------------|------|
+| **Add Funds** | `createSession()` | User has no USDC | ~$0.30 |
+| **Purchase** | `createTransfer()` | User has USDC balance | $0 |
+
+```javascript
+// Check user's USDC balance first
+const balance = await getUserBalance(); // Your wallet SDK
+
+if (balance >= purchaseAmount) {
+  // Direct transfer - no fees!
+  const transfer = await client.payments.createTransfer({
+    amount: 25.00,
+    userWalletAddress: '0xUserWallet...',
+    storeId: 'STORE001',
+  });
+} else {
+  // Onramp - small fee for ACH conversion
+  const session = await client.payments.createSession({
+    amount: 25.00,
+    storeId: 'STORE001',
+  });
+}
+```
+
+## API Reference
+
+### Payments
+
+#### Create Onramp Session
+
+```javascript
+const session = await client.payments.createSession({
+  amount: 25.00,              // Required: Amount in USD
+  orderId: 'ORDER-123',       // Optional: Your order reference
+  storeId: 'STORE001',        // Optional: Store ID (resolves wallet)
+  destinationAddress: '0x...', // Optional: Explicit wallet address
+  paymentMethod: 'ACH_BANK_ACCOUNT', // Optional: ACH_BANK_ACCOUNT, CARD
+});
+
+// Response
+{
+  intentId: 'uuid',
+  sessionId: 'sess_xxx',
+  orderId: 'ORDER-123',
+  onrampUrl: 'https://pay.coinbase.com/...',
+  expiresAt: '2024-12-23T10:30:00Z',
+  branding: { ... }
+}
+```
+
+#### Create Direct Transfer
+
+```javascript
+const transfer = await client.payments.createTransfer({
+  amount: 25.00,
+  userWalletAddress: '0xUserWallet...',
+  storeId: 'STORE001',
+});
+
+// Response includes transfer instructions
+{
+  intentId: 'uuid',
+  transfer: {
+    to: '0xRetailerWallet...',
+    amount: '25.00',
+    asset: 'USDC',
+    network: 'base',
+    chainId: 8453,
+  }
+}
+```
+
+#### Get Payment Status
+
+```javascript
+// By intent ID
+const status = await client.payments.getStatus('intent-uuid');
+
+// By your order ID
+const status = await client.payments.getStatusByOrderId('ORDER-123');
+
+// Poll until complete
+const finalStatus = await client.payments.waitForCompletion('intent-uuid', {
+  timeout: 300000,  // 5 minutes
+  interval: 2000,   // Check every 2 seconds
+  onStatusChange: (status) => console.log('Status:', status.status),
+});
+```
+
+### Refunds
+
+#### Request a Refund
+
+```javascript
+const refund = await client.refunds.create({
+  intentId: 'original-payment-intent-uuid',
+  amount: 25.00,           // Optional: Defaults to full refund
+  reason: 'Customer request',
+});
+
+// Response includes transfer instructions
+{
+  id: 'refund-uuid',
+  status: 'requested',
+  instructions: {
+    message: 'Send USDC to complete the refund...',
+    transfer: {
+      to: '0xUserWallet...',
+      amount: '25.00',
+      asset: 'USDC',
+    },
+    fromWallet: '0xYourStoreWallet...',
+  }
+}
+```
+
+#### Check Refund Status
+
+```javascript
+const refund = await client.refunds.get('refund-uuid');
+
+// List all refunds for a payment
+const refunds = await client.refunds.listForPayment('intent-uuid');
+
+// Wait for completion
+const completedRefund = await client.refunds.waitForCompletion('refund-uuid');
+```
+
+### Dashboard
+
+```javascript
+// Summary metrics
+const summary = await client.dashboard.getSummary();
+
+// Transaction list with filters
+const { transactions, pagination } = await client.dashboard.getTransactions({
+  status: 'completed',
+  storeId: 'STORE001',
+  startDate: '2024-01-01',
+  endDate: '2024-12-31',
+  limit: 50,
+});
+
+// Store breakdown
+const stores = await client.dashboard.getStores();
+
+// Daily data for charts
+const daily = await client.dashboard.getDaily({ days: 30 });
+
+// Export CSV
+const csv = await client.dashboard.export({
+  startDate: '2024-01-01',
+  endDate: '2024-12-31',
+});
+```
+
+### Branding
+
+```javascript
+// Get branding for white-label UI
+const branding = await client.branding.get('STORE001');
+
+// Generate CSS variables
+const css = client.branding.toCssVariables(branding);
+// --swiftshopr-primary: #E31837;
+// --swiftshopr-background: #FFFFFF;
+
+// Get CDP/OnchainKit theme tokens
+const cdpTheme = client.branding.toCdpTheme(branding);
+```
+
+## Webhooks
+
+### Verify Webhook Signatures
+
+```javascript
+const { SwiftShoprClient, webhookMiddleware } = require('swiftshopr-payments');
+
+// Option 1: Express middleware
+app.post('/webhooks/swiftshopr',
+  express.raw({ type: 'application/json' }),
+  webhookMiddleware('whsec_your_secret'),
+  (req, res) => {
+    const event = req.webhookEvent;
+
+    switch (event.type) {
+      case 'payment.completed':
+        console.log('Payment completed:', event.data.orderId);
+        break;
+      case 'refund.completed':
+        console.log('Refund completed:', event.data.refundId);
+        break;
+    }
+
+    res.json({ received: true });
+  }
+);
+
+// Option 2: Manual verification
+const client = new SwiftShoprClient({
+  apiKey: 'sk_live_...',
+  webhookSecret: 'whsec_your_secret',
+});
+
+const event = client.webhooks.constructEvent(
+  req.body,       // Raw body
+  req.headers     // { 'x-webhook-signature': '...', 'x-webhook-timestamp': '...' }
+);
+```
+
+### Webhook Events
+
+| Event | Description |
+|-------|-------------|
+| `payment.completed` | Payment confirmed on-chain |
+| `payment.failed` | Payment failed |
+| `payment.expired` | Payment intent expired |
+| `refund.requested` | Refund initiated |
+| `refund.completed` | Refund confirmed on-chain |
+| `refund.failed` | Refund failed |
+
+## Error Handling
+
+```javascript
+const { SwiftShoprError, HttpError, TimeoutError } = require('swiftshopr-payments');
+
+try {
+  await client.payments.createSession({ amount: 25.00 });
+} catch (error) {
+  if (error instanceof SwiftShoprError) {
+    // Validation or business logic error
+    console.log('Code:', error.code);
+    console.log('Message:', error.message);
+    console.log('Details:', error.details);
+  } else if (error instanceof HttpError) {
+    // HTTP error from API
+    console.log('Status:', error.statusCode);
+    console.log('Response:', error.response);
+  } else if (error instanceof TimeoutError) {
+    // Request timed out
+    console.log('Timeout after:', error.timeout, 'ms');
+  }
+}
+```
+
+## Configuration
+
+```javascript
+const client = new SwiftShoprClient({
+  apiKey: 'sk_live_...',           // Required
+  webhookSecret: 'whsec_...',      // Optional: For webhook verification
+  baseUrl: 'https://...',          // Optional: Custom API URL
+  timeout: 30000,                  // Optional: Request timeout (ms)
+  retries: 3,                      // Optional: Retry attempts
+
+  // Hooks for logging/monitoring
+  onRequest: ({ method, url }) => {
+    console.log(`[API] ${method} ${url}`);
+  },
+  onResponse: ({ status, data }) => {
+    console.log(`[API] Response: ${status}`);
+  },
+  onError: (error) => {
+    console.error('[API] Error:', error.message);
+  },
+});
+```
+
+## TypeScript
+
+Full TypeScript support with type definitions:
+
+```typescript
+import { SwiftShoprClient, PaymentStatus, RefundResult } from 'swiftshopr-payments';
+
+const client = new SwiftShoprClient({ apiKey: 'sk_live_...' });
+
+const status: PaymentStatus = await client.payments.getStatus('uuid');
+const refund: RefundResult = await client.refunds.create({ intentId: 'uuid' });
+```
+
+## Requirements
+
+- Node.js 18+ (uses native `fetch`)
+- SwiftShopr API key
+
+## Support
+
+- Documentation: https://docs.swiftshopr.com
+- Issues: https://github.com/swiftshopr/payments-sdk/issues
+- Email: sdk@swiftshopr.com
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "swiftshopr-payments",
+  "version": "1.0.0",
+  "description": "Official Node.js SDK for SwiftShopr Payments - Accept USDC payments with zero chargebacks",
+  "main": "src/index.js",
+  "types": "src/types/index.d.ts",
+  "exports": {
+    ".": {
+      "require": "./src/index.js",
+      "import": "./src/index.js",
+      "types": "./src/types/index.d.ts"
+    }
+  },
+  "files": [
+    "src/**/*",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "jest --passWithNoTests",
+    "lint": "echo 'Linting skipped - no eslint config'",
+    "prepublishOnly": "npm test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/swiftshopr/payments-sdk.git"
+  },
+  "keywords": [
+    "swiftshopr",
+    "payments",
+    "usdc",
+    "crypto",
+    "stablecoin",
+    "point-of-sale",
+    "pos",
+    "retail",
+    "sdk",
+    "api",
+    "base",
+    "coinbase",
+    "web3"
+  ],
+  "author": "SwiftShopr <sdk@swiftshopr.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/swiftshopr/payments-sdk/issues"
+  },
+  "homepage": "https://docs.swiftshopr.com/sdk",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {},
+  "dependencies": {}
+}

package/src/branding.js

@@ -0,0 +1,127 @@
+/**
+ * Branding API Module
+ * Fetch retailer branding for white-label UI
+ */
+
+const { SwiftShoprError } = require('./utils/http');
+
+/**
+ * Create Branding API instance
+ */
+function createBrandingAPI(http) {
+  return {
+    /**
+     * Get branding for a store
+     *
+     * @param {string} storeId - Store ID
+     * @returns {Promise<Object>} Branding configuration
+     */
+    async get(storeId) {
+      if (!storeId) {
+        throw new SwiftShoprError('VALIDATION_ERROR', 'storeId is required');
+      }
+
+      const response = await http.get(
+        `/api/v1/sdk/onramp/branding/${encodeURIComponent(storeId)}`,
+      );
+
+      return {
+        storeId: response.store_id,
+        branding: {
+          name: response.branding?.name || null,
+          logoUrl: response.branding?.logo_url || null,
+          theme: {
+            primaryColor: response.branding?.theme?.primary_color || '#000000',
+            secondaryColor:
+              response.branding?.theme?.secondary_color || '#FFFFFF',
+            backgroundColor:
+              response.branding?.theme?.background_color || '#FFFFFF',
+            textColor: response.branding?.theme?.text_color || '#333333',
+            accentColor: response.branding?.theme?.accent_color || '#007AFF',
+            mode: response.branding?.theme?.mode || 'light',
+            fontFamily: response.branding?.theme?.font_family || null,
+          },
+          // CDP/OnchainKit compatible theme tokens
+          cdpTheme: response.branding?.cdp_theme || null,
+        },
+      };
+    },
+
+    /**
+     * Generate CSS variables from branding
+     *
+     * @param {Object} branding - Branding object from get()
+     * @returns {string} CSS custom properties
+     */
+    toCssVariables(branding) {
+      if (!branding?.branding?.theme) {
+        return '';
+      }
+
+      const { theme } = branding.branding;
+      const vars = [
+        `--swiftshopr-primary: ${theme.primaryColor};`,
+        `--swiftshopr-secondary: ${theme.secondaryColor};`,
+        `--swiftshopr-background: ${theme.backgroundColor};`,
+        `--swiftshopr-text: ${theme.textColor};`,
+        `--swiftshopr-accent: ${theme.accentColor};`,
+      ];
+
+      if (theme.fontFamily) {
+        vars.push(`--swiftshopr-font: ${theme.fontFamily};`);
+      }
+
+      return vars.join('\n');
+    },
+
+    /**
+     * Generate style object for React inline styles
+     *
+     * @param {Object} branding - Branding object from get()
+     * @returns {Object} Style object
+     */
+    toStyleObject(branding) {
+      if (!branding?.branding?.theme) {
+        return {};
+      }
+
+      const { theme } = branding.branding;
+      return {
+        '--swiftshopr-primary': theme.primaryColor,
+        '--swiftshopr-secondary': theme.secondaryColor,
+        '--swiftshopr-background': theme.backgroundColor,
+        '--swiftshopr-text': theme.textColor,
+        '--swiftshopr-accent': theme.accentColor,
+        ...(theme.fontFamily && { '--swiftshopr-font': theme.fontFamily }),
+      };
+    },
+
+    /**
+     * Get CDP/OnchainKit theme tokens
+     *
+     * @param {Object} branding - Branding object from get()
+     * @returns {Object} CDP theme tokens for OnchainKit
+     */
+    toCdpTheme(branding) {
+      if (branding?.branding?.cdpTheme) {
+        return branding.branding.cdpTheme;
+      }
+
+      // Generate from standard theme
+      const theme = branding?.branding?.theme;
+      if (!theme) {
+        return null;
+      }
+
+      return {
+        'colors-bg-primary': theme.backgroundColor,
+        'colors-bg-secondary': theme.mode === 'dark' ? '#1a1a1a' : '#F5F5F5',
+        'colors-fg-default': theme.textColor,
+        'colors-accent': theme.accentColor || theme.primaryColor,
+        'colors-accent-foreground': '#FFFFFF',
+      };
+    },
+  };
+}
+
+module.exports = { createBrandingAPI };

package/src/client.js

@@ -0,0 +1,111 @@
+/**
+ * SwiftShopr Payments Client
+ * Main entry point for the SDK
+ */
+
+const { createHttpClient, SwiftShoprError } = require('./utils/http');
+const { createPaymentsAPI } = require('./payments');
+const { createRefundsAPI } = require('./refunds');
+const { createDashboardAPI } = require('./dashboard');
+const { createBrandingAPI } = require('./branding');
+const { createConfigAPI } = require('./config');
+const { createWebhooksHelper } = require('./webhooks');
+
+/**
+ * SwiftShopr Payments Client
+ *
+ * @example
+ * const client = new SwiftShoprClient({
+ *   apiKey: 'sk_live_...',
+ *   webhookSecret: 'whsec_...', // optional
+ * });
+ *
+ * // Create payment
+ * const session = await client.payments.createSession({
+ *   amount: 25.00,
+ *   orderId: 'ORDER-123',
+ *   storeId: 'STORE001',
+ * });
+ *
+ * // Request refund
+ * const refund = await client.refunds.create({
+ *   intentId: session.intentId,
+ *   reason: 'Customer request',
+ * });
+ *
+ * // Get dashboard metrics
+ * const summary = await client.dashboard.getSummary();
+ */
+class SwiftShoprClient {
+  /**
+   * Create a new SwiftShopr client
+   *
+   * @param {Object} config
+   * @param {string} config.apiKey - Your SwiftShopr API key (required)
+   * @param {string} [config.webhookSecret] - Webhook secret for signature verification
+   * @param {string} [config.baseUrl] - API base URL (default: production)
+   * @param {number} [config.timeout=30000] - Request timeout in ms
+   * @param {number} [config.retries=3] - Number of retries for failed requests
+   * @param {Function} [config.onRequest] - Hook called before each request
+   * @param {Function} [config.onResponse] - Hook called after each response
+   * @param {Function} [config.onError] - Hook called on errors
+   */
+  constructor(config) {
+    if (!config || !config.apiKey) {
+      throw new SwiftShoprError('CONFIG_ERROR', 'API key is required');
+    }
+
+    this._config = {
+      baseUrl: config.baseUrl || 'https://shopr-scanner-backend.onrender.com',
+      apiKey: config.apiKey,
+      webhookSecret: config.webhookSecret || null,
+      timeout: config.timeout || 30000,
+      retries: config.retries ?? 3,
+      onRequest: config.onRequest || null,
+      onResponse: config.onResponse || null,
+      onError: config.onError || null,
+    };
+
+    // Create HTTP client
+    this._http = createHttpClient(this._config);
+
+    // Initialize API modules
+    this.payments = createPaymentsAPI(this._http);
+    this.refunds = createRefundsAPI(this._http);
+    this.dashboard = createDashboardAPI(this._http);
+    this.branding = createBrandingAPI(this._http);
+    this.config = createConfigAPI(this._http);
+
+    // Webhooks helper (if secret provided)
+    if (this._config.webhookSecret) {
+      this.webhooks = createWebhooksHelper(this._config.webhookSecret);
+    } else {
+      // Provide method to create webhooks helper later
+      this.webhooks = {
+        configure: (secret) => createWebhooksHelper(secret),
+      };
+    }
+  }
+
+  /**
+   * Get SDK version
+   */
+  static get VERSION() {
+    return '1.0.0';
+  }
+
+  /**
+   * Get current configuration (without sensitive data)
+   */
+  getConfig() {
+    return {
+      baseUrl: this._config.baseUrl,
+      timeout: this._config.timeout,
+      retries: this._config.retries,
+      hasApiKey: !!this._config.apiKey,
+      hasWebhookSecret: !!this._config.webhookSecret,
+    };
+  }
+}
+
+module.exports = { SwiftShoprClient };