@profullstack/coinpay 0.6.10 → 0.8.0

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/lightning.js

@@ -1,14 +1,14 @@
 /**
  * Lightning Module for CoinPay SDK
  *
- * Manages BOLT12 Lightning Network operations: node provisioning,
- * offer creation, and payment tracking.
+ * Manages Lightning Network operations: wallet provisioning (via LNbits),
+ * lightning address registration, invoice creation, payment sending, and history.
+ *
+ * Lightning wallets are custodial — funds are held on CoinPay's server.
  */
 
-const DEFAULT_BASE_URL = 'https://coinpayportal.com/api';
-
 /**
- * Lightning client for BOLT12 operations
+ * Lightning client for LN operations
  */
 export class LightningClient {
   #client;
@@ -21,24 +21,31 @@ export class LightningClient {
   }
 
   // ──────────────────────────────────────────────
-  // Nodes
+  // Nodes / Wallet Provisioning
   // ──────────────────────────────────────────────
 
   /**
-   * Provision a Greenlight CLN node for a wallet.
+   * Enable Lightning for a wallet (provisions an LNbits custodial wallet).
    * @param {Object} params
    * @param {string} params.wallet_id - Wallet UUID
-   * @param {string} params.mnemonic - BIP39 mnemonic (used server-side to derive LN keys)
+   * @param {string} params.mnemonic - BIP39 mnemonic
    * @param {string} [params.business_id] - Optional business UUID
-   * @returns {Promise<Object>} The provisioned node
+   * @returns {Promise<Object>} The provisioned node record
    */
-  async provisionNode({ wallet_id, mnemonic, business_id }) {
+  async enableWallet({ wallet_id, mnemonic, business_id }) {
     return this.#client.request('/lightning/nodes', {
       method: 'POST',
       body: JSON.stringify({ wallet_id, mnemonic, business_id }),
     });
   }
 
+  /**
+   * @deprecated Use enableWallet() instead
+   */
+  async provisionNode(params) {
+    return this.enableWallet(params);
+  }
+
   /**
    * Get node status by ID.
    * @param {string} nodeId
@@ -58,30 +65,81 @@ export class LightningClient {
   }
 
   // ──────────────────────────────────────────────
-  // Offers
+  // Lightning Address
   // ──────────────────────────────────────────────
 
   /**
-   * Create a BOLT12 offer.
+   * Register a Lightning Address (username@coinpayportal.com).
+   * Requires Lightning to be enabled first.
    * @param {Object} params
-   * @param {string} params.node_id - Node UUID
-   * @param {string} params.description - Human-readable description
-   * @param {number} [params.amount_msat] - Fixed amount in millisatoshis (omit for any-amount)
-   * @param {string} [params.currency] - Currency code (default: "BTC")
-   * @param {string} [params.business_id] - Optional business UUID
-   * @returns {Promise<Object>}
+   * @param {string} params.wallet_id - Wallet UUID
+   * @param {string} params.username - Desired username (3-32 chars, lowercase alphanumeric)
+   * @returns {Promise<Object>} { lightning_address, username }
+   */
+  async registerAddress({ wallet_id, username }) {
+    return this.#client.request('/lightning/address', {
+      method: 'POST',
+      body: JSON.stringify({ wallet_id, username }),
+    });
+  }
+
+  /**
+   * Get Lightning Address for a wallet.
+   * @param {string} walletId - Wallet UUID
+   * @returns {Promise<Object>} { lightning_address, username } or { lightning_address: null }
+   */
+  async getAddress(walletId) {
+    return this.#client.request(`/lightning/address?wallet_id=${walletId}`);
+  }
+
+  /**
+   * Check if a Lightning Address username is available.
+   * @param {string} username
+   * @returns {Promise<Object>} { available: boolean }
+   */
+  async checkAddressAvailable(username) {
+    return this.#client.request(`/lightning/address?username=${encodeURIComponent(username)}`);
+  }
+
+  // ──────────────────────────────────────────────
+  // Invoices
+  // ──────────────────────────────────────────────
+
+  /**
+   * Create a BOLT11 invoice to receive a payment.
+   * @param {Object} params
+   * @param {string} params.wallet_id - Wallet UUID
+   * @param {number} params.amount_sats - Amount in satoshis
+   * @param {string} [params.description] - Invoice description/memo
+   * @returns {Promise<Object>} { payment_request, payment_hash, ... }
    */
-  async createOffer({ node_id, description, amount_msat, currency, business_id }) {
+  async createInvoice({ wallet_id, amount_sats, description }) {
+    return this.#client.request('/lightning/invoices', {
+      method: 'POST',
+      body: JSON.stringify({ wallet_id, amount_sats, description }),
+    });
+  }
+
+  // ──────────────────────────────────────────────
+  // Offers (BOLT12) — currently not supported
+  // ──────────────────────────────────────────────
+
+  /**
+   * Create a BOLT12 offer.
+   * @deprecated BOLT12 offers are not currently supported (LNbits limitation).
+   * Use createInvoice() or registerAddress() instead.
+   */
+  async createOffer(params) {
     return this.#client.request('/lightning/offers', {
       method: 'POST',
-      body: JSON.stringify({ node_id, description, amount_msat, currency, business_id }),
+      body: JSON.stringify(params),
     });
   }
 
   /**
    * Get offer by ID.
    * @param {string} offerId
-   * @returns {Promise<Object>} Includes offer and qr_uri
+   * @returns {Promise<Object>}
    */
   async getOffer(offerId) {
     return this.#client.request(`/lightning/offers/${offerId}`);
@@ -92,9 +150,9 @@ export class LightningClient {
    * @param {Object} [params]
    * @param {string} [params.business_id]
    * @param {string} [params.node_id]
-   * @param {string} [params.status] - "active" | "disabled" | "archived"
-   * @param {number} [params.limit] - Default 20
-   * @param {number} [params.offset] - Default 0
+   * @param {string} [params.status]
+   * @param {number} [params.limit]
+   * @param {number} [params.offset]
    * @returns {Promise<Object>} { offers, total, limit, offset }
    */
   async listOffers(params = {}) {
@@ -109,12 +167,31 @@ export class LightningClient {
   // Payments
   // ──────────────────────────────────────────────
 
+  /**
+   * Send a Lightning payment. Accepts:
+   * - BOLT11 invoice string
+   * - Lightning address (user@domain)
+   * @param {Object} params
+   * @param {string} params.wallet_id - Wallet UUID
+   * @param {string} params.destination - BOLT11 invoice or lightning address (user@domain)
+   * @param {number} [params.amount_sats] - Amount in satoshis (required for lightning addresses, optional for invoices with amount)
+   * @returns {Promise<Object>} { payment_hash, status }
+   */
+  async sendPayment({ wallet_id, destination, amount_sats }) {
+    return this.#client.request('/lightning/payments', {
+      method: 'POST',
+      body: JSON.stringify({ wallet_id, bolt12: destination, amount_sats }),
+    });
+  }
+
   /**
    * List Lightning payments.
    * @param {Object} [params]
+   * @param {string} [params.wallet_id]
    * @param {string} [params.business_id]
    * @param {string} [params.node_id]
    * @param {string} [params.offer_id]
+   * @param {string} [params.direction] - "incoming" | "outgoing"
    * @param {string} [params.status] - "pending" | "settled" | "failed"
    * @param {number} [params.limit] - Default 50
    * @param {number} [params.offset] - Default 0
@@ -128,21 +205,6 @@ export class LightningClient {
     return this.#client.request(`/lightning/payments?${qs}`);
   }
 
-  /**
-   * Send a payment to a BOLT12 offer or invoice.
-   * @param {Object} params
-   * @param {string} params.node_id - Node UUID
-   * @param {string} params.bolt12 - BOLT12 offer or invoice string
-   * @param {number} params.amount_sats - Amount in satoshis
-   * @returns {Promise<Object>}
-   */
-  async sendPayment({ node_id, bolt12, amount_sats }) {
-    return this.#client.request('/lightning/payments', {
-      method: 'POST',
-      body: JSON.stringify({ node_id, bolt12, amount_sats }),
-    });
-  }
-
   /**
    * Get payment status by payment hash.
    * @param {string} paymentHash

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

package/src/tokens.js

@@ -0,0 +1,34 @@
+import { CoinPayClient } from './client.js';
+
+/**
+ * List checkout tokens for a business.
+ * @param {Object} params
+ * @param {string} [params.apiKey] - API key if not using client
+ * @param {CoinPayClient} [params.client] - Existing client
+ * @param {string} [params.businessId] - Business ID
+ * @param {boolean} [params.activeOnly] - Only return active wallets
+ * @returns {Promise<Object>} Tokens response
+ */
+export async function getTokens({ apiKey, client, businessId, activeOnly } = {}) {
+  const coinpay = client || new CoinPayClient({ apiKey });
+  return coinpay.getTokens({ businessId, activeOnly });
+}
+
+/**
+ * List supported coins for a business.
+ * @param {Object} params
+ * @param {string} [params.apiKey] - API key if not using client
+ * @param {CoinPayClient} [params.client] - Existing client
+ * @param {string} [params.businessId] - Business ID
+ * @param {boolean} [params.activeOnly] - Only return active wallets
+ * @returns {Promise<Object>} Supported coins response
+ */
+export async function getSupportedCoins({ apiKey, client, businessId, activeOnly } = {}) {
+  const coinpay = client || new CoinPayClient({ apiKey });
+  return coinpay.getSupportedCoins({ businessId, activeOnly });
+}
+
+export default {
+  getTokens,
+  getSupportedCoins,
+};

package/src/wallet.d.ts

@@ -251,6 +251,17 @@ export declare function validateMnemonic(mnemonic: string): boolean;
  */
 export declare function getDerivationPath(chain: string, index?: number): string;
 
+/**
+ * Derive the address for a chain from a raw BIP-39 seed.
+ * (Standalone counterpart to `WalletClient.deriveAddress`; exported from
+ * wallet.js but previously missing from these type declarations.)
+ *
+ * @param seed - Raw seed bytes, e.g. bip39.mnemonicToSeedSync(mnemonic)
+ * @param chain - Chain id (e.g. 'BTC', 'ETH', 'SOL', 'POL', 'BCH')
+ * @param index - Address index (default 0)
+ */
+export declare function deriveAddress(seed: Uint8Array, chain: string, index?: number): string;
+
 /**
  * Restore a seed from encrypted backup
  */