@profullstack/coinpay 0.6.11 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@profullstack/coinpay",
-  "version": "0.6.11",
+  "version": "0.8.0",
   "description": "CoinPay SDK & CLI — Accept cryptocurrency payments (BTC, ETH, SOL, POL, BCH, USDC) with wallet and swap support",
   "type": "module",
   "main": "./src/index.js",
@@ -17,6 +17,10 @@
       "import": "./src/payments.js",
       "types": "./src/payments.d.ts"
     },
+    "./tokens": {
+      "import": "./src/tokens.js",
+      "types": "./src/tokens.d.ts"
+    },
     "./card-payments": {
       "import": "./src/card-payments.js",
       "types": "./src/card-payments.d.ts"
@@ -32,6 +36,18 @@
     "./swap": {
       "import": "./src/swap.js",
       "types": "./src/swap.d.ts"
+    },
+    "./x402": {
+      "import": "./src/x402.js"
+    },
+    "./x402-v2": {
+      "import": "./src/x402-v2.js"
+    },
+    "./x402-browser": {
+      "import": "./src/x402-browser.js"
+    },
+    "./x402-pay-server": {
+      "import": "./src/x402-pay-server.js"
     }
   },
   "files": [
@@ -87,7 +103,7 @@
     "node": ">=20.0.0"
   },
   "devDependencies": {
-    "vitest": "^2.1.8",
+    "vitest": "^4.1.0",
     "eslint": "^8.57.0",
     "prettier": "^3.4.1"
   },
@@ -96,6 +112,7 @@
     "@scure/bip39": "^1.4.0",
     "@scure/bip32": "^1.5.0",
     "@noble/curves": "^1.6.0",
-    "@noble/hashes": "^1.5.0"
+    "@noble/hashes": "^1.5.0",
+    "@inquirer/prompts": "^8.3.0"
   }
 }

package/src/auth.js

@@ -58,7 +58,8 @@ export async function loginMerchant(client, { email, password }) {
  * @returns {Promise<Object>} Merchant information
  */
 export async function getMe(client) {
+  // GET — the /auth/me endpoint is GET-only (a POST returns 405).
   return client.request('/auth/me', {
-    method: 'POST',
+    method: 'GET',
   });
 }

package/src/client.d.ts

@@ -41,6 +41,14 @@ export interface ListPaymentsParams {
   offset?: number;
 }
 
+/** Parameters for supported coin/token discovery */
+export interface SupportedCoinsParams {
+  /** Business ID. Required for merchant JWTs; optional with business API keys if it matches key scope. */
+  businessId?: string;
+  /** If true, only active wallets are returned. */
+  activeOnly?: boolean;
+}
+
 /** Options for the `waitForPayment` polling method */
 export interface WaitForPaymentOptions {
   /** Polling interval in milliseconds (default: `5000`) */
@@ -109,6 +117,36 @@ export interface ListPaymentsResponse {
   payments: Payment[];
 }
 
+/** Supported payment coin record */
+export interface SupportedCoin {
+  symbol: string;
+  name: string;
+  is_active: boolean;
+  has_wallet: boolean;
+  wallet_source: 'business' | 'merchant_global';
+}
+
+/** Checkout token record with lower-case code accepted by createPayment currency */
+export interface SupportedToken extends SupportedCoin {
+  code: string;
+  ticker: string;
+  chain?: string;
+}
+
+/** Response from supported coin discovery */
+export interface SupportedCoinsResponse {
+  success: boolean;
+  coins: SupportedCoin[];
+  business_id: string;
+  merchant_id?: string;
+  total: number;
+}
+
+/** Response from token discovery */
+export interface TokensResponse extends SupportedCoinsResponse {
+  tokens: SupportedToken[];
+}
+
 /**
  * CoinPay API Client
  *
@@ -186,6 +224,20 @@ export class CoinPayClient {
    */
   listPayments(params: ListPaymentsParams): Promise<ListPaymentsResponse>;
 
+  /**
+   * List supported payment coins for a business.
+   *
+   * Business wallets win; merchant global wallets are used as fallback.
+   */
+  getSupportedCoins(params?: SupportedCoinsParams): Promise<SupportedCoinsResponse>;
+
+  /**
+   * List checkout-friendly tokens for a business.
+   *
+   * Returns lower-case `code` values accepted by `createPayment({ currency })`.
+   */
+  getTokens(params?: SupportedCoinsParams): Promise<TokensResponse>;
+
   /**
    * Get a URL pointing to the QR code image for a payment.
    *

package/src/client.js

@@ -279,6 +279,45 @@ export class CoinPayClient {
     return this.request(`/payments?${params.toString()}`);
   }
 
+  /**
+   * Get supported payment coins for a business.
+   *
+   * Business API keys derive the business from the key. Passing businessId is
+   * still allowed and must match the key scope. Merchant JWTs require
+   * businessId.
+   *
+   * @param {Object} [params]
+   * @param {string} [params.businessId] - Business ID
+   * @param {boolean} [params.activeOnly] - Only return active wallets
+   * @returns {Promise<Object>} Supported coins response
+   */
+  async getSupportedCoins({ businessId, activeOnly } = {}) {
+    const params = new URLSearchParams();
+    if (businessId) params.set('business_id', businessId);
+    if (activeOnly) params.set('active_only', 'true');
+    const query = params.toString();
+    return this.request(`/supported-coins${query ? `?${query}` : ''}`);
+  }
+
+  /**
+   * Get payment-option tokens for a business.
+   *
+   * Returns lower-case `code` values accepted by /payments/create, plus
+   * display fields for checkout coin pickers.
+   *
+   * @param {Object} [params]
+   * @param {string} [params.businessId] - Business ID
+   * @param {boolean} [params.activeOnly] - Only return active wallets
+   * @returns {Promise<Object>} Tokens response
+   */
+  async getTokens({ businessId, activeOnly } = {}) {
+    const params = new URLSearchParams();
+    if (businessId) params.set('business_id', businessId);
+    if (activeOnly) params.set('active_only', 'true');
+    const query = params.toString();
+    return this.request(`/tokens${query ? `?${query}` : ''}`);
+  }
+
   /**
    * Get payment QR code URL
    *
@@ -685,22 +724,29 @@ export class CoinPayClient {
 
   /**
    * Create Stripe Connect onboarding link
-   * 
+   *
    * Generates a Stripe Express onboarding link for a merchant.
    * The merchant must complete this onboarding before they can accept card payments.
-   * 
+   *
+   * Country is required on the first onboarding call and is locked at Stripe
+   * account creation — it cannot be changed afterward. Subsequent calls (e.g.
+   * to finish remaining requirements) may omit it; the server reuses the
+   * country stored on the business. All Stripe Connect supported countries are
+   * accepted (US, CA, GB, AU, DE, FR, JP, SG, ...). See
+   * https://stripe.com/global for the full list.
+   *
    * @param {string} businessId - Business ID
    * @param {Object} [params] - Optional parameters
    * @param {string} [params.email] - Merchant email (pre-fills onboarding form)
-   * @param {string} [params.country='US'] - Country code (US, CA, GB, etc.)
+   * @param {string} [params.country] - ISO-3166-1 alpha-2 country code (e.g. 'US', 'CA', 'GB'). Required on first onboarding.
    * @returns {Promise<Object>} Onboarding link and account ID
-   * 
+   *
    * @example
    * const onboarding = await client.createStripeOnboardingLink('business-id', {
    *   email: 'merchant@example.com',
-   *   country: 'US'
+   *   country: 'CA'
    * });
-   * 
+   *
    * // Redirect merchant to onboarding.onboarding_url
    */
   async createStripeOnboardingLink(businessId, params = {}) {
@@ -913,4 +959,4 @@ export class CoinPayClient {
   }
 }
 
-export default CoinPayClient;
+export default CoinPayClient;

package/src/index.d.ts

@@ -12,9 +12,22 @@ export type {
   PaymentParams, 
   ListPaymentsParams, 
   WaitForPaymentOptions, 
-  CreateBusinessParams 
+  CreateBusinessParams,
+  SupportedCoinsParams,
+  SupportedCoin,
+  SupportedToken,
+  SupportedCoinsResponse,
+  TokensResponse,
 } from './client.js';
 
+export {
+  getTokens,
+  getSupportedCoins,
+} from './tokens.js';
+export type {
+  TokenDiscoveryParams,
+} from './tokens.js';
+
 // Payment exports
 export {
   createPayment,
@@ -31,6 +44,26 @@ export type {
   ListPaymentsFnParams 
 } from './payments.js';
 
+// Invoice exports
+export {
+  createInvoice,
+  getInvoice,
+  listInvoices,
+  updateInvoice,
+  deleteInvoice,
+  sendInvoice,
+  getInvoicePaymentData,
+  InvoiceStatus,
+} from './invoices.js';
+export type {
+  Invoice,
+  InvoiceStatusType,
+  CreateInvoiceParams,
+  ListInvoicesParams,
+  UpdateInvoiceParams,
+  ListInvoicesResult,
+} from './invoices.js';
+
 // Webhook exports
 export {
   verifyWebhookSignature,

package/src/index.js

@@ -46,6 +46,11 @@ import {
   PaymentStatus,
   FiatCurrency,
 } from './payments.js';
+import {
+  getTokens,
+  getSupportedCoins,
+  getSupportedCoins as getSupportedPaymentCoins,
+} from './tokens.js';
 import {
   verifyWebhookSignature,
   generateWebhookSignature,
@@ -66,6 +71,18 @@ import {
   authenticateEscrow,
 } from './escrow.js';
 
+// Invoice exports
+import {
+  createInvoice,
+  getInvoice,
+  listInvoices,
+  updateInvoice,
+  deleteInvoice,
+  sendInvoice,
+  getInvoicePaymentData,
+  InvoiceStatus,
+} from './invoices.js';
+
 // Wallet exports
 import {
   WalletClient,
@@ -156,6 +173,7 @@ import {
   verifyX402Payment,
   settleX402Payment,
   buildPaymentRequired,
+  expectedForProof,
   convertUsdToAssetAmount,
   PAYMENT_METHODS,
   USDC_CONTRACTS,
@@ -170,6 +188,9 @@ export {
   createPayment,
   getPayment,
   listPayments,
+  getTokens,
+  getSupportedCoins,
+  getSupportedPaymentCoins,
   
   // Escrow functions
   createEscrow,
@@ -182,6 +203,16 @@ export {
   waitForEscrow,
   authenticateEscrow,
   
+  // Invoice functions
+  createInvoice,
+  getInvoice,
+  listInvoices,
+  updateInvoice,
+  deleteInvoice,
+  sendInvoice,
+  getInvoicePaymentData,
+  InvoiceStatus,
+  
   // Wallet
   WalletClient,
   WalletChain,
@@ -263,6 +294,7 @@ export {
   verifyX402Payment,
   settleX402Payment,
   buildPaymentRequired,
+  expectedForProof,
   convertUsdToAssetAmount,
   PAYMENT_METHODS,
   USDC_CONTRACTS,

package/src/invoices.d.ts

@@ -0,0 +1,77 @@
+import type { CoinPayClient } from './client.js';
+
+export const InvoiceStatus: {
+  readonly DRAFT: 'draft';
+  readonly SENT: 'sent';
+  readonly PAID: 'paid';
+  readonly OVERDUE: 'overdue';
+  readonly CANCELLED: 'cancelled';
+};
+
+export type InvoiceStatusType = (typeof InvoiceStatus)[keyof typeof InvoiceStatus];
+
+export interface Invoice {
+  id: string;
+  invoiceNumber?: string;
+  businessId?: string;
+  clientId?: string;
+  currency?: string;
+  amount?: number;
+  cryptoCurrency?: string;
+  cryptoAmount?: string | number;
+  status?: InvoiceStatusType;
+  dueDate?: string;
+  notes?: string;
+  walletId?: string;
+  merchantWalletAddress?: string;
+  paymentAddress?: string;
+  stripeCheckoutUrl?: string;
+  paidAt?: string;
+  sentAt?: string;
+  createdAt?: string;
+  updatedAt?: string;
+}
+
+export interface CreateInvoiceParams {
+  businessId?: string;
+  clientId?: string;
+  currency: string;
+  amount: number;
+  cryptoCurrency?: string;
+  dueDate?: string;
+  notes?: string;
+  walletId?: string;
+  merchantWalletAddress?: string;
+}
+
+export interface ListInvoicesParams {
+  businessId?: string;
+  status?: InvoiceStatusType;
+  clientId?: string;
+  dateFrom?: string;
+  dateTo?: string;
+}
+
+export interface UpdateInvoiceParams {
+  amount?: number;
+  currency?: string;
+  cryptoCurrency?: string;
+  dueDate?: string;
+  notes?: string;
+  clientId?: string;
+  walletId?: string;
+  merchantWalletAddress?: string;
+}
+
+export interface ListInvoicesResult {
+  invoices: Invoice[];
+  total?: number;
+}
+
+export function createInvoice(client: CoinPayClient, options: CreateInvoiceParams): Promise<Invoice>;
+export function listInvoices(client: CoinPayClient, filters?: ListInvoicesParams): Promise<ListInvoicesResult>;
+export function getInvoice(client: CoinPayClient, id: string): Promise<Invoice>;
+export function updateInvoice(client: CoinPayClient, id: string, updates: UpdateInvoiceParams): Promise<Invoice>;
+export function deleteInvoice(client: CoinPayClient, id: string): Promise<Record<string, unknown>>;
+export function sendInvoice(client: CoinPayClient, id: string): Promise<Record<string, unknown>>;
+export function getInvoicePaymentData(client: CoinPayClient, id: string): Promise<Record<string, unknown>>;

package/src/invoices.js

@@ -0,0 +1,237 @@
+/**
+ * Invoice SDK Module
+ *
+ * Create, manage, and send invoices with crypto + card payment support.
+ * Invoices can be sent to clients who pay via generated crypto addresses
+ * or optional Stripe checkout.
+ *
+ * @example
+ * import { CoinPayClient } from '@profullstack/coinpay';
+ * import { createInvoice, sendInvoice, getInvoicePaymentData } from '@profullstack/coinpay';
+ *
+ * const client = new CoinPayClient({ apiKey: 'your-key' });
+ *
+ * // Create an invoice
+ * const invoice = await createInvoice(client, {
+ *   businessId: 'biz_123',
+ *   currency: 'USD',
+ *   amount: 250.00,
+ *   cryptoCurrency: 'ETH',
+ *   dueDate: '2026-04-01',
+ *   notes: 'Web development - March 2026',
+ * });
+ *
+ * // Send it to the client
+ * const sent = await sendInvoice(client, invoice.id);
+ *
+ * // Public: get payment data (no auth)
+ * const paymentData = await getInvoicePaymentData(client, invoice.id);
+ */
+
+/**
+ * Create a new invoice
+ * @param {CoinPayClient} client - API client instance
+ * @param {Object} options - Invoice parameters
+ * @param {string} [options.businessId] - Business ID (optional for business-scoped API keys)
+ * @param {string} [options.clientId] - Client ID (optional)
+ * @param {string} options.currency - Fiat currency code (USD, EUR, etc.)
+ * @param {number} options.amount - Invoice amount
+ * @param {string} [options.cryptoCurrency] - Preferred crypto for payment
+ * @param {string} [options.dueDate] - Due date (ISO string or YYYY-MM-DD)
+ * @param {string} [options.notes] - Notes / description
+ * @param {string} [options.walletId] - Wallet ID for receiving payment
+ * @param {string} [options.merchantWalletAddress] - Direct wallet address for receiving payment
+ * @returns {Promise<Object>} Created invoice
+ */
+export async function createInvoice(client, {
+  businessId,
+  clientId,
+  currency,
+  amount,
+  cryptoCurrency,
+  dueDate,
+  notes,
+  walletId,
+  merchantWalletAddress,
+}) {
+  const body = {
+    business_id: businessId,
+    currency,
+    amount,
+  };
+  if (clientId) body.client_id = clientId;
+  if (cryptoCurrency) body.crypto_currency = cryptoCurrency;
+  if (dueDate) body.due_date = dueDate;
+  if (notes) body.notes = notes;
+  if (walletId) body.wallet_id = walletId;
+  if (merchantWalletAddress) body.merchant_wallet_address = merchantWalletAddress;
+
+  const data = await client.request('/invoices', {
+    method: 'POST',
+    body: JSON.stringify(body),
+  });
+
+  return normalizeInvoice(data);
+}
+
+/**
+ * List invoices with optional filters
+ * @param {CoinPayClient} client
+ * @param {Object} [filters]
+ * @param {string} [filters.businessId] - Filter by business ID
+ * @param {string} [filters.status] - Filter by status (draft, sent, paid, overdue, cancelled)
+ * @param {string} [filters.clientId] - Filter by client ID
+ * @param {string} [filters.dateFrom] - Filter from date (ISO string)
+ * @param {string} [filters.dateTo] - Filter to date (ISO string)
+ * @returns {Promise<Object>} { invoices, total?, ... }
+ */
+export async function listInvoices(client, filters = {}) {
+  const params = new URLSearchParams();
+  if (filters.businessId) params.set('business_id', filters.businessId);
+  if (filters.status) params.set('status', filters.status);
+  if (filters.clientId) params.set('client_id', filters.clientId);
+  if (filters.dateFrom) params.set('date_from', filters.dateFrom);
+  if (filters.dateTo) params.set('date_to', filters.dateTo);
+
+  const query = params.toString();
+  const endpoint = query ? `/invoices?${query}` : '/invoices';
+  const data = await client.request(endpoint);
+
+  // Handle both array and paginated responses
+  if (Array.isArray(data)) {
+    return { invoices: data.map(normalizeInvoice) };
+  }
+
+  return {
+    invoices: (data.invoices || []).map(normalizeInvoice),
+    total: data.total,
+  };
+}
+
+/**
+ * Get a single invoice by ID
+ * @param {CoinPayClient} client
+ * @param {string} id - Invoice ID
+ * @returns {Promise<Object>} Invoice details
+ */
+export async function getInvoice(client, id) {
+  const data = await client.request(`/invoices/${encodeURIComponent(id)}`);
+  return normalizeInvoice(data);
+}
+
+/**
+ * Update an invoice
+ * @param {CoinPayClient} client
+ * @param {string} id - Invoice ID
+ * @param {Object} updates - Partial invoice fields to update
+ * @param {number} [updates.amount] - Updated amount
+ * @param {string} [updates.currency] - Updated currency
+ * @param {string} [updates.cryptoCurrency] - Updated crypto currency
+ * @param {string} [updates.dueDate] - Updated due date
+ * @param {string} [updates.notes] - Updated notes
+ * @param {string} [updates.clientId] - Updated client ID
+ * @param {string} [updates.walletId] - Updated wallet ID
+ * @param {string} [updates.merchantWalletAddress] - Updated wallet address
+ * @returns {Promise<Object>} Updated invoice
+ */
+export async function updateInvoice(client, id, updates) {
+  const body = {};
+  if (updates.amount !== undefined) body.amount = updates.amount;
+  if (updates.currency !== undefined) body.currency = updates.currency;
+  if (updates.cryptoCurrency !== undefined) body.crypto_currency = updates.cryptoCurrency;
+  if (updates.dueDate !== undefined) body.due_date = updates.dueDate;
+  if (updates.notes !== undefined) body.notes = updates.notes;
+  if (updates.clientId !== undefined) body.client_id = updates.clientId;
+  if (updates.walletId !== undefined) body.wallet_id = updates.walletId;
+  if (updates.merchantWalletAddress !== undefined) body.merchant_wallet_address = updates.merchantWalletAddress;
+
+  const data = await client.request(`/invoices/${encodeURIComponent(id)}`, {
+    method: 'PUT',
+    body: JSON.stringify(body),
+  });
+
+  return normalizeInvoice(data);
+}
+
+/**
+ * Delete a draft invoice
+ * @param {CoinPayClient} client
+ * @param {string} id - Invoice ID (must be in draft status)
+ * @returns {Promise<Object>} Deletion confirmation
+ */
+export async function deleteInvoice(client, id) {
+  return client.request(`/invoices/${encodeURIComponent(id)}`, {
+    method: 'DELETE',
+  });
+}
+
+/**
+ * Send an invoice to the client
+ * Generates a payment address and optional Stripe checkout link.
+ * @param {CoinPayClient} client
+ * @param {string} id - Invoice ID
+ * @returns {Promise<Object>} Send result with payment details
+ */
+export async function sendInvoice(client, id) {
+  const data = await client.request(`/invoices/${encodeURIComponent(id)}/send`, {
+    method: 'POST',
+  });
+  return data;
+}
+
+/**
+ * Get invoice payment data (public, no auth required)
+ * Used by clients/customers to view payment instructions.
+ * @param {CoinPayClient} client
+ * @param {string} id - Invoice ID
+ * @returns {Promise<Object>} Payment data (address, amount, status, etc.)
+ */
+export async function getInvoicePaymentData(client, id) {
+  const data = await client.requestUnauthenticated(`/invoices/${encodeURIComponent(id)}/pay`);
+  return data;
+}
+
+// ── Constants ──
+
+/**
+ * Invoice status constants
+ */
+export const InvoiceStatus = {
+  DRAFT: 'draft',
+  SENT: 'sent',
+  PAID: 'paid',
+  OVERDUE: 'overdue',
+  CANCELLED: 'cancelled',
+};
+
+// ── Helpers ──
+
+function normalizeInvoice(data) {
+  if (!data) return data;
+
+  // Single-invoice API responses are wrapped, while older SDK callers and
+  // tests may still supply the invoice object directly.
+  const invoice = data.invoice ?? data;
+
+  return {
+    id: invoice.id,
+    invoiceNumber: invoice.invoice_number,
+    businessId: invoice.business_id,
+    clientId: invoice.client_id,
+    currency: invoice.currency,
+    amount: invoice.amount,
+    cryptoCurrency: invoice.crypto_currency,
+    cryptoAmount: invoice.crypto_amount,
+    status: invoice.status,
+    dueDate: invoice.due_date,
+    notes: invoice.notes,
+    walletId: invoice.wallet_id,
+    merchantWalletAddress: invoice.merchant_wallet_address,
+    paymentAddress: invoice.payment_address,
+    stripeCheckoutUrl: invoice.stripe_checkout_url,
+    paidAt: invoice.paid_at,
+    sentAt: invoice.sent_at,
+    createdAt: invoice.created_at,
+    updatedAt: invoice.updated_at,
+  };
+}

package/src/tokens.d.ts

@@ -0,0 +1,14 @@
+import { CoinPayClient, SupportedCoinsParams, SupportedCoinsResponse, TokensResponse } from './client.js';
+
+export interface TokenDiscoveryParams extends SupportedCoinsParams {
+  /** API key — required if `client` is not provided */
+  apiKey?: string;
+  /** Existing CoinPayClient instance */
+  client?: CoinPayClient;
+}
+
+/** List checkout-friendly tokens for a business. */
+export function getTokens(params?: TokenDiscoveryParams): Promise<TokensResponse>;
+
+/** List supported payment coins for a business. */
+export function getSupportedCoins(params?: TokenDiscoveryParams): Promise<SupportedCoinsResponse>;