swiftshopr-payments 1.0.0

package/src/config.js

@@ -0,0 +1,273 @@
+/**
+ * Config API Module
+ * Retailer self-service configuration
+ */
+
+const { SwiftShoprError } = require('./utils/http');
+
+/**
+ * Ethereum address validation regex
+ */
+const ETH_ADDRESS_REGEX = /^0x[a-fA-F0-9]{40}$/;
+
+/**
+ * Validate Ethereum address
+ */
+function isValidEthAddress(address) {
+  return ETH_ADDRESS_REGEX.test(address);
+}
+
+/**
+ * Create Config API instance
+ */
+function createConfigAPI(http) {
+  return {
+    /**
+     * Get current retailer configuration
+     *
+     * @returns {Promise<Object>} Current configuration
+     */
+    async get() {
+      const response = await http.get('/api/v1/sdk/config');
+
+      if (!response.success) {
+        throw new SwiftShoprError(
+          'CONFIG_ERROR',
+          response.error || 'Failed to get configuration',
+        );
+      }
+
+      return {
+        chainId: response.config.chainId,
+        label: response.config.label,
+        webhook: response.config.webhook,
+        permissions: response.config.permissions,
+        rateLimit: response.config.rateLimit,
+        allowedIps: response.config.allowedIps,
+        createdAt: response.config.createdAt,
+        lastUsedAt: response.config.lastUsedAt,
+        stores: response.stores,
+      };
+    },
+
+    /**
+     * Configure webhook URL
+     *
+     * @param {Object} params
+     * @param {string} [params.url] - Webhook URL (HTTPS recommended)
+     * @param {boolean} [params.generateSecret] - Generate a new webhook secret
+     * @returns {Promise<Object>} Updated webhook config
+     */
+    async setWebhook(params = {}) {
+      const body = {};
+
+      if (params.url !== undefined) {
+        body.url = params.url;
+      }
+
+      if (params.generateSecret) {
+        body.generateSecret = true;
+      }
+
+      const response = await http.put('/api/v1/sdk/config/webhook', body);
+
+      if (!response.success) {
+        throw new SwiftShoprError(
+          'CONFIG_ERROR',
+          response.error || 'Failed to update webhook',
+        );
+      }
+
+      return {
+        url: response.webhook.url,
+        hasSecret: response.webhook.hasSecret,
+        secret: response.webhook.secret || null, // Only returned when generated
+        message: response.message || null,
+      };
+    },
+
+    /**
+     * Rotate webhook secret
+     *
+     * @returns {Promise<Object>} New webhook secret (save it!)
+     */
+    async rotateWebhookSecret() {
+      const response = await http.post(
+        '/api/v1/sdk/config/webhook/rotate-secret',
+        {},
+      );
+
+      if (!response.success) {
+        throw new SwiftShoprError(
+          'CONFIG_ERROR',
+          response.error || 'Failed to rotate webhook secret',
+        );
+      }
+
+      return {
+        url: response.webhook.url,
+        secret: response.webhook.secret,
+        message: response.message,
+      };
+    },
+
+    /**
+     * List all registered stores
+     *
+     * @returns {Promise<Array>} Store list
+     */
+    async getStores() {
+      const response = await http.get('/api/v1/sdk/config/stores');
+
+      if (!response.success) {
+        throw new SwiftShoprError(
+          'CONFIG_ERROR',
+          response.error || 'Failed to get stores',
+        );
+      }
+
+      return response.stores;
+    },
+
+    /**
+     * Register a new store with wallet address
+     *
+     * @param {Object} params
+     * @param {string} params.storeId - Unique store identifier
+     * @param {string} params.walletAddress - Ethereum wallet address for payments
+     * @param {string} [params.storeName] - Human-readable store name
+     * @param {string} [params.webhookUrl] - Store-specific webhook URL (optional)
+     * @param {Object} [params.branding] - Store branding configuration
+     * @returns {Promise<Object>} Created store
+     */
+    async registerStore(params) {
+      if (!params.storeId) {
+        throw new SwiftShoprError('VALIDATION_ERROR', 'storeId is required');
+      }
+
+      if (!params.walletAddress) {
+        throw new SwiftShoprError(
+          'VALIDATION_ERROR',
+          'walletAddress is required',
+        );
+      }
+
+      if (!isValidEthAddress(params.walletAddress)) {
+        throw new SwiftShoprError(
+          'VALIDATION_ERROR',
+          'walletAddress must be a valid Ethereum address',
+        );
+      }
+
+      const body = {
+        storeId: params.storeId,
+        walletAddress: params.walletAddress,
+        ...(params.storeName && { storeName: params.storeName }),
+        ...(params.webhookUrl && { webhookUrl: params.webhookUrl }),
+        ...(params.branding && { branding: params.branding }),
+      };
+
+      const response = await http.post('/api/v1/sdk/config/stores', body);
+
+      if (!response.success) {
+        throw new SwiftShoprError(
+          'CONFIG_ERROR',
+          response.error || 'Failed to register store',
+        );
+      }
+
+      return response.store;
+    },
+
+    /**
+     * Update a store configuration
+     *
+     * @param {string} storeId - Store ID to update
+     * @param {Object} updates - Fields to update
+     * @returns {Promise<Object>} Updated store
+     */
+    async updateStore(storeId, updates) {
+      if (!storeId) {
+        throw new SwiftShoprError('VALIDATION_ERROR', 'storeId is required');
+      }
+
+      if (updates.walletAddress && !isValidEthAddress(updates.walletAddress)) {
+        throw new SwiftShoprError(
+          'VALIDATION_ERROR',
+          'walletAddress must be a valid Ethereum address',
+        );
+      }
+
+      const response = await http.put(
+        `/api/v1/sdk/config/stores/${encodeURIComponent(storeId)}`,
+        updates,
+      );
+
+      if (!response.success) {
+        throw new SwiftShoprError(
+          'CONFIG_ERROR',
+          response.error || 'Failed to update store',
+        );
+      }
+
+      return response.store;
+    },
+
+    /**
+     * Deactivate a store
+     *
+     * @param {string} storeId - Store ID to deactivate
+     * @returns {Promise<Object>} Confirmation
+     */
+    async deactivateStore(storeId) {
+      if (!storeId) {
+        throw new SwiftShoprError('VALIDATION_ERROR', 'storeId is required');
+      }
+
+      const response = await http.delete(
+        `/api/v1/sdk/config/stores/${encodeURIComponent(storeId)}`,
+      );
+
+      if (!response.success) {
+        throw new SwiftShoprError(
+          'CONFIG_ERROR',
+          response.error || 'Failed to deactivate store',
+        );
+      }
+
+      return { message: response.message };
+    },
+
+    /**
+     * Rotate webhook secret for a specific store
+     *
+     * @param {string} storeId - Store ID
+     * @returns {Promise<Object>} New webhook secret
+     */
+    async rotateStoreWebhookSecret(storeId) {
+      if (!storeId) {
+        throw new SwiftShoprError('VALIDATION_ERROR', 'storeId is required');
+      }
+
+      const response = await http.post(
+        `/api/v1/sdk/config/stores/${encodeURIComponent(storeId)}/webhook/rotate-secret`,
+        {},
+      );
+
+      if (!response.success) {
+        throw new SwiftShoprError(
+          'CONFIG_ERROR',
+          response.error || 'Failed to rotate store webhook secret',
+        );
+      }
+
+      return {
+        url: response.webhook.url,
+        secret: response.webhook.secret,
+        message: response.message,
+      };
+    },
+  };
+}
+
+module.exports = { createConfigAPI };

package/src/dashboard.js

@@ -0,0 +1,265 @@
+/**
+ * Dashboard API Module
+ * Retailer analytics and transaction management
+ */
+
+const { SwiftShoprError } = require('./utils/http');
+
+/**
+ * Build query string from params
+ */
+function buildQueryString(params) {
+  const searchParams = new URLSearchParams();
+
+  Object.entries(params).forEach(([key, value]) => {
+    if (value !== undefined && value !== null && value !== '') {
+      searchParams.append(key, value);
+    }
+  });
+
+  const query = searchParams.toString();
+  return query ? `?${query}` : '';
+}
+
+/**
+ * Create Dashboard API instance
+ */
+function createDashboardAPI(http) {
+  return {
+    /**
+     * Get dashboard summary metrics
+     *
+     * @returns {Promise<Object>} Summary with today, week, month metrics
+     */
+    async getSummary() {
+      const response = await http.get('/api/v1/sdk/dashboard/summary');
+
+      return {
+        today: {
+          revenue: response.today?.revenue || 0,
+          transactionCount: response.today?.transaction_count || 0,
+          completed: response.today?.completed || 0,
+          pending: response.today?.pending || 0,
+          failed: response.today?.failed || 0,
+          revenueTrendPercent: response.today?.revenue_trend_percent || 0,
+        },
+        week: {
+          revenue: response.week?.revenue || 0,
+          transactionCount: response.week?.transaction_count || 0,
+          completed: response.week?.completed || 0,
+        },
+        month: {
+          revenue: response.month?.revenue || 0,
+          transactionCount: response.month?.transaction_count || 0,
+          completed: response.month?.completed || 0,
+          avgTransaction: response.month?.avg_transaction || 0,
+          estimatedCardSavings: response.month?.estimated_card_savings || 0,
+        },
+      };
+    },
+
+    /**
+     * Get paginated transaction list
+     *
+     * @param {Object} [params]
+     * @param {string} [params.status] - Filter by status (completed, pending, failed)
+     * @param {string} [params.storeId] - Filter by store
+     * @param {string} [params.startDate] - Start date (ISO format)
+     * @param {string} [params.endDate] - End date (ISO format)
+     * @param {number} [params.limit=50] - Results per page
+     * @param {number} [params.offset=0] - Pagination offset
+     * @param {string} [params.sort=-created_at] - Sort field
+     * @returns {Promise<Object>} Transactions with pagination
+     */
+    async getTransactions(params = {}) {
+      const query = buildQueryString({
+        status: params.status,
+        store_id: params.storeId,
+        start_date: params.startDate,
+        end_date: params.endDate,
+        limit: params.limit || 50,
+        offset: params.offset || 0,
+        sort: params.sort || '-created_at',
+      });
+
+      const response = await http.get(
+        `/api/v1/sdk/dashboard/transactions${query}`,
+      );
+
+      return {
+        transactions: (response.transactions || []).map((tx) => ({
+          id: tx.id,
+          orderId: tx.order_id,
+          status: tx.status,
+          amount: tx.amount,
+          storeId: tx.store_id,
+          txHash: tx.tx_hash,
+          explorerUrl: tx.explorer_url,
+          createdAt: tx.created_at,
+          confirmedAt: tx.confirmed_at,
+          refund: tx.refund
+            ? {
+                status: tx.refund.status,
+                amount: tx.refund.amount,
+                txHash: tx.refund.tx_hash,
+                refundedAt: tx.refund.refunded_at,
+              }
+            : null,
+        })),
+        pagination: {
+          total: response.pagination?.total || 0,
+          limit: response.pagination?.limit || 50,
+          offset: response.pagination?.offset || 0,
+          hasMore: response.pagination?.has_more || false,
+        },
+      };
+    },
+
+    /**
+     * Get all transactions (auto-paginated)
+     *
+     * @param {Object} [params] - Same as getTransactions
+     * @param {number} [params.maxResults=1000] - Maximum total results
+     * @returns {Promise<Array>} All matching transactions
+     */
+    async getAllTransactions(params = {}) {
+      const maxResults = params.maxResults || 1000;
+      const limit = 100;
+      let offset = 0;
+      const allTransactions = [];
+
+      while (allTransactions.length < maxResults) {
+        const { transactions, pagination } = await this.getTransactions({
+          ...params,
+          limit,
+          offset,
+        });
+
+        allTransactions.push(...transactions);
+
+        if (!pagination.hasMore || transactions.length === 0) {
+          break;
+        }
+
+        offset += limit;
+      }
+
+      return allTransactions.slice(0, maxResults);
+    },
+
+    /**
+     * Get store-level breakdown
+     *
+     * @returns {Promise<Array>} Store metrics
+     */
+    async getStores() {
+      const response = await http.get('/api/v1/sdk/dashboard/stores');
+
+      return (response.stores || response || []).map((store) => ({
+        storeId: store.store_id,
+        storeName: store.store_name,
+        revenue: store.revenue || 0,
+        transactionCount: store.transaction_count || 0,
+        completed: store.completed || 0,
+        pending: store.pending || 0,
+        failed: store.failed || 0,
+        successRate: store.success_rate || 0,
+        avgTransaction: store.avg_transaction || 0,
+      }));
+    },
+
+    /**
+     * Get daily metrics for charts
+     *
+     * @param {Object} [params]
+     * @param {number} [params.days=30] - Number of days
+     * @param {string} [params.storeId] - Filter by store
+     * @returns {Promise<Array>} Daily data points
+     */
+    async getDaily(params = {}) {
+      const query = buildQueryString({
+        days: params.days || 30,
+        store_id: params.storeId,
+      });
+
+      const response = await http.get(`/api/v1/sdk/dashboard/daily${query}`);
+
+      return (response.daily || response || []).map((day) => ({
+        date: day.date,
+        revenue: day.revenue || 0,
+        transactionCount: day.transaction_count || 0,
+        completed: day.completed || 0,
+        failed: day.failed || 0,
+        avgTransaction: day.avg_transaction || 0,
+      }));
+    },
+
+    /**
+     * Export transactions as CSV
+     *
+     * @param {Object} [params]
+     * @param {string} [params.startDate] - Start date
+     * @param {string} [params.endDate] - End date
+     * @param {string} [params.status] - Filter by status
+     * @param {string} [params.storeId] - Filter by store
+     * @returns {Promise<string>} CSV data
+     */
+    async export(params = {}) {
+      const query = buildQueryString({
+        start_date: params.startDate,
+        end_date: params.endDate,
+        status: params.status,
+        store_id: params.storeId,
+        format: 'csv',
+      });
+
+      const response = await http.get(`/api/v1/sdk/dashboard/export${query}`);
+
+      // Response might be CSV string or object with csv property
+      return typeof response === 'string' ? response : response.csv || response;
+    },
+
+    /**
+     * Get revenue analytics
+     *
+     * @param {Object} [params]
+     * @param {string} [params.period] - 'day', 'week', 'month', 'year'
+     * @param {number} [params.periods=12] - Number of periods
+     * @returns {Promise<Object>} Revenue analytics
+     */
+    async getRevenueAnalytics(params = {}) {
+      const period = params.period || 'month';
+      const periods = params.periods || 12;
+
+      // Get daily data and aggregate
+      const days =
+        period === 'day'
+          ? periods
+          : period === 'week'
+            ? periods * 7
+            : period === 'month'
+              ? periods * 30
+              : periods * 365;
+
+      const daily = await this.getDaily({ days: Math.min(days, 365) });
+
+      const totalRevenue = daily.reduce((sum, d) => sum + d.revenue, 0);
+      const totalTransactions = daily.reduce(
+        (sum, d) => sum + d.transactionCount,
+        0,
+      );
+      const avgDaily = daily.length > 0 ? totalRevenue / daily.length : 0;
+
+      return {
+        totalRevenue,
+        totalTransactions,
+        averageDailyRevenue: avgDaily,
+        averageTransactionValue:
+          totalTransactions > 0 ? totalRevenue / totalTransactions : 0,
+        dataPoints: daily,
+      };
+    },
+  };
+}
+
+module.exports = { createDashboardAPI };

package/src/index.js

@@ -0,0 +1,79 @@
+/**
+ * swiftshopr-payments
+ *
+ * Official Node.js SDK for SwiftShopr Payments API
+ * Accept USDC payments with zero chargebacks
+ *
+ * @example
+ * const { SwiftShoprClient } = require('swiftshopr-payments');
+ *
+ * const client = new SwiftShoprClient({
+ *   apiKey: 'sk_live_...',
+ * });
+ *
+ * // Create onramp session (Add Funds)
+ * const session = await client.payments.createSession({
+ *   amount: 25.00,
+ *   orderId: 'ORDER-123',
+ *   storeId: 'STORE001',
+ * });
+ *
+ * // Create direct transfer (Purchase)
+ * const transfer = await client.payments.createTransfer({
+ *   amount: 25.00,
+ *   userWalletAddress: '0x...',
+ *   storeId: 'STORE001',
+ * });
+ *
+ * // Check payment status
+ * const status = await client.payments.getStatus(transfer.intentId);
+ *
+ * // Request refund
+ * const refund = await client.refunds.create({
+ *   intentId: transfer.intentId,
+ *   reason: 'Customer request',
+ * });
+ *
+ * // Dashboard metrics
+ * const summary = await client.dashboard.getSummary();
+ */
+
+// Main client
+const { SwiftShoprClient } = require('./client');
+
+// Error types
+const {
+  HttpError,
+  TimeoutError,
+  SwiftShoprError,
+  generateIdempotencyKey,
+} = require('./utils/http');
+
+// Webhook helpers
+const {
+  createWebhooksHelper,
+  webhookMiddleware,
+  WebhookEvents,
+} = require('./webhooks');
+
+// Export everything
+module.exports = {
+  // Main client
+  SwiftShoprClient,
+
+  // Error types
+  HttpError,
+  TimeoutError,
+  SwiftShoprError,
+
+  // Utilities
+  generateIdempotencyKey,
+
+  // Webhook helpers
+  createWebhooksHelper,
+  webhookMiddleware,
+  WebhookEvents,
+
+  // Default export for ESM compatibility
+  default: SwiftShoprClient,
+};