@backendfree/payments 0.0.0-stage → 0.1.0

package/src/index.ts

@@ -0,0 +1,210 @@
+/**
+ * @backendfree/payments
+ *
+ * A project's money: what has been taken, and taking some.
+ *
+ *     import { Client } from '@backendfree/core';
+ *     import { Payments } from '@backendfree/payments';
+ *
+ *     const payments = new Payments(new Client({ origin, key: process.env.SECRET_KEY }));
+ *     const payment = await payments.checkout({ amount: 3500, success_url, cancel_url });
+ *     redirect(payment.checkout_url);
+ *
+ * Four things are worth knowing before using it.
+ *
+ * **All of it needs a secret key, and this throws on a publishable one.** A
+ * payment carries the paying customer's name and email, and a checkout is a
+ * charge on somebody's bank account. Neither belongs in a bundle whoever loads
+ * the site can read, so the mistake is refused at construction rather than by a
+ * 403 in production.
+ *
+ * **There is no refund method, and that is deliberate.** Refunding is the one
+ * act that moves money out of the business's own account, and it lives in the
+ * payments screen in the dashboard, behind a capability only the account owner
+ * holds. A leaked key that can read payments is one incident; one that could
+ * refund would drain the account. See the README.
+ *
+ * **Nothing here says a payment was made.** A checkout is a page that exists.
+ * The provider's webhook is what says money moved, and the page the customer
+ * lands on afterwards says nothing at all. Read `payment.status` back, or
+ * better, take the platform's `payment.succeeded` webhook and verify it with
+ * `verifyWebhook` from core.
+ *
+ * **Money is minor units and a currency, everywhere.** 3500 is CHF 35.00.
+ * `formatMoney` turns that into something to show a person, and dividing by a
+ * hundred yourself is wrong in both directions depending on the currency.
+ */
+
+import { ConfigError } from '@backendfree/core';
+import type { Client, Page as Paginated, RequestOptions } from '@backendfree/core';
+
+import type { CheckoutRequest, Money, Payment } from './types.js';
+
+/** Which payments to list. Every filter is optional and they combine. */
+export interface PaymentQuery extends RequestOptions {
+  status?: string;
+  /** For example `bookings.booking`. */
+  subject_type?: string;
+  /** That object's id, to answer "was this one paid for?". */
+  subject_id?: string;
+}
+
+/** Where to send the customer, when offering a page for a payment that exists. */
+export interface OfferOptions extends RequestOptions {
+  success_url: string;
+  cancel_url: string;
+  description?: string;
+}
+
+export class Payments {
+  readonly #client: Client;
+
+  constructor(client: Client) {
+    // Refused here rather than by the API, because the answer is the same
+    // either way and finding out at construction is a stack trace pointing at
+    // the line that is wrong.
+    if (client.publishable) {
+      throw new ConfigError(
+        'secret_key_required',
+        'Payments needs a secret key. A payment carries a customer name and email and a ' +
+          'checkout is a charge on a bank account, so none of it is safe in a browser.',
+      );
+    }
+    this.#client = client;
+  }
+
+  // --- what has been taken -----------------------------------------------------
+
+  /**
+   * Payments, newest first.
+   *
+   * Not cached, on purpose: a payment moves when the provider says so, and a
+   * stored answer would outlive the money it describes.
+   */
+  list(query: PaymentQuery = {}): Promise<Paginated<Payment>> {
+    const { status, subject_type, subject_id, ...rest } = query;
+    return this.#client.get<Paginated<Payment>>('/payments', {
+      ...rest,
+      query: { status, subject_type, subject_id, ...rest.query },
+    });
+  }
+
+  payment(id: string, options: RequestOptions = {}): Promise<Payment> {
+    return this.#client.get<Payment>(`/payments/${encodeURIComponent(id)}`, options);
+  }
+
+  /**
+   * Whether something on the platform has been paid for, in one call.
+   *
+   * What a booking confirmation page asks. Returns the payments against that
+   * object, because there can be more than one: a deposit and a balance, or a
+   * first attempt that failed and a second that did not.
+   */
+  async forSubject(
+    subject_type: string,
+    subject_id: string,
+    options: RequestOptions = {},
+  ): Promise<Payment[]> {
+    const { results } = await this.list({ ...options, subject_type, subject_id });
+    return results;
+  }
+
+  // --- taking some -------------------------------------------------------------
+
+  /**
+   * Open a payment page for one amount.
+   *
+   * An invoice, a deposit taken over the phone, a donation button. It settles
+   * nothing on the platform and names no booking, which is why it cannot be
+   * used to mark somebody else's appointment paid.
+   *
+   * Retrying this call is safe: core puts an idempotency key on it, and the
+   * same key is always the same charge. Pass your own order id as
+   * `idempotencyKey` to make a retry from another process count as the same
+   * request.
+   *
+   * A provider that refuses does not fail the call. The payment comes back with
+   * an empty `checkout_url` and the reason in `failure_message`, so the attempt
+   * is on record and you have an id to try again with. `offerAgain` is what
+   * tries again; calling this a second time would be a second payment for one
+   * order.
+   */
+  checkout(request: CheckoutRequest, options: RequestOptions = {}): Promise<Payment> {
+    return this.#client.post<Payment>('/checkouts', request, options);
+  }
+
+  /**
+   * Offer the page again for a payment that already exists.
+   *
+   * What a customer needs when the provider refused, or when they closed the
+   * tab. Keyed on the payment rather than on a fresh idempotency key, so asking
+   * twice is one page.
+   *
+   * What is owed comes off the payment, never off this call: the price was
+   * agreed when the payment was made. A payment that is settled or over is
+   * answered rather than re-opened, because re-opening one is how somebody pays
+   * twice.
+   */
+  offerAgain(id: string, options: OfferOptions): Promise<Payment> {
+    const { success_url, cancel_url, description, ...rest } = options;
+    return this.#client.post<Payment>(
+      `/payments/${encodeURIComponent(id)}/checkout`,
+      { success_url, cancel_url, description },
+      rest,
+    );
+  }
+}
+
+// --- reading a payment ---------------------------------------------------------
+
+/** Whether the money arrived. True of a refunded payment too: it did arrive. */
+export function hasPaid(payment: Payment): boolean {
+  return (
+    payment.status === 'paid' ||
+    payment.status === 'partially_refunded' ||
+    payment.status === 'refunded'
+  );
+}
+
+/**
+ * Whether nothing further will happen to this payment.
+ *
+ * What decides whether offering the page again is worth anything. A failed,
+ * cancelled, expired or fully refunded payment is over; a created or pending
+ * one can still be paid.
+ */
+export function isOver(payment: Payment): boolean {
+  return (
+    payment.status === 'failed' ||
+    payment.status === 'cancelled' ||
+    payment.status === 'expired' ||
+    payment.status === 'refunded'
+  );
+}
+
+/**
+ * An amount, written the way a person in a given place writes it.
+ *
+ * The one formatting helper worth shipping, for the same reason bookings ships
+ * one for time: the obvious version is wrong. Dividing by a hundred is right
+ * for CHF, wrong for JPY, which has no minor unit at all, and wrong the other
+ * way for KWD, which has three. The number of places comes from the currency
+ * rather than from a constant, so this is correct for currencies nobody thought
+ * about when writing it.
+ *
+ * `locales` defaults to the reader's own. Pass one to match a page's language.
+ */
+export function formatMoney(money: Money, locales?: string | string[]): string {
+  const format = new Intl.NumberFormat(locales, { style: 'currency', currency: money.currency });
+  const places = format.resolvedOptions().maximumFractionDigits ?? 2;
+  return format.format(money.amount / 10 ** places);
+}
+
+export type {
+  CheckoutRequest,
+  Money,
+  Payment,
+  PaymentStatus,
+  Refund,
+  RefundStatus,
+} from './types.js';

package/src/types.ts

@@ -0,0 +1,123 @@
+/**
+ * What `/v1` returns for payments, as the wire returns it.
+ *
+ * Money is an object rather than a bare number: `{amount: 3500, currency:
+ * "CHF"}` says what 3500 means. A bare number invites dividing by a hundred that
+ * somebody guessed at, which is wrong for JPY and wrong for KWD in the other
+ * direction. `formatMoney` does it properly.
+ *
+ * Three things a payment deliberately does not say, and their absence is the
+ * product rather than an omission. The provider account the money landed in is
+ * the business's alone and appears nowhere. Neither do the credentials behind it.
+ * Neither does the provider's own name or its session and charge references,
+ * because nothing a receipt renders needs them.
+ */
+
+export interface Money {
+  /** Minor units: 3500 is CHF 35.00. Never divide without the currency. */
+  amount: number;
+  currency: string;
+}
+
+/**
+ * Where one payment has got to.
+ *
+ * It only ever moves forward. A provider redelivers events for days and
+ * promises no order, so the platform applies a status as a maximum rather than
+ * as an assignment, and a late "still pending" cannot undo a payment that
+ * arrived.
+ *
+ * `created` is a payment whose page was never opened, which is a provider that
+ * refused rather than a customer who declined.
+ */
+export type PaymentStatus =
+  | 'created'
+  | 'pending'
+  | 'requires_action'
+  | 'paid'
+  | 'failed'
+  | 'cancelled'
+  | 'expired'
+  | 'partially_refunded'
+  | 'refunded';
+
+/**
+ * Where one refund has got to.
+ *
+ * Its own vocabulary rather than a corner of the payment's, because a refund
+ * succeeding and a payment being refunded are different facts: a payment can
+ * carry several refunds, and one of them failing does not move the payment.
+ */
+export type RefundStatus = 'pending' | 'succeeded' | 'failed' | 'cancelled';
+
+export interface Refund {
+  id: string;
+  amount: Money;
+  /** `pending` is money on its way, not money that has arrived. */
+  status: RefundStatus;
+  reason: string;
+  created_at: string;
+}
+
+export interface Payment {
+  id: string;
+  /** False for a payment a test key asked for, at the provider's test mode. */
+  livemode: boolean;
+  status: PaymentStatus;
+  amount: Money;
+  /** What has gone back so far. */
+  refunded: Money;
+  /**
+   * What is still there to give back.
+   *
+   * Published rather than left to be worked out, because the arithmetic is not
+   * what it looks like: a refund still settling is money already spent, and
+   * subtracting only the settled ones would show more left than there is.
+   */
+  refundable: Money;
+  /**
+   * What this settled on the platform, as a model label and that object's id.
+   * `"bookings.booking"`, or empty on a standalone payment page.
+   */
+  subject_type: string;
+  subject_id: string | null;
+  customer: { email: string; name: string };
+  /**
+   * Where to send the customer to pay.
+   *
+   * Empty only when no page was ever opened, which is a provider that refused.
+   * It is not cleared once the payment settles, so read `status` to decide
+   * whether to show it: the provider refuses a session that has been paid, but
+   * a paid receipt with a pay button on it is still a bad page.
+   */
+  checkout_url: string;
+  checkout_expires_at: string | null;
+  created_at: string;
+  /** When the provider said the money arrived. Null until it did. */
+  paid_at: string | null;
+  /** Why nothing was taken. `checkout_failed` means no page was ever opened. */
+  failure_code: string;
+  failure_message: string;
+  refunds: Refund[];
+}
+
+export interface CheckoutRequest {
+  /** Minor units. 3500 is CHF 35.00. */
+  amount: number;
+  /** Defaults to the project's own currency, which is nearly always the answer. */
+  currency?: string;
+  /** What the customer reads on the payment page. */
+  description?: string;
+  customer_email?: string;
+  customer_name?: string;
+  /**
+   * Where the provider sends the customer afterwards. Your pages, so your URLs.
+   *
+   * The success page confirms nothing. It means a form was submitted, and only
+   * the provider's webhook says money moved.
+   */
+  success_url: string;
+  cancel_url: string;
+  /** Your own references, carried to the provider and back on every webhook. */
+  metadata?: Record<string, string>;
+}