swiftshopr-payments 1.0.0 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swiftshopr-payments",
-  "version": "1.0.0",
+  "version": "1.1.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",

package/src/client.js

@@ -6,6 +6,7 @@
 const { createHttpClient, SwiftShoprError } = require('./utils/http');
 const { createPaymentsAPI } = require('./payments');
 const { createRefundsAPI } = require('./refunds');
+const { createReceiptsAPI } = require('./receipts');
 const { createDashboardAPI } = require('./dashboard');
 const { createBrandingAPI } = require('./branding');
 const { createConfigAPI } = require('./config');
@@ -72,6 +73,7 @@ class SwiftShoprClient {
     // Initialize API modules
     this.payments = createPaymentsAPI(this._http);
     this.refunds = createRefundsAPI(this._http);
+    this.receipts = createReceiptsAPI(this._http);
     this.dashboard = createDashboardAPI(this._http);
     this.branding = createBrandingAPI(this._http);
     this.config = createConfigAPI(this._http);
@@ -91,7 +93,7 @@ class SwiftShoprClient {
    * Get SDK version
    */
   static get VERSION() {
-    return '1.0.0';
+    return '1.1.0';
   }
 
   /**

package/src/receipts.js

@@ -0,0 +1,262 @@
+/**
+ * E-Receipts API Module
+ *
+ * Generate and verify e-receipts for Scan & Go checkout
+ *
+ * E-Receipt Flow:
+ * 1. Customer pays via USDC
+ * 2. Receipt is generated with verification code
+ * 3. Customer shows e-receipt on phone (screenshot-protected)
+ * 4. Employee visually verifies: code + timestamp + items
+ * 5. Customer exits store
+ *
+ * No hardware/scanners needed - just visual verification
+ */
+
+const { SwiftShoprError } = require('./utils/http');
+
+/**
+ * UUID validation regex
+ */
+const UUID_REGEX =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * Receipt ID validation regex (RCP-XXXXX-XXXXX format)
+ */
+const RECEIPT_ID_REGEX = /^RCP-[A-Z0-9]+-[A-Z0-9]+$/i;
+
+/**
+ * Validate receipt creation parameters
+ */
+function validateCreateParams(params) {
+  const errors = [];
+
+  if (!params.intentId) {
+    errors.push('intentId is required');
+  } else if (!UUID_REGEX.test(params.intentId)) {
+    errors.push('intentId must be a valid UUID');
+  }
+
+  if (!params.storeId) {
+    errors.push('storeId is required');
+  }
+
+  if (!params.items || !Array.isArray(params.items) || params.items.length === 0) {
+    errors.push('items array is required and must not be empty');
+  } else {
+    params.items.forEach((item, index) => {
+      if (!item.barcode) errors.push(`items[${index}].barcode is required`);
+      if (!item.name) errors.push(`items[${index}].name is required`);
+      if (typeof item.price !== 'number' || item.price < 0) {
+        errors.push(`items[${index}].price must be a positive number`);
+      }
+    });
+  }
+
+  if (typeof params.total !== 'number' || params.total <= 0) {
+    errors.push('total must be a positive number');
+  }
+
+  if (errors.length > 0) {
+    throw new SwiftShoprError('VALIDATION_ERROR', errors.join('; '), { errors });
+  }
+}
+
+/**
+ * Create Receipts API instance
+ */
+function createReceiptsAPI(http) {
+  return {
+    /**
+     * Generate an e-receipt after payment completion
+     *
+     * @param {Object} params
+     * @param {string} params.intentId - Payment intent ID (UUID)
+     * @param {string} params.storeId - Store identifier
+     * @param {Array} params.items - Array of purchased items
+     * @param {number} params.subtotal - Subtotal before tax
+     * @param {number} [params.tax=0] - Tax amount
+     * @param {number} params.total - Total amount paid
+     * @param {string} [params.orderId] - Optional order reference
+     * @returns {Promise<Object>} E-receipt with verification code
+     *
+     * @example
+     * const receipt = await client.receipts.create({
+     *   intentId: 'abc-123-def',
+     *   storeId: 'STORE001',
+     *   items: [
+     *     { barcode: '012345678901', name: 'Coca-Cola', quantity: 2, price: 2.49, total: 4.98 }
+     *   ],
+     *   subtotal: 4.98,
+     *   tax: 0.40,
+     *   total: 5.38
+     * });
+     *
+     * console.log(receipt.verificationCode); // "A7B3C9D2"
+     */
+    async create(params) {
+      validateCreateParams(params);
+
+      // Format items for API
+      const formattedItems = params.items.map(item => ({
+        barcode: item.barcode,
+        name: item.name,
+        quantity: item.quantity || 1,
+        price: item.price,
+        total: item.total || (item.price * (item.quantity || 1)),
+      }));
+
+      const body = {
+        intent_id: params.intentId,
+        store_id: params.storeId,
+        items: formattedItems,
+        subtotal: params.subtotal || params.total,
+        tax: params.tax || 0,
+        total: params.total,
+        ...(params.orderId && { order_id: params.orderId }),
+      };
+
+      const response = await http.post('/api/v1/sdk/receipts', body);
+
+      if (!response.success) {
+        throw new SwiftShoprError(
+          response.code || 'RECEIPT_ERROR',
+          response.error || 'Failed to create receipt',
+          response
+        );
+      }
+
+      return formatReceiptResponse(response.receipt);
+    },
+
+    /**
+     * Get an e-receipt by receipt ID
+     *
+     * @param {string} receiptId - Receipt ID (RCP-XXXXX-XXXXX format)
+     * @returns {Promise<Object>} E-receipt details
+     */
+    async get(receiptId) {
+      if (!receiptId) {
+        throw new SwiftShoprError('VALIDATION_ERROR', 'receiptId is required');
+      }
+
+      const response = await http.get(`/api/v1/sdk/receipts/${receiptId}`);
+
+      if (!response.success) {
+        throw new SwiftShoprError(
+          response.code || 'RECEIPT_ERROR',
+          response.error || 'Failed to get receipt',
+          response
+        );
+      }
+
+      return formatReceiptResponse(response.receipt);
+    },
+
+    /**
+     * Get receipt by payment intent ID
+     *
+     * @param {string} intentId - Payment intent ID (UUID)
+     * @returns {Promise<Object>} E-receipt details
+     */
+    async getByIntent(intentId) {
+      if (!intentId) {
+        throw new SwiftShoprError('VALIDATION_ERROR', 'intentId is required');
+      }
+
+      const response = await http.get(`/api/v1/sdk/receipts/intent/${intentId}`);
+
+      if (!response.success) {
+        throw new SwiftShoprError(
+          response.code || 'RECEIPT_ERROR',
+          response.error || 'Failed to get receipt',
+          response
+        );
+      }
+
+      return formatReceiptResponse(response.receipt);
+    },
+
+    /**
+     * Verify an e-receipt (for employee verification)
+     *
+     * This is typically called by a store employee's device to verify
+     * the receipt shown on the customer's phone.
+     *
+     * @param {string} receiptId - Receipt ID to verify
+     * @param {Object} [options]
+     * @param {string} [options.location='exit'] - Verification location
+     * @returns {Promise<Object>} Verification result
+     *
+     * @example
+     * const result = await client.receipts.verify('RCP-ABC123-XYZ789');
+     *
+     * if (result.valid) {
+     *   console.log('Verification code:', result.verificationCode);
+     *   console.log('Receipt age:', result.ageMinutes, 'minutes');
+     *   console.log('Items:', result.items);
+     *   console.log('Total:', result.total);
+     * }
+     */
+    async verify(receiptId, options = {}) {
+      if (!receiptId) {
+        throw new SwiftShoprError('VALIDATION_ERROR', 'receiptId is required');
+      }
+
+      const queryParams = options.location ? `?location=${options.location}` : '';
+      const response = await http.get(`/api/v1/sdk/receipts/${receiptId}/verify${queryParams}`);
+
+      return {
+        valid: response.valid,
+        receiptId: response.receipt_id,
+        verificationCode: response.verification_code,
+        storeId: response.store_id,
+        items: response.items || [],
+        itemCount: response.item_count,
+        total: response.total,
+        createdAt: response.created_at,
+        ageMinutes: response.age_minutes,
+        paymentConfirmed: response.payment_confirmed,
+        txHash: response.tx_hash,
+        firstVerification: response.first_verification,
+        verificationCount: response.verification_count,
+        // Error info if invalid
+        error: response.error,
+        errorCode: response.code,
+      };
+    },
+  };
+}
+
+/**
+ * Format receipt response for SDK consumers
+ */
+function formatReceiptResponse(receipt) {
+  return {
+    receiptId: receipt.receipt_id,
+    verificationCode: receipt.verification_code,
+    intentId: receipt.intent_id,
+    orderId: receipt.order_id,
+    storeId: receipt.store_id,
+    items: receipt.items,
+    itemCount: receipt.item_count,
+    subtotal: receipt.subtotal,
+    tax: receipt.tax,
+    total: receipt.total,
+    payment: {
+      status: receipt.payment?.status,
+      confirmedAt: receipt.payment?.confirmed_at,
+      txHash: receipt.payment?.tx_hash,
+      explorerUrl: receipt.payment?.explorer_url,
+    },
+    createdAt: receipt.created_at,
+    expiresAt: receipt.expires_at,
+    isExpired: receipt.is_expired,
+    verifiedAt: receipt.verified_at,
+    verificationCount: receipt.verification_count,
+    verifyUrl: receipt.verify_url,
+  };
+}
+
+module.exports = { createReceiptsAPI };

package/src/types/index.d.ts

@@ -176,6 +176,112 @@ export interface RefundStatus {
   completedAt: string | null;
 }
 
+// E-Receipt Types
+export interface CreateReceiptParams {
+  /** Payment intent ID */
+  intentId: string;
+  /** Store identifier */
+  storeId: string;
+  /** Items purchased */
+  items: ReceiptItem[];
+  /** Subtotal before tax */
+  subtotal?: number;
+  /** Tax amount */
+  tax?: number;
+  /** Total amount paid */
+  total: number;
+  /** Optional order reference */
+  orderId?: string;
+}
+
+export interface ReceiptItem {
+  /** Product barcode/UPC */
+  barcode: string;
+  /** Product name */
+  name: string;
+  /** Quantity purchased */
+  quantity?: number;
+  /** Unit price */
+  price: number;
+  /** Line total (price * quantity) */
+  total?: number;
+}
+
+export interface EReceipt {
+  /** Receipt ID (RCP-XXXXX-XXXXX format) */
+  receiptId: string;
+  /** 8-character verification code for employee verification */
+  verificationCode: string;
+  /** Payment intent ID */
+  intentId: string;
+  /** Order reference */
+  orderId: string | null;
+  /** Store ID */
+  storeId: string;
+  /** Items purchased */
+  items: ReceiptItem[];
+  /** Number of items */
+  itemCount: number;
+  /** Subtotal before tax */
+  subtotal: number;
+  /** Tax amount */
+  tax: number;
+  /** Total paid */
+  total: number;
+  /** Payment details */
+  payment: {
+    status: string;
+    confirmedAt: string | null;
+    txHash: string | null;
+    explorerUrl: string | null;
+  };
+  /** When receipt was created */
+  createdAt: string;
+  /** When receipt expires */
+  expiresAt: string;
+  /** Whether receipt has expired */
+  isExpired: boolean;
+  /** When receipt was verified by employee */
+  verifiedAt: string | null;
+  /** How many times receipt has been verified */
+  verificationCount: number;
+  /** API endpoint for verification */
+  verifyUrl: string;
+}
+
+export interface ReceiptVerification {
+  /** Whether receipt is valid */
+  valid: boolean;
+  /** Receipt ID */
+  receiptId: string;
+  /** 8-char verification code */
+  verificationCode: string;
+  /** Store ID */
+  storeId: string;
+  /** Items for employee to verify against bag */
+  items: ReceiptItem[];
+  /** Item count */
+  itemCount: number;
+  /** Total paid */
+  total: number;
+  /** When receipt was created */
+  createdAt: string;
+  /** How old the receipt is in minutes */
+  ageMinutes: number;
+  /** Whether payment was confirmed */
+  paymentConfirmed: boolean;
+  /** Transaction hash */
+  txHash: string | null;
+  /** Whether this is the first verification */
+  firstVerification: boolean;
+  /** Total verification count */
+  verificationCount: number;
+  /** Error message if invalid */
+  error?: string;
+  /** Error code if invalid */
+  errorCode?: string;
+}
+
 // Dashboard Types
 export interface DashboardSummary {
   today: {
@@ -341,6 +447,17 @@ export interface RefundsAPI {
   waitForCompletion(refundId: string, options?: WaitOptions): Promise<RefundStatus>;
 }
 
+export interface ReceiptsAPI {
+  /** Generate an e-receipt after payment completion */
+  create(params: CreateReceiptParams): Promise<EReceipt>;
+  /** Get e-receipt by receipt ID */
+  get(receiptId: string): Promise<EReceipt>;
+  /** Get e-receipt by payment intent ID */
+  getByIntent(intentId: string): Promise<EReceipt>;
+  /** Verify e-receipt (for employee verification) */
+  verify(receiptId: string, options?: { location?: string }): Promise<ReceiptVerification>;
+}
+
 export interface DashboardAPI {
   getSummary(): Promise<DashboardSummary>;
   getTransactions(params?: TransactionListParams): Promise<TransactionList>;
@@ -437,6 +554,7 @@ export declare class SwiftShoprClient {
 
   payments: PaymentsAPI;
   refunds: RefundsAPI;
+  receipts: ReceiptsAPI;
   dashboard: DashboardAPI;
   branding: BrandingAPI;
   config: ConfigAPI;