@percayso-community/cayso-contracts 0.23.0

package/dist/citizenship.d.ts

@@ -0,0 +1,215 @@
+/**
+ * `citizenship` — provisioning a citizen, and the sign-up grant that arrives
+ * with it (CAY-0031).
+ *
+ * Provisioning is an EXPLICIT, IDEMPOTENT CALL. It is not a side effect of
+ * reading a wallet, and it is not an event on a bus. `cayso.wallet` used to
+ * create a wallet on the first authenticated read (CAY-0022); it no longer
+ * creates anything, because a citizen who never opens a wallet page would never
+ * have been credited, and two concurrent first reads had no defined outcome.
+ * CAY-0031 amends that record: the wallet and the sign-up grant are
+ * provisioned together, by one call, in one transaction.
+ *
+ * ## A consumer can ask, and asking provisions nothing
+ *
+ * {@link ROUTES.citizenship} is a READ. It answers {@link CitizenshipView} for
+ * the calling citizen and writes nothing whatever the answer is — so a consumer
+ * may render "not provisioned yet" without that render being the thing that
+ * provisions. {@link ROUTES.citizenshipProvision} is the write, and it is the
+ * only one.
+ *
+ * The two are separate PATHS, not one path with two methods, and that is
+ * deliberate: the scope requirement CAY-0030's gate enforces is registered
+ * per-path, so a `GET` and a `POST` sharing `/api/citizenship` would share one
+ * scope requirement and the read would silently inherit the write's — or, worse,
+ * the write would inherit the read's. One path, one operation, one scope.
+ *
+ * ## The state is a CLOSED VALUE, never prose
+ *
+ * {@link Citizenship} is a discriminated union on `state`, so a consumer switches
+ * on a literal rather than pattern-matching a sentence. There is no `pending`, no
+ * `provisioning` and no `partial`. The call commits the wallet and the grant
+ * together or it commits neither, so a state meaning "half of it happened" would
+ * describe something this surface cannot produce.
+ *
+ * ## The third state is not "in between" (CAY-0081)
+ *
+ * A founder wallet is created at genesis, holding a founder's allocation, and is
+ * bound to its Citizen by a founder claim. A claimed founder was never provisioned
+ * and must never be: no sign-up grant reaches them by any route. So they are
+ * neither of the first two states. Reporting them as `not-provisioned` would
+ * invite the one call that must not happen, and a background retry of it would
+ * never stop. {@link CitizenshipFounderClaimed} says this Citizen holds a wallet,
+ * was never provisioned, and is not waiting to be.
+ *
+ * {@link FounderClaimRefusal} is the founder claim's closed set of refusals,
+ * answered by {@link ROUTES.citizenshipFounderClaim}. It carries
+ * `founder_wallet_lapsed` before anything can produce it, so that a consumer
+ * renders every member before it can arrive.
+ *
+ * ## NO NUMBERS LIVE HERE, AND THAT IS THE POINT
+ *
+ * {@link SignUpGrantTerms} names the sign-up grant's amount and its
+ * restriction period as FIELDS A CONSUMER READS AT RUNTIME. Their source is the
+ * canon PRD — the deck's tiered schedule, recorded in the canon's own questions
+ * table as governing — and they reach this surface as configuration read in one
+ * place, exactly as the policy figures do.
+ *
+ * **Do not "fix" this by inlining a figure.** A literal here would be a second
+ * home for a number whose only home is the canon, and the two go stale in
+ * opposite directions; the canon's own record of the figure exists precisely
+ * because an earlier verbal one was superseded. `cents` is a field, not a value.
+ * `restrictionMonths` is a field, not a duration. The same rule `cayso.wallet`
+ * states for `publishedValuePence` (CLAUDE.md, "Where numbers live").
+ *
+ * ## What this file must not decide
+ *
+ *   - **No operator path.** There is no field here by which somebody other than
+ *     the citizen could be provisioned, because in v1 there is not one: the call
+ *     is authorised by the citizen's own assertion and nothing else (CAY-0031).
+ *     The absence is structural, so there is nothing to refuse at runtime.
+ *   - **No sweep, no forfeiture, no vesting.** `expiresAt` is the promise that
+ *     was recorded (CAY-0020). Recording it is not the same as acting on it, and
+ *     nothing here acts on it.
+ *   - **No carve, no holding, no movement shape.** `movementId` is a handle a
+ *     consumer can quote back; the movement itself is not a consumer's business
+ *     and is not on this surface. Naming a grant `'restricted'` on arrival is where
+ *     it LANDS; what happens when it moves is CAY-0074's — a carve does not move
+ *     restriction, and a restricted lot may not be transferred.
+ */
+import type { Cents, Millis, WalletRecord } from './wallet.js';
+/**
+ * The wire code a read refuses with when the citizen it names has not been
+ * provisioned — a value, so a consumer can compare against the contract's own
+ * string rather than retyping ours.
+ *
+ * `cayso.wallet`'s read answers this, with no wallet and no balance, for a
+ * citizen who has never been provisioned. It is deliberately the same spelling
+ * Piper already uses for the same state: one word for one condition across the
+ * two pillars, rather than two that have to be mapped.
+ */
+export declare const NOT_PROVISIONED: "not_provisioned";
+/**
+ * The terms a provisioning applies: how much the sign-up grant is, and how
+ * long it lands restricted for.
+ *
+ * Read at runtime, from the deployment that serves them. See the file docblock:
+ * these are the canon's figures reaching a consumer as configuration, and they
+ * are never restated as literals anywhere — not here, not in a comment, not in
+ * the schema, not in an ADR.
+ */
+export interface SignUpGrantTerms {
+    /** The sign-up grant, in cents. A field, not a value. */
+    readonly cents: Cents;
+    /** How many months the grant lands restricted for. A field, not a duration. */
+    readonly restrictionMonths: number;
+}
+/**
+ * The sign-up grant a provisioned citizen actually received — one movement,
+ * final and append-only (CAY-0023). There is at most one of these per wallet,
+ * ever.
+ *
+ * It lands RESTRICTED and carries its expiry, because granted Cayso lands
+ * restricted and purchased Cayso does not (CONTEXT.md). `restriction` is typed as
+ * the literal `'restricted'` rather than the two-member vocabulary: a sign-up
+ * grant that arrived unrestricted is not a thing this surface can describe,
+ * which is the type half of the invariant the schema also enforces.
+ */
+export interface SignUpGrant {
+    /** The movement that carried the cents. Final; there is no second one. */
+    readonly movementId: string;
+    /** What arrived, in cents. The figure of the day it was granted, not today's terms. */
+    readonly cents: Cents;
+    /** Granted Cayso lands restricted. The literal is the invariant. */
+    readonly restriction: 'restricted';
+    /** The promised date the restriction lifts. Recorded, never swept (CAY-0020). */
+    readonly expiresAt: Millis;
+    readonly grantedAt: Millis;
+}
+/** A citizen this deployment has never provisioned. No wallet, no grant. */
+export interface CitizenshipNotProvisioned {
+    readonly state: 'not-provisioned';
+}
+/**
+ * A provisioned citizen: the wallet, and the one sign-up grant that arrived
+ * with it. Both, always — they were committed together, so a shape carrying one
+ * without the other would describe a state the call cannot produce.
+ */
+export interface CitizenshipProvisioned {
+    readonly state: 'provisioned';
+    readonly wallet: WalletRecord;
+    readonly signUpGrant: SignUpGrant;
+}
+/**
+ * A Citizen bound to a founder wallet by a founder claim (CAY-0081). The wallet,
+ * and NO sign-up grant.
+ *
+ * The absence is the type half of "a claimed founder never receives a sign-up
+ * grant". There is no `signUpGrant` field to be null, empty or zero, so a
+ * consumer cannot render a grant that was never made. The founder allocation is
+ * not described here either. It is the wallet's balance, read like any other
+ * balance, and not a fact about the claim.
+ *
+ * This is the answer to the founder claim, and the answer the citizenship read
+ * and the provisioning call give for the same Citizen. The provisioning call
+ * mints nothing when it gives it.
+ */
+export interface CitizenshipFounderClaimed {
+    readonly state: 'founder-claimed';
+    readonly wallet: WalletRecord;
+}
+/**
+ * Not provisioned, provisioned, or bound by a founder claim. Switch on `state`.
+ * There are three answers and a consumer's switch must handle all three.
+ */
+export type Citizenship = CitizenshipNotProvisioned | CitizenshipProvisioned | CitizenshipFounderClaimed;
+/**
+ * Why a founder claim is refused. A closed union, so a consumer renders a
+ * member instead of pattern-matching prose (CAY-0023), and every member is a
+ * wire code. The status each is answered with is recorded in CAY-0081 and
+ * served by the route. A new reason is a new member and a version bump.
+ *
+ * The gate's refusals of a credential are NOT repeated here. A bad credential, a
+ * missing scope, an unaccepted verification method and a claim credential with
+ * no founder claim reference are all refused before the claim is asked about,
+ * with the codes the gate already answers.
+ */
+export type FounderClaimRefusal = 
+/**
+ * This deployment has performed no founder genesis, so there is nothing to
+ * claim. Unconfigured, so closed.
+ */
+'founder_genesis_not_performed'
+/** The founder claim reference names no founder wallet. */
+ | 'founder_claim_reference_unknown'
+/** Another Citizen has already claimed this founder wallet. A claim is made once. */
+ | 'founder_wallet_already_claimed'
+/**
+ * The founder wallet's allocation lapsed and was forfeited to unissued. An
+ * empty founder wallet is not an allocation, and claiming it would leave a
+ * founder with neither an allocation nor a sign-up grant.
+ *
+ * In the union from its first version although nothing produces it yet: the
+ * lapse is built last (CAY-0081, open decision 6). A consumer renders it now
+ * rather than meeting it later as a change to a closed union.
+ */
+ | 'founder_wallet_lapsed'
+/**
+ * The caller is already bound to another wallet, provisioned ordinarily or
+ * claimed through another founder wallet. A Citizen holds one Citizen Wallet.
+ */
+ | 'citizen_already_holds_a_wallet';
+/**
+ * The answer to both citizenship routes: the current terms, and whether this
+ * citizen has been provisioned.
+ *
+ * `terms` is present either way on purpose. A consumer showing a citizen what
+ * provisioning would give them needs the figures BEFORE provisioning, and a
+ * consumer showing what a past provisioning gave them reads
+ * {@link SignUpGrant.cents} — the two can differ, because terms are today's
+ * configuration and a grant is a historical fact.
+ */
+export interface CitizenshipView {
+    readonly terms: SignUpGrantTerms;
+    readonly citizenship: Citizenship;
+}

package/dist/citizenship.js

@@ -0,0 +1,26 @@
+/*
+ * 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 wire code a read refuses with when the citizen it names has not been
+ * provisioned — a value, so a consumer can compare against the contract's own
+ * string rather than retyping ours.
+ *
+ * `cayso.wallet`'s read answers this, with no wallet and no balance, for a
+ * citizen who has never been provisioned. It is deliberately the same spelling
+ * Piper already uses for the same state: one word for one condition across the
+ * two pillars, rather than two that have to be mapped.
+ */
+export const NOT_PROVISIONED = 'not_provisioned';

package/dist/client.d.ts

@@ -0,0 +1,288 @@
+/**
+ * `@percayso-community/cayso-contracts/client` — the thin client (CAY-0026).
+ *
+ * This ships from a *separate* entry point so a consumer wanting nothing but the
+ * types (`@percayso-community/cayso-contracts`) takes on no runtime at all. The barrel reaches none
+ * of this file; a test on the built output is what enforces that, not this
+ * comment (CAY-0026: the client is on its own subpath for exactly this reason).
+ *
+ * The point of the client is to make the correct call the *easy* call: it owns
+ * the fetch, the `Authorization: Bearer <assertion>` header and the idempotent
+ * retry once, so a consumer does not own each of them badly. Piper's tree is the
+ * cautionary tale — 22 hand-rolled `lib/*Api.ts` modules, one of which redeclares
+ * the wallet shape and loses its guarantee.
+ *
+ * ## The assertion is fetched per request, never cached
+ *
+ * `getAssertion()` is called *inside* each network attempt, never once at
+ * construction and never into a variable that outlives the call. An assertion is
+ * short-lived (60–120 seconds; see `assertion.ts`), so a credential fetched once
+ * and reused is a bug that only surfaces under load — which is to say in
+ * production, on the money path (CAY-0021: the assertion is verified per request
+ * and never cached; the caller must mint it per request in kind). A *retried*
+ * request re-fetches for the same reason: a backoff can outlast the credential,
+ * so each attempt gets a fresh one. That the retry re-fetches is a decision, not
+ * an accident.
+ *
+ * ## One method per route, no method that is not
+ *
+ * Every method reads its method and path from `ROUTES` — no URL is hand-written
+ * here. `ROUTES` exists precisely so that no consumer hand-writes one, and a
+ * client that hand-wrote them would be the first consumer to break the rule.
+ *
+ * ## The retry rule, and only this rule
+ *
+ * Retry only a request that is safe to repeat — a `GET`, or a `POST` *carrying an
+ * idempotency key* (that key is the whole reason a purchase is safe to send
+ * twice; CAY-0023) — and only on 429, 502, 503, 504 and a network failure. Three
+ * attempts, exponential backoff, honouring `Retry-After`. A 4xx that is not 429
+ * is *never* retried: retry a declined card and it becomes a fraud signal; fail
+ * to retry a flaky network and somebody's purchase is lost.
+ *
+ * `Retry-After` is honoured in both forms the header takes: an integer count of
+ * seconds, and an HTTP-date. A value in neither form is ignored and the computed
+ * backoff is used instead.
+ *
+ * ## What this file is not
+ *
+ * Transport, not a cache. The client holds no wallet, no balance, no purchase, no
+ * assertion and no ETag; `createCaysoClient` hands back an object closing over the
+ * options and nothing else. It never converts, rounds, formats or divides a money
+ * amount — amounts pass through untouched (CLAUDE.md: integer cents, always). And
+ * it declares no dependency — `fetch` is global on Node 26, and if you find
+ * yourself wanting a retry library you have found the part of this slice that is
+ * the point.
+ *
+ * ## The one line it logs, and why it is safe
+ *
+ * The client is otherwise silent — a debug line printing an `Authorization` header
+ * is a credential in a log aggregator, and there is none here. It makes exactly one
+ * exception: {@link CaysoClient.getVersion} warns, ONCE per client instance, when
+ * the server reports a contract version whose MAJOR differs from the one this client
+ * was built against ({@link CONTRACT_VERSION}). A different major is a
+ * backwards-incompatible surface, and a consumer that never hears about it debugs
+ * shape mismatches blind — so this is the one thing worth a line. The line carries
+ * ONLY version strings (the server's and this client's); it never touches the
+ * assertion, a header, a wallet id or any identity. It is routed through an
+ * injectable `warn` (default `console.warn`) so a consumer can capture it and a test
+ * can prove both what it says and that it says it once — never per request.
+ */
+import type { BuyBackMade, BuyBackRequest, CitizenMarketViewed, QuotePlaced, QuoteRequest, QuoteWithdrawalRequest, QuoteWithdrawn } from './citizen-market.js';
+import type { CitizenshipFounderClaimed, CitizenshipView } from './citizenship.js';
+import type { CommercialPaymentMade, CommercialPaymentRequest } from './commercial-payment.js';
+import type { OrganisationView } from './organisation.js';
+import type { PurchaseAuthorised, PurchaseCancelled, PurchaseRequest, PurchaseResult, PurchaseTerminal } from './purchase.js';
+import type { WalletView } from './wallet.js';
+/**
+ * The version surface `GET /api/version` answers (slice 29). Four fields, each
+ * from ONE source on the server: the `contractVersion` this deployment publishes,
+ * the `supportedContractVersions` it will still speak (the negotiation set), the
+ * `schemaVersion` of its database (the migration runner's own number) and the
+ * `commit` it was built from — `'unknown'`, honestly, when the build did not stamp
+ * one. It carries no wallet, no balance and no economic number; a version endpoint
+ * reports versions.
+ */
+export interface CaysoVersion {
+    readonly contractVersion: string;
+    readonly supportedContractVersions: readonly string[];
+    readonly schemaVersion: number;
+    readonly commit: string;
+}
+export interface CaysoClientOptions {
+    readonly baseUrl: string;
+    /** Called before every request. Assertions are short-lived, so never cache one. */
+    getAssertion(): Promise<string>;
+    /** Injectable for tests. Defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+    /**
+     * Where a contract-version-skew warning goes. Defaults to `console.warn`. This is
+     * the ONLY thing the client ever logs, it fires at most ONCE per client instance,
+     * and its message is version strings alone — never an assertion, a header, a
+     * wallet id or any identity (see the file docblock). Injected so a consumer can
+     * route it and a test can capture it.
+     */
+    warn?: (message: string) => void;
+}
+/**
+ * One method per entry in `ROUTES`, and no method that is not. `getMyWallet`
+ * answers `null` where the contract says a wallet may not exist yet, rather than
+ * throwing.
+ */
+export interface CaysoClient {
+    getMyWallet(): Promise<WalletView | null>;
+    /**
+     * Whether the caller has been provisioned, and on what terms. Reads only —
+     * calling this provisions nobody, which is the whole reason it is a separate
+     * route from {@link provisionCitizenship} (CAY-0031).
+     */
+    getMyCitizenship(): Promise<CitizenshipView>;
+    /**
+     * Provision the caller: a wallet and its sign-up grant, committed together.
+     *
+     * IDEMPOTENT BY THE CALLER'S OWN IDENTITY, so it carries no idempotency key.
+     * The key a purchase needs exists because two purchases by one citizen are a
+     * legitimate thing to want and only the key tells them apart; two provisionings
+     * of one citizen are the same act by definition, and the schema makes the second
+     * one a no-op that answers with the first one's result. Calling it twice is
+     * safe, and so is retrying it.
+     */
+    provisionCitizenship(): Promise<CitizenshipView>;
+    /**
+     * Claim the founder wallet the caller's assertion names, and answer the wallet
+     * record (CAY-0081).
+     *
+     * IT TAKES NO ARGUMENT, for {@link provisionOrganisation}'s reason. The founder
+     * wallet is named by the founder claim reference, which travels inside the signed
+     * assertion and nowhere else; a reference passed beside the credential would be
+     * the caller's claim about which allocation is theirs (CAY-0021).
+     *
+     * IDEMPOTENT BY THE CALLER'S OWN IDENTITY, like {@link provisionCitizenship}: the
+     * Citizen who already claimed the wallet gets the same answer and nothing is
+     * written. So it carries no idempotency key and a retry is safe. Each attempt
+     * fetches a fresh assertion, which is what a single-use `jti` needs.
+     *
+     * The answer is `founder-claimed` alone, with no `terms` beside it. A founder is
+     * never offered a sign-up grant, so the grant's terms are not part of the answer.
+     * A refusal arrives as a thrown {@link CaysoApiError} whose `code` is a
+     * `FounderClaimRefusal` member, or one of the gate's codes.
+     */
+    claimFounderWallet(): Promise<CitizenshipFounderClaimed>;
+    /**
+     * Provision the ORGANISATION the caller's assertion attests authority for, and
+     * answer its wallet (CAY-0059).
+     *
+     * IT TAKES NO ARGUMENT, AND THAT IS THE DECISION RATHER THAN AN OVERSIGHT. The
+     * Organisation ID is read from the organisation-authority claim on the verified
+     * assertion and from nowhere else — so there is no value a caller could pass
+     * that would reach the holder key, and a signature here naming an organisation
+     * would be the wallet-creation oracle CAY-0057 describes.
+     *
+     * IDEMPOTENT on the attested Organisation ID, exactly as
+     * {@link provisionCitizenship} is idempotent on the caller's own identity, so it
+     * carries no idempotency key and a repeat is the same act rather than a second
+     * one. A credential carrying no organisation authority is refused; absence
+     * provisions nothing.
+     */
+    provisionOrganisation(): Promise<OrganisationView>;
+    /**
+     * Authorise a purchase — or REPLAY one (CAY-0032). Posting the same
+     * `idempotencyKey` twice returns the ORIGINAL authorisation, at the original
+     * price, with a freshly minted client secret; the purchase is never minted twice
+     * and there is no second hold at the payment gateway. Resume IS this call, which
+     * is why there is no `resumePurchase` beside it.
+     *
+     * The answer is the contract's declared union, MINUS its refused branch: a
+     * refusal arrives as a non-2xx and this client turns every non-2xx into a thrown
+     * {@link CaysoApiError} whose `code` is that branch's `error` — one closed reason,
+     * reached through the mechanism a consumer already handles. So a caller switches
+     * on `outcome` over the two branches it can be handed, and catches for the third.
+     *
+     * `'terminal'` means the key's purchase has finished and will not change: a
+     * repeat of it will keep answering `'terminal'` forever, and the remedy is a new
+     * purchase under a NEW key.
+     */
+    authorisePurchase(req: PurchaseRequest): Promise<PurchaseAuthorised | PurchaseTerminal>;
+    getPurchase(purchaseId: string): Promise<PurchaseResult>;
+    /**
+     * Cancel a purchase the caller started, releasing its reservation (CAY-0032).
+     *
+     * IDEMPOTENT: cancelling an already-cancelled purchase answers the same
+     * {@link PurchaseCancelled} and is not an error, so a retry after a dropped
+     * connection is safe and carries no key of its own — the purchase id IS the key.
+     * A purchase that has already reached a terminal status is REFUSED, and the
+     * refusal arrives as a thrown {@link CaysoApiError} whose `code` is the closed
+     * {@link import('./purchase.js').PurchaseCancelRefusalReason}; a succeeded purchase can never be
+     * cancelled, because undoing an issued and captured purchase is a refund and
+     * that is a different act.
+     */
+    cancelPurchase(purchaseId: string): Promise<PurchaseCancelled>;
+    /**
+     * Pay a Citizen from an Organisation Wallet — or REPLAY a payment already made
+     * under the same key (CAY-0079).
+     *
+     * A replay with the same key, payee and cents answers the movement already
+     * written, in the same shape, so a retry after a dropped connection is safe and
+     * never moves cents twice. The same key with a different payee or a different
+     * number of cents is refused, never answered at either.
+     *
+     * The answer is {@link CommercialPaymentMade} alone. A refusal arrives as a
+     * thrown {@link CaysoApiError} whose `code` is a `CommercialPaymentRefusal`
+     * member, one of the gate's codes, or a seam code, as {@link authorisePurchase}'s
+     * refusals do. A refusal means nothing moved.
+     */
+    makeCommercialPayment(req: CommercialPaymentRequest): Promise<CommercialPaymentMade>;
+    /**
+     * Read the citizen market as the caller sees it (CAY-0080 §1.4): the published
+     * value and its band, both bounds per quote unit, the best bid and the best ask with
+     * their sizes, and the caller's own quotes. No match price and no history. Reading
+     * writes nothing. A refusal arrives as a thrown {@link CaysoApiError} whose `code`
+     * is a `CitizenMarketViewRefusal` member or a seam code.
+     */
+    getCitizenMarket(): Promise<CitizenMarketViewed>;
+    /**
+     * Place a quote — or REPLAY one already placed under the same key (CAY-0080 §1).
+     *
+     * A replay with the same key, side, price and size answers the quote already
+     * placed, in the same shape, so a retry after a dropped connection never places
+     * two. The answer says the quote was accepted and nothing about fills: what has
+     * matched is on {@link getCitizenMarket}, among the caller's own quotes. A refusal
+     * arrives as a thrown {@link CaysoApiError} whose `code` is a
+     * `QuotePlacementRefusal` member, one of the gate's codes, or a seam code, and
+     * means nothing was written.
+     */
+    placeQuote(req: QuoteRequest): Promise<QuotePlaced>;
+    /**
+     * Withdraw one of the caller's resting quotes, after its minimum resting time.
+     *
+     * IDEMPOTENT: withdrawing a quote the caller already withdrew answers the same
+     * {@link QuoteWithdrawn}, so a retry carries no key of its own — the quote id IS
+     * the key. A refusal arrives as a thrown {@link CaysoApiError} whose `code` is a
+     * `QuoteWithdrawalRefusal` member, and the quote rests as it was.
+     */
+    withdrawQuote(req: QuoteWithdrawalRequest): Promise<QuoteWithdrawn>;
+    /**
+     * Ask the Treasury to buy back unrestricted cents at the floor reference, in whole
+     * quote units — or REPLAY a buy-back already made under the same key (CAY-0080 §2.2).
+     *
+     * A replay with the same key and size answers the buy-back already made, in the same
+     * shape, so a retry after a dropped connection never sells twice. The same key with
+     * a different size is refused. A refusal arrives as a thrown {@link CaysoApiError}
+     * whose `code` is a `BuyBackRefusal` member, one of the gate's codes, or a seam code,
+     * and means nothing moved and nothing is paid.
+     */
+    requestBuyBack(req: BuyBackRequest): Promise<BuyBackMade>;
+    getVersion(): Promise<CaysoVersion>;
+}
+/**
+ * Raised for any non-2xx response and any network failure. `code` is parsed from
+ * the body's `{ error, message }`, falling back to `'request_failed'` when the
+ * body is absent, empty, unparseable or the wrong shape — the client never throws
+ * a `SyntaxError` out at a consumer. Exported as a value, extending `Error` with
+ * a fixed prototype and name, so `instanceof CaysoApiError` holds for a consumer.
+ */
+export declare class CaysoApiError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly detail?: string;
+    constructor(code: string, status: number, detail?: string);
+}
+/**
+ * The injectable timing seam, kept deliberately *off* `CaysoClientOptions` — the
+ * public options are `baseUrl`, `getAssertion` and `fetchImpl` and nothing more.
+ * The suite drives the backoff schedule through this without sleeping for real; a
+ * test suite that slept for real is a test suite people stop running.
+ */
+interface CaysoClientInternals {
+    sleep(ms: number): Promise<void>;
+}
+export declare function createCaysoClient(options: CaysoClientOptions): CaysoClient;
+/**
+ * The construction seam the test suite uses to inject `sleep`. Not part of the
+ * supported client surface — a consumer calls {@link createCaysoClient}. It lives
+ * here rather than on the public options type so the timing stays untestable-by-
+ * accident for a consumer and fully testable for the suite.
+ *
+ * @internal
+ */
+export declare function createCaysoClientWithInternals(options: CaysoClientOptions, internals: CaysoClientInternals): CaysoClient;
+export {};