@profullstack/coinpay 0.6.2 → 0.6.4

package/bin/coinpay.js

@@ -227,6 +227,10 @@ ${colors.cyan}Commands:${colors.reset}
     badge [did]           Get embeddable reputation badge URL
     verify <id>           Verify a credential
     revocations           List revoked credentials
+    issuer register       Register platform issuer (--name, --domain)
+    issuer list           List your platform issuers
+    issuer rotate         Rotate issuer API key (--id)
+    issuer deactivate     Deactivate an issuer (--id)
 
   ${colors.bright}webhook${colors.reset}
     logs <business-id>    Get webhook logs
@@ -1863,6 +1867,98 @@ async function handleReputation(subcommand, args, flags) {
       break;
     }
 
+    case 'issuer': {
+      const issuerSubcommand = args[0];
+      const client = createClient();
+
+      switch (issuerSubcommand) {
+        case 'register': {
+          const name = flags.name;
+          const domain = flags.domain;
+          if (!name || !domain) {
+            print.error('Required: --name <name> --domain <domain>');
+            return;
+          }
+          const { registerPlatformIssuer } = await import('../src/reputation.js');
+          const result = await registerPlatformIssuer(client, { name, domain, did: flags.did });
+
+          if (result.success) {
+            print.success(`Issuer registered: ${result.issuer.name}`);
+            print.info(`  ID: ${result.issuer.id}`);
+            print.info(`  DID: ${result.issuer.did}`);
+            print.info(`  Domain: ${result.issuer.domain}`);
+            console.log(`\n  ${colors.bright}${colors.yellow}⚠️  API Key (shown only once):${colors.reset}`);
+            console.log(`  ${colors.yellow}${result.api_key}${colors.reset}\n`);
+          } else {
+            print.error(result.error || 'Registration failed');
+          }
+          if (flags.json) print.json(result);
+          break;
+        }
+
+        case 'list': {
+          const { listPlatformIssuers } = await import('../src/reputation.js');
+          const result = await listPlatformIssuers(client);
+
+          if (result.success) {
+            print.info(`Platform issuers (${result.issuers.length}):`);
+            for (const iss of result.issuers) {
+              const status = iss.active ? `${colors.green}active${colors.reset}` : `${colors.red}inactive${colors.reset}`;
+              console.log(`  ${iss.id} | ${iss.name} | ${iss.domain} | ${status} | key: ${iss.api_key || 'none'}`);
+            }
+          } else {
+            print.error(result.error || 'Failed to list issuers');
+          }
+          if (flags.json) print.json(result);
+          break;
+        }
+
+        case 'rotate': {
+          const id = flags.id || args[1];
+          if (!id) {
+            print.error('Required: --id <issuer-id>');
+            return;
+          }
+          const { rotatePlatformApiKey } = await import('../src/reputation.js');
+          const result = await rotatePlatformApiKey(client, id);
+
+          if (result.success) {
+            print.success(`API key rotated for: ${result.issuer.name}`);
+            console.log(`\n  ${colors.bright}${colors.yellow}⚠️  New API Key (shown only once):${colors.reset}`);
+            console.log(`  ${colors.yellow}${result.api_key}${colors.reset}\n`);
+          } else {
+            print.error(result.error || 'Rotation failed');
+          }
+          if (flags.json) print.json(result);
+          break;
+        }
+
+        case 'deactivate': {
+          const id = flags.id || args[1];
+          if (!id) {
+            print.error('Required: --id <issuer-id>');
+            return;
+          }
+          const { deactivatePlatformIssuer } = await import('../src/reputation.js');
+          const result = await deactivatePlatformIssuer(client, id);
+
+          if (result.success) {
+            print.success(`Issuer deactivated: ${result.issuer.name}`);
+          } else {
+            print.error(result.error || 'Deactivation failed');
+          }
+          if (flags.json) print.json(result);
+          break;
+        }
+
+        default:
+          print.error(`Unknown issuer command: ${issuerSubcommand}`);
+          print.info('Available: register, list, rotate, deactivate');
+          process.exit(1);
+      }
+      break;
+    }
+
     case 'badge': {
       const did = args[0];
       if (!did) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@profullstack/coinpay",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "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"
     },
+    "./card-payments": {
+      "import": "./src/card-payments.js",
+      "types": "./src/card-payments.d.ts"
+    },
     "./webhooks": {
       "import": "./src/webhooks.js",
       "types": "./src/webhooks.d.ts"

package/src/card-payments.js

@@ -0,0 +1,298 @@
+/**
+ * CoinPay Card Payments - Convenience functions for Stripe integration
+ * 
+ * This module provides high-level convenience functions for working with
+ * card payments through Stripe Connect, similar to the payments.js module.
+ */
+
+/**
+ * Quick card payment creation with sensible defaults
+ * 
+ * @param {import('./client.js').CoinPayClient} client - CoinPay client instance
+ * @param {string} businessId - Business ID
+ * @param {number} amountUSD - Amount in USD (will be converted to cents)
+ * @param {string} description - Payment description
+ * @param {Object} [options] - Additional options
+ * @param {Object} [options.metadata] - Custom metadata
+ * @param {string} [options.successUrl] - Success redirect URL
+ * @param {string} [options.cancelUrl] - Cancel redirect URL
+ * @param {boolean} [options.escrowMode=false] - Enable escrow mode
+ * @returns {Promise<Object>} Payment session with checkout URL
+ * 
+ * @example
+ * import { createQuickCardPayment } from '@profullstack/coinpay/card-payments';
+ * 
+ * const payment = await createQuickCardPayment(client, 'business-id', 50, 'Order #123', {
+ *   metadata: { orderId: '123' },
+ *   escrowMode: true
+ * });
+ * 
+ * // Redirect customer to: payment.checkout_url
+ */
+export async function createQuickCardPayment(client, businessId, amountUSD, description, options = {}) {
+  const {
+    metadata = {},
+    successUrl,
+    cancelUrl,
+    escrowMode = false,
+  } = options;
+
+  // Convert USD to cents
+  const amountCents = Math.round(amountUSD * 100);
+
+  return client.createCardPayment({
+    businessId,
+    amount: amountCents,
+    currency: 'usd',
+    description,
+    metadata,
+    successUrl,
+    cancelUrl,
+    escrowMode,
+  });
+}
+
+/**
+ * Wait for merchant to complete Stripe onboarding
+ * 
+ * Polls the Stripe account status until onboarding is complete.
+ * Useful for integration flows where you need to wait for merchant setup.
+ * 
+ * @param {import('./client.js').CoinPayClient} client - CoinPay client instance
+ * @param {string} businessId - Business ID
+ * @param {Object} [options] - Polling options
+ * @param {number} [options.intervalMs=5000] - Polling interval in ms
+ * @param {number} [options.timeoutMs=300000] - Timeout in ms (default: 5 minutes)
+ * @param {Function} [options.onStatusChange] - Callback for status changes
+ * @returns {Promise<Object>} Final account status when onboarding complete
+ * 
+ * @example
+ * const accountStatus = await waitForStripeOnboarding(client, 'business-id', {
+ *   onStatusChange: (status) => {
+ *     console.log(`Onboarding status: ${JSON.stringify(status)}`);
+ *   }
+ * });
+ */
+export async function waitForStripeOnboarding(client, businessId, options = {}) {
+  const {
+    intervalMs = 5000,
+    timeoutMs = 300000, // 5 minutes
+    onStatusChange,
+  } = options;
+
+  const startTime = Date.now();
+
+  while (Date.now() - startTime < timeoutMs) {
+    const status = await client.getStripeAccountStatus(businessId);
+
+    if (onStatusChange) {
+      onStatusChange(status);
+    }
+
+    if (status.onboarding_complete) {
+      return status;
+    }
+
+    // Wait before next poll
+    await new Promise(resolve => setTimeout(resolve, intervalMs));
+  }
+
+  throw new Error(`Stripe onboarding timeout after ${timeoutMs}ms`);
+}
+
+/**
+ * Create payment with automatic merchant onboarding check
+ * 
+ * Checks if merchant has completed Stripe onboarding first, and provides
+ * helpful error messages if not. Prevents failed payment attempts.
+ * 
+ * @param {import('./client.js').CoinPayClient} client - CoinPay client instance
+ * @param {Object} params - Payment parameters (same as createCardPayment)
+ * @returns {Promise<Object>} Payment session or onboarding info if incomplete
+ * 
+ * @example
+ * const result = await createCardPaymentWithOnboardingCheck(client, {
+ *   businessId: 'business-id',
+ *   amount: 5000,
+ *   description: 'Order #123'
+ * });
+ * 
+ * if (result.requires_onboarding) {
+ *   // Redirect merchant to result.onboarding_url
+ * } else {
+ *   // Redirect customer to result.checkout_url
+ * }
+ */
+export async function createCardPaymentWithOnboardingCheck(client, params) {
+  try {
+    // Check onboarding status first
+    const status = await client.getStripeAccountStatus(params.businessId);
+
+    if (!status.onboarding_complete) {
+      // Generate onboarding link if needed
+      const onboarding = await client.createStripeOnboardingLink(params.businessId);
+      
+      return {
+        requires_onboarding: true,
+        onboarding_url: onboarding.onboarding_url,
+        status: status,
+        message: 'Merchant must complete Stripe onboarding before accepting card payments',
+      };
+    }
+
+    // Onboarding complete, create payment
+    const payment = await client.createCardPayment(params);
+    return {
+      requires_onboarding: false,
+      ...payment,
+    };
+
+  } catch (error) {
+    if (error.status === 404) {
+      // No Stripe account exists, need onboarding
+      const onboarding = await client.createStripeOnboardingLink(params.businessId);
+      
+      return {
+        requires_onboarding: true,
+        onboarding_url: onboarding.onboarding_url,
+        status: null,
+        message: 'Merchant needs to complete Stripe onboarding',
+      };
+    }
+    throw error;
+  }
+}
+
+/**
+ * Get payment method support status
+ * 
+ * Returns which payment methods are available for a merchant.
+ * Helps with conditional UI rendering.
+ * 
+ * @param {import('./client.js').CoinPayClient} client - CoinPay client instance
+ * @param {string} businessId - Business ID
+ * @returns {Promise<Object>} Available payment methods
+ * 
+ * @example
+ * const support = await getPaymentMethodSupport(client, 'business-id');
+ * console.log(support);
+ * // {
+ * //   crypto: true,
+ * //   cards: true,
+ * //   escrow: true,
+ * //   stripe_onboarding_complete: true
+ * // }
+ */
+export async function getPaymentMethodSupport(client, businessId) {
+  try {
+    // Check if business exists (crypto payments always work)
+    await client.getBusiness(businessId);
+    
+    let cardSupport = false;
+    let stripeOnboardingComplete = false;
+
+    // Check Stripe status
+    try {
+      const stripeStatus = await client.getStripeAccountStatus(businessId);
+      cardSupport = stripeStatus.onboarding_complete;
+      stripeOnboardingComplete = stripeStatus.onboarding_complete;
+    } catch (error) {
+      // No Stripe account = no card support yet
+      cardSupport = false;
+      stripeOnboardingComplete = false;
+    }
+
+    return {
+      crypto: true, // Always available
+      cards: cardSupport,
+      escrow: cardSupport, // Card escrow requires Stripe
+      stripe_onboarding_complete: stripeOnboardingComplete,
+    };
+
+  } catch (error) {
+    if (error.status === 404) {
+      return {
+        crypto: false,
+        cards: false,
+        escrow: false,
+        stripe_onboarding_complete: false,
+        error: 'Business not found',
+      };
+    }
+    throw error;
+  }
+}
+
+/**
+ * Format amount for display
+ * 
+ * Converts cents to dollar amount with proper formatting.
+ * 
+ * @param {number} amountCents - Amount in cents
+ * @param {string} [currency='USD'] - Currency code
+ * @returns {string} Formatted amount string
+ * 
+ * @example
+ * formatCardAmount(5000); // "$50.00"
+ * formatCardAmount(5050); // "$50.50"
+ * formatCardAmount(500, 'EUR'); // "€5.00"
+ */
+export function formatCardAmount(amountCents, currency = 'USD') {
+  const amount = amountCents / 100;
+  
+  const formatters = {
+    USD: (amt) => `$${amt.toFixed(2)}`,
+    EUR: (amt) => `€${amt.toFixed(2)}`,
+    GBP: (amt) => `£${amt.toFixed(2)}`,
+    CAD: (amt) => `C$${amt.toFixed(2)}`,
+  };
+
+  const formatter = formatters[currency.toUpperCase()];
+  if (formatter) {
+    return formatter(amount);
+  }
+
+  // Fallback for unknown currencies
+  return `${amount.toFixed(2)} ${currency.toUpperCase()}`;
+}
+
+/**
+ * Calculate platform fees for card payments
+ * 
+ * @param {number} amountCents - Payment amount in cents
+ * @param {string} tier - Merchant tier ('free' or 'pro')
+ * @returns {Object} Fee breakdown
+ * 
+ * @example
+ * const fees = calculateCardPaymentFees(5000, 'free');
+ * console.log(fees);
+ * // {
+ * //   amount: 5000,
+ * //   platformFee: 50,
+ * //   platformFeePercent: 1,
+ * //   merchantReceives: 4950 // before Stripe fees
+ * // }
+ */
+export function calculateCardPaymentFees(amountCents, tier = 'free') {
+  const platformFeePercent = tier === 'pro' ? 0.5 : 1.0; // 0.5% or 1%
+  const platformFeeCents = Math.round(amountCents * (platformFeePercent / 100));
+  
+  return {
+    amount: amountCents,
+    platformFee: platformFeeCents,
+    platformFeePercent,
+    merchantReceives: amountCents - platformFeeCents, // Before Stripe processing fees
+  };
+}
+
+/**
+ * Default export with all convenience functions
+ */
+export default {
+  createQuickCardPayment,
+  waitForStripeOnboarding,
+  createCardPaymentWithOnboardingCheck,
+  getPaymentMethodSupport,
+  formatCardAmount,
+  calculateCardPaymentFees,
+};

package/src/client.js

@@ -522,6 +522,169 @@ export class CoinPayClient {
     const { authenticateEscrow } = await import('./escrow.js');
     return authenticateEscrow(this, escrowId, token);
   }
+
+  // ── Stripe Card Payment Methods ────────────────────────
+
+  /**
+   * Create a card payment using Stripe
+   * 
+   * Creates a card payment session through Stripe Connect. Returns a checkout URL
+   * that customers can use to pay with their credit/debit card.
+   * 
+   * @param {Object} params - Payment parameters
+   * @param {string} params.businessId - Business ID (merchant must have completed Stripe onboarding)
+   * @param {number} params.amount - Amount in cents (e.g., 5000 = $50.00)
+   * @param {string} [params.currency='usd'] - Currency code (usd, eur, etc.)
+   * @param {string} [params.description] - Payment description
+   * @param {Object} [params.metadata] - Custom metadata
+   * @param {string} [params.successUrl] - URL to redirect on successful payment
+   * @param {string} [params.cancelUrl] - URL to redirect on payment cancellation
+   * @param {boolean} [params.escrowMode=false] - Whether to use escrow mode (holds funds until release)
+   * @returns {Promise<Object>} Payment session with checkout URL
+   * 
+   * @example
+   * // Create a $50 card payment
+   * const payment = await client.createCardPayment({
+   *   businessId: 'your-business-id',
+   *   amount: 5000, // $50.00 in cents
+   *   currency: 'usd',
+   *   description: 'Order #12345',
+   *   metadata: { orderId: '12345' },
+   *   successUrl: 'https://yourdomain.com/success',
+   *   cancelUrl: 'https://yourdomain.com/cancel'
+   * });
+   * 
+   * // Redirect customer to payment.checkout_url
+   */
+  async createCardPayment({
+    businessId,
+    amount,
+    currency = 'usd',
+    description,
+    metadata,
+    successUrl,
+    cancelUrl,
+    escrowMode = false
+  }) {
+    return this.request('/stripe/payments/create', {
+      method: 'POST',
+      body: JSON.stringify({
+        businessId,
+        amount,
+        currency,
+        description,
+        metadata,
+        successUrl,
+        cancelUrl,
+        escrowMode
+      }),
+    });
+  }
+
+  /**
+   * Get Stripe account onboarding status
+   * 
+   * Checks whether a merchant has completed Stripe Connect onboarding
+   * and is able to accept card payments.
+   * 
+   * @param {string} businessId - Business ID
+   * @returns {Promise<Object>} Account status and capabilities
+   * 
+   * @example
+   * const status = await client.getStripeAccountStatus('business-id');
+   * if (status.onboarding_complete) {
+   *   console.log('Merchant can accept card payments');
+   * }
+   */
+  async getStripeAccountStatus(businessId) {
+    return this.request(`/stripe/connect/status/${businessId}`);
+  }
+
+  /**
+   * 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.
+   * 
+   * @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.)
+   * @returns {Promise<Object>} Onboarding link and account ID
+   * 
+   * @example
+   * const onboarding = await client.createStripeOnboardingLink('business-id', {
+   *   email: 'merchant@example.com',
+   *   country: 'US'
+   * });
+   * 
+   * // Redirect merchant to onboarding.onboarding_url
+   */
+  async createStripeOnboardingLink(businessId, params = {}) {
+    return this.request('/stripe/connect/onboard', {
+      method: 'POST',
+      body: JSON.stringify({
+        businessId,
+        ...params
+      }),
+    });
+  }
+
+  /**
+   * Release card escrow funds to merchant
+   * 
+   * Releases funds held in card escrow mode to the merchant's Stripe account.
+   * Only works for payments created with escrowMode: true.
+   * 
+   * @param {string} escrowId - Escrow ID (returned from escrow payment creation)
+   * @param {string} [reason] - Reason for release
+   * @returns {Promise<Object>} Release confirmation with transfer details
+   * 
+   * @example
+   * const release = await client.releaseCardEscrow('escrow-id', 'Work completed');
+   * console.log(`Released $${release.amount_transferred / 100} to merchant`);
+   */
+  async releaseCardEscrow(escrowId, reason) {
+    return this.request('/stripe/escrow/release', {
+      method: 'POST',
+      body: JSON.stringify({
+        escrowId,
+        reason
+      }),
+    });
+  }
+
+  /**
+   * Refund a card payment
+   * 
+   * Creates a refund for a card payment. Works for both gateway and escrow mode payments.
+   * For escrow payments, refunds from held funds. For gateway payments, refunds from merchant account.
+   * 
+   * @param {string} paymentId - Payment intent ID or escrow ID
+   * @param {Object} [params] - Optional parameters
+   * @param {number} [params.amount] - Refund amount in cents (partial refund). Omit for full refund.
+   * @param {string} [params.reason] - Reason for refund
+   * @returns {Promise<Object>} Refund confirmation
+   * 
+   * @example
+   * // Full refund
+   * const refund = await client.refundCardPayment('payment-id');
+   * 
+   * // Partial refund
+   * const partialRefund = await client.refundCardPayment('payment-id', {
+   *   amount: 2500, // $25.00 refund
+   *   reason: 'Customer complaint'
+   * });
+   */
+  async refundCardPayment(paymentId, params = {}) {
+    return this.request('/stripe/escrow/refund', {
+      method: 'POST',
+      body: JSON.stringify({
+        escrowId: paymentId, // API expects escrowId param
+        ...params
+      }),
+    });
+  }
 }
 
 export default CoinPayClient;

package/src/reputation.d.ts

@@ -113,3 +113,20 @@ export interface DidInfo {
 export function getMyDid(client: CoinPayClient): Promise<DidInfo>;
 export function claimDid(client: CoinPayClient): Promise<DidInfo>;
 export function linkDid(client: CoinPayClient, params: { did: string; publicKey: string; signature: string }): Promise<DidInfo>;
+
+// Platform Issuer Self-Service
+
+export interface PlatformIssuer {
+  id: string;
+  did: string;
+  name: string;
+  domain: string;
+  active: boolean;
+  api_key: string | null;
+  created_at: string;
+}
+
+export function registerPlatformIssuer(client: CoinPayClient, params: { name: string; domain: string; did?: string }): Promise<{ success: boolean; issuer: PlatformIssuer; api_key: string }>;
+export function listPlatformIssuers(client: CoinPayClient): Promise<{ success: boolean; issuers: PlatformIssuer[] }>;
+export function rotatePlatformApiKey(client: CoinPayClient, issuerId: string): Promise<{ success: boolean; issuer: PlatformIssuer; api_key: string }>;
+export function deactivatePlatformIssuer(client: CoinPayClient, issuerId: string): Promise<{ success: boolean; issuer: PlatformIssuer }>;

package/src/reputation.js

@@ -180,3 +180,56 @@ export async function getTrustProfile(client, agentDid) {
 export function getBadgeUrl(baseUrl, did) {
   return `${baseUrl}/api/reputation/badge/${encodeURIComponent(did)}`;
 }
+
+// ═══════════════════════════════════════════════════════════
+// Platform Issuer Self-Service
+// ═══════════════════════════════════════════════════════════
+
+/**
+ * Register a new platform issuer
+ * @param {import('./client.js').CoinPayClient} client
+ * @param {Object} params
+ * @param {string} params.name - Issuer name (alphanumeric, dots, hyphens, underscores)
+ * @param {string} params.domain - Issuer domain
+ * @param {string} [params.did] - Optional DID (auto-generated from domain if omitted)
+ * @returns {Promise<Object>} { success, issuer, api_key }
+ */
+export async function registerPlatformIssuer(client, { name, domain, did }) {
+  return client.request('/reputation/issuers', {
+    method: 'POST',
+    body: JSON.stringify({ name, domain, did }),
+  });
+}
+
+/**
+ * List merchant's registered platform issuers (keys masked)
+ * @param {import('./client.js').CoinPayClient} client
+ * @returns {Promise<Object>} { success, issuers }
+ */
+export async function listPlatformIssuers(client) {
+  return client.request('/reputation/issuers');
+}
+
+/**
+ * Rotate a platform issuer's API key
+ * @param {import('./client.js').CoinPayClient} client
+ * @param {string} issuerId - The issuer ID
+ * @returns {Promise<Object>} { success, issuer, api_key }
+ */
+export async function rotatePlatformApiKey(client, issuerId) {
+  return client.request(`/reputation/issuers/${issuerId}/rotate`, {
+    method: 'POST',
+  });
+}
+
+/**
+ * Deactivate a platform issuer (soft delete)
+ * @param {import('./client.js').CoinPayClient} client
+ * @param {string} issuerId - The issuer ID
+ * @returns {Promise<Object>} { success, issuer }
+ */
+export async function deactivatePlatformIssuer(client, issuerId) {
+  return client.request(`/reputation/issuers/${issuerId}`, {
+    method: 'DELETE',
+  });
+}