@tuppence/js 0.0.0-stage → 0.1.1

package/dist/tuppence.js

@@ -0,0 +1,484 @@
+import { externalAccountParams } from "./bank-details.js";
+import { TuppenceError } from "./errors.js";
+import { AddressField, ExpressCheckout, } from "./express.js";
+import { Http } from "./http.js";
+import { browserLanguage, stripeLocale } from "./locale.js";
+import { PaymentSheet, SetupSheet, } from "./sheet.js";
+import { StorefrontCartClient } from "./storefront.js";
+const DEFAULT_API = "https://api.tuppence.ai";
+/** A publishable key travels in this header, never in a URL (a URL is logged, cached, shared). */
+const PUBLISHABLE_KEY_HEADER = "Tuppence-Publishable-Key";
+const CLIENT_SECRET_HEADER = "Tuppence-Client-Secret";
+/** Where Stripe may know more than Tuppence does: the payer's bank is checking, or Stripe is. */
+const WAITING = new Set(["requires_action", "processing"]);
+/**
+ * Still worth reading back: the bank is checking, or a CARD is processing (seconds, rarely). A
+ * bank debit that is `processing` — a Bacs Direct Debit, `payment_method_type` other than `card`
+ * — takes working days: that IS the answer, with `processing.expected_debit_date`, and nothing
+ * waits for `succeeded`.
+ */
+const stillWaiting = (current) => WAITING.has(current.status) &&
+    !(current.status === "processing" &&
+        typeof current.payment_method_type === "string" &&
+        current.payment_method_type !== "card");
+/** A hosted top-up page's address, as `POST /v1/issuing/topup_links` answers it (54-18). */
+const TOPUP_PAGE = /^\/card-topup\/[A-Za-z0-9]{20,64}\/?$/;
+const LOCAL = new Set(["localhost", "127.0.0.1", "[::1]"]);
+/** `pay_…_secret_…` → `pay_…`: the object a client secret belongs to, or a clear refusal. */
+function objectOf(clientSecret, prefix) {
+    const secret = typeof clientSecret === "string" ? clientSecret : "";
+    const at = secret.indexOf("_secret_");
+    const id = at > 0 ? secret.slice(0, at) : "";
+    if (!id.startsWith(prefix) || !/^[A-Za-z0-9_]+$/.test(id)) {
+        const what = prefix === "pay_" ? "a payment" : "a setup session";
+        throw new TypeError(`Expected the client secret of ${what} (${prefix}…_secret_…).`);
+    }
+    return id;
+}
+const secretHeader = (clientSecret) => ({ [CLIENT_SECRET_HEADER]: clientSecret });
+/** The bank refused the card: the object says why, in words written for the payer. */
+const refused = (last) => new TuppenceError({
+    type: "card_error",
+    message: last.message ?? "The card was declined.",
+    code: last.code,
+    declineCode: last.decline_code,
+    status: 402,
+});
+/**
+ * No answer, a confirm already in flight, or a server error: the card MAY have been presented.
+ * Such an outcome is read back — the card is never presented twice.
+ */
+const unknownOutcome = (error) => error.status === 0 || error.status === 409 || error.status >= 500;
+/**
+ * Takes a card in the browser for a Tuppence payment — through Stripe's own fields, on the
+ * business's own Stripe account. Card details go from the payer's device to Stripe and never
+ * through Tuppence, this code, or yours.
+ */
+export class Tuppence {
+    constructor(options = {}, 
+    /** What `loadTuppence` learned about its key; null for a page that only holds client secrets. */
+    config = null) {
+        this.config = config;
+        this.stripes = new Map();
+        /** The Stripe instance each set of card fields came from: its token must come from it too. */
+        this.owners = new WeakMap();
+        /**
+         * The card balance's hosted top-up page (54-18). Your server makes a link
+         * (`POST /v1/issuing/topup_links`, with your secret key) and hands its `url` to the page;
+         * `tuppence.topups.redirect({ url })` sends the person there — to top up by card or by bank
+         * transfer, in your (or your Connect platform's) branding — and they come back to the link's
+         * `return_url`. Only a Tuppence top-up page's address is followed: anything else throws.
+         */
+        this.topups = {
+            /**
+             * Stripe's card fields for a hosted top-up page's card (54-18), to charge `amount` (the
+             * card option's `total`). Null where no Stripe is behind the environment: there,
+             * `pay({ testPaymentMethod })` names one of Stripe's test cards.
+             */
+            elements: async (page, options) => {
+                const stripe = await this.stripeFor(page);
+                if (!stripe)
+                    return null;
+                const { amount, ...look } = options;
+                const elements = stripe.elements({
+                    ...look,
+                    mode: "payment",
+                    amount,
+                    currency: page.currency,
+                    captureMethod: "automatic",
+                    paymentMethodTypes: ["card"],
+                });
+                this.owners.set(elements, stripe);
+                return elements;
+            },
+            /**
+             * Tops up by card on a hosted top-up page (54-18): the card presented (Stripe's fields make a
+             * confirmation token), the top-up made, the bank's check in Stripe's own frame if it asks,
+             * then the page read back until the bank and Stripe have answered. `businessFunds: true` is
+             * the person's word that the card is the business's own money.
+             */
+            pay: async (options) => {
+                const path = `/public/issuing_topup_links/${encodeURIComponent(options.token)}`;
+                const presented = await this.present({
+                    clientSecret: "",
+                    elements: options.elements,
+                    testPaymentMethod: options.testPaymentMethod,
+                }, false);
+                if ("error" in presented) {
+                    return { page: await this.http.get(path, {}), error: presented.error };
+                }
+                let page = await this.http.post(`${path}/topups`, {}, {
+                    ...presented.body,
+                    business_funds: options.businessFunds,
+                    ...(options.amount === undefined ? {} : { amount: options.amount }),
+                });
+                const secret = page.topup?.status === "requires_action" ? page.topup.client_secret : null;
+                const stripe = secret ? await this.stripeFor(page) : null;
+                // The simulated gateway has no bank page of its own: the caller shows its pretend one.
+                if (!secret || !stripe)
+                    return { page };
+                const handled = await stripe.handleNextAction({ clientSecret: secret });
+                for (let waited = 0; waited < this.timeoutMs; waited += this.intervalMs) {
+                    page = await this.http.get(path, {});
+                    if (page.topup?.status !== "requires_action")
+                        break;
+                    await this.sleep(this.intervalMs);
+                }
+                return handled.error ? { page, error: TuppenceError.fromStripe(handled.error) } : { page };
+            },
+            /**
+             * Finishes the bank's check on a hosted page's card top-up that waited for it when the page
+             * opened (a reload half-way), in Stripe's own frame, then reads the page back.
+             */
+            resume: async (options) => {
+                const path = `/public/issuing_topup_links/${encodeURIComponent(options.token)}`;
+                let page = await this.http.get(path, {});
+                const secret = page.topup?.status === "requires_action" ? page.topup.client_secret : null;
+                const stripe = secret ? await this.stripeFor(page) : null;
+                if (!secret || !stripe)
+                    return { page };
+                const handled = await stripe.handleNextAction({ clientSecret: secret });
+                for (let waited = 0; waited < this.timeoutMs; waited += this.intervalMs) {
+                    page = await this.http.get(path, {});
+                    if (page.topup?.status !== "requires_action")
+                        break;
+                    await this.sleep(this.intervalMs);
+                }
+                return handled.error ? { page, error: TuppenceError.fromStripe(handled.error) } : { page };
+            },
+            redirect: (options) => {
+                let target = null;
+                try {
+                    target = new URL(typeof options?.url === "string" ? options.url : "");
+                }
+                catch {
+                    target = null;
+                }
+                const secure = target?.protocol === "https:" ||
+                    (target?.protocol === "http:" && LOCAL.has(target.hostname));
+                if (!target || !secure || !TOPUP_PAGE.test(target.pathname) || target.search || target.hash) {
+                    throw new TypeError("topups.redirect takes a top-up link's `url`, as `POST /v1/issuing/topup_links` answered it (https://…/card-topup/…).");
+                }
+                this.navigate(target.toString());
+            },
+        };
+        const fetchImpl = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+        this.fetchImpl = fetchImpl;
+        this.sleep = options.poll?.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+        this.navigate = options.navigate ?? ((url) => globalThis.location.assign(url));
+        this.http = new Http((options.apiBase ?? DEFAULT_API).replace(/\/+$/, ""), fetchImpl, this.sleep);
+        this.loadStripe =
+            options.loadStripe ??
+                (async (key, { stripeAccount, locale }) => {
+                    // Stripe's loader arrives only when card fields are first asked for: a page on the
+                    // simulated gateway, or one that never shows fields, never downloads it.
+                    const { loadStripe } = await import("@stripe/stripe-js/pure");
+                    return loadStripe(key, { stripeAccount, locale });
+                });
+        this.locale = stripeLocale(options.locale ?? browserLanguage());
+        this.intervalMs = options.poll?.intervalMs ?? 1000;
+        this.timeoutMs = options.poll?.timeoutMs ?? 30000;
+    }
+    /** `loadTuppence`: the key checked here, then what the API says about it. */
+    static async load(publishableKey, options = {}) {
+        const key = typeof publishableKey === "string" ? publishableKey : "";
+        // A secret key is refused by its code (`invalid_api_key`, as the API refuses one): every
+        // payer-side SDK uses the same code, each in its own words (56-03, A9).
+        if (/^(sk|rk)_/.test(key)) {
+            throw new TuppenceError({
+                type: "authentication_error",
+                code: "invalid_api_key",
+                message: "That is a secret key: it must never be in a page. Roll it, and pass your publishable key (pk_…) here.",
+            });
+        }
+        if (!/^pk_(test|live)_[A-Za-z0-9]+$/.test(key)) {
+            throw new TypeError("loadTuppence needs your publishable key (pk_test_… or pk_live_…).");
+        }
+        const config = await new Tuppence(options).http.get("/public/sdk/config", {
+            [PUBLISHABLE_KEY_HEADER]: key,
+        });
+        const tuppence = new Tuppence(options, config);
+        // Stripe.js starts loading now, so the card fields appear the moment they are asked for.
+        void tuppence.stripeFor(config).catch(() => undefined);
+        return tuppence;
+    }
+    /** The payment a client secret belongs to, as its payer sees it. */
+    retrievePayment(clientSecret) {
+        const id = objectOf(clientSecret, "pay_");
+        return this.http.get(`/public/payments/${id}`, secretHeader(clientSecret));
+    }
+    /** The setup session a client secret belongs to, as its customer sees it. */
+    retrieveSetupSession(clientSecret) {
+        const id = objectOf(clientSecret, "sets_");
+        return this.http.get(`/public/setup_sessions/${id}`, secretHeader(clientSecret));
+    }
+    /**
+     * Stripe's card fields for a payment — `elements.create("payment").mount(el)` shows them. What
+     * they collect matches the charge Tuppence will make: its amount, currency, how it is
+     * captured and whether it saves the card. Null where no Stripe is behind the environment (the
+     * simulated gateway): there, `testPaymentMethod` names one of Stripe's test cards instead.
+     *
+     * A page that adds to the amount (a tip) says so with `elements.update({ amount })`.
+     */
+    async elements(payment, options = {}) {
+        const stripe = await this.stripeFor(payment);
+        if (!stripe)
+            return null;
+        const { amount, ...look } = options;
+        // Stripe.js in this mode offers what the business's settings offer, whatever the
+        // PaymentIntent says: what can't be used here (Direct Debit on a booking) is left out.
+        const excluded = payment.excluded_payment_method_types ?? [];
+        const elements = stripe.elements({
+            ...look,
+            mode: "payment",
+            amount: amount ?? payment.amount,
+            currency: payment.currency,
+            ...(payment.capture_method ? { captureMethod: payment.capture_method } : {}),
+            ...(payment.setup_future_usage ? { setupFutureUsage: payment.setup_future_usage } : {}),
+            ...(excluded.length > 0 ? { excludedPaymentMethodTypes: [...excluded] } : {}),
+        });
+        this.owners.set(elements, stripe);
+        return elements;
+    }
+    /** Stripe's card fields for saving a card with nothing charged — cards only, as the session saves. */
+    async setupElements(session, options = {}) {
+        const stripe = await this.stripeFor(session);
+        if (!stripe)
+            return null;
+        const elements = stripe.elements({ ...options, mode: "setup", paymentMethodTypes: ["card"] });
+        this.owners.set(elements, stripe);
+        return elements;
+    }
+    /**
+     * Stripe's Payment Element for a payment, dressed in the business's branding:
+     * `tuppence.paymentSheet({ clientSecret }).mount("#card")`, then `sheet.confirm()`. Its events
+     * say when the fields show (`ready`), whether they are complete (`change`), and why they
+     * cannot show (`error` — on the simulated gateway there are none).
+     */
+    paymentSheet(options) {
+        return new PaymentSheet(this, options);
+    }
+    /**
+     * A store's basket (85-10): `get()` it, or `quote()` it for an address and a delivery choice
+     * without changing it. On the store's own hosts the basket is its cookie; headless (M94) pass
+     * `base: "https://api.tuppence.ai"`, the publishable key and the basket's token.
+     */
+    cart(options = {}) {
+        return new StorefrontCartClient(this.fetchImpl, options);
+    }
+    /**
+     * Apple Pay, Google Pay and Link for a store's basket (85-10): Stripe's Express Checkout
+     * Element in deferred mode, in the business's branding. The sheet's address and delivery
+     * choices are priced by the basket's quote, and the total in the sheet follows;
+     * `onConfirm` gets Stripe's confirmation token for your server to pay with.
+     * `tuppence.expressCheckout(payable, { onConfirm }).mount("#express")`.
+     */
+    expressCheckout(payable, options) {
+        const cart = options.cart instanceof StorefrontCartClient ? options.cart : this.cart(options.cart);
+        return new ExpressCheckout(this, payable, options, cart);
+    }
+    /**
+     * Stripe's Address Element, with Stripe's autocomplete (85-10): in a payment's own Elements
+     * group (from `elements()`) so a shipping address goes with the payment, or, from a payment
+     * alone, in Elements of its own in the business's branding.
+     */
+    address(from, options) {
+        return new AddressField(this, from, options);
+    }
+    /**
+     * Stripe's confirmation token for fields this SDK made: the fields checked, then the token.
+     * @internal For the SDK's own wallets; pages pay through `confirmPayment`.
+     */
+    async confirmationToken(elements, params) {
+        const stripe = this.owners.get(elements);
+        if (!stripe) {
+            throw new TypeError("Pass the card fields this SDK made (`tuppence.elements()`): they carry the account the card is for.");
+        }
+        const submitted = await elements.submit();
+        if (submitted.error)
+            return { error: TuppenceError.fromStripe(submitted.error) };
+        const token = await stripe.createConfirmationToken({ elements, ...(params ? { params } : {}) });
+        if (token.error)
+            return { error: TuppenceError.fromStripe(token.error) };
+        return { id: token.confirmationToken.id };
+    }
+    /** The same for saving a card with nothing charged. */
+    setupSheet(options) {
+        return new SetupSheet(this, options);
+    }
+    /**
+     * Pays a payment: the card is presented (Stripe's fields make a confirmation token), the
+     * payer's bank checks it's them if it asks (in Stripe's own frame), and the payment is read
+     * back until it settles. A refused card is `{ error }` with the payment as it now stands —
+     * never an exception. If an answer is lost on the way, the outcome is read back: the card is
+     * never presented twice.
+     *
+     * A Bacs Direct Debit answers at once with `status: "processing"`, `payment_method_type:
+     * "bacs_debit"` and `processing.expected_debit_date` (`YYYY-MM-DD`): the mandate is set up and
+     * the money is collected in a few working days. Show the payer that; `succeeded` (or
+     * `failed`) comes later, by webhook — `payment.succeeded`, `payment.failed`.
+     */
+    async confirmPayment(options) {
+        const id = objectOf(options.clientSecret, "pay_");
+        const presented = await this.present(options, true);
+        if ("error" in presented)
+            return { error: presented.error, payment: null };
+        const body = options.tipAmount === undefined
+            ? presented.body
+            : { ...presented.body, tip_amount: options.tipAmount };
+        const outcome = await this.run(`/public/payments/${id}`, options.clientSecret, body);
+        return outcome.error
+            ? { error: outcome.error, payment: outcome.value }
+            : { payment: outcome.value };
+    }
+    /** Saves a card with nothing charged — the same steps as a payment. */
+    async confirmSetup(options) {
+        const id = objectOf(options.clientSecret, "sets_");
+        const presented = await this.present(options, false);
+        if ("error" in presented)
+            return { error: presented.error, setupSession: null };
+        const outcome = await this.run(`/public/setup_sessions/${id}`, options.clientSecret, presented.body);
+        return outcome.error
+            ? { error: outcome.error, setupSession: outcome.value }
+            : { setupSession: outcome.value };
+    }
+    /**
+     * Finishes what a payment waits on when the page opens — the payer's bank checking it's them
+     * (a charge to a saved card that asked for it, a check left half-way) — in Stripe's own frame,
+     * then reads it back. On the simulated gateway it answers the payment as it stands.
+     */
+    async resumePayment(options) {
+        const id = objectOf(options.clientSecret, "pay_");
+        const outcome = await this.resume(`/public/payments/${id}`, options.clientSecret);
+        return outcome.error
+            ? { error: outcome.error, payment: outcome.value }
+            : { payment: outcome.value };
+    }
+    /** The same for a card being saved. */
+    async resumeSetup(options) {
+        const id = objectOf(options.clientSecret, "sets_");
+        const outcome = await this.resume(`/public/setup_sessions/${id}`, options.clientSecret);
+        return outcome.error
+            ? { error: outcome.error, setupSession: outcome.value }
+            : { setupSession: outcome.value };
+    }
+    async resume(path, clientSecret) {
+        const headers = secretHeader(clientSecret);
+        try {
+            return await this.onward(path, headers, await this.http.get(path, headers));
+        }
+        catch (caught) {
+            const error = caught instanceof TuppenceError
+                ? caught
+                : new TuppenceError({ type: "api_error", message: String(caught) });
+            return { error, value: null };
+        }
+    }
+    /**
+     * A bank account, checked and shaped for `POST /v1/accounts/{id}/external_accounts` — the only
+     * way to add one (52-09, 52-17): your server sends `externalAccount` on to Tuppence as
+     * `external_account`, and Tuppence keeps the details (encrypted, for verification) and has Stripe
+     * make the bank account. Tuppence refuses a Stripe bank token. Nothing is sent from
+     * here; a wrong field comes back as an error naming it.
+     */
+    bankAccountDetails(details) {
+        return externalAccountParams(details);
+    }
+    /** Stripe.js for an object's publishable key and account — loaded once for each pair. */
+    stripeFor(view) {
+        const key = view.stripe_publishable_key;
+        const account = view.stripe_account;
+        if (!key || !account)
+            return Promise.resolve(null);
+        const memo = `${key} ${account}`;
+        let loading = this.stripes.get(memo);
+        if (!loading) {
+            loading = this.loadStripe(key, { stripeAccount: account, locale: this.locale });
+            this.stripes.set(memo, loading);
+            // A script that failed to load may be asked for again.
+            loading.catch(() => this.stripes.delete(memo));
+        }
+        return loading;
+    }
+    /** A card, as the confirm route takes it: a confirmation token, a saved card, or a test card. */
+    async present(options, canUseSavedCard) {
+        if (options.elements) {
+            const token = await this.confirmationToken(options.elements, options.params);
+            if ("error" in token)
+                return { error: token.error };
+            return { body: { confirmation_token: token.id } };
+        }
+        if (canUseSavedCard && options.savedCard) {
+            return { body: { saved_card: true } };
+        }
+        if (options.testPaymentMethod)
+            return { body: { payment_method: options.testPaymentMethod } };
+        throw new TypeError("Present a card: `elements` — or, on the simulated gateway in test mode, `testPaymentMethod`.");
+    }
+    /** Confirm, then the bank's check if it asks, then read back until it settles. */
+    async run(path, clientSecret, body) {
+        const headers = secretHeader(clientSecret);
+        let current;
+        try {
+            current = await this.http.post(`${path}/confirm`, headers, body);
+        }
+        catch (caught) {
+            const error = caught instanceof TuppenceError
+                ? caught
+                : new TuppenceError({ type: "api_error", message: String(caught) });
+            if (!unknownOutcome(error)) {
+                return { error, value: await this.http.get(path, headers).catch(() => null) };
+            }
+            current = await this.settle(path, headers).catch(() => null);
+            if (!current || current.status === "requires_payment_method") {
+                return { error, value: current };
+            }
+        }
+        return this.onward(path, headers, current);
+    }
+    /** What follows a confirm: the bank's check if it asks, then a read-back until it settles. */
+    async onward(path, headers, confirmed) {
+        let current = confirmed;
+        if (current.status === "requires_action" && current.next_action?.type === "use_stripe_sdk") {
+            const stripe = await this.stripeFor(current);
+            // The simulated gateway has no bank page of its own: the caller shows its pretend one.
+            if (!stripe)
+                return { value: current };
+            const handled = await stripe.handleNextAction({
+                clientSecret: current.next_action.stripe_client_secret,
+            });
+            current = (await this.settle(path, headers).catch(() => null)) ?? current;
+            if (handled.error && current.status === "requires_payment_method") {
+                return { error: TuppenceError.fromStripe(handled.error), value: current };
+            }
+        }
+        else if (stillWaiting(current)) {
+            current = (await this.settle(path, headers).catch(() => null)) ?? current;
+        }
+        if (current.status === "requires_payment_method" && current.last_error) {
+            return { error: refused(current.last_error), value: current };
+        }
+        return { value: current };
+    }
+    /** Reads an object back until neither the bank nor Stripe is still deciding, or time is up. */
+    async settle(path, headers) {
+        let current = await this.http.get(path, headers);
+        for (let waited = 0; stillWaiting(current) && waited < this.timeoutMs;) {
+            await this.sleep(this.intervalMs);
+            waited += this.intervalMs;
+            current = await this.http.get(path, headers);
+        }
+        return current;
+    }
+}
+/** For a page that holds client secrets and no key — Tuppence's own pay pages. */
+export function createTuppence(options = {}) {
+    return new Tuppence(options);
+}
+/**
+ * Starts the SDK with your PUBLISHABLE key (`pk_test_…` or `pk_live_…`). A secret key is
+ * refused here, before it is sent anywhere: it must never be in a page.
+ */
+export function loadTuppence(publishableKey, options = {}) {
+    return Tuppence.load(publishableKey, options);
+}

package/dist/types.d.ts

@@ -0,0 +1,147 @@
+/**
+ * What the browser's routes answer — the fields this SDK reads. Each object carries more (the
+ * business's branding, a receipt, a tip…), kept as they come.
+ */
+/** Where a payment is: `requires_action` waits on the payer's bank, `processing` on Stripe. */
+export type PaymentStatus = "requires_payment_method" | "requires_action" | "processing" | "requires_capture" | "succeeded" | "canceled";
+/** Which gateway the environment runs: `fake` has no card fields — Stripe's test cards by name. */
+export type Gateway = "fake" | "sandbox" | "live";
+export interface NextAction {
+    type: string;
+    /** Stripe's own secret for the bank's check, which Stripe.js finishes. */
+    stripe_client_secret: string;
+}
+export interface LastError {
+    code: string | null;
+    decline_code: string | null;
+    message: string | null;
+}
+/** The business's look on its payers' pages (plan 09-08): its accent colour, contrast-checked. */
+export interface Branding {
+    display_name?: string;
+    accent_color?: string | null;
+}
+/** What Stripe.js needs to take a card for this object — null where no Stripe is behind it. */
+interface StripeFields {
+    branding?: Branding;
+    stripe: Gateway;
+    stripe_publishable_key: string | null;
+    /** The connected account the card fields act for: the charge is a direct charge on it. */
+    stripe_account: string | null;
+}
+/** A payment, as its payer sees it (`GET /public/payments/:id`). */
+export interface PublicPayment extends StripeFields {
+    object: "payment";
+    id: string;
+    livemode: boolean;
+    status: PaymentStatus;
+    /** In the currency's smallest unit: pence, cents. */
+    amount: number;
+    currency: string;
+    next_action: NextAction | null;
+    last_error: LastError | null;
+    capture_method: "automatic" | "manual";
+    /** `off_session` when paying also saves the card. */
+    setup_future_usage: "off_session" | null;
+    /**
+     * What the payer can pay with here: `card` (Apple Pay and Google Pay are cards), and
+     * `bacs_debit` where the business takes Direct Debit and this payment allows it.
+     */
+    payment_method_types?: string[];
+    /**
+     * What Stripe's Payment Element must leave out for this payment (`bacs_debit` on a booking's
+     * money, a till's, a credit top-up): `elements()` passes it to Stripe.js.
+     */
+    excluded_payment_method_types?: string[];
+    /** How it was paid, once a method was presented: `card`, `bacs_debit`, … */
+    payment_method_type?: string | null;
+    /**
+     * While `processing`: when the money is expected to leave the payer's account (`YYYY-MM-DD`,
+     * Stripe's estimate or Tuppence's; not guaranteed). A Bacs Direct Debit is `processing` for a
+     * few working days — the payer has nothing more to do. `null` otherwise.
+     */
+    processing?: PaymentProcessing | null;
+    [field: string]: unknown;
+}
+/** A payment on its way: a bank debit takes days. */
+export interface PaymentProcessing {
+    /** `YYYY-MM-DD`, or null for a method with no estimate. */
+    expected_debit_date: string | null;
+}
+/** A card being saved with nothing charged, as its customer sees it (`GET /public/setup_sessions/:id`). */
+export interface PublicSetupSession extends StripeFields {
+    object: "setup_session";
+    id: string;
+    livemode: boolean;
+    status: "requires_payment_method" | "requires_action" | "processing" | "succeeded" | "canceled";
+    next_action: NextAction | null;
+    last_error: LastError | null;
+    [field: string]: unknown;
+}
+/** What `loadTuppence` learns about its key (`GET /public/sdk/config`). */
+export interface SdkConfig extends StripeFields {
+    object: "sdk_config";
+    livemode: boolean;
+}
+/**
+ * A bank account as `POST /v1/accounts/{id}/external_accounts` takes it in `external_account`
+ * (52-09): what `bankAccountDetails` gives your page to send on, through your server, to Tuppence.
+ */
+export interface ExternalAccountParams {
+    object: "bank_account";
+    country: string;
+    currency: string;
+    account_holder_name: string;
+    account_holder_type: "individual" | "company";
+    /** The sort code (GB) or routing number (US). None in the eurozone, where the IBAN says it. */
+    routing_number?: string;
+    /** The account number, or in the eurozone the IBAN (spaces out, upper case). */
+    account_number: string;
+}
+/** A bank account's details, for `bankAccountDetails` (41-05, 52-09, 52-17). */
+export interface BankAccountDetails {
+    /** `GB`, `US`, or a eurozone country (`DE`, `FR`, `IE`…). */
+    country: string;
+    /** `gbp`, `usd` or `eur`. */
+    currency: string;
+    accountHolderName: string;
+    accountHolderType: "individual" | "company";
+    /** The sort code (GB, six digits) or the routing number (US). Leave it out in the eurozone. */
+    routingNumber?: string;
+    /** The account number, or in the eurozone the IBAN (spaces are fine). */
+    accountNumber: string;
+}
+/** A card top-up made on a hosted top-up page (54-18), as the person following it sees it. */
+export interface PublicLinkTopup {
+    id: string;
+    /** `requires_action` (the bank's check), `processing`, `available`, `failed`… */
+    status: string;
+    amount: number;
+    total: number;
+    /** While the bank checks it's the cardholder: Stripe.js finishes it. */
+    client_secret: string | null;
+    failure_message: string | null;
+    [field: string]: unknown;
+}
+/** A hosted top-up page (54-18): `GET /public/issuing_topup_links/:token`. */
+export interface PublicTopupLinkPage {
+    object: "issuing_topup_link_page";
+    livemode: boolean;
+    /** `open`, `used` or `expired`. */
+    status: string;
+    currency: string;
+    /** Fixed by the link; null: the person chooses. */
+    amount: number | null;
+    /** Where the person goes afterwards; null: nowhere — they close the page. */
+    return_url: string | null;
+    card: {
+        available: boolean;
+        total: number | null;
+        [field: string]: unknown;
+    } | null;
+    topup: PublicLinkTopup | null;
+    stripe_publishable_key: string | null;
+    stripe_account: string | null;
+    [field: string]: unknown;
+}
+export {};

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * What the browser's routes answer — the fields this SDK reads. Each object carries more (the
+ * business's branding, a receipt, a tip…), kept as they come.
+ */
+export {};