@percayso-community/cayso-contracts 0.23.0

package/dist/purchase.d.ts

@@ -0,0 +1,531 @@
+/**
+ * `cayso.purchase` — the request and response shapes for a holder buying Cayso
+ * with sterling, the closed set of reasons a purchase can fail, and — since
+ * CAY-0032 — what a repeat of the same idempotency key does, which statuses are
+ * terminal, what cancelling does and what expiry releases.
+ *
+ * A `Purchase` and a `Movement` are different nouns (CAY-0023). A purchase has a
+ * lifecycle — pending, then succeeded, failed or cancelled — and lives entirely
+ * off the ledger; a movement is the single, final, append-only consequence of a
+ * *succeeded* purchase, and a consumer of this surface never sees one. So there
+ * is no movement type here, and nothing on these shapes can express one.
+ *
+ * ## Why the failure reason is a closed union, not a string
+ *
+ * Every interesting failure — verification refused, the card declined, over the
+ * backing ceiling — happens **before** any cents move, so the reason belongs to
+ * the purchase rather than to a movement that never occurred. It is a union of
+ * fixed string literals for a regulatory-shaped reason: an open string means a
+ * consumer (Piper) pattern-matches on our prose, and our prose changes. A new
+ * failure mode is therefore a **new union member and a minor version**, never a
+ * free-text field and never a widening to `string`. Nothing on `PurchaseResult`
+ * can carry prose — that is the property its tests pin.
+ *
+ * ## Why the published value is recorded on the purchase
+ *
+ * The published value ratchets: it rises and never falls (CAY-0013). A purchase
+ * is priced at the value **fixed at authorisation** and that figure is carried on
+ * `PurchaseAuthorised` and echoed on `PurchaseResult`, so a revaluation between
+ * authorising and settling cannot silently change what somebody gets. Reading the
+ * value again later would price the purchase at a different rate than the one the
+ * holder was quoted.
+ *
+ * ## A repeat `POST /api/purchases` with the same key REPLAYS (CAY-0032)
+ *
+ * A consumer on a money path must not have to guess what a retry does, and this
+ * is the statement of record.
+ *
+ * **Posting the same `idempotencyKey` twice returns the ORIGINAL authorisation.**
+ * Same `purchaseId`, same `cents`, same `publishedValuePence`, with a freshly
+ * minted `paymentClientSecret` for the browser to confirm with. It is answered
+ * `200` where the first authorisation was answered `201`, and it is the whole of
+ * "resume": there is no separate resume operation, because the retry a consumer
+ * already performs after a dropped connection is the resume.
+ *
+ *   - **The purchase is never minted twice.** One key is one purchase and one
+ *     issuance (CLAUDE.md). A repeat writes no second purchase, reserves no
+ *     second slice of headroom and takes no second hold at the payment gateway —
+ *     the gateway deduplicates on the same key, so re-deriving the client secret
+ *     returns the same hold rather than a second one.
+ *   - **The price does not move.** The cents were priced at authorisation, at the
+ *     published value recorded on the purchase, and a replay echoes THAT figure.
+ *     If the published value ratchets between the first `POST` and the retry, the
+ *     retry still answers the original `publishedValuePence` and the original
+ *     `cents`. The value fixed at authorisation governs, so a revaluation
+ *     mid-refresh cannot change what somebody gets — which is why replay was
+ *     chosen over refusing the repeat and superseding it with a fresh
+ *     authorisation: superseding would re-price, and re-pricing a retry is how a
+ *     holder pays for a dropped connection.
+ *   - **A repeat of a purchase that has already reached a terminal status does
+ *     not revive it.** It reports the terminal outcome (see below), and in
+ *     particular an EXPIRED purchase is not resurrected: its reservation has been
+ *     released and its headroom belongs to somebody else now. The consumer's
+ *     remedy is to start a new purchase under a NEW key.
+ *
+ * ## One response union, discriminated by `outcome`
+ *
+ * `POST /api/purchases` answers exactly one of {@link PurchaseAuthorisationResponse}'s
+ * three branches, and a consumer tells them apart by reading `outcome` — never by
+ * sniffing which fields happen to be present. Shape-sniffing is how a consumer
+ * comes to depend on a field being absent, and an absent field is not a contract.
+ *
+ *   - `'authorised'` — a live authorisation to confirm in the browser. Fresh
+ *     (`201`) and replayed (`200`) are the SAME shape, on purpose: a replay is not
+ *     a lesser answer, and a consumer that had to branch on which it got would be
+ *     branching on something it cannot control.
+ *   - `'terminal'` — the purchase has already reached a terminal status and will
+ *     not change again. Carries the status and, when it failed, the closed reason.
+ *   - `'unresolved'` — the purchase is `'issued_uncaptured'`: its cents landed and
+ *     its capture did not, so there is nothing to confirm and nothing has ended.
+ *     A consumer polls the result route and does not re-post (CAY-0033).
+ *   - `'refused'` — the authorisation was refused, with a member of the closed
+ *     {@link PurchaseFailureReason} union. Nothing was charged: refuse comes
+ *     before charge (CAY-0023).
+ *
+ * ONE REFUSAL ARRIVES BEFORE THE HANDLER, AND IS STATED HERE RATHER THAN HIDDEN.
+ *   A credential that is not money-grade is refused AT THE GATE — the shared
+ *   assurance check that guards every value-moving route (CAY-0029) — before this
+ *   route's handler runs. That refusal is the gate's own shape, `403
+ *   {"error":"verification_refused"}`, carried with no `outcome` because it is not
+ *   this route's answer: the same body is what `citizenshipProvision` and the
+ *   operator surface give, and one route may not redefine a refusal it shares with
+ *   every other. `'verification_refused'` is still a member of
+ *   {@link PurchaseFailureReason} so a consumer renders it from the same closed
+ *   set, and a consumer reading a `403` should read `error` without expecting
+ *   `outcome`. Stated, rather than left for somebody to discover.
+ *
+ * ## Which statuses are terminal
+ *
+ * `'pending'` and `'issued_uncaptured'` are the non-terminal statuses.
+ * {@link TERMINAL_PURCHASE_STATUSES} and {@link isTerminalPurchaseStatus} are the
+ * statement of that, exported so a consumer can stop polling on the same rule the
+ * service settles on rather than on its own list. A purchase in a terminal status
+ * never transitions again: it cannot be cancelled, cannot be re-authorised, and a
+ * repeat of its key reports it rather than reviving it.
+ *
+ * ## `issued_uncaptured` — the cents landed and the sterling did not (CAY-0033)
+ *
+ * CAY-0023 orders authorise, issue, then capture, so nothing is charged unless the
+ * cents landed. This status is that order's other half: the cents landed and the
+ * capture that should have taken the sterling did not, so cents exist that nobody
+ * has paid for and the purchase is neither a success nor a failure yet.
+ *
+ * **It is neither `'succeeded'` nor `'failed'`, and it may still become either.** A
+ * consumer polling `GET /api/purchases/:purchaseId` reads it there plainly and
+ * keeps polling: {@link isTerminalPurchaseStatus} answers `false` for it and it is
+ * absent from {@link TERMINAL_PURCHASE_STATUSES}. It carries **no failure reason**
+ * — nothing has failed yet, and a reason would be a verdict nobody has reached.
+ *
+ * **The cents ARE in the holder's balance while it lasts.** `GET /api/wallet`
+ * counts them and they can be spent; there is no provisional figure netting them
+ * off and no second balance to consult. A balance is the sum of a wallet's holdings
+ * (CAY-0019) and the holding is real — a surface that hid it would report a figure
+ * the ledger does not hold, which is the one thing a derived balance must never do.
+ *
+ * **Capture is retried a bounded number of times.** At most
+ * {@link MAX_CAPTURE_ATTEMPTS} attempts are made in all, each under the purchase's
+ * own idempotency key, so a transient gateway failure resolves with nobody involved
+ * and a re-attempt can neither take a second hold nor charge twice. When the
+ * attempts are spent, the purchase waits in this status for a person.
+ *
+ * **Resolution is operator-only.** No route a consumer can call moves a purchase
+ * out of this status, and a holder cannot cancel it — cancel refuses with
+ * `'already_issued'`, because the cents have already landed and a cancellation must
+ * not un-land them. An operator either re-attempts the capture or records a
+ * compensating movement. Meanwhile the holder sees this status on the purchase and
+ * the cents in their balance, and nothing else about their wallet changes.
+ *
+ * **What the holder eventually sees.** A re-attempted capture that succeeds moves
+ * the purchase to `'succeeded'` and the cents stay. A compensation carves the cents
+ * back out of the wallet as a NEW, final, append-only movement — never an
+ * amendment, and never an undoing, of the movement that issued them — and the
+ * purchase becomes `'failed'` with the closed reason `'capture_failed'`. `failed`
+ * is the honest word for it: nobody paid, so the holder does not keep the cents,
+ * and no other status says that.
+ *
+ * ## Cancel: `POST /api/purchases/:purchaseId/cancel`
+ *
+ * Cancelling a pending purchase releases its reservation and moves it to
+ * `'cancelled'` — a terminal status of its own, deliberately NOT folded into
+ * `'failed'`. A failure is something that happened TO a holder; a cancellation is
+ * something the holder (or an operator acting on their wallet) CHOSE, and a
+ * surface that rendered the two identically would tell somebody their payment
+ * failed when they had simply changed their mind. A cancelled purchase therefore
+ * carries **no failure reason**: there is no member of the closed union that
+ * describes a choice, and inventing one would make "failed" mean both things
+ * again.
+ *
+ * Cancel is idempotent — cancelling an already-cancelled purchase answers the
+ * same `'cancelled'` outcome and is not an error — and it refuses a purchase that
+ * has already reached a terminal status, with the closed
+ * {@link PurchaseCancelRefusalReason} union. **A succeeded purchase cannot be
+ * cancelled**: its cents have been issued and its card captured, and undoing that
+ * is a refund, which is a different act with different rules and is not this.
+ *
+ * **A cancelled purchase is not a reversed movement.** There is no movement to
+ * reverse, because cancel only ever reaches a purchase that never captured — a
+ * movement is final and append-only, and one that did not happen is not a
+ * movement (CAY-0023, CLAUDE.md).
+ *
+ * ## Expiry: how long, what it releases, what a poller sees
+ *
+ * An authorisation holds its slice of the backing ceiling for
+ * {@link PURCHASE_RESERVATION_WINDOW_SECONDS} from the moment it is authorised;
+ * `expiresAt` on {@link PurchaseAuthorised} is that instant, and a consumer should
+ * read the field rather than recompute it.
+ *
+ * When the window lapses, the reservation is released — the reserved headroom
+ * returns to the economy and is available to the next authorisation — and the
+ * purchase becomes `'failed'` with the reason `'expired'`. Releasing is
+ * idempotent: a reservation released twice frees nothing the second time, so a
+ * cancel racing the expiry sweep cannot return the same headroom to the ceiling
+ * twice.
+ *
+ * What expiry does NOT release is as important: **nothing was charged and nothing
+ * was minted**, so there is no money to return. Expiry releases a *reservation*, a
+ * promise on headroom, and never a movement, a holding or a capture.
+ *
+ * A consumer polling `GET /api/purchases/:purchaseId` sees `pending` until the
+ * window lapses and the sweep runs, then `failed` with `'expired'` — a terminal
+ * status, so polling stops there. A repeat `POST` under the same key answers the
+ * `'terminal'` branch for the same purchase and does NOT re-authorise it; the
+ * remedy is a new purchase under a new key.
+ *
+ * ## What this file must not decide
+ *
+ *   - **Sterling in, cents out.** A caller asks in `sterlingPence` and is answered
+ *     in `cents`; there is no formatted money and no money in a string on this
+ *     surface. Pence are the sterling side and stay a bare `number`; cent amounts
+ *     are `Cents` and timestamps are `Millis`, matching `cayso.wallet`.
+ *   - **No economic numbers.** No amount, rate, tier or ceiling lives here or in
+ *     these comments. `publishedValuePence` is a field, not a value. They live in
+ *     the canon PRD and are read from one place. The single figure stated here is
+ *     the reservation window — a MECHANISM parameter of this contract, not an
+ *     economic one, stated for the same reason and in the same way
+ *     `assertion.ts` states the credential's lifetime ceiling and skew tolerance:
+ *     a consumer is entitled to know the window its authorisation is measured
+ *     against, and cannot read it from a type.
+ *   - **No flow.** The refusal ladder, the reservation, the sterling gateway, the
+ *     expiry sweep and the capture all live in `apps/api`. This file is the shapes
+ *     those slices exchange with a consumer — no handler, no state machine, no
+ *     reservation record, no provider client.
+ *   - **No credential.** `paymentClientSecret` is a value the payment provider
+ *     mints for the caller's browser to confirm with. No provider key, publishable
+ *     key, webhook secret or bank credential belongs anywhere near this tree.
+ *   - `onBehalfOfWalletId` lets a caller buy for an organisation it holds the
+ *     mandate for. It moves nothing out of that organisation and sets no Signatory
+ *     threshold (a canon figure, read from configuration). An organisation paying a
+ *     Citizen is the commercial payment, its own operation in
+ *     `commercial-payment.ts` (CAY-0079), and never a purchase.
+ */
+import type { Cents, Millis } from './wallet.js';
+/** The capability this contract surfaces. Matches the glossary exactly. */
+export declare const PURCHASE_CAPABILITY: "cayso.purchase";
+/**
+ * How long, in **seconds**, an authorisation holds its slice of the backing
+ * ceiling before the reservation is released and the purchase expires.
+ *
+ * A MECHANISM parameter of this contract, not a canon economic figure — no
+ * amount, rate, tier or schedule is restated here (CLAUDE.md). It is the
+ * browser-confirmation window: long enough for a holder to complete the payment
+ * provider's confirmation step after the client secret is handed over, short
+ * enough that an abandoned authorisation frees its headroom promptly rather than
+ * walling it off. It is not a number anyone tunes for economics.
+ *
+ * It lives on the contract for the reason {@link
+ * import('./assertion.js').MAX_ASSERTION_LIFETIME_SECONDS} does — that is the
+ * precedent, and this follows it. Two parties read this window: the service that
+ * computes `expiresAt` from it, and the consumer that has to decide how long to
+ * keep a confirmation page alive. A consumer cannot read a window from a type, and
+ * a consumer guessing it is a consumer that abandons a live authorisation or waits
+ * on a dead one. Seconds, matching the credential parameters beside it; the
+ * `expiresAt` a consumer actually renders is `Millis`, and is a FIELD it should
+ * read rather than recompute from this.
+ */
+export declare const PURCHASE_RESERVATION_WINDOW_SECONDS: number;
+/**
+ * How many times in all a purchase's capture is attempted before it stops being
+ * attempted without a person: the first attempt plus its bounded retries.
+ *
+ * A MECHANISM parameter of this contract, not a canon economic figure — no amount,
+ * rate, tier or schedule is restated here (CLAUDE.md). It is a bound on how long
+ * the service will keep calling a gateway that is not answering, chosen so a
+ * transient failure resolves by itself and a persistent one reaches a person
+ * promptly rather than being retried at forever. It is not a number anyone tunes
+ * for economics.
+ *
+ * It lives on the contract for the reason {@link PURCHASE_RESERVATION_WINDOW_SECONDS}
+ * does, which in turn follows {@link import('./assertion.js').MAX_ASSERTION_LIFETIME_SECONDS}
+ * — that is the precedent, and this follows it. Two parties read the bound: the
+ * service, which stops at it, and the consumer, which is entitled to know that a
+ * purchase sitting in `'issued_uncaptured'` is not being retried indefinitely and
+ * that after this many attempts only an operator will move it. A consumer cannot
+ * read a bound from a type. The schema carries it a second time, as a `CHECK` on
+ * the stored attempt count, so neither layer can drift past it alone.
+ */
+export declare const MAX_CAPTURE_ATTEMPTS = 3;
+/** Asked for in sterling; answered in cents. */
+export interface PurchaseRequest {
+    readonly sterlingPence: number;
+    /** Caller-generated. The same key must never mint twice; a repeat REPLAYS. */
+    readonly idempotencyKey: string;
+    /** Buying for an organisation the caller holds the mandate for. */
+    readonly onBehalfOfWalletId?: string;
+}
+/**
+ * A live authorisation: the purchase is `pending` and the browser has what it
+ * needs to confirm. Answered `201` for a fresh authorisation and `200` for a
+ * REPLAY of the same idempotency key — identical shape, identical `purchaseId`,
+ * `cents` and `publishedValuePence`, and a freshly minted client secret. The
+ * `outcome` discriminant is what a consumer switches on.
+ */
+export interface PurchaseAuthorised {
+    readonly outcome: 'authorised';
+    readonly purchaseId: string;
+    readonly cents: Cents;
+    /** The rate this purchase was priced at, fixed at authorisation. A replay echoes it unchanged. */
+    readonly publishedValuePence: number;
+    /** For the caller's browser to confirm with the payment provider. */
+    readonly paymentClientSecret: string;
+    readonly expiresAt: Millis;
+}
+/**
+ * The purchase has already reached a terminal status and will not change again —
+ * the answer to a repeat `POST` of a key whose purchase succeeded, failed
+ * (including by expiry) or was cancelled. It is NOT an authorisation: there is no
+ * client secret and no `expiresAt`, because there is nothing live to confirm.
+ *
+ * A consumer that wants to buy after seeing this starts a NEW purchase under a NEW
+ * key. Re-posting this key will keep answering this branch forever.
+ */
+export interface PurchaseTerminal {
+    readonly outcome: 'terminal';
+    readonly purchaseId: string;
+    readonly status: TerminalPurchaseStatus;
+    readonly cents: Cents;
+    readonly publishedValuePence: number;
+    /** The closed reason, when the purchase failed. `null` for succeeded and for cancelled. */
+    readonly failureReason: PurchaseFailureReason | null;
+}
+/**
+ * The purchase's cents landed and its capture did not: it is `'issued_uncaptured'`
+ * (CAY-0033). A repeat `POST` of its key is answered with this rather than with
+ * `'authorised'` or `'terminal'`, because neither would be true — there is no live
+ * hold to confirm, and nothing has ended.
+ *
+ * It is its own branch rather than a `'terminal'` one with a live status, for the
+ * reason {@link TerminalPurchaseStatus} exists: a "terminal" answer that carried a
+ * status the purchase can still leave is a contradiction, and a consumer that
+ * stopped on it would stop one step before the answer. A consumer reading this
+ * polls `GET /api/purchases/:purchaseId` and does not re-post; re-posting this key
+ * will keep answering this branch until the purchase resolves.
+ */
+export interface PurchaseUnresolved {
+    readonly outcome: 'unresolved';
+    readonly purchaseId: string;
+    readonly status: 'issued_uncaptured';
+    readonly cents: Cents;
+    readonly publishedValuePence: number;
+}
+/**
+ * The authorisation was refused, with a member of the closed reason union.
+ * Nothing was charged and nothing was reserved that is not already released:
+ * refuse comes before charge (CAY-0023).
+ */
+export interface PurchaseRefused {
+    readonly outcome: 'refused';
+    readonly error: PurchaseFailureReason;
+}
+/**
+ * The ONE declared response of `POST /api/purchases`, discriminated by `outcome`.
+ *
+ * A consumer switches on `outcome` and the compiler makes the switch exhaustive.
+ * It does not test for the presence of `paymentClientSecret` to decide whether it
+ * was authorised, and it does not read a field that is absent on the branch it
+ * actually received — which is precisely the failure a discriminant exists to
+ * prevent on a money path.
+ */
+export type PurchaseAuthorisationResponse = PurchaseAuthorised | PurchaseTerminal | PurchaseUnresolved | PurchaseRefused;
+export type PurchaseFailureReason = 'verification_refused' | 'card_declined' | 'ceiling_exceeded'
+/**
+ * The reservation window lapsed before the purchase settled. The headroom has
+ * been released; the purchase is terminal, and a repeat of its key reports it
+ * rather than re-authorising it. The remedy is a new purchase under a new key.
+ */
+ | 'expired' | 'not_authorised_for_wallet' | 'gateway_unavailable'
+/**
+ * The caller has never been provisioned, so there is no wallet to mint into.
+ * Since CAY-0031 nothing provisions as a side effect — a self-purchase used to
+ * bring a wallet into being on first touch, and no longer does — so this is the
+ * honest refusal rather than a silent creation. The remedy is
+ * `ROUTES.citizenshipProvision`, and it is the caller's to take.
+ */
+ | 'not_provisioned'
+/**
+ * The idempotency key has already been used, by this same holder, for a
+ * purchase of a DIFFERENT amount of sterling.
+ *
+ * A Replay is "the same idempotency key again" answered with the authorisation
+ * that key already has — the same purchase, the same cents, the same published
+ * value (CONTEXT.md, `Replay`). That licenses answering a REPEATED request. A
+ * request carrying the same key and a different `sterlingPence` is not a
+ * repeat of anything: the two amounts cannot both be what the caller asked
+ * for, so there is no honest answer to give and the request is refused rather
+ * than silently answered at the first amount or re-priced at the second. The
+ * remedy is a new key; the existing purchase is untouched and still replayable
+ * at its own amount.
+ */
+ | 'amount_mismatch'
+/**
+ * The sterling asked for cannot be expressed in cents at all.
+ *
+ * ₡1 is 100 cents and ₡1 is `publishedValuePence` pence, so a purchase of
+ * `sterlingPence` is `sterlingPence × 100 ÷ publishedValuePence` cents — and
+ * above some sterling that figure is larger than the ledger's integer cents can
+ * hold. There is no honest answer to give for such a request: rounding it would
+ * hand back a number nobody computed, and the amount is not malformed, so
+ * refusing it as a bad request would be saying the wrong thing.
+ *
+ * WHERE THE BOUND SITS IS NOT A FIGURE ANYONE PICKS. It is arithmetic: the
+ * largest sterling that still prices inside the range, at the published value
+ * in force at the moment of the check. It therefore MOVES — the published value
+ * ratchets upward and never falls (CAY-0002, CAY-0013), so the bound only ever
+ * rises, and an amount refused with this reason before a quickening may be
+ * admitted after one. A consumer renders it as "ask for less", not as "never".
+ *
+ * Nothing is authorised, nothing is reserved and the payment provider is never
+ * spoken to: this refusal arrives before any of them.
+ */
+ | 'amount_not_priceable'
+/**
+ * The cents were issued and the sterling was never taken (CAY-0033). Capture was
+ * attempted up to {@link MAX_CAPTURE_ATTEMPTS} times and did not succeed, and an
+ * operator resolved the purchase by recording a compensating movement — a NEW
+ * movement carving the issued cents back out of the wallet, never an amendment of
+ * the movement that put them there. The purchase is terminal and did not succeed;
+ * the holder was not charged, and does not keep the cents.
+ */
+ | 'capture_failed'
+/**
+ * The holder's binding was erased while the purchase was still authorised and
+ * nothing had been issued (CAY-0085). An erasure resolves every purchase still in
+ * flight before the binding goes, so the purchase ends here: nothing was issued,
+ * the hold on the sterling is released, and nothing is taken. It is also the
+ * answer a delivery gets for a purchase whose wallet no longer has a binding —
+ * settlement issues nothing into a wallet bound to nobody. The purchase is
+ * terminal and there is no remedy to offer: the person it was for asked to be
+ * forgotten.
+ */
+ | 'holder_erased';
+/**
+ * A status a purchase never leaves. Stated as its own union so that `status` on
+ * {@link PurchaseTerminal} cannot be `'pending'` — a "terminal" answer that
+ * carried a live status would be a contradiction the type language can rule out,
+ * so it does.
+ *
+ * `'cancelled'` is a member and is deliberately NOT `'failed'`: a cancellation is
+ * a choice and a failure is not, and a consumer rendering them identically would
+ * tell somebody their payment failed when they had changed their mind. A cancelled
+ * purchase carries no failure reason.
+ */
+export type TerminalPurchaseStatus = 'succeeded' | 'failed' | 'cancelled';
+/**
+ * A status a purchase is still moving through. `'pending'` is the authorisation
+ * before anything landed; `'issued_uncaptured'` is the cents having landed and the
+ * sterling not having been taken (CAY-0033). Neither is a verdict, so neither
+ * carries a failure reason, and a consumer polls on through both.
+ */
+export type LivePurchaseStatus = 'pending' | 'issued_uncaptured';
+/**
+ * The lifecycle of a purchase: the statuses it can still leave
+ * ({@link LivePurchaseStatus}) and the ones it cannot
+ * ({@link TerminalPurchaseStatus}). Written as that composition so the three unions
+ * can never drift into disagreement about which statuses exist.
+ */
+export type PurchaseStatus = LivePurchaseStatus | TerminalPurchaseStatus;
+/**
+ * Every status a purchase never leaves. Derived from the terminality map rather
+ * than listed a second time, so a status classified there appears here without
+ * anybody having to remember to add it.
+ *
+ * A consumer stops polling when it sees one of these. Exporting it means the
+ * consumer stops on OUR rule rather than on a list it maintained itself, which is
+ * the list that goes stale the day a status is added.
+ */
+export declare const TERMINAL_PURCHASE_STATUSES: readonly PurchaseStatus[];
+/** Whether a purchase in this status is finished — it will never transition again. */
+export declare function isTerminalPurchaseStatus(status: PurchaseStatus): boolean;
+/**
+ * Why a cancellation was refused. A closed union, for the reason
+ * {@link PurchaseFailureReason} is one: a consumer renders it rather than
+ * pattern-matching on our prose.
+ *
+ * Two members are "it is already finished", and they are kept apart because they
+ * are different things to tell somebody: their purchase went through, or it did
+ * not. There is deliberately no `'already_cancelled'` member — cancelling a
+ * cancelled purchase is not a refusal, it is the same answer again.
+ *
+ * The third, `'already_issued'`, is not "finished" at all: the purchase is live, in
+ * `'issued_uncaptured'`, and cancelling is refused precisely because its cents have
+ * already landed. Cancel releases a reservation; it has never had the power to take
+ * back a movement, and giving it that power here would make it the reversal
+ * CAY-0023 forbids.
+ */
+export type PurchaseCancelRefusalReason = 
+/**
+ * The cents were issued and the card captured. Undoing that is a refund — a
+ * different act, with different rules — and it is not this operation.
+ */
+'already_succeeded'
+/** It had already failed, with its own closed reason. There is nothing left to release. */
+ | 'already_failed'
+/**
+ * The cents have landed and the capture has not settled (`'issued_uncaptured'`,
+ * CAY-0033). There is no reservation left to release and cancelling cannot un-land
+ * a movement, so it is refused. The purchase is still going: a bounded capture
+ * retry, or an operator, resolves it to succeeded or failed.
+ */
+ | 'already_issued';
+/**
+ * The purchase is cancelled: its reservation is released and it will not
+ * transition again. Answered for the cancellation that did the work AND for a
+ * repeat of it — cancel is idempotent, and a second cancel is not an error.
+ *
+ * The figures describe the authorisation that was released, not anything minted: a
+ * cancelled purchase mints nothing, and there is no movement here to reverse.
+ */
+export interface PurchaseCancelled {
+    readonly outcome: 'cancelled';
+    readonly purchaseId: string;
+    readonly status: 'cancelled';
+    readonly cents: Cents;
+    readonly publishedValuePence: number;
+}
+/** The cancellation was refused: the purchase had already reached a terminal status. */
+export interface PurchaseCancelRefused {
+    readonly outcome: 'refused';
+    readonly error: PurchaseCancelRefusalReason;
+}
+/**
+ * The ONE declared response of `POST /api/purchases/:purchaseId/cancel`,
+ * discriminated by `outcome` — the same discipline the authorisation response
+ * follows, and for the same reason.
+ */
+export type PurchaseCancelResponse = PurchaseCancelled | PurchaseCancelRefused;
+/**
+ * What `GET /api/purchases/:purchaseId` answers: where the purchase has got to.
+ *
+ * `status` is reported as it stands, including the two live statuses. A consumer
+ * that reads `'issued_uncaptured'` has been told plainly that the purchase is
+ * neither a success nor a failure, that it may still become either, and — per the
+ * statement at the head of this file — that the cents are in the holder's balance
+ * meanwhile. It carries no failure reason, because nothing has failed.
+ */
+export interface PurchaseResult {
+    readonly purchaseId: string;
+    readonly status: PurchaseStatus;
+    readonly cents?: Cents;
+    readonly publishedValuePence?: number;
+    /** Present only on a FAILED purchase. No live or cancelled purchase carries a reason. */
+    readonly failureReason?: PurchaseFailureReason;
+}

package/dist/purchase.js

@@ -0,0 +1,107 @@
+/*
+ * Copyright 2026 Percayso Community
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/** The capability this contract surfaces. Matches the glossary exactly. */
+export const PURCHASE_CAPABILITY = 'cayso.purchase';
+/**
+ * How long, in **seconds**, an authorisation holds its slice of the backing
+ * ceiling before the reservation is released and the purchase expires.
+ *
+ * A MECHANISM parameter of this contract, not a canon economic figure — no
+ * amount, rate, tier or schedule is restated here (CLAUDE.md). It is the
+ * browser-confirmation window: long enough for a holder to complete the payment
+ * provider's confirmation step after the client secret is handed over, short
+ * enough that an abandoned authorisation frees its headroom promptly rather than
+ * walling it off. It is not a number anyone tunes for economics.
+ *
+ * It lives on the contract for the reason {@link
+ * import('./assertion.js').MAX_ASSERTION_LIFETIME_SECONDS} does — that is the
+ * precedent, and this follows it. Two parties read this window: the service that
+ * computes `expiresAt` from it, and the consumer that has to decide how long to
+ * keep a confirmation page alive. A consumer cannot read a window from a type, and
+ * a consumer guessing it is a consumer that abandons a live authorisation or waits
+ * on a dead one. Seconds, matching the credential parameters beside it; the
+ * `expiresAt` a consumer actually renders is `Millis`, and is a FIELD it should
+ * read rather than recompute from this.
+ */
+export const PURCHASE_RESERVATION_WINDOW_SECONDS = 15 * 60;
+/**
+ * How many times in all a purchase's capture is attempted before it stops being
+ * attempted without a person: the first attempt plus its bounded retries.
+ *
+ * A MECHANISM parameter of this contract, not a canon economic figure — no amount,
+ * rate, tier or schedule is restated here (CLAUDE.md). It is a bound on how long
+ * the service will keep calling a gateway that is not answering, chosen so a
+ * transient failure resolves by itself and a persistent one reaches a person
+ * promptly rather than being retried at forever. It is not a number anyone tunes
+ * for economics.
+ *
+ * It lives on the contract for the reason {@link PURCHASE_RESERVATION_WINDOW_SECONDS}
+ * does, which in turn follows {@link import('./assertion.js').MAX_ASSERTION_LIFETIME_SECONDS}
+ * — that is the precedent, and this follows it. Two parties read the bound: the
+ * service, which stops at it, and the consumer, which is entitled to know that a
+ * purchase sitting in `'issued_uncaptured'` is not being retried indefinitely and
+ * that after this many attempts only an operator will move it. A consumer cannot
+ * read a bound from a type. The schema carries it a second time, as a `CHECK` on
+ * the stored attempt count, so neither layer can drift past it alone.
+ */
+export const MAX_CAPTURE_ATTEMPTS = 3;
+/**
+ * Whether each status is terminal, written out as a total map over
+ * {@link PurchaseStatus}.
+ *
+ * The mapped type is the exhaustiveness check the whole terminal-status
+ * declaration rests on: adding a member to `PurchaseStatus` does not compile until
+ * somebody writes down whether a purchase in it is finished. That is a deliberate
+ * decision forced at the one place it matters, rather than a new status silently
+ * inheriting "not terminal" and a consumer polling it forever. It did its job in
+ * CAY-0033: `'issued_uncaptured'` — the "issued but not captured" status CAY-0032
+ * anticipated — was classified here, as NOT terminal, before anything else compiled.
+ *
+ * It is module-private on purpose. The exported statements are
+ * {@link TERMINAL_PURCHASE_STATUSES} and {@link isTerminalPurchaseStatus}: a
+ * consumer needs the answer, not the table, and a published mapped type is a shape
+ * the contract-schema generator cannot describe.
+ */
+const PURCHASE_STATUS_TERMINALITY = {
+    // The authorisation is held, the browser may still confirm, and the reservation is
+    // still counted against the ceiling. Nothing has landed and nothing was charged.
+    pending: false,
+    // Issued and NOT captured: the cents landed, the sterling did not. Not terminal —
+    // a bounded capture retry or an operator still moves it to succeeded or failed, so
+    // a consumer that stopped polling here would stop one step before the answer.
+    issued_uncaptured: false,
+    // Issued and captured. Terminal, and the one status cancel refuses outright.
+    succeeded: true,
+    // Refused, declined or expired, with a closed reason. Terminal.
+    failed: true,
+    // Chosen, by the holder or by an operator acting on their wallet. Terminal, and
+    // carries no failure reason — see TerminalPurchaseStatus.
+    cancelled: true,
+};
+/**
+ * Every status a purchase never leaves. Derived from the terminality map rather
+ * than listed a second time, so a status classified there appears here without
+ * anybody having to remember to add it.
+ *
+ * A consumer stops polling when it sees one of these. Exporting it means the
+ * consumer stops on OUR rule rather than on a list it maintained itself, which is
+ * the list that goes stale the day a status is added.
+ */
+export const TERMINAL_PURCHASE_STATUSES = Object.keys(PURCHASE_STATUS_TERMINALITY).filter((status) => PURCHASE_STATUS_TERMINALITY[status]);
+/** Whether a purchase in this status is finished — it will never transition again. */
+export function isTerminalPurchaseStatus(status) {
+    return PURCHASE_STATUS_TERMINALITY[status];
+}