@profullstack/coinpay 0.2.0 → 0.3.0

package/bin/coinpay.js

@@ -154,7 +154,7 @@ ${colors.cyan}Options:${colors.reset}
   --business-id <id>      Business ID for operations
   --amount <amount>       Payment amount in fiat currency
   --currency <code>       Fiat currency (USD, EUR, etc.) - default: USD
-  --blockchain <code>     Blockchain (BTC, ETH, SOL, MATIC, BCH, USDC_ETH, USDC_MATIC, USDC_SOL)
+  --blockchain <code>     Blockchain (BTC, ETH, SOL, POL, BCH, USDC_ETH, USDC_POL, USDC_SOL)
   --description <text>    Payment description
 
 ${colors.cyan}Examples:${colors.reset}
@@ -168,7 +168,7 @@ ${colors.cyan}Examples:${colors.reset}
   coinpay payment create --business-id biz_123 --amount 50 --blockchain ETH --description "Order #12345"
 
   # Create a USDC payment on Polygon
-  coinpay payment create --business-id biz_123 --amount 25 --blockchain USDC_MATIC
+  coinpay payment create --business-id biz_123 --amount 25 --blockchain USDC_POL
 
   # Get payment status
   coinpay payment get pay_abc123

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@profullstack/coinpay",
-  "version": "0.2.0",
-  "description": "CoinPay SDK & CLI - Cryptocurrency payment integration for Node.js",
+  "version": "0.3.0",
+  "description": "CoinPay SDK & CLI — Accept cryptocurrency payments (BTC, ETH, SOL, POL, BCH, USDC) in your Node.js application",
   "type": "module",
   "main": "./src/index.js",
+  "types": "./src/index.d.ts",
   "bin": {
     "coinpay": "./bin/coinpay.js"
   },
@@ -24,22 +25,44 @@
   "files": [
     "src",
     "bin",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
   ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src bin test",
+    "format": "prettier --write src bin test",
+    "prepublishOnly": "npm run test && npm run lint"
+  },
   "keywords": [
     "coinpay",
     "profullstack",
     "cryptocurrency",
+    "crypto",
     "payments",
     "bitcoin",
     "ethereum",
     "solana",
     "polygon",
+    "usdc",
+    "stablecoin",
+    "non-custodial",
+    "wallet",
     "sdk",
-    "cli"
+    "cli",
+    "web3",
+    "blockchain",
+    "payment-gateway",
+    "merchant"
   ],
   "author": "Profullstack, Inc.",
   "license": "MIT",
+  "homepage": "https://coinpayportal.com",
+  "bugs": {
+    "url": "https://github.com/profullstack/coinpayportal/issues"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/profullstack/coinpayportal.git",
@@ -54,11 +77,5 @@
     "prettier": "^3.4.1"
   },
   "peerDependencies": {},
-  "dependencies": {},
-  "scripts": {
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "lint": "eslint src bin test",
-    "format": "prettier --write src bin test"
-  }
-}
+  "dependencies": {}
+}

package/src/client.d.ts

@@ -0,0 +1,266 @@
+/**
+ * CoinPay API Client
+ * Main client class for interacting with the CoinPay API
+ */
+
+/** Options for constructing a CoinPayClient */
+export interface CoinPayClientOptions {
+  /** Your CoinPay API key (starts with `cp_live_` or `cp_test_`) */
+  apiKey: string;
+  /** API base URL (default: `https://coinpayportal.com/api`) */
+  baseUrl?: string;
+  /** Request timeout in milliseconds (default: `30000`) */
+  timeout?: number;
+}
+
+/** Parameters for creating a payment */
+export interface PaymentParams {
+  /** Business ID from your CoinPay dashboard */
+  businessId: string;
+  /** Amount in fiat currency (e.g., `100.00`) */
+  amount: number;
+  /** Fiat currency code (default: `'USD'`) */
+  currency?: string;
+  /** Blockchain/cryptocurrency code: `BTC`, `ETH`, `SOL`, `POL`, `BCH`, `USDC_ETH`, `USDC_POL`, `USDC_SOL` */
+  blockchain: string;
+  /** Payment description shown to the customer */
+  description?: string;
+  /** Custom metadata attached to the payment (e.g., `{ orderId: 'ORD-123' }`) */
+  metadata?: Record<string, unknown>;
+}
+
+/** Parameters for listing payments */
+export interface ListPaymentsParams {
+  /** Business ID */
+  businessId: string;
+  /** Filter by payment status */
+  status?: string;
+  /** Number of results to return (default: `20`) */
+  limit?: number;
+  /** Pagination offset (default: `0`) */
+  offset?: number;
+}
+
+/** Options for the `waitForPayment` polling method */
+export interface WaitForPaymentOptions {
+  /** Polling interval in milliseconds (default: `5000`) */
+  interval?: number;
+  /** Maximum wait time in milliseconds (default: `3600000` — 1 hour) */
+  timeout?: number;
+  /** Payment statuses that stop polling (default: `['confirmed', 'forwarded', 'expired', 'failed']`) */
+  targetStatuses?: string[];
+  /** Callback invoked when the payment status changes */
+  onStatusChange?: (status: string, payment: Record<string, unknown>) => void;
+}
+
+/** Parameters for creating a business */
+export interface CreateBusinessParams {
+  /** Business name */
+  name: string;
+  /** Webhook URL for payment notifications */
+  webhookUrl?: string;
+  /** Wallet addresses keyed by blockchain code */
+  walletAddresses?: Record<string, string>;
+}
+
+/** Generic API response envelope */
+export interface ApiResponse<T = Record<string, unknown>> {
+  success: boolean;
+  [key: string]: unknown;
+}
+
+/** Payment object returned by the API */
+export interface Payment {
+  id: string;
+  business_id: string;
+  amount: number;
+  currency: string;
+  blockchain: string;
+  crypto_amount: string;
+  payment_address: string;
+  qr_code?: string;
+  status: string;
+  tx_hash?: string;
+  expires_at?: string;
+  created_at: string;
+  metadata?: Record<string, unknown>;
+}
+
+/** Response from payment creation */
+export interface CreatePaymentResponse {
+  success: boolean;
+  payment: Payment;
+  usage?: {
+    current: number;
+    limit: number;
+    remaining: number;
+  };
+}
+
+/** Response from getting a single payment */
+export interface GetPaymentResponse {
+  success: boolean;
+  payment: Payment;
+}
+
+/** Response from listing payments */
+export interface ListPaymentsResponse {
+  success: boolean;
+  payments: Payment[];
+}
+
+/**
+ * CoinPay API Client
+ *
+ * The primary class for interacting with the CoinPay payment API.
+ * Handles authentication, request signing, and provides methods
+ * for all API operations.
+ *
+ * @example
+ * ```typescript
+ * import { CoinPayClient } from '@profullstack/coinpay';
+ *
+ * const client = new CoinPayClient({ apiKey: 'cp_live_xxxxx' });
+ *
+ * const payment = await client.createPayment({
+ *   businessId: 'biz_123',
+ *   amount: 99.99,
+ *   blockchain: 'BTC',
+ * });
+ * ```
+ */
+export class CoinPayClient {
+  /**
+   * Create a new CoinPay client
+   * @throws {Error} If `apiKey` is not provided
+   */
+  constructor(options: CoinPayClientOptions);
+
+  /**
+   * Make an authenticated API request.
+   *
+   * Automatically adds `Authorization: Bearer <apiKey>` and `Content-Type: application/json` headers.
+   * Handles timeouts via `AbortController`.
+   *
+   * @param endpoint - API endpoint path (e.g., `/payments/create`)
+   * @param options  - Standard `fetch` options (method, body, headers, etc.)
+   * @returns Parsed JSON response
+   * @throws {Error} On HTTP errors (non-2xx) or timeout
+   */
+  request(endpoint: string, options?: RequestInit): Promise<Record<string, unknown>>;
+
+  /**
+   * Create a new payment request.
+   *
+   * Generates a unique blockchain address and optional QR code for the customer to pay.
+   *
+   * @returns Created payment with `payment_address`, `crypto_amount`, and `qr_code`
+   */
+  createPayment(params: PaymentParams): Promise<CreatePaymentResponse>;
+
+  /**
+   * Get payment details by ID.
+   *
+   * @param paymentId - Payment ID (e.g., `'pay_abc123'`)
+   * @returns Payment details including current status
+   */
+  getPayment(paymentId: string): Promise<GetPaymentResponse>;
+
+  /**
+   * Poll until a payment reaches a terminal status.
+   *
+   * Terminal statuses: `confirmed`, `forwarded`, `expired`, `failed`.
+   * For production, prefer webhooks over polling.
+   *
+   * @param paymentId - Payment ID
+   * @param options   - Polling configuration
+   * @returns Final payment details
+   * @throws {Error} If timeout is reached before a terminal status
+   */
+  waitForPayment(paymentId: string, options?: WaitForPaymentOptions): Promise<GetPaymentResponse>;
+
+  /**
+   * List payments for a business.
+   *
+   * @returns Paginated list of payments
+   */
+  listPayments(params: ListPaymentsParams): Promise<ListPaymentsResponse>;
+
+  /**
+   * Get a URL pointing to the QR code image for a payment.
+   *
+   * The URL returns binary PNG data suitable for `<img src="...">`.
+   * This method is synchronous — it does not make a network request.
+   *
+   * @param paymentId - Payment ID
+   * @returns Full URL to the QR code PNG endpoint
+   */
+  getPaymentQRUrl(paymentId: string): string;
+
+  /**
+   * Fetch the QR code image as binary data.
+   *
+   * @param paymentId - Payment ID
+   * @returns QR code PNG image as an `ArrayBuffer`
+   */
+  getPaymentQR(paymentId: string): Promise<ArrayBuffer>;
+
+  /**
+   * Get the exchange rate for a cryptocurrency.
+   *
+   * @param cryptocurrency - Crypto code (e.g., `'BTC'`, `'ETH'`)
+   * @param fiatCurrency   - Fiat code (default: `'USD'`)
+   */
+  getExchangeRate(cryptocurrency: string, fiatCurrency?: string): Promise<Record<string, unknown>>;
+
+  /**
+   * Get exchange rates for multiple cryptocurrencies in a single request.
+   *
+   * @param cryptocurrencies - Array of crypto codes
+   * @param fiatCurrency     - Fiat code (default: `'USD'`)
+   */
+  getExchangeRates(cryptocurrencies: string[], fiatCurrency?: string): Promise<Record<string, unknown>>;
+
+  /**
+   * Get business details.
+   *
+   * @param businessId - Business ID
+   */
+  getBusiness(businessId: string): Promise<Record<string, unknown>>;
+
+  /** List all businesses associated with your API key. */
+  listBusinesses(): Promise<Record<string, unknown>>;
+
+  /**
+   * Create a new business.
+   *
+   * @param params - Business creation parameters
+   */
+  createBusiness(params: CreateBusinessParams): Promise<Record<string, unknown>>;
+
+  /**
+   * Update an existing business.
+   *
+   * @param businessId - Business ID
+   * @param params     - Fields to update
+   */
+  updateBusiness(businessId: string, params: Record<string, unknown>): Promise<Record<string, unknown>>;
+
+  /**
+   * Get webhook delivery logs for a business.
+   *
+   * @param businessId - Business ID
+   * @param limit      - Number of log entries (default: `50`)
+   */
+  getWebhookLogs(businessId: string, limit?: number): Promise<Record<string, unknown>>;
+
+  /**
+   * Send a test webhook event to your configured endpoint.
+   *
+   * @param businessId - Business ID
+   * @param eventType  - Event type to simulate (default: `'payment.completed'`)
+   */
+  testWebhook(businessId: string, eventType?: string): Promise<Record<string, unknown>>;
+}
+
+export default CoinPayClient;

package/src/client.js

@@ -83,7 +83,7 @@ export class CoinPayClient {
    * @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, MATIC, BCH, USDC_ETH, USDC_MATIC, USDC_SOL)
+   * @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

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/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

@@ -31,7 +31,7 @@ import { CoinPayClient } from './client.js';
  * @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, MATIC, BCH, USDC_ETH, USDC_MATIC, USDC_SOL)
+ * @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
@@ -143,14 +143,14 @@ export const Blockchain = {
   BCH: 'BCH',
   /** Ethereum */
   ETH: 'ETH',
-  /** Polygon (MATIC) */
-  MATIC: 'MATIC',
+  /** Polygon (POL) */
+  POL: 'POL',
   /** Solana */
   SOL: 'SOL',
   /** USDC on Ethereum */
   USDC_ETH: 'USDC_ETH',
   /** USDC on Polygon */
-  USDC_MATIC: 'USDC_MATIC',
+  USDC_POL: 'USDC_POL',
   /** USDC on Solana */
   USDC_SOL: 'USDC_SOL',
 };