@profullstack/coinpay 0.24.1 → 0.25.0

package/CHANGELOG.md

@@ -5,6 +5,15 @@ 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.25.0] - 2026-10-21
+
+### Added
+- `createCheckoutSession({ amount, customerEmail, accountId, property, metadata, successUrl, cancelUrl, expiresInMinutes, allowedMethods })`
+  and `getCheckoutSession(id)`: one hosted checkout URL where the buyer picks any coin the business can
+  receive, or PayPal. Webhooks for the resulting payment carry `checkout_session_id`, `customer_email`,
+  `account_id`, `property` and `metadata`.
+- `createPayment({ customerEmail, accountId, property })`, stored in the payment's metadata.
+
 ## [0.23.0] - 2026-10-21
 
 ### Added

package/bin/coinpay.js

@@ -712,7 +712,8 @@ ${colors.cyan}Commands:${colors.reset}
                             --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)
+                            complete months) or --from/--to, --name "Holder", --format pdf|html|csv|json,
+                            --newest-first puts the latest month first)
     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.24.1",
+  "version": "0.25.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

@@ -31,6 +31,57 @@ export interface PaymentParams {
   successUrl?: string;
   /** Where "Back to merchant" goes from an expired or abandoned checkout */
   cancelUrl?: string;
+  /** Email of the person paying; stored in metadata and sent on webhooks */
+  customerEmail?: string;
+  /** Your site's user id or handle for the payer */
+  accountId?: string;
+  /** Your site hostname */
+  property?: string;
+}
+
+/** Parameters for creating a hosted checkout session */
+export interface CheckoutSessionParams {
+  /** Amount in USD */
+  amount: number;
+  /** Only `'USD'` */
+  currency?: 'USD';
+  description?: string;
+  /** Email of the person paying (required) */
+  customerEmail: string;
+  /** Your site's user id or handle for the payer (required) */
+  accountId: string;
+  /** Your site hostname (defaults to the business name) */
+  property?: string;
+  metadata?: Record<string, unknown>;
+  /** `{CHECKOUT_SESSION_ID}` and `{PAYMENT_ID}` are filled in */
+  successUrl?: string;
+  cancelUrl?: string;
+  /** 15 to 120, default 60 */
+  expiresInMinutes?: number;
+  /** Coin codes (e.g. `'USDC_POL'`), `'CRYPTO'` or `'PAYPAL'`; default all */
+  allowedMethods?: string[];
+  /** Only with a merchant session token; a business API key implies it */
+  businessId?: string;
+}
+
+/** Response from `createCheckoutSession` */
+export interface CheckoutSessionResponse {
+  success: boolean;
+  id: string;
+  url: string;
+  status: 'open' | 'paid' | 'expired';
+  amount: number;
+  currency: 'USD';
+  description: string | null;
+  customer_email: string;
+  account_id: string;
+  property: string;
+  metadata: Record<string, unknown>;
+  success_url: string | null;
+  cancel_url: string | null;
+  expires_at: string;
+  methods: string[];
+  [key: string]: unknown;
 }
 
 /** Parameters for listing payments */
@@ -200,6 +251,15 @@ export class CoinPayClient {
    */
   createPayment(params: PaymentParams): Promise<CreatePaymentResponse>;
 
+  /**
+   * Create a hosted checkout session; redirect the buyer to `url`. The buyer
+   * picks any coin the business can receive, or PayPal.
+   */
+  createCheckoutSession(params: CheckoutSessionParams): Promise<CheckoutSessionResponse>;
+
+  /** Get a checkout session (`cs_...`). */
+  getCheckoutSession(sessionId: string): Promise<Record<string, unknown>>;
+
   /**
    * Get payment details by ID.
    *

package/src/client.js

@@ -255,6 +255,9 @@ export class CoinPayClient {
     metadata,
     successUrl,
     cancelUrl,
+    customerEmail,
+    accountId,
+    property,
   }) {
     // Map to API field names (snake_case)
     return this.request('/payments/create', {
@@ -268,10 +271,90 @@ export class CoinPayClient {
         metadata,
         success_url: successUrl,
         cancel_url: cancelUrl,
+        customer_email: customerEmail,
+        account_id: accountId,
+        property,
       }),
     });
   }
 
+  /**
+   * Create a hosted checkout session.
+   *
+   * Redirect the buyer to the returned `url`. There they choose any coin your
+   * business has a wallet for (stablecoins first) or PayPal when connected.
+   * The payment and every webhook for it carry `checkout_session_id`,
+   * `customer_email`, `account_id`, `property` and your `metadata`.
+   *
+   * @param {Object} params
+   * @param {number} params.amount - Amount in USD
+   * @param {string} params.customerEmail - Email of the person paying (required)
+   * @param {string} params.accountId - Your site's user id or handle for the payer (required)
+   * @param {string} [params.property] - Your site hostname (defaults to the business name)
+   * @param {string} [params.description]
+   * @param {Object} [params.metadata]
+   * @param {string} [params.successUrl] - `{CHECKOUT_SESSION_ID}` and `{PAYMENT_ID}` are filled in
+   * @param {string} [params.cancelUrl]
+   * @param {number} [params.expiresInMinutes=60] - 15 to 120
+   * @param {string[]} [params.allowedMethods] - coin codes, 'CRYPTO' or 'PAYPAL' (default: all)
+   * @returns {Promise<{success: boolean, id: string, url: string, status: string, expires_at: string, methods: string[]}>}
+   *
+   * @example
+   * const { id, url } = await client.createCheckoutSession({
+   *   amount: 9.99,
+   *   description: 'Pro plan',
+   *   customerEmail: 'buyer@example.com',
+   *   accountId: 'user_123',
+   *   property: 'example.com',
+   *   successUrl: 'https://example.com/thanks?session={CHECKOUT_SESSION_ID}',
+   *   cancelUrl: 'https://example.com/pricing',
+   * });
+   * // res.redirect(url)
+   */
+  async createCheckoutSession({
+    amount,
+    currency = 'USD',
+    description,
+    customerEmail,
+    accountId,
+    property,
+    metadata,
+    successUrl,
+    cancelUrl,
+    expiresInMinutes,
+    allowedMethods,
+    businessId,
+  }) {
+    return this.request('/checkout/sessions', {
+      method: 'POST',
+      body: JSON.stringify({
+        amount,
+        currency,
+        description,
+        customer_email: customerEmail,
+        account_id: accountId,
+        property,
+        metadata,
+        success_url: successUrl,
+        cancel_url: cancelUrl,
+        expires_in_minutes: expiresInMinutes,
+        allowed_methods: allowedMethods,
+        business_id: businessId,
+      }),
+    });
+  }
+
+  /**
+   * Get a checkout session. With your business API key the response includes
+   * the customer fields, metadata and the underlying payment ids.
+   *
+   * @param {string} sessionId - `cs_...`
+   * @returns {Promise<Object>} `{ success, session }`
+   */
+  async getCheckoutSession(sessionId) {
+    return this.request(`/checkout/sessions/${encodeURIComponent(sessionId)}`);
+  }
+
   /**
    * Get payment by ID
    *

package/src/finances-commands.js

@@ -816,9 +816,10 @@ export async function runFinancesCommand(subcommand, args, flags, ctx) {
         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 order = flags['newest-first'] === true ? 'newest' : typeof flags.order === 'string' ? flags.order : undefined;
         const written = [];
         for (const scope of wanted) {
-          const file = await api.exportPnl(client, { scope, months, period, from, to, timezone, name, format });
+          const file = await api.exportPnl(client, { scope, months, period, from, to, timezone, name, format, order });
           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 });
         }

package/src/finances-reports.js

@@ -403,8 +403,8 @@ export async function exportBooks(client, { period, from, to, timezone, scope, f
  * 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 })}`);
+export async function exportPnl(client, { scope, months, period, from, to, timezone, name, format = 'pdf', order } = {}) {
+  return client.requestBinary(`/finances/pnl${query({ scope, months, period, from, to, timezone, name, format, order })}`);
 }
 
 // ── Raw provider payloads ──