swiftshopr-payments 1.0.0

package/src/types/index.d.ts

@@ -0,0 +1,460 @@
+/**
+ * TypeScript definitions for swiftshopr-payments
+ */
+
+export interface SwiftShoprConfig {
+  /** Your SwiftShopr API key */
+  apiKey: string;
+  /** Webhook secret for signature verification */
+  webhookSecret?: string;
+  /** API base URL (default: production) */
+  baseUrl?: string;
+  /** Request timeout in milliseconds (default: 30000) */
+  timeout?: number;
+  /** Number of retries for failed requests (default: 3) */
+  retries?: number;
+  /** Hook called before each request */
+  onRequest?: (info: RequestInfo) => void;
+  /** Hook called after each response */
+  onResponse?: (info: ResponseInfo) => void;
+  /** Hook called on errors */
+  onError?: (error: Error) => void;
+}
+
+export interface RequestInfo {
+  method: string;
+  url: string;
+  headers: Record<string, string>;
+  body?: unknown;
+}
+
+export interface ResponseInfo {
+  status: number;
+  data: unknown;
+  headers: Headers;
+}
+
+// Payment Types
+export interface CreateSessionParams {
+  /** Amount in USD */
+  amount: number;
+  /** Your order reference */
+  orderId?: string;
+  /** Store ID (resolves wallet automatically) */
+  storeId?: string;
+  /** Retailer wallet address */
+  destinationAddress?: string;
+  /** Payment method (ACH_BANK_ACCOUNT, CARD, etc.) */
+  paymentMethod?: string;
+  /** Custom metadata */
+  metadata?: Record<string, unknown>;
+  /** Idempotency key for safe retries */
+  idempotencyKey?: string;
+}
+
+export interface CreateTransferParams {
+  /** Amount in USD */
+  amount: number;
+  /** User's wallet address */
+  userWalletAddress: string;
+  /** Your order reference */
+  orderId?: string;
+  /** Store ID */
+  storeId?: string;
+  /** Retailer wallet address */
+  destinationAddress?: string;
+  /** Custom metadata */
+  metadata?: Record<string, unknown>;
+  /** Idempotency key */
+  idempotencyKey?: string;
+}
+
+export interface PaymentSession {
+  intentId: string;
+  sessionId: string;
+  orderId: string | null;
+  quoteId: string | null;
+  onrampUrl: string;
+  expiresAt: string;
+  branding: Branding | null;
+}
+
+export interface TransferResult {
+  intentId: string;
+  orderId: string | null;
+  status: string;
+  transfer: {
+    to: string;
+    amount: string;
+    asset: string;
+    network: string;
+    chainId: number;
+  };
+  expiresAt: string;
+  branding: Branding | null;
+}
+
+export interface PaymentStatus {
+  intentId: string;
+  orderId: string | null;
+  status: 'pending' | 'processing' | 'completed' | 'failed' | 'canceled' | 'expired';
+  amount: number;
+  storeId: string | null;
+  destinationAddress: string;
+  txHash: string | null;
+  explorerUrl: string | null;
+  confirmedAt: string | null;
+  createdAt: string;
+  expiresAt: string;
+  isExpired: boolean;
+  refund: RefundInfo | null;
+}
+
+export interface RefundInfo {
+  status: string;
+  amount: number;
+  txHash: string | null;
+  refundedAt: string | null;
+}
+
+export interface WaitOptions {
+  /** Max wait time in ms (default: 300000 for payments, 600000 for refunds) */
+  timeout?: number;
+  /** Poll interval in ms (default: 2000 for payments, 5000 for refunds) */
+  interval?: number;
+  /** Callback on status change */
+  onStatusChange?: (status: PaymentStatus | RefundStatus) => void;
+}
+
+// Refund Types
+export interface CreateRefundParams {
+  /** Original payment intent ID */
+  intentId: string;
+  /** Refund amount (optional, defaults to full refund) */
+  amount?: number;
+  /** Reason for refund */
+  reason?: string;
+  /** Idempotency key */
+  idempotencyKey?: string;
+}
+
+export interface RefundResult {
+  id: string;
+  intentId: string;
+  orderId: string | null;
+  status: 'requested' | 'pending' | 'completed' | 'failed';
+  amount: number;
+  originalAmount: number;
+  isPartial: boolean;
+  reason: string;
+  createdAt: string;
+  instructions: {
+    message: string;
+    transfer: {
+      to: string;
+      amount: string;
+      asset: string;
+      network: string;
+      chainId: number;
+    };
+    fromWallet: string;
+  };
+}
+
+export interface RefundStatus {
+  id: string;
+  intentId: string;
+  orderId: string | null;
+  amount: number;
+  reason: string;
+  status: string;
+  txHash: string | null;
+  explorerUrl: string | null;
+  fromAddress: string;
+  toAddress: string;
+  createdAt: string;
+  completedAt: string | null;
+}
+
+// Dashboard Types
+export interface DashboardSummary {
+  today: {
+    revenue: number;
+    transactionCount: number;
+    completed: number;
+    pending: number;
+    failed: number;
+    revenueTrendPercent: number;
+  };
+  week: {
+    revenue: number;
+    transactionCount: number;
+    completed: number;
+  };
+  month: {
+    revenue: number;
+    transactionCount: number;
+    completed: number;
+    avgTransaction: number;
+    estimatedCardSavings: number;
+  };
+}
+
+export interface TransactionListParams {
+  status?: string;
+  storeId?: string;
+  startDate?: string;
+  endDate?: string;
+  limit?: number;
+  offset?: number;
+  sort?: string;
+}
+
+export interface Transaction {
+  id: string;
+  orderId: string | null;
+  status: string;
+  amount: number;
+  storeId: string | null;
+  txHash: string | null;
+  explorerUrl: string | null;
+  createdAt: string;
+  confirmedAt: string | null;
+  refund: RefundInfo | null;
+}
+
+export interface TransactionList {
+  transactions: Transaction[];
+  pagination: {
+    total: number;
+    limit: number;
+    offset: number;
+    hasMore: boolean;
+  };
+}
+
+export interface StoreMetrics {
+  storeId: string;
+  storeName: string | null;
+  revenue: number;
+  transactionCount: number;
+  completed: number;
+  pending: number;
+  failed: number;
+  successRate: number;
+  avgTransaction: number;
+}
+
+export interface DailyMetrics {
+  date: string;
+  revenue: number;
+  transactionCount: number;
+  completed: number;
+  failed: number;
+  avgTransaction: number;
+}
+
+// Branding Types
+export interface Branding {
+  storeId: string;
+  branding: {
+    name: string | null;
+    logoUrl: string | null;
+    theme: {
+      primaryColor: string;
+      secondaryColor: string;
+      backgroundColor: string;
+      textColor: string;
+      accentColor: string;
+      mode: 'light' | 'dark';
+      fontFamily: string | null;
+    };
+    cdpTheme: Record<string, string> | null;
+  };
+}
+
+// Webhook Types
+export interface WebhookEvent {
+  type: string;
+  data: {
+    intentId: string;
+    orderId: string | null;
+    txHash: string | null;
+    amount: string;
+    status: string;
+    currency: string;
+    network: string;
+    explorerUrl: string | null;
+    storeId: string | null;
+    timestamp: string;
+    refundId?: string;
+    refundAmount?: string;
+    refundReason?: string;
+  };
+  receivedAt: string;
+}
+
+export interface WebhooksHelper {
+  verify(payload: string | object, signature: string, timestamp: string): boolean;
+  constructEvent(payload: string | object, headers: Record<string, string>): WebhookEvent;
+  events: typeof WebhookEvents;
+}
+
+export declare const WebhookEvents: {
+  PAYMENT_COMPLETED: 'payment.completed';
+  PAYMENT_FAILED: 'payment.failed';
+  PAYMENT_EXPIRED: 'payment.expired';
+  REFUND_REQUESTED: 'refund.requested';
+  REFUND_COMPLETED: 'refund.completed';
+  REFUND_FAILED: 'refund.failed';
+};
+
+// Error Types
+export declare class HttpError extends Error {
+  statusCode: number;
+  response: unknown;
+  requestId: string | null;
+}
+
+export declare class TimeoutError extends Error {
+  timeout: number;
+}
+
+export declare class SwiftShoprError extends Error {
+  code: string;
+  details: Record<string, unknown>;
+}
+
+// API Modules
+export interface PaymentsAPI {
+  createSession(params: CreateSessionParams): Promise<PaymentSession>;
+  createTransfer(params: CreateTransferParams): Promise<TransferResult>;
+  getStatus(intentId: string): Promise<PaymentStatus>;
+  getStatusByOrderId(orderId: string): Promise<PaymentStatus>;
+  waitForCompletion(intentId: string, options?: WaitOptions): Promise<PaymentStatus>;
+}
+
+export interface RefundsAPI {
+  create(params: CreateRefundParams): Promise<RefundResult>;
+  get(refundId: string): Promise<RefundStatus>;
+  listForPayment(intentId: string): Promise<RefundStatus[]>;
+  waitForCompletion(refundId: string, options?: WaitOptions): Promise<RefundStatus>;
+}
+
+export interface DashboardAPI {
+  getSummary(): Promise<DashboardSummary>;
+  getTransactions(params?: TransactionListParams): Promise<TransactionList>;
+  getAllTransactions(params?: TransactionListParams & { maxResults?: number }): Promise<Transaction[]>;
+  getStores(): Promise<StoreMetrics[]>;
+  getDaily(params?: { days?: number; storeId?: string }): Promise<DailyMetrics[]>;
+  export(params?: { startDate?: string; endDate?: string; status?: string; storeId?: string }): Promise<string>;
+  getRevenueAnalytics(params?: { period?: 'day' | 'week' | 'month' | 'year'; periods?: number }): Promise<{
+    totalRevenue: number;
+    totalTransactions: number;
+    averageDailyRevenue: number;
+    averageTransactionValue: number;
+    dataPoints: DailyMetrics[];
+  }>;
+}
+
+export interface BrandingAPI {
+  get(storeId: string): Promise<Branding>;
+  toCssVariables(branding: Branding): string;
+  toStyleObject(branding: Branding): Record<string, string>;
+  toCdpTheme(branding: Branding): Record<string, string> | null;
+}
+
+// Config Types
+export interface RetailerConfig {
+  chainId: string;
+  label: string | null;
+  webhook: {
+    url: string | null;
+    hasSecret: boolean;
+  };
+  permissions: Record<string, boolean>;
+  rateLimit: number;
+  allowedIps: string[] | null;
+  createdAt: string;
+  lastUsedAt: string | null;
+  stores: RegisteredStore[];
+}
+
+export interface RegisteredStore {
+  id: string;
+  storeId: string;
+  storeName: string | null;
+  walletAddress: string;
+  webhook: {
+    url: string | null;
+    hasSecret: boolean;
+  } | null;
+  branding: Record<string, unknown>;
+  isActive: boolean;
+  createdAt: string;
+  updatedAt?: string;
+}
+
+export interface WebhookConfig {
+  url: string | null;
+  hasSecret: boolean;
+  secret?: string;
+  message?: string;
+}
+
+export interface RegisterStoreParams {
+  storeId: string;
+  walletAddress: string;
+  storeName?: string;
+  webhookUrl?: string;
+  branding?: Record<string, unknown>;
+}
+
+export interface UpdateStoreParams {
+  storeName?: string;
+  walletAddress?: string;
+  webhookUrl?: string;
+  branding?: Record<string, unknown>;
+  isActive?: boolean;
+}
+
+export interface ConfigAPI {
+  get(): Promise<RetailerConfig>;
+  setWebhook(params?: { url?: string; generateSecret?: boolean }): Promise<WebhookConfig>;
+  rotateWebhookSecret(): Promise<WebhookConfig>;
+  getStores(): Promise<RegisteredStore[]>;
+  registerStore(params: RegisterStoreParams): Promise<RegisteredStore>;
+  updateStore(storeId: string, updates: UpdateStoreParams): Promise<RegisteredStore>;
+  deactivateStore(storeId: string): Promise<{ message: string }>;
+  rotateStoreWebhookSecret(storeId: string): Promise<WebhookConfig>;
+}
+
+// Main Client
+export declare class SwiftShoprClient {
+  constructor(config: SwiftShoprConfig);
+
+  static readonly VERSION: string;
+
+  payments: PaymentsAPI;
+  refunds: RefundsAPI;
+  dashboard: DashboardAPI;
+  branding: BrandingAPI;
+  config: ConfigAPI;
+  webhooks: WebhooksHelper | { configure(secret: string): WebhooksHelper };
+
+  getConfig(): {
+    baseUrl: string;
+    timeout: number;
+    retries: number;
+    hasApiKey: boolean;
+    hasWebhookSecret: boolean;
+  };
+}
+
+// Utility exports
+export declare function generateIdempotencyKey(): string;
+export declare function createWebhooksHelper(secret: string): WebhooksHelper;
+export declare function webhookMiddleware(secret: string): (req: any, res: any, next: any) => void;
+
+// Default export
+export default SwiftShoprClient;

package/src/utils/http.js

@@ -0,0 +1,217 @@
+/**
+ * HTTP Client for SwiftShopr API
+ * Zero dependencies - uses native fetch
+ */
+
+const DEFAULT_BASE_URL = 'https://shopr-scanner-backend.onrender.com';
+const DEFAULT_TIMEOUT = 30000;
+const DEFAULT_RETRIES = 3;
+const RETRY_STATUS_CODES = [408, 429, 500, 502, 503, 504];
+
+class HttpError extends Error {
+  constructor(message, statusCode, response, requestId) {
+    super(message);
+    this.name = 'HttpError';
+    this.statusCode = statusCode;
+    this.response = response;
+    this.requestId = requestId;
+  }
+}
+
+class TimeoutError extends Error {
+  constructor(message, timeout) {
+    super(message);
+    this.name = 'TimeoutError';
+    this.timeout = timeout;
+  }
+}
+
+class SwiftShoprError extends Error {
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = 'SwiftShoprError';
+    this.code = code;
+    this.details = details;
+  }
+}
+
+/**
+ * Sleep for specified milliseconds
+ */
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Generate idempotency key
+ */
+const generateIdempotencyKey = () => {
+  const timestamp = Date.now().toString(36);
+  const random = Math.random().toString(36).substring(2, 10);
+  return `idem_${timestamp}_${random}`;
+};
+
+/**
+ * Create HTTP client with configuration
+ */
+function createHttpClient(config = {}) {
+  const baseUrl = config.baseUrl || DEFAULT_BASE_URL;
+  const { apiKey } = config;
+  const timeout = config.timeout || DEFAULT_TIMEOUT;
+  const maxRetries = config.retries ?? DEFAULT_RETRIES;
+  const onRequest = config.onRequest || null;
+  const onResponse = config.onResponse || null;
+  const onError = config.onError || null;
+
+  if (!apiKey) {
+    throw new SwiftShoprError('CONFIG_ERROR', 'API key is required');
+  }
+
+  /**
+   * Make HTTP request with retries and timeout
+   */
+  async function request(method, path, options = {}) {
+    const url = `${baseUrl}${path}`;
+    const idempotencyKey =
+      options.idempotencyKey ||
+      (['POST', 'PUT', 'PATCH'].includes(method)
+        ? generateIdempotencyKey()
+        : null);
+
+    const headers = {
+      'Content-Type': 'application/json',
+      'x-swiftshopr-key': apiKey,
+      ...(idempotencyKey && { 'Idempotency-Key': idempotencyKey }),
+      ...options.headers,
+    };
+
+    const fetchOptions = {
+      method,
+      headers,
+      ...(options.body && { body: JSON.stringify(options.body) }),
+    };
+
+    // Call onRequest hook
+    if (onRequest) {
+      onRequest({ method, url, headers, body: options.body });
+    }
+
+    let lastError;
+    let attempt = 0;
+
+    while (attempt <= maxRetries) {
+      attempt++;
+
+      try {
+        // Create abort controller for timeout
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+        const response = await fetch(url, {
+          ...fetchOptions,
+          signal: controller.signal,
+        });
+
+        clearTimeout(timeoutId);
+
+        // Parse response
+        const contentType = response.headers.get('content-type');
+        let data;
+
+        if (contentType && contentType.includes('application/json')) {
+          data = await response.json();
+        } else {
+          data = await response.text();
+        }
+
+        // Call onResponse hook
+        if (onResponse) {
+          onResponse({
+            status: response.status,
+            data,
+            headers: response.headers,
+          });
+        }
+
+        // Handle non-2xx responses
+        if (!response.ok) {
+          const error = new HttpError(
+            data?.message || data?.error || `HTTP ${response.status}`,
+            response.status,
+            data,
+            data?.requestId,
+          );
+
+          // Retry on specific status codes
+          if (
+            RETRY_STATUS_CODES.includes(response.status) &&
+            attempt <= maxRetries
+          ) {
+            lastError = error;
+            const backoff = Math.min(1000 * 2 ** (attempt - 1), 10000);
+            await sleep(backoff);
+            continue;
+          }
+
+          if (onError) {
+            onError(error);
+          }
+          throw error;
+        }
+
+        return data;
+      } catch (error) {
+        // Handle abort (timeout)
+        if (error.name === 'AbortError') {
+          const timeoutError = new TimeoutError(
+            `Request timed out after ${timeout}ms`,
+            timeout,
+          );
+
+          if (attempt <= maxRetries) {
+            lastError = timeoutError;
+            const backoff = Math.min(1000 * 2 ** (attempt - 1), 10000);
+            await sleep(backoff);
+            continue;
+          }
+
+          if (onError) {
+            onError(timeoutError);
+          }
+          throw timeoutError;
+        }
+
+        // Network errors - retry
+        if (error.name === 'TypeError' && attempt <= maxRetries) {
+          lastError = error;
+          const backoff = Math.min(1000 * 2 ** (attempt - 1), 10000);
+          await sleep(backoff);
+          continue;
+        }
+
+        if (onError) {
+          onError(error);
+        }
+        throw error;
+      }
+    }
+
+    // All retries exhausted
+    throw lastError;
+  }
+
+  return {
+    get: (path, options) => request('GET', path, options),
+    post: (path, body, options) => request('POST', path, { ...options, body }),
+    put: (path, body, options) => request('PUT', path, { ...options, body }),
+    patch: (path, body, options) =>
+      request('PATCH', path, { ...options, body }),
+    delete: (path, options) => request('DELETE', path, options),
+  };
+}
+
+module.exports = {
+  createHttpClient,
+  HttpError,
+  TimeoutError,
+  SwiftShoprError,
+  generateIdempotencyKey,
+};