@tuppence/js 0.0.0-stage → 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { appearanceFor } from "./appearance.js";
+export { TuppenceError } from "./errors.js";
+export type { AddressChange, AddressField, AddressOptions, AddressValue, ExpressCheckout, ExpressCheckoutOptions, ExpressConfirm, } from "./express.js";
+export type { Fetch } from "./http.js";
+export { stripeLocale } from "./locale.js";
+export type { PaymentSheet, PaymentSheetOptions, SetupSheet, SetupSheetOptions, SheetChange, SheetOptions, } from "./sheet.js";
+export { type CartAddress, type CartDeliveryOption, type CartTotals, type StorefrontCart, StorefrontCartClient, type StorefrontOptions, } from "./storefront.js";
+export { type BankAccountDetailsResult, type ConfirmPaymentOptions, type ConfirmSetupOptions, createTuppence, type ElementsOptions, type LoadStripe, loadTuppence, type Payable, type PaymentResult, type SetupResult, Tuppence, type TuppenceOptions, } from "./tuppence.js";
+export type { BankAccountDetails, Branding, ExternalAccountParams, Gateway, LastError, NextAction, PaymentProcessing, PaymentStatus, PublicLinkTopup, PublicPayment, PublicSetupSession, PublicTopupLinkPage, SdkConfig, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { appearanceFor } from "./appearance.js";
+export { TuppenceError } from "./errors.js";
+export { stripeLocale } from "./locale.js";
+export { StorefrontCartClient, } from "./storefront.js";
+export { createTuppence, loadTuppence, Tuppence, } from "./tuppence.js";

package/dist/locale.d.ts

@@ -0,0 +1,12 @@
+import type { StripeElementLocale } from "@stripe/stripe-js";
+/**
+ * The locale Stripe.js is loaded with for a payer's language (100-18), a BCP 47 tag such as
+ * `de-AT`: Stripe's own variant where it has one (`en-GB`, `fr-CA`, `pt-BR`), else the language
+ * (`de-AT` is `de`), else English. With no language at all, Stripe decides (`auto`).
+ *
+ * Stripe's `pt` is Brazilian Portuguese, so a payer in Portugal (`pt-PT`, or a bare `pt`) gets
+ * Stripe's English rather than Brazilian wording; only `pt-BR` gets Stripe's Portuguese.
+ */
+export declare function stripeLocale(tag: string | null | undefined): StripeElementLocale;
+/** The browser's language, where there is a browser. */
+export declare function browserLanguage(): string | undefined;

package/dist/locale.js

@@ -0,0 +1,79 @@
+/** The locales Stripe.js and its Elements speak (Stripe's `StripeElementLocale`, less `auto`). */
+const STRIPE_LOCALES = new Set([
+    "ar",
+    "bg",
+    "cs",
+    "da",
+    "de",
+    "el",
+    "en",
+    "en-AU",
+    "en-CA",
+    "en-NZ",
+    "en-GB",
+    "es",
+    "es-ES",
+    "es-419",
+    "et",
+    "fi",
+    "fil",
+    "fr",
+    "fr-CA",
+    "fr-FR",
+    "he",
+    "hu",
+    "hr",
+    "id",
+    "it",
+    "it-IT",
+    "ja",
+    "ko",
+    "lt",
+    "lv",
+    "ms",
+    "mt",
+    "nb",
+    "nl",
+    "no",
+    "pl",
+    "pt",
+    "pt-BR",
+    "ro",
+    "ru",
+    "sk",
+    "sl",
+    "sv",
+    "th",
+    "tr",
+    "vi",
+    "zh",
+    "zh-HK",
+    "zh-TW",
+]);
+/**
+ * The locale Stripe.js is loaded with for a payer's language (100-18), a BCP 47 tag such as
+ * `de-AT`: Stripe's own variant where it has one (`en-GB`, `fr-CA`, `pt-BR`), else the language
+ * (`de-AT` is `de`), else English. With no language at all, Stripe decides (`auto`).
+ *
+ * Stripe's `pt` is Brazilian Portuguese, so a payer in Portugal (`pt-PT`, or a bare `pt`) gets
+ * Stripe's English rather than Brazilian wording; only `pt-BR` gets Stripe's Portuguese.
+ */
+export function stripeLocale(tag) {
+    const parts = (tag ?? "").trim().replace(/_/g, "-").split("-").filter(Boolean);
+    const language = parts[0]?.toLowerCase();
+    if (!language || !/^[a-z]{2,3}$/.test(language))
+        return "auto";
+    // The region is the two-letter or three-digit subtag (a script such as `Hant` is skipped).
+    const region = parts.slice(1).find((p) => /^([A-Za-z]{2}|\d{3})$/.test(p));
+    const variant = region ? `${language}-${region.toUpperCase()}` : null;
+    if (language === "pt")
+        return variant === "pt-BR" ? "pt-BR" : "en";
+    if (variant && STRIPE_LOCALES.has(variant))
+        return variant;
+    return STRIPE_LOCALES.has(language) ? language : "en";
+}
+/** The browser's language, where there is a browser. */
+export function browserLanguage() {
+    const nav = globalThis.navigator;
+    return typeof nav?.language === "string" && nav.language ? nav.language : undefined;
+}

package/dist/sheet.d.ts

@@ -0,0 +1,92 @@
+import type { Appearance, ConfirmationTokenCreateParams, StripeElementLocale, StripeElements, StripePaymentElement } from "@stripe/stripe-js";
+import { TuppenceError } from "./errors.js";
+import type { PaymentResult, SetupResult, Tuppence } from "./tuppence.js";
+import type { PublicPayment, PublicSetupSession } from "./types.js";
+/** What a sheet tells the page: its fields are showing, their state, or why they cannot show. */
+export type SheetChange = {
+    complete: boolean;
+    empty: boolean;
+};
+type Handlers = {
+    ready: () => void;
+    change: (change: SheetChange) => void;
+    error: (error: TuppenceError) => void;
+};
+export interface SheetOptions {
+    /** The object's client secret, from your server. */
+    clientSecret: string;
+    /** How the fields look: the business's branding on the payer's view unless you say. */
+    appearance?: Appearance;
+    /** Apple Pay and Google Pay where the device has them (`auto`, the default), or `never`. */
+    wallets?: "auto" | "never";
+    /** Stripe's layout for the payment methods: `tabs` (the default) or `accordion`. */
+    layout?: "tabs" | "accordion";
+    /**
+     * The language Stripe's fields speak, one of Stripe.js's locales (`de`, `fr`, `en-GB`…): the
+     * browser's (`auto`, Stripe's default) unless you say. Your payer's language on your own page.
+     */
+    locale?: StripeElementLocale;
+}
+export interface PaymentSheetOptions extends SheetOptions {
+    /** The payment, as `retrievePayment` answered it — read when the sheet mounts if not given. */
+    payment?: PublicPayment;
+    /** What is charged, when the page adds to it (a tip) — the payment's `amount` otherwise. */
+    amount?: number;
+}
+export interface SetupSheetOptions extends SheetOptions {
+    setupSession?: PublicSetupSession;
+}
+type Mounted = {
+    elements: StripeElements;
+    element: StripePaymentElement;
+};
+/** A sheet: Stripe's Payment Element, mounted where the page says, confirmed through Tuppence. */
+declare abstract class Sheet<Result> {
+    protected readonly tuppence: Tuppence;
+    protected readonly options: SheetOptions;
+    private handlers;
+    protected mounted: Promise<Mounted | null> | null;
+    /** Taken down: a load still under way never mounts, and nothing is told any more. */
+    private destroyed;
+    constructor(tuppence: Tuppence, options: SheetOptions);
+    /** The card fields' group, once mounted: for a page that needs Stripe's own methods. */
+    protected abstract elementsFor(): Promise<StripeElements | null>;
+    abstract confirm(options?: {
+        params?: ConfirmationTokenCreateParams;
+    }): Promise<Result>;
+    on<E extends keyof Handlers>(event: E, handler: Handlers[E]): this;
+    /** Shows the fields in `target` (an element, or a selector). Loads Stripe.js if it must. */
+    mount(target: string | HTMLElement): this;
+    /**
+     * Takes the fields off the page — or, while they are still loading, keeps them off it — and
+     * says nothing more. The sheet can be mounted again.
+     */
+    destroy(): void;
+    protected emit<E extends keyof Handlers>(event: E, ...detail: Parameters<Handlers[E]>): void;
+    protected ready(): Promise<Mounted>;
+    private load;
+}
+/** Stripe's Payment Element for a payment: `tuppence.paymentSheet({ clientSecret }).mount(el)`. */
+export declare class PaymentSheet extends Sheet<PaymentResult> {
+    private readonly paymentOptions;
+    private amount;
+    constructor(tuppence: Tuppence, paymentOptions: PaymentSheetOptions);
+    protected elementsFor(): Promise<StripeElements | null>;
+    /** What is charged changed (a tip): the fields — and Apple Pay's sheet — show the new total. */
+    setAmount(amount: number): void;
+    /** Pays: the steps of `confirmPayment`, with the fields this sheet shows. */
+    confirm(options?: {
+        tipAmount?: number;
+        params?: ConfirmationTokenCreateParams;
+    }): Promise<PaymentResult>;
+}
+/** Stripe's Payment Element for saving a card with nothing charged. */
+export declare class SetupSheet extends Sheet<SetupResult> {
+    private readonly setupOptions;
+    constructor(tuppence: Tuppence, setupOptions: SetupSheetOptions);
+    protected elementsFor(): Promise<StripeElements | null>;
+    confirm(options?: {
+        params?: ConfirmationTokenCreateParams;
+    }): Promise<SetupResult>;
+}
+export {};

package/dist/sheet.js

@@ -0,0 +1,136 @@
+import { appearanceFor } from "./appearance.js";
+import { TuppenceError } from "./errors.js";
+/** No card fields where no Stripe is behind the environment. */
+const simulated = () => new TuppenceError({
+    type: "invalid_request_error",
+    code: "no_card_fields",
+    message: "There are no card fields here: this environment runs the simulated gateway. Pay with `testPaymentMethod` instead.",
+});
+/** A sheet: Stripe's Payment Element, mounted where the page says, confirmed through Tuppence. */
+class Sheet {
+    constructor(tuppence, options) {
+        this.tuppence = tuppence;
+        this.options = options;
+        this.handlers = {
+            ready: [],
+            change: [],
+            error: [],
+        };
+        this.mounted = null;
+        /** Taken down: a load still under way never mounts, and nothing is told any more. */
+        this.destroyed = false;
+    }
+    on(event, handler) {
+        this.handlers[event].push(handler);
+        return this;
+    }
+    /** Shows the fields in `target` (an element, or a selector). Loads Stripe.js if it must. */
+    mount(target) {
+        this.destroyed = false;
+        this.mounted ?? (this.mounted = this.load(target).catch((caught) => {
+            this.emit("error", caught instanceof TuppenceError
+                ? caught
+                : new TuppenceError({ type: "api_error", message: String(caught) }));
+            return null;
+        }));
+        return this;
+    }
+    /**
+     * Takes the fields off the page — or, while they are still loading, keeps them off it — and
+     * says nothing more. The sheet can be mounted again.
+     */
+    destroy() {
+        this.destroyed = true;
+        const mounted = this.mounted;
+        this.mounted = null;
+        void mounted?.then((m) => m?.element.destroy());
+    }
+    emit(event, ...detail) {
+        if (this.destroyed)
+            return;
+        for (const handler of this.handlers[event])
+            handler(...detail);
+    }
+    async ready() {
+        const mounted = await this.mounted;
+        if (!mounted) {
+            throw new TypeError("Mount the sheet, and let its fields load, before confirming.");
+        }
+        return mounted;
+    }
+    async load(target) {
+        const elements = await this.elementsFor();
+        // Taken down while Stripe.js loaded (a page that moved on, React's double mount in dev).
+        if (this.destroyed)
+            return null;
+        if (!elements) {
+            this.emit("error", simulated());
+            return null;
+        }
+        const wallet = this.options.wallets ?? "auto";
+        const element = elements.create("payment", {
+            layout: this.options.layout ?? "tabs",
+            wallets: { applePay: wallet, googlePay: wallet },
+        });
+        element.on("ready", () => this.emit("ready"));
+        element.on("change", (event) => this.emit("change", { complete: event.complete, empty: event.empty }));
+        element.on("loaderror", (event) => this.emit("error", TuppenceError.fromStripe(event.error)));
+        element.mount(target);
+        return { elements, element };
+    }
+}
+/** Stripe's Payment Element for a payment: `tuppence.paymentSheet({ clientSecret }).mount(el)`. */
+export class PaymentSheet extends Sheet {
+    constructor(tuppence, paymentOptions) {
+        super(tuppence, paymentOptions);
+        this.paymentOptions = paymentOptions;
+        this.amount = paymentOptions.amount;
+    }
+    async elementsFor() {
+        const payment = this.paymentOptions.payment ??
+            (await this.tuppence.retrievePayment(this.paymentOptions.clientSecret));
+        return this.tuppence.elements(payment, {
+            appearance: this.paymentOptions.appearance ?? appearanceFor(payment.branding),
+            ...(this.paymentOptions.locale ? { locale: this.paymentOptions.locale } : {}),
+            ...(this.amount === undefined ? {} : { amount: this.amount }),
+        });
+    }
+    /** What is charged changed (a tip): the fields — and Apple Pay's sheet — show the new total. */
+    setAmount(amount) {
+        this.amount = amount;
+        void this.mounted?.then((m) => m?.elements.update({ amount }));
+    }
+    /** Pays: the steps of `confirmPayment`, with the fields this sheet shows. */
+    async confirm(options = {}) {
+        const { elements } = await this.ready();
+        return this.tuppence.confirmPayment({
+            clientSecret: this.paymentOptions.clientSecret,
+            elements,
+            ...(options.tipAmount === undefined ? {} : { tipAmount: options.tipAmount }),
+            ...(options.params ? { params: options.params } : {}),
+        });
+    }
+}
+/** Stripe's Payment Element for saving a card with nothing charged. */
+export class SetupSheet extends Sheet {
+    constructor(tuppence, setupOptions) {
+        super(tuppence, setupOptions);
+        this.setupOptions = setupOptions;
+    }
+    async elementsFor() {
+        const session = this.setupOptions.setupSession ??
+            (await this.tuppence.retrieveSetupSession(this.setupOptions.clientSecret));
+        return this.tuppence.setupElements(session, {
+            appearance: this.setupOptions.appearance ?? appearanceFor(session.branding),
+            ...(this.setupOptions.locale ? { locale: this.setupOptions.locale } : {}),
+        });
+    }
+    async confirm(options = {}) {
+        const { elements } = await this.ready();
+        return this.tuppence.confirmSetup({
+            clientSecret: this.setupOptions.clientSecret,
+            elements,
+            ...(options.params ? { params: options.params } : {}),
+        });
+    }
+}

package/dist/storefront.d.ts

@@ -0,0 +1,90 @@
+import { type Fetch } from "./http.js";
+/** Where a store's basket is (plan/85 §Basket): the routes under `/storefront/v1/cart`. */
+export interface StorefrontOptions {
+    /**
+     * The store's address, before `/storefront/v1/…`: `""` on the store's own domain (the
+     * default), `/<slug>` or `/test/<slug>` on the shared address, or Tuppence's API headless.
+     * On the store's own hosts the basket's cookie rides along; headless it never does.
+     */
+    base?: string;
+    /** Headless only: the account's publishable key. */
+    publishableKey?: string;
+    /** Headless only: the basket's token, as the call that made the basket answered it. */
+    cartToken?: string;
+}
+/** Where an order goes, as far as pricing needs: the wallet sheet's address is only this much. */
+export interface CartAddress {
+    /** ISO 3166-1 alpha-2: `GB`, `US`. */
+    country: string;
+    /** A US state or other subdivision's code: `TX`. */
+    region?: string | null;
+    postcode?: string | null;
+}
+/** A delivery or collection choice with its promise (`YYYY-MM-DD` in the shop's zone). */
+export interface CartDeliveryOption {
+    /**
+     * What to send back as `delivery` to choose it. Opaque: on shipping profiles it joins one rate
+     * per profile in the basket, so it can run to a few thousand characters.
+     */
+    key: string;
+    name: string;
+    /** `delivery` or `collection`. */
+    kind: string;
+    amount: number;
+    earliest: string;
+    latest: string;
+    /** The day it leaves (collection: the day it is ready), `YYYY-MM-DD`. */
+    dispatch_by: string;
+    /** What to show: "Arrives Fri 4 to Sat 5 Sep", "Ready to collect Wednesday 2 September". */
+    label: string;
+    selected: boolean;
+}
+/** The basket's figures, every one the server's (store-core on the till's engine). */
+export interface CartTotals {
+    subtotal: number;
+    discount: number;
+    delivery: number;
+    tax: number;
+    prices_include_tax: boolean;
+    total: number;
+    gift_cards: number;
+    /** What the shopper pays by card or wallet. */
+    due: number;
+}
+/** The basket, as `GET /storefront/v1/cart` and `POST …/quote` answer it. */
+export interface StorefrontCart {
+    object: "cart";
+    id: string | null;
+    livemode: boolean;
+    currency: string;
+    status: string;
+    count: number;
+    lines: Array<{
+        id: string;
+        name: string;
+        quantity: number;
+        amount: number;
+        [f: string]: unknown;
+    }>;
+    totals: CartTotals | null;
+    delivery_options: CartDeliveryOption[];
+    /** Why nothing can be delivered here, in words for the shopper. */
+    delivery_refusal: {
+        code: string;
+        message: string;
+    } | null;
+    [field: string]: unknown;
+}
+/** A store's basket routes: reads, and the quote the wallet sheet asks for. */
+export declare class StorefrontCartClient {
+    private readonly http;
+    private readonly headers;
+    constructor(fetchImpl: Fetch, options?: StorefrontOptions);
+    /** The shopper's basket on this store, priced. */
+    get(): Promise<StorefrontCart>;
+    /** The totals for an address and a delivery choice, changing nothing. */
+    quote(input: {
+        address?: CartAddress | null;
+        delivery?: string | null;
+    }): Promise<StorefrontCart>;
+}

package/dist/storefront.js

@@ -0,0 +1,25 @@
+import { Http } from "./http.js";
+/** A store's basket routes: reads, and the quote the wallet sheet asks for. */
+export class StorefrontCartClient {
+    constructor(fetchImpl, options = {}) {
+        const base = (options.base ?? "").replace(/\/+$/, "");
+        const headless = /^https?:\/\//.test(base);
+        // Same origin: the store's HttpOnly cookie is the basket. Headless: headers, no cookie.
+        this.http = new Http(base, fetchImpl, undefined, headless ? "omit" : "same-origin");
+        this.headers = {
+            ...(options.publishableKey ? { "Tuppence-Publishable-Key": options.publishableKey } : {}),
+            ...(options.cartToken ? { "Tuppence-Cart": options.cartToken } : {}),
+        };
+    }
+    /** The shopper's basket on this store, priced. */
+    get() {
+        return this.http.get("/storefront/v1/cart", this.headers);
+    }
+    /** The totals for an address and a delivery choice, changing nothing. */
+    quote(input) {
+        return this.http.post("/storefront/v1/cart/quote", this.headers, {
+            address: input.address ?? null,
+            delivery: input.delivery ?? null,
+        });
+    }
+}