@backendfree/payments 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,129 @@
+/**
+ * @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;
+}
+/** 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 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 3.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,uBAAuB,CAAC;AAEvF,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;CACrB;AAED,kFAAkF;AAClF,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.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;CACrB;AAED,kFAAkF;AAClF,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, ...rest } = query;
+        return this.#client.get('/payments', {
+            ...rest,
+            query: { status, subject_type, subject_id, ...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 3.map

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

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAqBhD,MAAM,OAAO,QAAQ;IACV,OAAO,CAAS;IAEzB,YAAY,MAAc;QACxB,sEAAsE;QACtE,0EAA0E;QAC1E,0BAA0B;QAC1B,IAAI,MAAM,CAAC,WAAW,EAAE,CAAC;YACvB,MAAM,IAAI,WAAW,CACnB,qBAAqB,EACrB,iFAAiF;gBAC/E,6EAA6E,CAChF,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IACxB,CAAC;IAED,gFAAgF;IAEhF;;;;;OAKG;IACH,IAAI,CAAC,QAAsB,EAAE;QAC3B,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,UAAU,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,CAAC;QAC5D,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAqB,WAAW,EAAE;YACvD,GAAG,IAAI;YACP,KAAK,EAAE,EAAE,MAAM,EAAE,YAAY,EAAE,UAAU,EAAE,GAAG,IAAI,CAAC,KAAK,EAAE;SAC3D,CAAC,CAAC;IACL,CAAC;IAED,OAAO,CAAC,EAAU,EAAE,UAA0B,EAAE;QAC9C,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAU,aAAa,kBAAkB,CAAC,EAAE,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;IACnF,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,UAAU,CACd,YAAoB,EACpB,UAAkB,EAClB,UAA0B,EAAE;QAE5B,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,CAAC,CAAC;QAC9E,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,gFAAgF;IAEhF;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,OAAwB,EAAE,UAA0B,EAAE;QAC7D,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAU,YAAY,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IACpE,CAAC;IAED;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,EAAU,EAAE,OAAqB;QAC1C,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC;QAClE,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CACtB,aAAa,kBAAkB,CAAC,EAAE,CAAC,WAAW,EAC9C,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,EACxC,IAAI,CACL,CAAC;IACJ,CAAC;CACF;AAED,kFAAkF;AAElF,gFAAgF;AAChF,MAAM,UAAU,OAAO,CAAC,OAAgB;IACtC,OAAO,CACL,OAAO,CAAC,MAAM,KAAK,MAAM;QACzB,OAAO,CAAC,MAAM,KAAK,oBAAoB;QACvC,OAAO,CAAC,MAAM,KAAK,UAAU,CAC9B,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,MAAM,CAAC,OAAgB;IACrC,OAAO,CACL,OAAO,CAAC,MAAM,KAAK,QAAQ;QAC3B,OAAO,CAAC,MAAM,KAAK,WAAW;QAC9B,OAAO,CAAC,MAAM,KAAK,SAAS;QAC5B,OAAO,CAAC,MAAM,KAAK,UAAU,CAC9B,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,WAAW,CAAC,KAAY,EAAE,OAA2B;IACnE,MAAM,MAAM,GAAG,IAAI,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC/F,MAAM,MAAM,GAAG,MAAM,CAAC,eAAe,EAAE,CAAC,qBAAqB,IAAI,CAAC,CAAC;IACnE,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,GAAG,EAAE,IAAI,MAAM,CAAC,CAAC;AACpD,CAAC"}

package/dist/types 3.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 client'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.d 3.ts

@@ -0,0 +1,110 @@
+/**
+ * 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 client'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;
+    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>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts

@@ -0,0 +1,112 @@
+/**
+ * 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>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts 3.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,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;;;;;;;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;;;;;OAKG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC"}

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;;;;;;;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;;;;;OAKG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,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 3.map

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

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,47 @@
 {
   "name": "@backendfree/payments",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "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",
+    "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",
+    "prepublishOnly": "npm test"
+  }
+}