@profullstack/coinpay 0.6.8 → 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;
@@ -2615,6 +2767,14 @@ async function main() {
       case 'reputation':
         await handleReputation(subcommand, args, flags);
         break;
+
+      case 'x402':
+        await handleX402(subcommand, args, flags);
+        break;
+
+      case 'oauth':
+        await handleOAuth(subcommand, args, flags);
+        break;
         
       default:
         print.error(`Unknown command: ${command}`);
@@ -2630,4 +2790,225 @@ 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
+ */
+async function handleX402(subcommand, args, flags) {
+  const config = loadConfig();
+
+  if (!subcommand) {
+    console.log(`
+${colors.bright}x402 Payment Protocol${colors.reset}
+
+Usage: coinpay x402 <command> [options]
+
+Commands:
+  status          Check x402 facilitator status
+  test            Test x402 flow against an endpoint
+
+Options:
+  --url <url>     Endpoint URL for testing
+  --network <net> Network: base, ethereum, polygon (default: base)
+  --amount <amt>  Amount in USDC smallest unit (default: 1000000 = 1 USDC)
+`);
+    return;
+  }
+
+  switch (subcommand) {
+    case 'status': {
+      const apiKey = flags['api-key'] || config.apiKey;
+      const baseUrl = flags['base-url'] || config.baseUrl || 'https://coinpayportal.com';
+
+      print.info('Checking x402 facilitator status...');
+
+      try {
+        const response = await fetch(`${baseUrl}/api/x402/verify`, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            ...(apiKey ? { 'X-API-Key': apiKey } : {}),
+          },
+          body: JSON.stringify({ payment: { test: true } }),
+        });
+
+        if (response.status === 401) {
+          print.error('API key required or invalid. Set with: coinpay config set apiKey <key>');
+        } else if (response.status === 400) {
+          print.success('x402 facilitator is reachable and responding');
+          print.info(`Facilitator URL: ${baseUrl}/api/x402`);
+          print.info('Networks: Base, Ethereum, Polygon (Solana coming soon)');
+        } else {
+          print.warn(`Unexpected response: HTTP ${response.status}`);
+        }
+      } catch (err) {
+        print.error(`Cannot reach facilitator at ${baseUrl}: ${err.message}`);
+      }
+      break;
+    }
+
+    case 'test': {
+      const url = flags.url || args[0];
+      if (!url) {
+        print.error('URL required: coinpay x402 test --url http://localhost:3000/api/premium');
+        return;
+      }
+
+      const network = flags.network || 'base';
+      const amount = flags.amount || '1000000';
+
+      print.info(`Testing x402 flow against ${url}`);
+
+      // Step 1: Request without payment
+      try {
+        print.info('Step 1: Requesting resource without payment...');
+        const response = await fetch(url);
+
+        if (response.status === 402) {
+          const body = await response.json();
+          print.success('Received HTTP 402 Payment Required');
+
+          if (body.x402Version) {
+            print.success(`x402 version: ${body.x402Version}`);
+          }
+
+          if (body.accepts && body.accepts.length > 0) {
+            print.success(`${body.accepts.length} payment method(s) offered:`);
+            for (const accept of body.accepts) {
+              const label = accept.extra?.label || `${accept.asset} on ${accept.network}`;
+              const symbol = accept.extra?.assetSymbol || accept.asset || '';
+              print.info(`  • ${label}`);
+              print.info(`    Amount: ${accept.maxAmountRequired} ${symbol}`);
+              print.info(`    Pay to: ${accept.payTo || 'not specified'}`);
+            }
+            const facilitator = body.accepts[0]?.extra?.facilitator;
+            if (facilitator) {
+              print.info(`  Facilitator: ${facilitator}`);
+            }
+          }
+
+          print.success('x402 endpoint is correctly configured!');
+          print.warn('Note: Full payment test requires a funded wallet. Use the dashboard for end-to-end testing.');
+        } else if (response.status === 200) {
+          print.warn('Endpoint returned 200 OK — no payment required (is x402 middleware active?)');
+        } else {
+          print.warn(`Unexpected status: HTTP ${response.status}`);
+        }
+      } catch (err) {
+        print.error(`Failed to reach ${url}: ${err.message}`);
+      }
+      break;
+    }
+
+    default:
+      print.error(`Unknown x402 command: ${subcommand}`);
+      print.info('Available: status, test');
+  }
+}
+
 main().then(() => process.exit(0));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@profullstack/coinpay",
-  "version": "0.6.8",
+  "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

@@ -3,6 +3,8 @@
  * Main client class for interacting with the CoinPay API
  */
 
+import { LightningClient } from './lightning.js';
+
 const DEFAULT_BASE_URL = 'https://coinpayportal.com/api';
 
 /**
@@ -24,6 +26,9 @@ export class CoinPayClient {
     this.#apiKey = apiKey;
     this.#baseUrl = baseUrl.replace(/\/$/, ''); // Remove trailing slash
     this.#timeout = timeout;
+
+    /** @type {LightningClient} Lightning/BOLT12 operations */
+    this.lightning = new LightningClient(this);
   }
 
   /**
@@ -821,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/index.js

@@ -147,6 +147,21 @@ import {
   SubscriptionStatus,
 } from './subscriptions.js';
 
+// Lightning
+import { LightningClient } from './lightning.js';
+
+// x402 Protocol
+import {
+  createX402Middleware,
+  verifyX402Payment,
+  settleX402Payment,
+  buildPaymentRequired,
+  convertUsdToAssetAmount,
+  PAYMENT_METHODS,
+  USDC_CONTRACTS,
+  CHAIN_IDS,
+} from './x402.js';
+
 export {
   // Client
   CoinPayClient,
@@ -235,11 +250,24 @@ export {
   linkDid,
   getMyDid,
   
+  // Lightning
+  LightningClient,
+  
   // Auth
   registerMerchant,
   loginMerchant,
   getMe,
   
+  // x402 Protocol
+  createX402Middleware,
+  verifyX402Payment,
+  settleX402Payment,
+  buildPaymentRequired,
+  convertUsdToAssetAmount,
+  PAYMENT_METHODS,
+  USDC_CONTRACTS,
+  CHAIN_IDS,
+  
   // Webhook utilities
   verifyWebhookSignature,
   generateWebhookSignature,