@profullstack/coinpay 0.6.10 → 0.6.11

package/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to `@profullstack/coinpay` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.11] - 2026-03-19
+
+### Added
+- OAuth client management methods: `listOAuthClients()`, `createOAuthClient()`, `getOAuthClient()`, `deleteOAuthClient()`
+- CLI `coinpay oauth` commands: `list`, `create`, `get`, `delete`
+- OAuth section in SDK documentation
+
 ## [0.2.0] - 2025-01-15
 
 ### Added

package/bin/coinpay.js

@@ -244,6 +244,12 @@ ${colors.cyan}Commands:${colors.reset}
     events <id>           Get escrow audit log
     auth <id>             Authenticate with escrow token
 
+  ${colors.bright}oauth${colors.reset}
+    list                  List OAuth clients
+    create                Create a new OAuth client
+    get <id>              Get OAuth client details
+    delete <id>           Delete an OAuth client
+
   ${colors.bright}reputation${colors.reset}
     submit                Submit a task receipt
     query <agent-did>     Query agent reputation
@@ -2567,6 +2573,147 @@ async function main() {
   }
   
   try {
+    
+async function handleLightning(subcommand, args, flags) {
+  const client = createClient();
+
+  switch (subcommand) {
+    case 'enable': {
+      const walletId = flags['wallet-id'] || flags['wallet'];
+      if (!walletId) {
+        console.error(colors.red + 'Error: --wallet-id required' + colors.reset);
+        process.exit(1);
+      }
+      const mnemonic = await getDecryptedMnemonic(flags);
+      const result = await client.lightning.enableWallet({
+        wallet_id: walletId,
+        mnemonic,
+        business_id: flags['business-id'],
+      });
+      console.log(colors.green + '⚡ Lightning wallet enabled!' + colors.reset);
+      console.log(JSON.stringify(result, null, 2));
+      break;
+    }
+
+    case 'address': {
+      const walletId = flags['wallet-id'] || flags['wallet'];
+      const username = flags['username'] || args[0];
+      if (!walletId) {
+        console.error(colors.red + 'Error: --wallet-id required' + colors.reset);
+        process.exit(1);
+      }
+      if (!username) {
+        // GET current address
+        const result = await client.lightning.getAddress(walletId);
+        if (result.lightning_address) {
+          console.log(colors.green + '⚡ ' + result.lightning_address + colors.reset);
+        } else {
+          console.log('No Lightning Address registered. Use: coinpay ln address --username <name>');
+        }
+      } else {
+        // POST register address
+        const result = await client.lightning.registerAddress({ wallet_id: walletId, username });
+        console.log(colors.green + '⚡ Registered: ' + result.lightning_address + colors.reset);
+      }
+      break;
+    }
+
+    case 'address-check': {
+      const username = flags['username'] || args[0];
+      if (!username) {
+        console.error(colors.red + 'Error: --username required' + colors.reset);
+        process.exit(1);
+      }
+      const result = await client.lightning.checkAddressAvailable(username);
+      console.log(result.available
+        ? colors.green + '✓ ' + username + ' is available' + colors.reset
+        : colors.red + '✗ ' + username + ' is taken' + colors.reset);
+      break;
+    }
+
+    case 'invoice': {
+      const walletId = flags['wallet-id'] || flags['wallet'];
+      const amount = parseInt(flags['amount'] || args[0]);
+      if (!walletId || !amount) {
+        console.error(colors.red + 'Error: --wallet-id and --amount required' + colors.reset);
+        process.exit(1);
+      }
+      const result = await client.lightning.createInvoice({
+        wallet_id: walletId,
+        amount_sats: amount,
+        description: flags['description'] || flags['desc'] || '',
+      });
+      console.log(colors.green + '⚡ Invoice created' + colors.reset);
+      console.log(JSON.stringify(result, null, 2));
+      break;
+    }
+
+    case 'send': {
+      const walletId = flags['wallet-id'] || flags['wallet'];
+      const destination = flags['to'] || args[0];
+      const amount = flags['amount'] ? parseInt(flags['amount']) : undefined;
+      if (!walletId || !destination) {
+        console.error(colors.red + 'Error: --wallet-id and --to required' + colors.reset);
+        process.exit(1);
+      }
+      const result = await client.lightning.sendPayment({
+        wallet_id: walletId,
+        destination,
+        amount_sats: amount,
+      });
+      console.log(colors.green + '⚡ Payment sent!' + colors.reset);
+      console.log(JSON.stringify(result, null, 2));
+      break;
+    }
+
+    case 'payments': {
+      const walletId = flags['wallet-id'] || flags['wallet'];
+      if (!walletId) {
+        console.error(colors.red + 'Error: --wallet-id required' + colors.reset);
+        process.exit(1);
+      }
+      const result = await client.lightning.listPayments({
+        wallet_id: walletId,
+        direction: flags['direction'],
+        limit: flags['limit'] ? parseInt(flags['limit']) : undefined,
+      });
+      const payments = result.data?.payments || result.payments || [];
+      if (payments.length === 0) {
+        console.log('No Lightning payments found.');
+      } else {
+        for (const p of payments) {
+          const dir = p.direction === 'outgoing' ? colors.red + '↑ SENT' : colors.green + '↓ RECV';
+          const sats = Math.floor((p.amount_msat || 0) / 1000);
+          console.log(`${dir}${colors.reset}  ${sats} sats  ${p.status}  ${p.created_at}`);
+        }
+      }
+      break;
+    }
+
+    case 'balance': {
+      const walletId = flags['wallet-id'] || flags['wallet'];
+      if (!walletId) {
+        console.error(colors.red + 'Error: --wallet-id required' + colors.reset);
+        process.exit(1);
+      }
+      // Use the web-wallet balance endpoint filtered by LN
+      const result = await client.request(`/web-wallet/balance?wallet_id=${walletId}`);
+      const balances = result.data?.balances || result.balances || [];
+      const ln = balances.find(b => b.chain === 'LN' || b.currency === 'LN');
+      if (ln) {
+        console.log(colors.green + '⚡ ' + ln.balance + ' BTC (' + Math.floor(parseFloat(ln.balance) * 100_000_000) + ' sats)' + colors.reset);
+      } else {
+        console.log('No Lightning balance. Enable Lightning first: coinpay ln enable');
+      }
+      break;
+    }
+
+    default:
+      console.log(`Unknown lightning command: ${subcommand}`);
+      showHelp();
+  }
+}
+
     switch (command) {
       case 'config':
         await handleConfig(subcommand, args);
@@ -2596,6 +2743,11 @@ async function main() {
         await handleEscrow(subcommand, args, flags);
         break;
 
+      case 'ln':
+      case 'lightning':
+        await handleLightning(subcommand, args, flags);
+        break;
+
       case 'webhook':
         await handleWebhook(subcommand, args, flags);
         break;
@@ -2619,6 +2771,10 @@ async function main() {
       case 'x402':
         await handleX402(subcommand, args, flags);
         break;
+
+      case 'oauth':
+        await handleOAuth(subcommand, args, flags);
+        break;
         
       default:
         print.error(`Unknown command: ${command}`);
@@ -2634,6 +2790,112 @@ async function main() {
   }
 }
 
+/**
+ * OAuth commands
+ */
+async function handleOAuth(subcommand, args, flags) {
+  const client = createClient();
+
+  switch (subcommand) {
+    case 'list': {
+      const result = await client.listOAuthClients();
+      const clients = result.clients || [];
+
+      if (clients.length === 0) {
+        print.info('No OAuth clients found.');
+      } else {
+        console.log(`\n${colors.bright}OAuth Clients${colors.reset} (${clients.length})\n`);
+        for (const c of clients) {
+          console.log(`  ${colors.bright}${c.name}${colors.reset}`);
+          console.log(`    Client ID: ${c.client_id}`);
+          if (c.description) console.log(`    Description: ${c.description}`);
+          if (c.redirect_uris) console.log(`    Redirect URIs: ${c.redirect_uris.join(', ')}`);
+          if (c.scopes) console.log(`    Scopes: ${Array.isArray(c.scopes) ? c.scopes.join(', ') : c.scopes}`);
+          console.log();
+        }
+      }
+
+      if (flags.json) print.json(result);
+      break;
+    }
+
+    case 'create': {
+      const name = flags.name;
+      const redirectUri = flags['redirect-uri'];
+      const scope = flags.scope;
+      const description = flags.description;
+
+      if (!name || !redirectUri) {
+        print.error('Required: --name, --redirect-uri');
+        print.info('Example: coinpay oauth create --name "My App" --redirect-uri https://myapp.com/callback --scope openid,profile');
+        return;
+      }
+
+      const redirectUris = redirectUri.split(',').map(u => u.trim());
+      const scopes = scope ? scope.split(',').map(s => s.trim()) : undefined;
+
+      const result = await client.createOAuthClient({
+        name,
+        redirectUris,
+        scopes,
+        description,
+      });
+
+      print.success('OAuth client created');
+      if (result.client_id) {
+        console.log(`\n  ${colors.bright}Client ID:${colors.reset}     ${result.client_id}`);
+      }
+      if (result.client_secret) {
+        console.log(`  ${colors.bright}Client Secret:${colors.reset} ${colors.yellow}${result.client_secret}${colors.reset}`);
+        console.log();
+        print.warn('Save the client secret — it is only shown once!');
+      }
+
+      if (flags.json) print.json(result);
+      break;
+    }
+
+    case 'get': {
+      const id = args[0];
+      if (!id) {
+        print.error('OAuth client ID required');
+        print.info('Usage: coinpay oauth get <client-id>');
+        return;
+      }
+
+      const result = await client.getOAuthClient(id);
+
+      print.success(`OAuth Client: ${result.name || id}`);
+      if (result.client_id) print.info(`  Client ID: ${result.client_id}`);
+      if (result.description) print.info(`  Description: ${result.description}`);
+      if (result.redirect_uris) print.info(`  Redirect URIs: ${result.redirect_uris.join(', ')}`);
+      if (result.scopes) print.info(`  Scopes: ${Array.isArray(result.scopes) ? result.scopes.join(', ') : result.scopes}`);
+      if (result.created_at) print.info(`  Created: ${result.created_at}`);
+
+      if (flags.json) print.json(result);
+      break;
+    }
+
+    case 'delete': {
+      const id = args[0];
+      if (!id) {
+        print.error('OAuth client ID required');
+        print.info('Usage: coinpay oauth delete <client-id>');
+        return;
+      }
+
+      await client.deleteOAuthClient(id);
+      print.success(`OAuth client ${id} deleted`);
+      break;
+    }
+
+    default:
+      print.error(`Unknown oauth command: ${subcommand}`);
+      print.info('Available: list, create, get, delete');
+      process.exit(1);
+  }
+}
+
 /**
  * Handle x402 commands
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@profullstack/coinpay",
-  "version": "0.6.10",
+  "version": "0.6.11",
   "description": "CoinPay SDK & CLI — Accept cryptocurrency payments (BTC, ETH, SOL, POL, BCH, USDC) with wallet and swap support",
   "type": "module",
   "main": "./src/index.js",

package/src/auth.js

@@ -18,6 +18,9 @@
  * @returns {Promise<Object>} { success: boolean, merchant: Object, token: string }
  */
 export async function registerMerchant(client, { email, password, name }) {
+  if (!email) throw new Error('Email is required');
+  if (!password) throw new Error('Password is required');
+
   return client.requestUnauthenticated('/auth/register', {
     method: 'POST',
     body: JSON.stringify({
@@ -37,6 +40,9 @@ export async function registerMerchant(client, { email, password, name }) {
  * @returns {Promise<Object>} { success: boolean, merchant: Object, token: string }
  */
 export async function loginMerchant(client, { email, password }) {
+  if (!email) throw new Error('Email is required');
+  if (!password) throw new Error('Password is required');
+
   return client.requestUnauthenticated('/auth/login', {
     method: 'POST',
     body: JSON.stringify({

package/src/client.js

@@ -826,6 +826,91 @@ export class CoinPayClient {
       method: 'DELETE',
     });
   }
+
+  // ── OAuth Client Methods ─────────────────────────────────
+
+  /**
+   * List OAuth clients
+   *
+   * Returns all OAuth clients registered under your account.
+   *
+   * @returns {Promise<Object>} List of OAuth clients
+   *
+   * @example
+   * const result = await client.listOAuthClients();
+   * for (const app of result.clients) {
+   *   console.log(app.client_id, app.name);
+   * }
+   */
+  async listOAuthClients() {
+    return this.request('/oauth/clients');
+  }
+
+  /**
+   * Create a new OAuth client
+   *
+   * Registers a new OAuth application. Returns the client_id and client_secret.
+   * Store the client_secret securely — it is only shown once.
+   *
+   * @param {Object} params - OAuth client parameters
+   * @param {string} params.name - Application name
+   * @param {string[]} params.redirectUris - Authorized redirect URIs
+   * @param {string[]} [params.scopes] - Requested scopes (e.g., ['openid', 'profile'])
+   * @param {string} [params.description] - Application description
+   * @returns {Promise<Object>} Created OAuth client with client_id and client_secret
+   *
+   * @example
+   * const app = await client.createOAuthClient({
+   *   name: 'My App',
+   *   redirectUris: ['https://myapp.com/callback'],
+   *   scopes: ['openid', 'profile'],
+   *   description: 'My awesome application',
+   * });
+   * console.log('Client ID:', app.client_id);
+   * console.log('Client Secret:', app.client_secret);
+   */
+  async createOAuthClient({ name, redirectUris, scopes, description }) {
+    return this.request('/oauth/clients', {
+      method: 'POST',
+      body: JSON.stringify({
+        name,
+        redirect_uris: redirectUris,
+        scopes,
+        description,
+      }),
+    });
+  }
+
+  /**
+   * Get an OAuth client by ID
+   *
+   * @param {string} id - OAuth client ID
+   * @returns {Promise<Object>} OAuth client details
+   *
+   * @example
+   * const app = await client.getOAuthClient('oac_abc123');
+   * console.log(app.name, app.redirect_uris);
+   */
+  async getOAuthClient(id) {
+    return this.request(`/oauth/clients/${id}`);
+  }
+
+  /**
+   * Delete an OAuth client
+   *
+   * Permanently removes an OAuth client and revokes all associated tokens.
+   *
+   * @param {string} id - OAuth client ID
+   * @returns {Promise<Object>} Deletion confirmation
+   *
+   * @example
+   * await client.deleteOAuthClient('oac_abc123');
+   */
+  async deleteOAuthClient(id) {
+    return this.request(`/oauth/clients/${id}`, {
+      method: 'DELETE',
+    });
+  }
 }
 
 export default CoinPayClient;

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