@tuppence/js 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,183 @@
-# Temporary Holding Version
+# @tuppence/js
 
-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.
+Take a card in the browser for a [Tuppence](https://tuppence.ai) payment — through Stripe's own
+card fields, never ours. Card details go from the payer's device to Stripe, and never through
+Tuppence, this package, or your code.
+
+```bash
+npm install @tuppence/js
+```
+
+## Pay a payment
+
+Your server creates the payment (`POST /v1/payments`) and hands the browser its `client_secret`.
+
+```js
+import { loadTuppence } from "@tuppence/js";
+
+// Your PUBLISHABLE key: a secret key is refused before it is sent anywhere.
+const tuppence = await loadTuppence("pk_test_…");
+
+// Stripe's Payment Element, in the business's colours, set up to match the charge.
+const sheet = tuppence.paymentSheet({ clientSecret }).mount("#card");
+sheet.on("ready", () => (payButton.disabled = false));
+sheet.on("error", (error) => show(error.message));
+
+form.addEventListener("submit", async (event) => {
+  event.preventDefault();
+  const result = await sheet.confirm();
+  if (result.error) {
+    show(result.error.message); // a refused card is an answer, written for the payer
+  } else if (result.payment.status === "succeeded") {
+    done();
+  }
+});
+```
+
+`confirm` presents the card (Stripe's fields make a confirmation token), lets the payer's bank
+check it's them if it asks — in Stripe's own frame — and reads the payment back until it settles.
+If an answer is lost on the way, it reads back what happened: a card is never presented twice.
+A read the server briefly can't answer (a 503, no answer) is sent again, twice at most; a confirm
+never is.
+
+A page that adds to what is charged (a tip) calls `sheet.setAmount(total)` and passes
+`sheet.confirm({ tipAmount })`. `wallets: "never"` hides Apple Pay and Google Pay, and
+`layout: "accordion"` changes Stripe's layout.
+
+A payment that waits on the payer's bank when your page opens (a charge to a saved card whose
+bank asked) is finished with `tuppence.resumePayment({ clientSecret })`.
+
+For your own layout, `tuppence.elements(payment)` gives Stripe's Elements group, set up to match
+the charge, and `tuppence.confirmPayment({ clientSecret, elements })` pays with it.
+
+## Bacs Direct Debit
+
+Where the business takes Direct Debit, Stripe's Payment Element offers *Bacs Direct Debit* beside
+cards, and shows the mandate and the Direct Debit Guarantee itself — don't hide or clip it. A
+debit takes a few working days, so `confirm` answers at once with the payment `processing`:
+
+```js
+const { payment } = await sheet.confirm();
+if (payment.status === "processing" && payment.payment_method_type === "bacs_debit") {
+  // "Your Direct Debit is set up. We'll collect £50.00 on or around Tue 14 Oct."
+  showSetUp(payment.amount, payment.processing.expected_debit_date); // YYYY-MM-DD, or null
+}
+```
+
+Nothing waits for `succeeded`: that (or `failed`) arrives days later, by webhook
+(`payment.succeeded`, `payment.failed`). Stripe emails the payer to confirm the mandate.
+Where a debit can't be used — a booking's deposit, a till, a credit top-up — the payment's
+`excluded_payment_method_types` says so, and the sheet leaves Bacs out.
+
+## Apple Pay, Google Pay and Link on a store
+
+A Tuppence store's checkout puts the wallet buttons first. `expressCheckout` mounts Stripe's
+Express Checkout Element in deferred mode (nothing is made until the shopper approves), in the
+business's branding:
+
+```js
+import { createTuppence } from "@tuppence/js";
+
+const tuppence = createTuppence();
+const cart = tuppence.cart(); // the store's own domain; `{ base: "/<slug>" }` on the shared address
+const basket = await cart.get();
+
+const express = tuppence
+  .expressCheckout(checkout, { basket, onConfirm }) // `checkout`: amount, currency, Stripe's key and account
+  .mount("#express");
+express.on("total", (quoted) => showTotal(quoted.totals.due));
+express.on("error", (error) => show(error.message)); // "Sorry, we don't deliver to Jersey."
+
+async function onConfirm({ confirmationToken, amount, delivery, email, shippingAddress }) {
+  // Your server pays the checkout with the token. Answer `{ error: { message } }` and the
+  // wallet says the payment failed.
+}
+```
+
+Each address and delivery choice in the wallet's sheet is priced by the basket's quote
+(`POST /storefront/v1/cart/quote`, which changes nothing), and the sheet's total follows it
+(`elements.update({ amount })`). Stripe gives the sheet 20 seconds to hear back; a quote that
+takes 15 is refused (`quote_timeout`), so the sheet says so rather than hanging. An address the
+store doesn't deliver to is refused in the sheet, and the `error` event carries the store's
+reason. Closing the sheet puts the basket's own total back. `amount` in `onConfirm` is what the
+sheet showed: the server charges its own figure, never the page's.
+
+Pass `onShippingAddressChange` or `onShippingRateChange` to price the sheet yourself,
+`shipping: false` for a basket with nothing to send, and `buttons` for Stripe's own button
+options. On the store's own hosts the basket's cookie rides along with the quote; headless, pass
+`tuppence.cart({ base: "https://api.tuppence.ai", publishableKey, cartToken })`.
+
+## An address with Stripe's autocomplete
+
+```js
+const elements = await tuppence.elements(checkout); // the payment's own fields
+const address = tuppence
+  .address(elements, { mode: "shipping", defaultValues: { address: { country: "GB" } } })
+  .mount("#address");
+address.on("change", ({ complete, address }) => complete && cart.quote({ address }));
+const { complete, value } = await address.value(); // Stripe shows what's missing by its field
+```
+
+In the payment's own Elements group a shipping address goes with the payment, and Stripe's
+autocomplete works with no key of yours. `tuppence.address(checkout, { mode: "billing" })` makes
+Elements of its own, in the business's branding.
+
+## Save a card with nothing charged
+
+```js
+const sheet = tuppence.setupSheet({ clientSecret: setupClientSecret }).mount("#card");
+const result = await sheet.confirm();
+```
+
+## Test mode without a Stripe sandbox
+
+An environment with no Stripe sandbox behind it runs Tuppence's simulated gateway: there are no
+card fields (`elements()` answers `null`, and a sheet's `error` event says so), and you name one
+of Stripe's test cards instead —
+`confirmPayment({ clientSecret, testPaymentMethod: "pm_card_gb" })`. `tuppence.config.stripe`
+says which gateway you are on.
+
+## Another API address
+
+The SDK calls `https://api.tuppence.ai`. To use another Tuppence environment you have been given,
+pass `apiBase`, and allow that address in your page's `connect-src`:
+
+```js
+const tuppence = await loadTuppence("pk_test_…", { apiBase: "https://…" });
+```
+
+## Your page's Content-Security-Policy
+
+Stripe.js is loaded from `js.stripe.com` — never bundled — when card fields are first asked for.
+Allow what Stripe's integration security guide lists, and Tuppence's API, beside your page's own
+sources (`script-src 'self'`, and so on):
+
+```
+script-src https://js.stripe.com https://*.js.stripe.com
+frame-src https://js.stripe.com https://*.js.stripe.com https://hooks.stripe.com
+connect-src https://api.stripe.com https://api.tuppence.ai
+```
+
+`hooks.stripe.com` is where a bank's check (3-D Secure) opens. The SDK itself needs nothing more:
+no inline script or style, no `eval`. Tuppence's own tests run a checkout under exactly this
+policy, read from this file, and pay through Stripe's fields.
+
+The publishable key and client secrets travel in headers, never in a URL, and no cookie is sent
+(except a store's own basket cookie, to its own host's basket routes).
+
+### No integrity hash on Stripe.js
+
+Stripe serves Stripe.js from `js.stripe.com` and changes it in place — fixes, and the fraud
+signals Radar relies on — so it cannot carry a Subresource Integrity (SRI) hash: Stripe does not
+support one, and does not allow Stripe.js to be bundled or hosted anywhere else. The SDK loads it
+through Stripe's own loader (`@stripe/stripe-js`), with no `integrity` attribute. What keeps the
+page's scripts in check is the policy above: scripts only from your origin and Stripe's.
+
+`@tuppence/js` itself is part of your bundle, pinned by your lockfile's integrity hash.
+
+### What this package never does
+
+It never renders a card field of its own — Stripe's iframes take the card — and never carries
+Stripe.js. Its build fails if either creeps in: the bundle and every published file are checked
+for an `<input>`, for the names card fields go by (`cardnumber`, `cc-number`, `cvc`…), and for
+Stripe.js's own code.

package/dist/appearance.d.ts

@@ -0,0 +1,8 @@
+import type { Appearance } from "@stripe/stripe-js";
+import type { Branding } from "./types.js";
+/**
+ * Stripe's card fields dressed as the business's page (plan 09-06): its accent colour — already
+ * checked for contrast when it was set (09-08) — on Tuppence's type and corners, so the fields
+ * look like the rest of the page rather than like a form from somewhere else.
+ */
+export declare function appearanceFor(branding: Branding | null | undefined): Appearance;

package/dist/appearance.js

@@ -0,0 +1,25 @@
+/** Tuppence Blue — the pay pages' accent where the business has not set its own. */
+const TUPPENCE_BLUE = "#3b5bff";
+/**
+ * Stripe's card fields dressed as the business's page (plan 09-06): its accent colour — already
+ * checked for contrast when it was set (09-08) — on Tuppence's type and corners, so the fields
+ * look like the rest of the page rather than like a form from somewhere else.
+ */
+export function appearanceFor(branding) {
+    const accent = branding?.accent_color ?? TUPPENCE_BLUE;
+    return {
+        theme: "stripe",
+        variables: {
+            colorPrimary: accent,
+            colorText: "#1f2937",
+            colorDanger: "#b42318",
+            fontFamily: '"Inter", system-ui, -apple-system, sans-serif',
+            fontSizeBase: "16px",
+            borderRadius: "8px",
+            spacingUnit: "4px",
+        },
+        rules: {
+            ".Input:focus": { borderColor: accent, boxShadow: `0 0 0 2px ${accent}33` },
+        },
+    };
+}

package/dist/bank-details.d.ts

@@ -0,0 +1,12 @@
+import { TuppenceError } from "./errors.js";
+import type { BankAccountDetails, ExternalAccountParams } from "./types.js";
+/**
+ * `bankAccountDetails`'s work (52-09): the details checked and put in the shape
+ * `POST /v1/accounts/{id}/external_accounts` takes as `external_account`. Pure — nothing is sent
+ * from here. Messages name the field, never its value.
+ */
+export declare function externalAccountParams(details: BankAccountDetails): {
+    externalAccount: ExternalAccountParams;
+} | {
+    error: TuppenceError;
+};

package/dist/bank-details.js

@@ -0,0 +1,117 @@
+import { TuppenceError } from "./errors.js";
+const invalid = (message, param) => new TuppenceError({ type: "invalid_request_error", code: "parameter_invalid", message, param });
+/**
+ * The eurozone's bank accounts are IBANs (100-25): each live country's length, as Tuppence
+ * checks them. Bulgaria joins when it opens.
+ */
+const IBAN_LENGTHS = {
+    AT: 20,
+    BE: 16,
+    CY: 28,
+    DE: 22,
+    EE: 20,
+    ES: 24,
+    FI: 18,
+    FR: 27,
+    GR: 27,
+    HR: 21,
+    IE: 22,
+    IT: 27,
+    LT: 20,
+    LU: 20,
+    LV: 21,
+    MT: 31,
+    NL: 18,
+    PT: 25,
+    SI: 19,
+    SK: 24,
+};
+/** Whether an IBAN's check digits are right: its rearranged digits leave 1 when divided by 97. */
+function mod97(iban) {
+    let remainder = 0;
+    for (const ch of `${iban.slice(4)}${iban.slice(0, 4)}`) {
+        for (const digit of String(Number.parseInt(ch, 36))) {
+            remainder = (remainder * 10 + Number(digit)) % 97;
+        }
+    }
+    return remainder === 1;
+}
+/** Why `iban` can't be a bank account in `country`, or null. Never the value itself. */
+function ibanError(iban, country, length) {
+    if (!/^[A-Z]{2}\d{2}[A-Z0-9]+$/.test(iban) || !iban.startsWith(country)) {
+        return invalid("Enter the IBAN: it starts with the bank's country code.", "account_number");
+    }
+    if (iban.length !== length) {
+        return invalid(`Check the IBAN: it is ${length} characters in this country.`, "account_number");
+    }
+    if (!mod97(iban)) {
+        return invalid("Check the IBAN: a character is wrong.", "account_number");
+    }
+    return null;
+}
+/**
+ * `bankAccountDetails`'s work (52-09): the details checked and put in the shape
+ * `POST /v1/accounts/{id}/external_accounts` takes as `external_account`. Pure — nothing is sent
+ * from here. Messages name the field, never its value.
+ */
+export function externalAccountParams(details) {
+    const country = details.country.toUpperCase();
+    const routing = (details.routingNumber ?? "").replace(/[\s-]/g, "");
+    const account = details.accountNumber.replace(/[\s-]/g, "").toUpperCase();
+    const holder = details.accountHolderName.trim();
+    const ibanLength = IBAN_LENGTHS[country];
+    if (country !== "GB" && country !== "US" && !ibanLength) {
+        return {
+            error: invalid("Bank accounts can be added in GB, the US or the eurozone.", "country"),
+        };
+    }
+    if (!holder)
+        return { error: invalid("Enter the name on the account.", "account_holder_name") };
+    if (ibanLength) {
+        if (routing) {
+            return {
+                error: invalid("For this country, the IBAN is the whole bank account: leave the routing number out.", "routing_number"),
+            };
+        }
+        const error = ibanError(account, country, ibanLength);
+        if (error)
+            return { error };
+        return {
+            externalAccount: {
+                object: "bank_account",
+                country,
+                currency: details.currency.toLowerCase(),
+                account_holder_name: holder,
+                account_holder_type: details.accountHolderType,
+                account_number: account,
+            },
+        };
+    }
+    if (country === "GB") {
+        if (!/^\d{6}$/.test(routing)) {
+            return { error: invalid("A sort code is 6 digits, like 10-88-00.", "routing_number") };
+        }
+        if (!/^\d{8}$/.test(account)) {
+            return { error: invalid("A UK account number is 8 digits.", "account_number") };
+        }
+    }
+    else {
+        if (!/^\d{9}$/.test(routing)) {
+            return { error: invalid("A routing number is 9 digits.", "routing_number") };
+        }
+        if (!/^\d{4,17}$/.test(account)) {
+            return { error: invalid("Check the account number: 4 to 17 digits.", "account_number") };
+        }
+    }
+    return {
+        externalAccount: {
+            object: "bank_account",
+            country,
+            currency: details.currency.toLowerCase(),
+            account_holder_name: holder,
+            account_holder_type: details.accountHolderType,
+            routing_number: routing,
+            account_number: account,
+        },
+    };
+}

package/dist/errors.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Why something did not happen — Tuppence's error envelope, or Stripe.js's, in one shape.
+ *
+ * `type` is `card_error` for a card the bank refused (show `message` to the payer: it is written
+ * for them), `validation_error` for card fields that are not complete, `api_connection_error`
+ * when Tuppence could not be reached, and otherwise the API's own type.
+ */
+export declare class TuppenceError extends Error {
+    readonly type: string;
+    readonly code: string | null;
+    readonly declineCode: string | null;
+    readonly param: string | null;
+    /** The HTTP status, or 0 when there was no answer. */
+    readonly status: number;
+    constructor(fields: {
+        type: string;
+        message: string;
+        code?: string | null;
+        declineCode?: string | null;
+        param?: string | null;
+        status?: number;
+    });
+    /** The API's envelope: `{ error: { type, code, message, param, decline_code } }`. */
+    static fromEnvelope(status: number, body: unknown): TuppenceError;
+    /** Stripe.js's error (card fields, a confirmation token, a bank's check). */
+    static fromStripe(error: {
+        type?: string;
+        message?: string;
+        code?: string;
+        decline_code?: string;
+        param?: string;
+    }): TuppenceError;
+}

package/dist/errors.js

@@ -0,0 +1,41 @@
+/**
+ * Why something did not happen — Tuppence's error envelope, or Stripe.js's, in one shape.
+ *
+ * `type` is `card_error` for a card the bank refused (show `message` to the payer: it is written
+ * for them), `validation_error` for card fields that are not complete, `api_connection_error`
+ * when Tuppence could not be reached, and otherwise the API's own type.
+ */
+export class TuppenceError extends Error {
+    constructor(fields) {
+        super(fields.message);
+        this.name = "TuppenceError";
+        this.type = fields.type;
+        this.code = fields.code ?? null;
+        this.declineCode = fields.declineCode ?? null;
+        this.param = fields.param ?? null;
+        this.status = fields.status ?? 0;
+    }
+    /** The API's envelope: `{ error: { type, code, message, param, decline_code } }`. */
+    static fromEnvelope(status, body) {
+        const error = body?.error ?? {};
+        const text = (key) => (typeof error[key] === "string" ? String(error[key]) : null);
+        return new TuppenceError({
+            type: text("type") ?? "api_error",
+            message: text("message") ?? `Tuppence answered ${status}.`,
+            code: text("code"),
+            declineCode: text("decline_code"),
+            param: text("param"),
+            status,
+        });
+    }
+    /** Stripe.js's error (card fields, a confirmation token, a bank's check). */
+    static fromStripe(error) {
+        return new TuppenceError({
+            type: error.type ?? "api_error",
+            message: error.message ?? "Stripe could not take the card.",
+            code: error.code ?? null,
+            declineCode: error.decline_code ?? null,
+            param: error.param ?? null,
+        });
+    }
+}

package/dist/express-mount.d.ts

@@ -0,0 +1,49 @@
+import type { StripeElements } from "@stripe/stripe-js";
+import { type AddressHandlers, type AddressOptions, type AddressValue, type ExpressCheckoutOptions, type ExpressHandlers, type Host } from "./express.js";
+import type { CartAddress, StorefrontCartClient } from "./storefront.js";
+import type { Payable, Tuppence } from "./tuppence.js";
+/**
+ * A wallet's or the Address Element's address, as the quote takes it. Wallets redact it until
+ * the payment is authorised (a city, a region, part of a postcode). A region that is a name
+ * ("West Yorkshire") is no code, so it is left out.
+ */
+export declare function cartAddressOf(address: {
+    country?: string | null;
+    state?: string | null;
+    postal_code?: string | null;
+}): CartAddress;
+/** The address as the basket's quote takes it, once there is a country. */
+export declare const asCartAddress: (value: AddressValue | undefined) => CartAddress | null;
+/**
+ * What `ExpressCheckout` does once it is mounted (85-10): Stripe's Express Checkout Element (Apple
+ * Pay, Google Pay, Link) for a store's basket, in deferred mode: nothing is made until the shopper
+ * approves. Each address and delivery choice in the sheet is priced by the basket's quote and the
+ * sheet's total follows it (`elements.update({ amount })`); the server charges its own figure at
+ * the end. One per `ExpressCheckout`, so a remount keeps the basket as last quoted.
+ */
+export declare class Wallet {
+    private readonly host;
+    private readonly tuppence;
+    private readonly payable;
+    private readonly options;
+    private readonly cart;
+    private basket;
+    private address;
+    private delivery;
+    private amount;
+    private elements;
+    constructor(host: Host<ExpressHandlers>, tuppence: Tuppence, payable: Payable, options: ExpressCheckoutOptions, cart: StorefrontCartClient);
+    /** The delivery choices as the sheet lists them: the chosen one first, as Stripe selects it. */
+    private ratesOf;
+    /** A quote, or why there is none: refused after 15 s rather than left to hang the sheet. */
+    private within;
+    /** The quote's answer for the sheet, or the reason it can't be delivered. */
+    private deliverable;
+    private priced;
+    private addressChanged;
+    private rateChanged;
+    private confirmed;
+    load(target: string | HTMLElement): Promise<void>;
+}
+/** Stripe's Address Element, with Stripe's autocomplete, for `AddressField`. */
+export declare function mountAddress(host: Host<AddressHandlers>, tuppence: Tuppence, from: StripeElements | Payable, options: AddressOptions, target: string | HTMLElement): Promise<void>;