@backendfree/payments 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,132 @@
-# Temporary Holding Version
+# @backendfree/payments
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A project's money: what has been taken, and taking some. Built on
+[`@backendfree/core`](../core).
+
+```sh
+npm install @backendfree/core @backendfree/payments
+```
+
+```ts
+import { Client } from '@backendfree/core';
+import { Payments } from '@backendfree/payments';
+
+const payments = new Payments(
+  new Client({ origin: 'https://backendfree.com', key: process.env.BACKENDFREE_SECRET_KEY! }),
+);
+
+const payment = await payments.checkout({
+  amount: 3500,                              // minor units: CHF 35.00
+  description: 'Deposit',
+  success_url: 'https://shop.example/thanks?payment={id}',
+  cancel_url: 'https://shop.example/cart',
+  metadata: { order: 'A-1042' },             // your own references, returned on every read and event
+});
+
+redirect(payment.checkout_url);
+```
+
+`{id}` in either address becomes the payment's id, which does not exist until
+this call returns, so the page after paying can read the payment it was for.
+`metadata` comes back on the payment and in every `payment.*` event about it,
+so the webhook can find the order it paid for: at most 20 keys, each value text.
+
+## Server only
+
+Every method here needs a secret key, and constructing `Payments` with a
+publishable one throws. A payment carries the paying customer's name and email,
+and a checkout is a charge on a bank account, so none of it belongs in a bundle
+whoever loads the site can read.
+
+That is also why the mistake is refused at construction rather than by a 403 in
+production: the stack trace points at the line that is wrong.
+
+## Why there is no refund method
+
+Refunding is the one act that moves money out of the business's own account, so
+it lives in the payments screen in the dashboard, behind a capability only the
+account owner holds.
+
+A secret key lives in server code, deploy settings and CI, which is further than
+the account owner's own screen. A leaked key that can read payment records is one
+incident; one that could refund would drain the account. Reading payment records
+with a key is deliberate and bounded, so a developer can render a receipt;
+issuing money back is not the same thing and is not in the API.
+
+## 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.
+
+Take the platform's `payment.succeeded` webhook and verify it:
+
+```ts
+import { verifyWebhook } from '@backendfree/core';
+
+const event = await verifyWebhook({ body: await request.text(), headers, secret });
+if (event.name === 'payment.succeeded') {
+  markPaid(event.data.metadata.order, event.data.amount, event.data.currency);
+}
+```
+
+## When the provider refuses
+
+`checkout()` does not throw for a provider that would not open a page. The
+payment comes back with an empty `checkout_url` and the reason on it, so the
+attempt is on record and you have an id to try again with.
+
+```ts
+if (!payment.checkout_url) {
+  payment = await payments.offerAgain(payment.id, { success_url, cancel_url });
+}
+```
+
+`offerAgain` is keyed on the payment, so asking twice is one page, and what is
+owed comes off the payment rather than off the call. Calling `checkout()` a
+second time would record a second payment for one order, and a customer handed
+both pages could pay twice.
+
+## Reading what has been taken
+
+```ts
+await payments.list({ status: 'paid' });
+await payments.payment(id);
+await payments.forSubject('bookings.booking', bookingId);   // was it paid for?
+```
+
+A payment says what it settled, how much, what has gone back and what is left to
+give back. It never says which provider account the money landed in: that is the
+business's own and appears nowhere in this API.
+
+`refundable` is published rather than left to you to work out, because the
+arithmetic is not what it looks like. A refund that is still settling is money
+already spent, so subtracting only the settled ones shows more left than there
+is.
+
+## Money
+
+Always minor units and a currency. `3500` with `CHF` is 35 francs.
+
+```ts
+import { formatMoney } from '@backendfree/payments';
+
+formatMoney({ amount: 6500, currency: 'CHF' }, 'de-CH');   // CHF 65.00
+formatMoney({ amount: 6500, currency: 'JPY' }, 'en-US');   // ¥6,500
+```
+
+Dividing by a hundred yourself is wrong in both directions: JPY has no minor
+unit and KWD has three places. The number of places comes from the currency
+rather than from a constant.
+
+## Reading a status
+
+```ts
+import { hasPaid, isOver } from '@backendfree/payments';
+
+hasPaid(payment);   // the money arrived, refunded payments included
+isOver(payment);    // nothing further will happen, so do not offer a page
+```
+
+A status only ever moves forward. A provider redelivers events for days and
+promises no order, so the platform applies each one as a maximum and a late
+"still pending" cannot undo a payment that arrived.

package/dist/index.d.ts

@@ -0,0 +1,132 @@
+/**
+ * @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 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;
+    /** Which page: 25 to a page unless asked for up to 100. */
+    page?: number;
+    page_size?: number;
+}
+/** Where to send the customer, when offering a page for a payment that exists. `{id}` becomes its id. */
+export interface OfferOptions extends RequestOptions {
+    success_url: string;
+    cancel_url: string;
+    description?: string;
+}
+export declare class Payments {
+    #private;
+    constructor(client: Client);
+    /**
+     * 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>>;
+    payment(id: string, options?: RequestOptions): Promise<Payment>;
+    /**
+     * 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.
+     */
+    forSubject(subject_type: string, subject_id: string, options?: RequestOptions): Promise<Payment[]>;
+    /**
+     * 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>;
+    /**
+     * 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>;
+}
+/** Whether the money arrived. True of a refunded payment too: it did arrive. */
+export declare function hasPaid(payment: Payment): boolean;
+/**
+ * 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 declare function isOver(payment: Payment): boolean;
+/**
+ * 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 declare function formatMoney(money: Money, locales?: string | string[]): string;
+export type { CheckoutRequest, Money, Payment, PaymentStatus, Refund, RefundStatus, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,IAAI,IAAI,SAAS,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnF,OAAO,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAElE,yEAAyE;AACzE,MAAM,WAAW,YAAa,SAAQ,cAAc;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,yGAAyG;AACzG,MAAM,WAAW,YAAa,SAAQ,cAAc;IAClD,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,QAAQ;;gBAGP,MAAM,EAAE,MAAM;IAgB1B;;;;;OAKG;IACH,IAAI,CAAC,KAAK,GAAE,YAAiB,GAAG,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IAQ3D,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,OAAO,CAAC;IAInE;;;;;;OAMG;IACG,UAAU,CACd,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,OAAO,EAAE,CAAC;IAOrB;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,OAAO,EAAE,eAAe,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,OAAO,CAAC;IAIlF;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC;CAQhE;AAID,gFAAgF;AAChF,wBAAgB,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAMjD;AAED;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAOhD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,MAAM,CAI7E;AAED,YAAY,EACV,eAAe,EACf,KAAK,EACL,OAAO,EACP,aAAa,EACb,MAAM,EACN,YAAY,GACb,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,154 @@
+/**
+ * @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';
+export class Payments {
+    #client;
+    constructor(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 = {}) {
+        const { status, subject_type, subject_id, page, page_size, ...rest } = query;
+        return this.#client.get('/payments', {
+            ...rest,
+            query: { status, subject_type, subject_id, page, page_size, ...rest.query },
+        });
+    }
+    payment(id, options = {}) {
+        return this.#client.get(`/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, subject_id, options = {}) {
+        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, options = {}) {
+        return this.#client.post('/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, options) {
+        const { success_url, cancel_url, description, ...rest } = options;
+        return this.#client.post(`/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) {
+    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) {
+    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, locales) {
+    const format = new Intl.NumberFormat(locales, { style: 'currency', currency: money.currency });
+    const places = format.resolvedOptions().maximumFractionDigits ?? 2;
+    return format.format(money.amount / 10 ** places);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,120 @@
+/**
+ * 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;
+    };
+    /** Your own references, as the checkout was given them. `{}` when there were none. */
+    metadata: Record<string, 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.
+     * `{id}` in either becomes the payment's id, so the page after paying knows
+     * which payment it was: `https://shop.example/thanks?payment={id}`.
+     *
+     * 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: at most 20 keys, each value text. Returned on the
+     * payment and in every `payment.*` event about it, so a webhook handler can
+     * find its order without a second call.
+     */
+    metadata?: Record<string, string>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,KAAK;IACpB,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,aAAa,GACrB,SAAS,GACT,SAAS,GACT,iBAAiB,GACjB,MAAM,GACN,QAAQ,GACR,WAAW,GACX,SAAS,GACT,oBAAoB,GACpB,UAAU,CAAC;AAEf;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAC;AAE5E,MAAM,WAAW,MAAM;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,KAAK,CAAC;IACd,iEAAiE;IACjE,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,6EAA6E;IAC7E,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,aAAa,CAAC;IACtB,MAAM,EAAE,KAAK,CAAC;IACd,iCAAiC;IACjC,QAAQ,EAAE,KAAK,CAAC;IAChB;;;;;;OAMG;IACH,UAAU,EAAE,KAAK,CAAC;IAClB;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1C,sFAAsF;IACtF,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;;;;;OAOG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,8EAA8E;IAC9E,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;OAOG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC"}

package/dist/types.js

@@ -0,0 +1,16 @@
+/**
+ * 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 {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG"}

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@backendfree/payments",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Typed access to a BackendFree project's money: what has been taken, and opening a payment page.",
+  "keywords": [
+    "backendfree",
+    "payments",
+    "checkout",
+    "stripe",
+    "sdk",
+    "typescript"
+  ],
+  "license": "MIT",
+  "author": "BackendFree",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "!dist/.tsbuildinfo",
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@backendfree/core": "^0.1.0"
+  },
+  "scripts": {
+    "clean": "tsc --build --clean && rm -rf dist",
+    "build": "tsc --build",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "prepare": "npm run build",
+    "prepack": "npm run clean && npm run build",
+    "prepublishOnly": "npm test"
+  }
+}

package/src/index.ts

@@ -0,0 +1,213 @@
+/**
+ * @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;
+  /** Which page: 25 to a page unless asked for up to 100. */
+  page?: number;
+  page_size?: number;
+}
+
+/** Where to send the customer, when offering a page for a payment that exists. `{id}` becomes its id. */
+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, page, page_size, ...rest } = query;
+    return this.#client.get<Paginated<Payment>>('/payments', {
+      ...rest,
+      query: { status, subject_type, subject_id, page, page_size, ...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,131 @@
+/**
+ * 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 };
+  /** Your own references, as the checkout was given them. `{}` when there were none. */
+  metadata: Record<string, 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.
+   * `{id}` in either becomes the payment's id, so the page after paying knows
+   * which payment it was: `https://shop.example/thanks?payment={id}`.
+   *
+   * 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: at most 20 keys, each value text. Returned on the
+   * payment and in every `payment.*` event about it, so a webhook handler can
+   * find its order without a second call.
+   */
+  metadata?: Record<string, string>;
+}