@profullstack/coinpay 0.1.0 → 0.3.0

package/bin/coinpay.js

@@ -6,7 +6,7 @@
  */
 
 import { CoinPayClient } from '../src/client.js';
-import { PaymentStatus, Cryptocurrency, FiatCurrency } from '../src/payments.js';
+import { PaymentStatus, Blockchain, FiatCurrency } from '../src/payments.js';
 import { readFileSync, writeFileSync, existsSync } from 'fs';
 import { homedir } from 'os';
 import { join } from 'path';
@@ -70,7 +70,7 @@ function getApiKey() {
  */
 function getBaseUrl() {
   const config = loadConfig();
-  return process.env.COINPAY_BASE_URL || config.baseUrl || 'https://coinpay.dev/api';
+  return process.env.COINPAY_BASE_URL || config.baseUrl || 'https://coinpayportal.com/api';
 }
 
 /**
@@ -152,15 +152,31 @@ ${colors.cyan}Options:${colors.reset}
   --version, -v           Show version
   --json                  Output as JSON
   --business-id <id>      Business ID for operations
-  --amount <amount>       Payment amount
-  --currency <code>       Fiat currency (USD, EUR, etc.)
-  --crypto <code>         Cryptocurrency (BTC, ETH, etc.)
+  --amount <amount>       Payment amount in fiat currency
+  --currency <code>       Fiat currency (USD, EUR, etc.) - default: USD
+  --blockchain <code>     Blockchain (BTC, ETH, SOL, POL, BCH, USDC_ETH, USDC_POL, USDC_SOL)
+  --description <text>    Payment description
 
 ${colors.cyan}Examples:${colors.reset}
-  coinpay config set-key sk_live_xxxxx
-  coinpay payment create --business-id biz_123 --amount 100 --currency USD --crypto BTC
+  # Configure your API key (get it from your CoinPay dashboard)
+  coinpay config set-key cp_live_xxxxx
+
+  # Create a $100 Bitcoin payment
+  coinpay payment create --business-id biz_123 --amount 100 --blockchain BTC
+
+  # Create a $50 Ethereum payment with description
+  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_POL
+
+  # Get payment status
   coinpay payment get pay_abc123
+
+  # Get exchange rates
   coinpay rates get BTC
+
+  # List your businesses
   coinpay business list
 
 ${colors.cyan}Environment Variables:${colors.reset}
@@ -218,10 +234,11 @@ async function handlePayment(subcommand, args, flags) {
   
   switch (subcommand) {
     case 'create': {
-      const { 'business-id': businessId, amount, currency, crypto, description } = flags;
+      const { 'business-id': businessId, amount, currency = 'USD', blockchain, description } = flags;
       
-      if (!businessId || !amount || !currency || !crypto) {
-        print.error('Required: --business-id, --amount, --currency, --crypto');
+      if (!businessId || !amount || !blockchain) {
+        print.error('Required: --business-id, --amount, --blockchain');
+        print.info('Example: coinpay payment create --business-id biz_123 --amount 100 --blockchain BTC');
         return;
       }
       
@@ -229,12 +246,19 @@ async function handlePayment(subcommand, args, flags) {
         businessId,
         amount: parseFloat(amount),
         currency,
-        cryptocurrency: crypto,
+        blockchain,
         description,
       });
       
       print.success('Payment created');
-      print.json(payment);
+      if (payment.payment) {
+        print.info(`Payment Address: ${payment.payment.payment_address}`);
+        print.info(`Amount: ${payment.payment.crypto_amount} ${payment.payment.blockchain}`);
+        print.info(`Expires: ${payment.payment.expires_at}`);
+      }
+      if (!flags.json) {
+        print.json(payment);
+      }
       break;
     }
     
@@ -364,7 +388,7 @@ async function handleRates(subcommand, args, flags) {
       const { fiat } = flags;
       
       if (!crypto) {
-        print.error('Cryptocurrency code required (BTC, ETH, etc.)');
+        print.error('Blockchain code required (BTC, ETH, SOL, etc.)');
         return;
       }
       
@@ -375,7 +399,7 @@ async function handleRates(subcommand, args, flags) {
     
     case 'list': {
       const { fiat } = flags;
-      const cryptos = Object.values(Cryptocurrency);
+      const cryptos = Object.values(Blockchain);
       const rates = await client.getExchangeRates(cryptos, fiat);
       print.json(rates);
       break;

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@profullstack/coinpay",
-  "version": "0.1.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;