@profullstack/coinpay 0.22.0 → 0.24.0

package/CHANGELOG.md

@@ -5,6 +5,14 @@ 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.23.0] - 2026-10-21
+
+### Added
+- `createPayment({ successUrl, cancelUrl })`, like Stripe Checkout: once the payment confirms, the
+  hosted pay page sends the customer to `successUrl` (`{PAYMENT_ID}` is replaced with the payment id);
+  `cancelUrl` is the "Back to merchant" link from an expired checkout. Before this the crypto checkout
+  had no way to return the buyer and left them on "Payment Complete!".
+
 ## [0.22.0] - 2026-10-19
 
 ### Added

package/bin/coinpay.js

@@ -710,6 +710,9 @@ ${colors.cyan}Commands:${colors.reset}
     books summary         Totals by tax category (--period 2026|2026-Q3|2026-08, --scope)
     books export          CPA pack (--period, --scope, --format csv|pdf|html|json, --output;
                             --with-documents: a ZIP with the period's tax documents, up to 8 MiB)
+    pnl                   Profit and loss, personal and business as separate files
+                            (--scope personal|business, --months 3 (default: last 3
+                            complete months) or --from/--to, --name "Holder", --format pdf|html|csv|json)
     payloads [list|download <id>]  Raw provider responses, exactly as received
     reports send <id>     Email a report (--to a@x,b@y, --format pdf,csv, --message, --no-attach)
     books send            Email the CPA pack (--to, --period, --scope, --format,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@profullstack/coinpay",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "CoinPay SDK & CLI \u2014 Accept cryptocurrency and card payments (BTC, ETH, SOL, POL, BCH, USDC) with wallet, swap and a live finances dashboard",
   "type": "module",
   "main": "./src/index.js",

package/src/client.d.ts

@@ -27,6 +27,10 @@ export interface PaymentParams {
   description?: string;
   /** Custom metadata attached to the payment (e.g., `{ orderId: 'ORD-123' }`) */
   metadata?: Record<string, unknown>;
+  /** Where the pay page sends the customer once the payment confirms, like Stripe's `success_url`. `{PAYMENT_ID}` is replaced with the payment id. */
+  successUrl?: string;
+  /** Where "Back to merchant" goes from an expired or abandoned checkout */
+  cancelUrl?: string;
 }
 
 /** Parameters for listing payments */

package/src/client.js

@@ -228,6 +228,8 @@ export class CoinPayClient {
    * @param {string} params.blockchain - Blockchain/cryptocurrency (BTC, ETH, SOL, POL, BCH, USDC_ETH, USDC_POL, USDC_SOL)
    * @param {string} [params.description] - Payment description (shown to customer)
    * @param {Object} [params.metadata] - Custom metadata (e.g., { orderId: 'ORD-123', customerId: 'CUST-456' })
+   * @param {string} [params.successUrl] - Where the pay page sends the customer once the payment confirms, like Stripe's success_url. {PAYMENT_ID} is replaced with the payment id.
+   * @param {string} [params.cancelUrl] - Where "Back to merchant" goes from an expired or abandoned checkout
    * @returns {Promise<Object>} Created payment with address and QR code
    *
    * @example
@@ -238,7 +240,8 @@ export class CoinPayClient {
    *   currency: 'USD',
    *   blockchain: 'BTC',
    *   description: 'Order #12345',
-   *   metadata: { orderId: '12345', customerEmail: 'customer@example.com' }
+   *   metadata: { orderId: '12345', customerEmail: 'customer@example.com' },
+   *   successUrl: 'https://yoursite.com/orders/12345?payment={PAYMENT_ID}',
    * });
    *
    * // Display payment.payment_address and payment.qr_code to customer
@@ -250,6 +253,8 @@ export class CoinPayClient {
     blockchain,
     description,
     metadata,
+    successUrl,
+    cancelUrl,
   }) {
     // Map to API field names (snake_case)
     return this.request('/payments/create', {
@@ -261,6 +266,8 @@ export class CoinPayClient {
         blockchain: blockchain?.toUpperCase(),
         description,
         metadata,
+        success_url: successUrl,
+        cancel_url: cancelUrl,
       }),
     });
   }

package/src/finances-commands.js

@@ -802,6 +802,30 @@ export async function runFinancesCommand(subcommand, args, flags, ctx) {
         throw new CliExit(EXIT.INVALID, 'Usage: coinpay finances books [queue|confirm <id>|confirm-all --yes|categorize|rules [add|delete]|summary|export|send]');
       }
 
+      case 'pnl':
+      case 'profit-loss': {
+        const scopes = listFlag(flags.scope);
+        const wanted = scopes.length ? scopes : ['personal', 'business'];
+        for (const s of wanted) if (s !== 'personal' && s !== 'business') throw new CliExit(EXIT.INVALID, `--scope must be personal, business or both (got ${s})`);
+        const format = typeof flags.format === 'string' ? flags.format.toLowerCase() : 'pdf';
+        if (!['pdf', 'html', 'csv', 'json'].includes(format)) throw new CliExit(EXIT.INVALID, '--format must be pdf, html, csv or json');
+        const months = flags.months === undefined ? undefined : Number(flags.months);
+        if (months !== undefined && (!Number.isInteger(months) || months < 1 || months > 24)) throw new CliExit(EXIT.INVALID, '--months must be 1 to 24');
+        const period = typeof flags.period === 'string' ? flags.period : undefined;
+        const from = typeof flags.from === 'string' ? flags.from : undefined;
+        const to = typeof flags.to === 'string' ? flags.to : undefined;
+        const timezone = typeof flags.timezone === 'string' ? flags.timezone : undefined;
+        const name = typeof flags.name === 'string' ? flags.name : undefined;
+        const written = [];
+        for (const scope of wanted) {
+          const file = await api.exportPnl(client, { scope, months, period, from, to, timezone, name, format });
+          const output = typeof flags.output === 'string' && wanted.length === 1 ? flags.output : file.filename || `pnl-${scope}.${format}`;
+          written.push({ scope, output: writeDownload(output, Buffer.from(file.bytes), { overwrite: flags.overwrite === true }), bytes: file.bytes.length });
+        }
+        emit({ files: written }, written.map((w) => `Wrote ${w.output} (${w.scope}, ${w.bytes} bytes)`).join('\n'));
+        return EXIT.OK;
+      }
+
       case 'digest': {
         const action = args[0] || 'show';
         const DAY_NAMES = ['sun', 'mon', 'tue', 'wed', 'thu', 'fri', 'sat'];
@@ -966,4 +990,4 @@ export async function runFinancesCommand(subcommand, args, flags, ctx) {
   }
 }
 
-export const EXTENDED_SUBCOMMANDS = ['connect', 'disconnect', 'consent', 'backfill', 'jobs', 'coverage', 'report', 'reports', 'statements', 'books', 'payloads', 'digest', 'due', 'due-soon', 'recurring', 'due-day', 'daily'];
+export const EXTENDED_SUBCOMMANDS = ['connect', 'disconnect', 'consent', 'backfill', 'jobs', 'coverage', 'report', 'reports', 'statements', 'books', 'pnl', 'profit-loss', 'payloads', 'digest', 'due', 'due-soon', 'recurring', 'due-day', 'daily'];

package/src/finances-reports.js

@@ -397,6 +397,16 @@ export async function exportBooks(client, { period, from, to, timezone, scope, f
   return client.requestBinary(`/finances/books/export${query({ period, from, to, timezone, scope, format, with_documents: withDocuments ? 1 : undefined })}`);
 }
 
+// ── Profit and loss ──
+
+/**
+ * Profit and loss statement for one scope. With no period it covers the
+ * last `months` complete calendar months (server default 3).
+ */
+export async function exportPnl(client, { scope, months, period, from, to, timezone, name, format = 'pdf' } = {}) {
+  return client.requestBinary(`/finances/pnl${query({ scope, months, period, from, to, timezone, name, format })}`);
+}
+
 // ── Raw provider payloads ──
 
 export async function listFinancePayloads(client, { connectionId, limit, offset } = {}) {

package/src/payments.d.ts

@@ -25,6 +25,10 @@ export interface CreatePaymentParams {
   description?: string;
   /** Custom metadata for your records */
   metadata?: Record<string, unknown>;
+  /** Where the pay page sends the customer once the payment confirms, like Stripe's `success_url`. `{PAYMENT_ID}` is replaced with the payment id. */
+  successUrl?: string;
+  /** Where "Back to merchant" goes from an expired or abandoned checkout */
+  cancelUrl?: string;
 }
 
 /** Parameters for the standalone `getPayment` function */

package/src/payments.js

@@ -34,6 +34,8 @@ import { CoinPayClient } from './client.js';
  * @param {string} params.blockchain - Blockchain to use (BTC, ETH, SOL, POL, BCH, USDC_ETH, USDC_POL, USDC_SOL)
  * @param {string} [params.description] - Payment description shown to customer
  * @param {Object} [params.metadata] - Custom metadata for your records
+ * @param {string} [params.successUrl] - Where the pay page sends the customer after the payment confirms ({PAYMENT_ID} is filled in)
+ * @param {string} [params.cancelUrl] - Where "Back to merchant" goes from an expired checkout
  * @returns {Promise<Object>} Created payment with address and QR code
  *
  * @example
@@ -60,6 +62,8 @@ export async function createPayment({
   blockchain,
   description,
   metadata,
+  successUrl,
+  cancelUrl,
 }) {
   const coinpay = client || new CoinPayClient({ apiKey });
   
@@ -70,6 +74,8 @@ export async function createPayment({
     blockchain,
     description,
     metadata,
+    successUrl,
+    cancelUrl,
   });
 }