@profullstack/coinpay 0.1.0 → 0.3.0

package/src/client.js

@@ -3,7 +3,7 @@
  * Main client class for interacting with the CoinPay API
  */
 
-const DEFAULT_BASE_URL = 'https://coinpay.dev/api';
+const DEFAULT_BASE_URL = 'https://coinpayportal.com/api';
 
 /**
  * CoinPay API Client
@@ -17,7 +17,7 @@ export class CoinPayClient {
    * Create a new CoinPay client
    * @param {Object} options - Client options
    * @param {string} options.apiKey - Your CoinPay API key
-   * @param {string} [options.baseUrl] - API base URL (default: https://coinpay.dev/api)
+   * @param {string} [options.baseUrl] - API base URL (default: https://coinpayportal.com/api)
    * @param {number} [options.timeout] - Request timeout in ms (default: 30000)
    */
   constructor({ apiKey, baseUrl = DEFAULT_BASE_URL, timeout = 30000 }) {
@@ -47,7 +47,7 @@ export class CoinPayClient {
         signal: controller.signal,
         headers: {
           'Content-Type': 'application/json',
-          'X-API-Key': this.#apiKey,
+          'Authorization': `Bearer ${this.#apiKey}`,
           ...options.headers,
         },
       });
@@ -74,48 +74,142 @@ export class CoinPayClient {
 
   /**
    * Create a new payment
+   *
+   * This is the primary method for merchants to create payment requests.
+   * When a customer needs to pay, call this method to generate a unique
+   * payment address and QR code.
+   *
    * @param {Object} params - Payment parameters
-   * @param {string} params.businessId - Business ID
-   * @param {number} params.amount - Amount in fiat currency
-   * @param {string} params.currency - Fiat currency code (USD, EUR, etc.)
-   * @param {string} params.cryptocurrency - Cryptocurrency code (BTC, ETH, etc.)
-   * @param {string} [params.description] - Payment description
-   * @param {string} [params.metadata] - Custom metadata (JSON string)
-   * @param {string} [params.callbackUrl] - Webhook callback URL
-   * @returns {Promise<Object>} Created payment
+   * @param {string} params.businessId - Business ID (from your CoinPay dashboard)
+   * @param {number} params.amount - Amount in fiat currency (e.g., 100.00)
+   * @param {string} [params.currency='USD'] - Fiat currency code (USD, EUR, etc.)
+   * @param {string} params.blockchain - Blockchain/cryptocurrency (BTC, ETH, SOL, POL, BCH, USDC_ETH, USDC_POL, USDC_SOL)
+   * @param {string} [params.description] - Payment description (shown to customer)
+   * @param {Object} [params.metadata] - Custom metadata (e.g., { orderId: 'ORD-123', customerId: 'CUST-456' })
+   * @returns {Promise<Object>} Created payment with address and QR code
+   *
+   * @example
+   * // Create a $50 payment in Bitcoin
+   * const payment = await client.createPayment({
+   *   businessId: 'your-business-id',
+   *   amount: 50.00,
+   *   currency: 'USD',
+   *   blockchain: 'BTC',
+   *   description: 'Order #12345',
+   *   metadata: { orderId: '12345', customerEmail: 'customer@example.com' }
+   * });
+   *
+   * // Display payment.payment_address and payment.qr_code to customer
    */
   async createPayment({
     businessId,
     amount,
-    currency,
-    cryptocurrency,
+    currency = 'USD',
+    blockchain,
     description,
     metadata,
-    callbackUrl,
   }) {
+    // Map to API field names (snake_case)
     return this.request('/payments/create', {
       method: 'POST',
       body: JSON.stringify({
-        businessId,
+        business_id: businessId,
         amount,
         currency,
-        cryptocurrency,
+        blockchain: blockchain?.toUpperCase(),
         description,
         metadata,
-        callbackUrl,
       }),
     });
   }
 
   /**
    * Get payment by ID
+   *
+   * Use this to check the current status of a payment. You can poll this
+   * endpoint to wait for payment completion, or use webhooks for real-time
+   * notifications.
+   *
    * @param {string} paymentId - Payment ID
-   * @returns {Promise<Object>} Payment details
+   * @returns {Promise<Object>} Payment details including status
+   *
+   * @example
+   * const result = await client.getPayment('pay_abc123');
+   * console.log(result.payment.status); // 'pending', 'confirmed', 'forwarded', etc.
    */
   async getPayment(paymentId) {
     return this.request(`/payments/${paymentId}`);
   }
 
+  /**
+   * Wait for payment to reach a terminal status
+   *
+   * Polls the payment status until it reaches a terminal state (confirmed,
+   * forwarded, expired, or failed). Useful for simple integrations that
+   * don't use webhooks.
+   *
+   * For production use, webhooks are recommended over polling.
+   *
+   * @param {string} paymentId - Payment ID
+   * @param {Object} [options] - Polling options
+   * @param {number} [options.interval=5000] - Polling interval in ms (default: 5 seconds)
+   * @param {number} [options.timeout=3600000] - Maximum wait time in ms (default: 1 hour)
+   * @param {string[]} [options.targetStatuses] - Statuses to wait for (default: ['confirmed', 'forwarded', 'expired', 'failed'])
+   * @param {Function} [options.onStatusChange] - Callback when status changes
+   * @returns {Promise<Object>} Final payment details
+   *
+   * @example
+   * // Simple usage - wait for payment to complete
+   * const payment = await client.waitForPayment('pay_abc123');
+   * if (payment.payment.status === 'confirmed' || payment.payment.status === 'forwarded') {
+   *   console.log('Payment successful!');
+   * }
+   *
+   * @example
+   * // With status change callback
+   * const payment = await client.waitForPayment('pay_abc123', {
+   *   interval: 3000,
+   *   timeout: 600000, // 10 minutes
+   *   onStatusChange: (status, payment) => {
+   *     console.log(`Payment status: ${status}`);
+   *   }
+   * });
+   */
+  async waitForPayment(paymentId, options = {}) {
+    const {
+      interval = 5000,
+      timeout = 3600000,
+      targetStatuses = ['confirmed', 'forwarded', 'expired', 'failed'],
+      onStatusChange,
+    } = options;
+
+    const startTime = Date.now();
+    let lastStatus = null;
+
+    while (Date.now() - startTime < timeout) {
+      const result = await this.getPayment(paymentId);
+      const currentStatus = result.payment?.status;
+
+      // Notify on status change
+      if (currentStatus !== lastStatus) {
+        if (onStatusChange && lastStatus !== null) {
+          onStatusChange(currentStatus, result.payment);
+        }
+        lastStatus = currentStatus;
+      }
+
+      // Check if we've reached a target status
+      if (targetStatuses.includes(currentStatus)) {
+        return result;
+      }
+
+      // Wait before next poll
+      await new Promise(resolve => setTimeout(resolve, interval));
+    }
+
+    throw new Error(`Payment status check timed out after ${timeout}ms`);
+  }
+
   /**
    * List payments for a business
    * @param {Object} params - Query parameters
@@ -140,13 +234,66 @@ export class CoinPayClient {
   }
 
   /**
-   * Get payment QR code
+   * Get payment QR code URL
+   *
+   * Returns the URL to the QR code image endpoint. The endpoint returns
+   * binary PNG image data that can be used directly in an <img> tag.
+   *
    * @param {string} paymentId - Payment ID
-   * @param {string} [format] - QR code format (png, svg)
-   * @returns {Promise<Object>} QR code data
+   * @returns {string} URL to the QR code image
+   *
+   * @example
+   * // Get QR code URL for use in HTML
+   * const qrUrl = client.getPaymentQRUrl('pay_abc123');
+   * // Use in HTML: <img src={qrUrl} alt="Payment QR Code" />
    */
-  async getPaymentQR(paymentId, format = 'png') {
-    return this.request(`/payments/${paymentId}/qr?format=${format}`);
+  getPaymentQRUrl(paymentId) {
+    return `${this.#baseUrl}/payments/${paymentId}/qr`;
+  }
+
+  /**
+   * Get payment QR code as binary image data
+   *
+   * Fetches the QR code image as binary data (ArrayBuffer).
+   * Useful for server-side processing or saving to file.
+   *
+   * @param {string} paymentId - Payment ID
+   * @returns {Promise<ArrayBuffer>} QR code image as binary data
+   *
+   * @example
+   * // Get QR code as binary data
+   * const imageData = await client.getPaymentQR('pay_abc123');
+   * // Save to file (Node.js)
+   * fs.writeFileSync('qr.png', Buffer.from(imageData));
+   */
+  async getPaymentQR(paymentId) {
+    const url = `${this.#baseUrl}/payments/${paymentId}/qr`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.#timeout);
+
+    try {
+      const response = await fetch(url, {
+        signal: controller.signal,
+        headers: {
+          'Authorization': `Bearer ${this.#apiKey}`,
+        },
+      });
+
+      if (!response.ok) {
+        const error = new Error(`HTTP ${response.status}`);
+        error.status = response.status;
+        throw error;
+      }
+
+      return response.arrayBuffer();
+    } catch (error) {
+      if (error.name === 'AbortError') {
+        throw new Error(`Request timeout after ${this.#timeout}ms`);
+      }
+      throw error;
+    } finally {
+      clearTimeout(timeoutId);
+    }
   }
 
   /**

package/src/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @profullstack/coinpay - CoinPay SDK
+ * Cryptocurrency payment integration for Node.js
+ *
+ * @module @profullstack/coinpay
+ */
+
+export { CoinPayClient } from './client.js';
+export type { CoinPayClientOptions, PaymentParams, ListPaymentsParams, WaitForPaymentOptions, CreateBusinessParams } from './client.js';
+
+export {
+  createPayment,
+  getPayment,
+  listPayments,
+  Blockchain,
+  Cryptocurrency,
+  PaymentStatus,
+  FiatCurrency,
+} from './payments.js';
+export type { CreatePaymentParams, GetPaymentParams, ListPaymentsFnParams } from './payments.js';
+
+export {
+  verifyWebhookSignature,
+  generateWebhookSignature,
+  parseWebhookPayload,
+  createWebhookHandler,
+  WebhookEvent,
+} from './webhooks.js';
+export type {
+  VerifyWebhookParams,
+  GenerateWebhookParams,
+  WebhookHandlerOptions,
+  ParsedWebhookEvent,
+} from './webhooks.js';
+
+import { CoinPayClient } from './client.js';
+export default CoinPayClient;

package/src/index.js

@@ -3,10 +3,31 @@
  * Cryptocurrency payment integration for Node.js
  *
  * @module @profullstack/coinpay
+ *
+ * @example
+ * // Quick start
+ * import { CoinPayClient, Blockchain } from '@profullstack/coinpay';
+ *
+ * const client = new CoinPayClient({ apiKey: 'cp_live_xxxxx' });
+ *
+ * const payment = await client.createPayment({
+ *   businessId: 'your-business-id',
+ *   amount: 100,
+ *   blockchain: Blockchain.BTC,
+ *   description: 'Order #12345'
+ * });
  */
 
 import { CoinPayClient } from './client.js';
-import { createPayment, getPayment, listPayments } from './payments.js';
+import {
+  createPayment,
+  getPayment,
+  listPayments,
+  Blockchain,
+  Cryptocurrency,
+  PaymentStatus,
+  FiatCurrency,
+} from './payments.js';
 import {
   verifyWebhookSignature,
   generateWebhookSignature,
@@ -16,10 +37,21 @@ import {
 } from './webhooks.js';
 
 export {
+  // Client
   CoinPayClient,
+  
+  // Payment functions
   createPayment,
   getPayment,
   listPayments,
+  
+  // Constants
+  Blockchain,
+  Cryptocurrency,  // Deprecated, use Blockchain
+  PaymentStatus,
+  FiatCurrency,
+  
+  // Webhook utilities
   verifyWebhookSignature,
   generateWebhookSignature,
   parseWebhookPayload,

package/src/payments.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Payment utilities for CoinPay SDK
+ *
+ * Standalone functions for creating and managing payments without
+ * manually instantiating a `CoinPayClient`.
+ */
+
+import { CoinPayClient } from './client.js';
+
+/** Parameters for the standalone `createPayment` function */
+export interface CreatePaymentParams {
+  /** API key — required if `client` is not provided */
+  apiKey?: string;
+  /** Existing CoinPayClient instance (takes precedence over `apiKey`) */
+  client?: CoinPayClient;
+  /** Business ID from your CoinPay dashboard */
+  businessId: string;
+  /** Amount in fiat currency */
+  amount: number;
+  /** Fiat currency code (default: `'USD'`) */
+  currency?: string;
+  /** Blockchain code: `BTC`, `ETH`, `SOL`, `POL`, `BCH`, `USDC_ETH`, `USDC_POL`, `USDC_SOL` */
+  blockchain: string;
+  /** Payment description shown to the customer */
+  description?: string;
+  /** Custom metadata for your records */
+  metadata?: Record<string, unknown>;
+}
+
+/** Parameters for the standalone `getPayment` function */
+export interface GetPaymentParams {
+  /** API key — required if `client` is not provided */
+  apiKey?: string;
+  /** Existing CoinPayClient instance */
+  client?: CoinPayClient;
+  /** Payment ID to look up */
+  paymentId: string;
+}
+
+/** Parameters for the standalone `listPayments` function */
+export interface ListPaymentsFnParams {
+  /** API key — required if `client` is not provided */
+  apiKey?: string;
+  /** Existing CoinPayClient instance */
+  client?: CoinPayClient;
+  /** Business ID */
+  businessId: string;
+  /** Filter by payment status */
+  status?: string;
+  /** Number of results (default: `20`) */
+  limit?: number;
+  /** Pagination offset */
+  offset?: number;
+}
+
+/**
+ * Create a payment using an API key or existing client.
+ *
+ * Convenience wrapper — for multiple operations, prefer creating a
+ * `CoinPayClient` instance and reusing it.
+ *
+ * @example
+ * ```typescript
+ * import { createPayment, Blockchain } from '@profullstack/coinpay';
+ *
+ * const result = await createPayment({
+ *   apiKey: 'cp_live_xxxxx',
+ *   businessId: 'biz_123',
+ *   amount: 50,
+ *   blockchain: Blockchain.BTC,
+ * });
+ * console.log(result.payment.payment_address);
+ * ```
+ */
+export function createPayment(params: CreatePaymentParams): Promise<Record<string, unknown>>;
+
+/**
+ * Get a payment by ID.
+ *
+ * @example
+ * ```typescript
+ * const result = await getPayment({
+ *   apiKey: 'cp_live_xxxxx',
+ *   paymentId: 'pay_abc123',
+ * });
+ * console.log(result.payment.status);
+ * ```
+ */
+export function getPayment(params: GetPaymentParams): Promise<Record<string, unknown>>;
+
+/**
+ * List payments for a business.
+ *
+ * @example
+ * ```typescript
+ * const result = await listPayments({
+ *   apiKey: 'cp_live_xxxxx',
+ *   businessId: 'biz_123',
+ *   status: 'completed',
+ *   limit: 10,
+ * });
+ * console.log(result.payments);
+ * ```
+ */
+export function listPayments(params: ListPaymentsFnParams): Promise<Record<string, unknown>>;
+
+/**
+ * Supported blockchains/cryptocurrencies.
+ *
+ * Use these constants when creating payments to avoid typos.
+ */
+export declare const Blockchain: {
+  /** Bitcoin */
+  readonly BTC: 'BTC';
+  /** Bitcoin Cash */
+  readonly BCH: 'BCH';
+  /** Ethereum */
+  readonly ETH: 'ETH';
+  /** Polygon (POL) */
+  readonly POL: 'POL';
+  /** Solana */
+  readonly SOL: 'SOL';
+  /** USDC on Ethereum */
+  readonly USDC_ETH: 'USDC_ETH';
+  /** USDC on Polygon */
+  readonly USDC_POL: 'USDC_POL';
+  /** USDC on Solana */
+  readonly USDC_SOL: 'USDC_SOL';
+};
+
+/**
+ * @deprecated Use `Blockchain` instead.
+ */
+export declare const Cryptocurrency: typeof Blockchain;
+
+/** Payment status constants */
+export declare const PaymentStatus: {
+  readonly PENDING: 'pending';
+  readonly CONFIRMING: 'confirming';
+  readonly COMPLETED: 'completed';
+  readonly EXPIRED: 'expired';
+  readonly FAILED: 'failed';
+  readonly REFUNDED: 'refunded';
+};
+
+/** Supported fiat currencies */
+export declare const FiatCurrency: {
+  readonly USD: 'USD';
+  readonly EUR: 'EUR';
+  readonly GBP: 'GBP';
+  readonly CAD: 'CAD';
+  readonly AUD: 'AUD';
+};

package/src/payments.js

@@ -1,33 +1,65 @@
 /**
  * Payment utilities for CoinPay SDK
+ *
+ * This module provides helper functions for creating and managing cryptocurrency payments.
+ *
+ * @example
+ * // Quick payment creation
+ * import { createPayment } from '@coinpay/sdk';
+ *
+ * const payment = await createPayment({
+ *   apiKey: 'cp_live_xxxxx',
+ *   businessId: 'your-business-id',
+ *   amount: 100.00,
+ *   blockchain: 'ETH',
+ *   description: 'Order #12345'
+ * });
  */
 
 import { CoinPayClient } from './client.js';
 
 /**
  * Create a payment using a client instance or API key
+ *
+ * This is a convenience function for creating payments without manually
+ * instantiating a client. For multiple operations, create a client instance
+ * and reuse it.
+ *
  * @param {Object} params - Payment parameters
- * @param {string} params.apiKey - API key (if not using client)
- * @param {CoinPayClient} [params.client] - Existing client instance
- * @param {string} params.businessId - Business ID
- * @param {number} params.amount - Amount in fiat currency
- * @param {string} params.currency - Fiat currency code
- * @param {string} params.cryptocurrency - Cryptocurrency code
- * @param {string} [params.description] - Payment description
- * @param {string} [params.metadata] - Custom metadata
- * @param {string} [params.callbackUrl] - Webhook callback URL
- * @returns {Promise<Object>} Created payment
+ * @param {string} params.apiKey - API key (required if not using client)
+ * @param {CoinPayClient} [params.client] - Existing client instance (optional)
+ * @param {string} params.businessId - Business ID from your CoinPay dashboard
+ * @param {number} params.amount - Amount in fiat currency (e.g., 100.00)
+ * @param {string} [params.currency='USD'] - Fiat currency code (USD, EUR, etc.)
+ * @param {string} params.blockchain - Blockchain to use (BTC, ETH, SOL, POL, BCH, USDC_ETH, USDC_POL, USDC_SOL)
+ * @param {string} [params.description] - Payment description shown to customer
+ * @param {Object} [params.metadata] - Custom metadata for your records
+ * @returns {Promise<Object>} Created payment with address and QR code
+ *
+ * @example
+ * // Create a Bitcoin payment
+ * const payment = await createPayment({
+ *   apiKey: 'cp_live_xxxxx',
+ *   businessId: 'biz_123',
+ *   amount: 50.00,
+ *   currency: 'USD',
+ *   blockchain: 'BTC',
+ *   description: 'Premium subscription',
+ *   metadata: { userId: 'user_456', plan: 'premium' }
+ * });
+ *
+ * console.log('Payment address:', payment.payment.payment_address);
+ * console.log('Amount in BTC:', payment.payment.crypto_amount);
  */
 export async function createPayment({
   apiKey,
   client,
   businessId,
   amount,
-  currency,
-  cryptocurrency,
+  currency = 'USD',
+  blockchain,
   description,
   metadata,
-  callbackUrl,
 }) {
   const coinpay = client || new CoinPayClient({ apiKey });
   
@@ -35,10 +67,9 @@ export async function createPayment({
     businessId,
     amount,
     currency,
-    cryptocurrency,
+    blockchain,
     description,
     metadata,
-    callbackUrl,
   });
 }
 
@@ -91,16 +122,44 @@ export const PaymentStatus = {
 };
 
 /**
- * Supported cryptocurrencies
+ * Supported blockchains/cryptocurrencies
+ *
+ * Use these constants when creating payments to ensure valid blockchain values.
+ *
+ * @example
+ * import { Blockchain, createPayment } from '@coinpay/sdk';
+ *
+ * const payment = await createPayment({
+ *   apiKey: 'cp_live_xxxxx',
+ *   businessId: 'biz_123',
+ *   amount: 100,
+ *   blockchain: Blockchain.ETH
+ * });
  */
-export const Cryptocurrency = {
+export const Blockchain = {
+  /** Bitcoin */
   BTC: 'BTC',
+  /** Bitcoin Cash */
   BCH: 'BCH',
+  /** Ethereum */
   ETH: 'ETH',
-  MATIC: 'MATIC',
+  /** Polygon (POL) */
+  POL: 'POL',
+  /** Solana */
   SOL: 'SOL',
+  /** USDC on Ethereum */
+  USDC_ETH: 'USDC_ETH',
+  /** USDC on Polygon */
+  USDC_POL: 'USDC_POL',
+  /** USDC on Solana */
+  USDC_SOL: 'USDC_SOL',
 };
 
+/**
+ * @deprecated Use Blockchain instead
+ */
+export const Cryptocurrency = Blockchain;
+
 /**
  * Supported fiat currencies
  */
@@ -117,6 +176,7 @@ export default {
   getPayment,
   listPayments,
   PaymentStatus,
+  Blockchain,
   Cryptocurrency,
   FiatCurrency,
 };