@tuppence/js 0.0.0-stage → 0.1.0

package/dist/tuppence.d.ts

@@ -0,0 +1,278 @@
+import type { ConfirmationTokenCreateParams, Stripe, StripeElementLocale, StripeElements, StripeElementsOptionsMode } from "@stripe/stripe-js";
+import { TuppenceError } from "./errors.js";
+import { AddressField, type AddressOptions, ExpressCheckout, type ExpressCheckoutOptions } from "./express.js";
+import { type Fetch } from "./http.js";
+import { PaymentSheet, type PaymentSheetOptions, SetupSheet, type SetupSheetOptions } from "./sheet.js";
+import { StorefrontCartClient, type StorefrontOptions } from "./storefront.js";
+import type { BankAccountDetails, ExternalAccountParams, PublicPayment, PublicSetupSession, PublicTopupLinkPage, SdkConfig } from "./types.js";
+/**
+ * Loads Stripe.js for one publishable key and connected account. The default is Stripe's own
+ * loader, which adds js.stripe.com's script to the page when first asked: Stripe.js is never
+ * bundled, as Stripe's terms and PCI guidance require.
+ */
+export type LoadStripe = (publishableKey: string, options: {
+    /** The connected account whose card fields these are. */
+    stripeAccount: string;
+    /** The payer's language for Stripe's fields and messages, as Stripe names it (`stripeLocale`). */
+    locale: StripeElementLocale;
+}) => Promise<Stripe | null>;
+export interface TuppenceOptions {
+    /** Where Tuppence's API is: `https://api.tuppence.ai` unless you say otherwise. */
+    apiBase?: string;
+    /** The `fetch` to call it with — the browser's own unless you pass one. */
+    fetch?: Fetch;
+    /** How Stripe.js is loaded — Stripe's own loader unless you pass one. */
+    loadStripe?: LoadStripe;
+    /**
+     * The payer's language, a BCP 47 tag such as `de-AT`: Stripe's card fields and messages speak
+     * it (`de`). The browser's unless you pass one. Stripe's `pt` is Brazilian Portuguese, so a
+     * payer in Portugal (`pt-PT`) gets Stripe's English; only `pt-BR` gets Stripe's Portuguese.
+     */
+    locale?: string;
+    /**
+     * While a payment settles: how often it is read back, for how long, and how to wait (also
+     * between the retries of a read the server briefly couldn't answer).
+     */
+    poll?: {
+        intervalMs?: number;
+        timeoutMs?: number;
+        sleep?: (ms: number) => Promise<void>;
+    };
+    /** How the page is sent elsewhere (`topups.redirect`) — `window.location.assign` unless you pass one. */
+    navigate?: (url: string) => void;
+}
+/**
+ * What Stripe's fields need to know about a charge before it exists (deferred mode): a
+ * payment, or what a store's checkout says it will charge.
+ */
+export type Payable = Pick<PublicPayment, "amount" | "currency" | "stripe_publishable_key" | "stripe_account"> & Partial<Pick<PublicPayment, "branding" | "capture_method" | "setup_future_usage" | "excluded_payment_method_types">>;
+/** How Stripe's card fields look and read — Stripe's own options, passed as they are. */
+export type ElementsOptions = Pick<StripeElementsOptionsMode, "appearance" | "fonts" | "locale" | "loader"> & {
+    /** What is charged, when the page adds to it (a tip): the payment's `amount` otherwise. */
+    amount?: number;
+};
+export interface ConfirmPaymentOptions {
+    /** The payment's client secret (`pay_…_secret_…`), from your server. */
+    clientSecret: string;
+    /** Stripe's card fields, from `tuppence.elements(payment)`. */
+    elements?: StripeElements;
+    /** More for Stripe to know about the card (billing details), passed as it is. */
+    params?: ConfirmationTokenCreateParams;
+    /** Pay with the card the customer saved, for a charge that waits for them. */
+    savedCard?: boolean;
+    /**
+     * TEST MODE, on the simulated gateway only (where there are no card fields): one of Stripe's
+     * test payment methods by name, such as `pm_card_gb`.
+     */
+    testPaymentMethod?: string;
+    /** A tip the payer adds, where the payment offers one — in the smallest unit, as `amount`. */
+    tipAmount?: number;
+}
+export interface ConfirmSetupOptions {
+    /** The setup session's client secret (`sets_…_secret_…`), from your server. */
+    clientSecret: string;
+    /** Stripe's card fields, from `tuppence.setupElements(session)`. */
+    elements?: StripeElements;
+    params?: ConfirmationTokenCreateParams;
+    /** TEST MODE, on the simulated gateway only: one of Stripe's test payment methods by name. */
+    testPaymentMethod?: string;
+}
+export type BankAccountDetailsResult = {
+    externalAccount: ExternalAccountParams;
+    error?: undefined;
+} | {
+    error: TuppenceError;
+    externalAccount?: undefined;
+};
+export type PaymentResult = {
+    payment: PublicPayment;
+    error?: undefined;
+} | {
+    error: TuppenceError;
+    payment: PublicPayment | null;
+};
+export type SetupResult = {
+    setupSession: PublicSetupSession;
+    error?: undefined;
+} | {
+    error: TuppenceError;
+    setupSession: PublicSetupSession | null;
+};
+/**
+ * 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 declare class Tuppence {
+    /** What `loadTuppence` learned about its key; null for a page that only holds client secrets. */
+    readonly config: SdkConfig | null;
+    private readonly http;
+    private readonly fetchImpl;
+    private readonly loadStripe;
+    /** What Stripe.js is loaded with for the payer's language (100-18). */
+    private readonly locale;
+    private readonly stripes;
+    /** The Stripe instance each set of card fields came from: its token must come from it too. */
+    private readonly owners;
+    private readonly intervalMs;
+    private readonly timeoutMs;
+    private readonly sleep;
+    private readonly navigate;
+    /**
+     * 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.
+     */
+    readonly 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: (page: PublicTopupLinkPage, options: ElementsOptions & {
+            amount: number;
+        }) => Promise<StripeElements | null>;
+        /**
+         * 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: (options: {
+            token: string;
+            businessFunds: boolean;
+            amount?: number;
+            elements?: StripeElements;
+            testPaymentMethod?: string;
+        }) => Promise<{
+            page: PublicTopupLinkPage;
+            error?: TuppenceError;
+        }>;
+        /**
+         * 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: (options: {
+            token: string;
+        }) => Promise<{
+            page: PublicTopupLinkPage;
+            error?: TuppenceError;
+        }>;
+        redirect: (options: {
+            url: string;
+        }) => void;
+    };
+    constructor(options?: TuppenceOptions, 
+    /** What `loadTuppence` learned about its key; null for a page that only holds client secrets. */
+    config?: SdkConfig | null);
+    /** `loadTuppence`: the key checked here, then what the API says about it. */
+    static load(publishableKey: string, options?: TuppenceOptions): Promise<Tuppence>;
+    /** The payment a client secret belongs to, as its payer sees it. */
+    retrievePayment(clientSecret: string): Promise<PublicPayment>;
+    /** The setup session a client secret belongs to, as its customer sees it. */
+    retrieveSetupSession(clientSecret: string): Promise<PublicSetupSession>;
+    /**
+     * 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 })`.
+     */
+    elements(payment: Payable, options?: ElementsOptions): Promise<StripeElements | null>;
+    /** Stripe's card fields for saving a card with nothing charged — cards only, as the session saves. */
+    setupElements(session: PublicSetupSession, options?: Omit<ElementsOptions, "amount">): Promise<StripeElements | null>;
+    /**
+     * 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: PaymentSheetOptions): PaymentSheet;
+    /**
+     * 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?: StorefrontOptions): StorefrontCartClient;
+    /**
+     * 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: Payable, options: ExpressCheckoutOptions): ExpressCheckout;
+    /**
+     * 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: StripeElements | Payable, options: AddressOptions): AddressField;
+    /**
+     * 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`.
+     */
+    confirmationToken(elements: StripeElements, params?: ConfirmationTokenCreateParams): Promise<{
+        id: string;
+    } | {
+        error: TuppenceError;
+    }>;
+    /** The same for saving a card with nothing charged. */
+    setupSheet(options: SetupSheetOptions): SetupSheet;
+    /**
+     * 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`.
+     */
+    confirmPayment(options: ConfirmPaymentOptions): Promise<PaymentResult>;
+    /** Saves a card with nothing charged — the same steps as a payment. */
+    confirmSetup(options: ConfirmSetupOptions): Promise<SetupResult>;
+    /**
+     * 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.
+     */
+    resumePayment(options: {
+        clientSecret: string;
+    }): Promise<PaymentResult>;
+    /** The same for a card being saved. */
+    resumeSetup(options: {
+        clientSecret: string;
+    }): Promise<SetupResult>;
+    private resume;
+    /**
+     * 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: BankAccountDetails): BankAccountDetailsResult;
+    /** Stripe.js for an object's publishable key and account — loaded once for each pair. */
+    private stripeFor;
+    /** A card, as the confirm route takes it: a confirmation token, a saved card, or a test card. */
+    private present;
+    /** Confirm, then the bank's check if it asks, then read back until it settles. */
+    private run;
+    /** What follows a confirm: the bank's check if it asks, then a read-back until it settles. */
+    private onward;
+    /** Reads an object back until neither the bank nor Stripe is still deciding, or time is up. */
+    private settle;
+}
+/** For a page that holds client secrets and no key — Tuppence's own pay pages. */
+export declare function createTuppence(options?: TuppenceOptions): Tuppence;
+/**
+ * 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 declare function loadTuppence(publishableKey: string, options?: TuppenceOptions): Promise<Tuppence>;