@percayso-community/cayso-contracts 0.23.0

package/dist/client.js

@@ -0,0 +1,370 @@
+/*
+ * 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.
+ */
+import { CONTRACT_VERSION, NOT_PROVISIONED } from './index.js';
+import { ROUTES } from './routes.js';
+// --- The retry mechanism -----------------------------------------------------
+// These are this slice's own mechanism, not economics: an attempt count, a
+// backoff base and the set of retryable statuses. No amount, rate, tier,
+// schedule or threshold lives here (CLAUDE.md, "No numbers").
+/** Total attempts, the first included. Three means three — never four. */
+const MAX_ATTEMPTS = 3;
+/** Base backoff in milliseconds; the wait doubles with each spent attempt. */
+const BACKOFF_BASE_MS = 100;
+/** The statuses a *safe* request retries on. Everything else fails fast. */
+const RETRYABLE_STATUS = new Set([429, 502, 503, 504]);
+/**
+ * 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 class CaysoApiError extends Error {
+    code;
+    status;
+    detail;
+    constructor(code, status, detail) {
+        super(detail ?? code);
+        // A class extending a built-in loses `instanceof` once compiled down unless
+        // the prototype is restored and the name set explicitly.
+        this.name = 'CaysoApiError';
+        this.code = code;
+        this.status = status;
+        this.detail = detail;
+        Object.setPrototypeOf(this, CaysoApiError.prototype);
+    }
+}
+const realSleep = (ms) => new Promise((resolve) => {
+    setTimeout(resolve, ms);
+});
+export function createCaysoClient(options) {
+    return buildClient(options, { sleep: realSleep });
+}
+/**
+ * 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 function createCaysoClientWithInternals(options, internals) {
+    return buildClient(options, internals);
+}
+function buildClient(options, internals) {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const { sleep } = internals;
+    const base = options.baseUrl.replace(/\/+$/, '');
+    const warn = options.warn ?? ((message) => console.warn(message));
+    // "Once" is scoped to THIS client instance: the flag is closed over here, not held
+    // in a module-level variable, so two clients warn independently and a test can prove
+    // the scope by constructing two. It never resets — a warning is a one-time nudge to
+    // upgrade, not a per-request alarm that would bury the money path in noise.
+    let versionSkewWarned = false;
+    /**
+     * Warn at most once, and only when the server's contract MAJOR differs from this
+     * client's. A missing or unparseable version on either side is not a skew we can
+     * assert, so it stays silent rather than crying wolf. Only version strings reach
+     * the log line — never a credential.
+     */
+    function warnOnVersionSkew(serverContractVersion) {
+        if (versionSkewWarned)
+            return;
+        const localMajor = majorOf(CONTRACT_VERSION);
+        const serverMajor = majorOf(serverContractVersion);
+        if (localMajor === null || serverMajor === null || localMajor === serverMajor)
+            return;
+        versionSkewWarned = true;
+        warn(`@percayso-community/cayso-contracts: the server publishes contract version ${serverContractVersion} ` +
+            `(major ${serverMajor}) but this client was built against ${CONTRACT_VERSION} ` +
+            `(major ${localMajor}); upgrade @percayso-community/cayso-contracts to match the server's major.`);
+    }
+    async function send(spec) {
+        let attempt = 0;
+        for (;;) {
+            attempt += 1;
+            // Per attempt, never cached: a short-lived credential must not outlive the
+            // backoff it was minted before (CAY-0021).
+            const assertion = await options.getAssertion();
+            const headers = {
+                Authorization: `Bearer ${assertion}`,
+                Accept: 'application/json',
+            };
+            if (spec.body !== undefined)
+                headers['Content-Type'] = 'application/json';
+            // The key travels to the server so a redelivered request is deduplicated
+            // there rather than minting twice (CAY-0023).
+            if (spec.idempotencyKey !== undefined && spec.idempotencyKey.length > 0) {
+                headers['Idempotency-Key'] = spec.idempotencyKey;
+            }
+            const init = { method: spec.method, headers };
+            if (spec.body !== undefined)
+                init.body = JSON.stringify(spec.body);
+            let response;
+            try {
+                response = await fetchImpl(`${base}${spec.path}`, init);
+            }
+            catch (cause) {
+                if (spec.idempotent && attempt < MAX_ATTEMPTS) {
+                    await sleep(backoffFor(attempt));
+                    continue;
+                }
+                throw new CaysoApiError('request_failed', 0, networkDetail(cause));
+            }
+            if (response.ok)
+                return response;
+            if (spec.idempotent && RETRYABLE_STATUS.has(response.status) && attempt < MAX_ATTEMPTS) {
+                const retryAfter = parseRetryAfter(response.headers.get('retry-after'));
+                await sleep(retryAfter ?? backoffFor(attempt));
+                continue;
+            }
+            throw await errorFrom(response);
+        }
+    }
+    async function requestJson(spec) {
+        const response = await send(spec);
+        return (await readJson(response));
+    }
+    return {
+        async getMyWallet() {
+            try {
+                const view = await requestJson({
+                    method: ROUTES.wallet.method,
+                    path: ROUTES.wallet.path,
+                    idempotent: true,
+                });
+                // A wallet that does not exist yet is `null`, not an error.
+                return view ?? null;
+            }
+            catch (error) {
+                // An UNPROVISIONED citizen has no wallet, and since CAY-0031 reading does
+                // not create one — the server answers 404 with the closed `not_provisioned`
+                // code. `null` is the honest translation: there is no wallet to hand back.
+                // A consumer that needs to know WHY there is none calls
+                // {@link CaysoClient.getMyCitizenship}, which distinguishes the states; this
+                // method's contract is `WalletView | null` and it keeps it.
+                if (error instanceof CaysoApiError && error.status === 404)
+                    return null;
+                if (error instanceof CaysoApiError && error.code === NOT_PROVISIONED)
+                    return null;
+                throw error;
+            }
+        },
+        async getMyCitizenship() {
+            return requestJson({
+                method: ROUTES.citizenship.method,
+                path: ROUTES.citizenship.path,
+                idempotent: true,
+            });
+        },
+        async provisionCitizenship() {
+            return requestJson({
+                method: ROUTES.citizenshipProvision.method,
+                path: ROUTES.citizenshipProvision.path,
+                // Safe to retry with no key, unlike a purchase: the operation is
+                // idempotent on the caller's own identity, so a repeat is the same act
+                // rather than a second one (see the interface docblock).
+                idempotent: true,
+            });
+        },
+        async claimFounderWallet() {
+            return requestJson({
+                method: ROUTES.citizenshipFounderClaim.method,
+                path: ROUTES.citizenshipFounderClaim.path,
+                // Safe to retry with no key, for provisioning's reason: the claim is
+                // idempotent on the caller's own identity, and each attempt mints a fresh
+                // assertion, so the single-use `jti` is never presented twice.
+                idempotent: true,
+            });
+        },
+        async provisionOrganisation() {
+            return requestJson({
+                method: ROUTES.organisationProvision.method,
+                path: ROUTES.organisationProvision.path,
+                // Safe to retry with no key, for the same reason provisioning a citizen
+                // is: the operation is idempotent on the attested Organisation ID, so a
+                // repeat is the same act rather than a second one.
+                idempotent: true,
+            });
+        },
+        async authorisePurchase(req) {
+            return requestJson({
+                method: ROUTES.purchaseAuthorise.method,
+                path: ROUTES.purchaseAuthorise.path,
+                // A POST is safe to repeat only because of the key it carries.
+                idempotent: typeof req.idempotencyKey === 'string' && req.idempotencyKey.length > 0,
+                body: req,
+                idempotencyKey: req.idempotencyKey,
+            });
+        },
+        async makeCommercialPayment(req) {
+            return requestJson({
+                method: ROUTES.commercialPayment.method,
+                path: ROUTES.commercialPayment.path,
+                // A POST is safe to repeat only because of the key it carries: a repeat
+                // under the same key replays the payment rather than making a second one.
+                idempotent: typeof req.idempotencyKey === 'string' && req.idempotencyKey.length > 0,
+                body: req,
+                idempotencyKey: req.idempotencyKey,
+            });
+        },
+        async getCitizenMarket() {
+            return requestJson({
+                method: ROUTES.citizenMarket.method,
+                path: ROUTES.citizenMarket.path,
+                idempotent: true,
+            });
+        },
+        async placeQuote(req) {
+            return requestJson({
+                method: ROUTES.placeQuote.method,
+                path: ROUTES.placeQuote.path,
+                // A POST is safe to repeat only because of the key it carries: a repeat
+                // under the same key replays the quote rather than placing a second one.
+                idempotent: typeof req.idempotencyKey === 'string' && req.idempotencyKey.length > 0,
+                body: req,
+                idempotencyKey: req.idempotencyKey,
+            });
+        },
+        async withdrawQuote(req) {
+            return requestJson({
+                method: ROUTES.withdrawQuote.method,
+                path: ROUTES.withdrawQuote.path,
+                // Safe to repeat with no key of its own: the quote id names the one thing
+                // withdrawn, and withdrawing it again is the same answer, not a second act.
+                idempotent: true,
+                body: req,
+            });
+        },
+        async requestBuyBack(req) {
+            return requestJson({
+                method: ROUTES.requestBuyBack.method,
+                path: ROUTES.requestBuyBack.path,
+                // A POST is safe to repeat only because of the key it carries: a repeat
+                // under the same key replays the buy-back rather than selling twice.
+                idempotent: typeof req.idempotencyKey === 'string' && req.idempotencyKey.length > 0,
+                body: req,
+                idempotencyKey: req.idempotencyKey,
+            });
+        },
+        async getPurchase(purchaseId) {
+            return requestJson({
+                method: ROUTES.purchaseResult.method,
+                path: fillPath(ROUTES.purchaseResult.path, { purchaseId }),
+                idempotent: true,
+            });
+        },
+        async cancelPurchase(purchaseId) {
+            return requestJson({
+                method: ROUTES.purchaseCancel.method,
+                path: fillPath(ROUTES.purchaseCancel.path, { purchaseId }),
+                // A POST, and safe to repeat with NO idempotency key — unlike authorising.
+                // The purchase id names the one thing being cancelled, and cancelling an
+                // already-cancelled purchase is the same answer rather than a second act,
+                // so a retried cancel cannot produce two of anything.
+                idempotent: true,
+            });
+        },
+        async getVersion() {
+            const version = await requestJson({
+                method: ROUTES.version.method,
+                path: ROUTES.version.path,
+                idempotent: true,
+            });
+            // The one line this client logs — at most once per instance, version strings
+            // only. A different major means the server's surface is not this package's.
+            warnOnVersionSkew(version.contractVersion);
+            return version;
+        },
+    };
+}
+// --- Helpers -----------------------------------------------------------------
+/** Substitute `:param` segments in a route path from `ROUTES`. */
+function fillPath(path, params) {
+    let out = path;
+    for (const [name, value] of Object.entries(params)) {
+        out = out.replace(`:${name}`, encodeURIComponent(value));
+    }
+    return out;
+}
+/** Exponential backoff for a spent attempt (1-based): base, then base·2, … */
+function backoffFor(attempt) {
+    return BACKOFF_BASE_MS * 2 ** (attempt - 1);
+}
+/**
+ * The major component of a `MAJOR.minor.patch` version, or `null` when the string
+ * is absent or does not begin with a run of digits. `null` means "cannot tell", and
+ * the skew check stays silent on it rather than guessing — an unparseable version is
+ * not evidence of a mismatch.
+ */
+function majorOf(version) {
+    if (version === undefined)
+        return null;
+    const first = version.split('.')[0];
+    if (first === undefined || !/^\d+$/.test(first))
+        return null;
+    return Number(first);
+}
+/**
+ * `Retry-After` in milliseconds, or `null` when absent or unrecognised. Both
+ * documented forms are handled: an integer count of seconds, and an HTTP-date.
+ */
+function parseRetryAfter(value) {
+    if (value === null)
+        return null;
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        return null;
+    if (/^\d+$/.test(trimmed))
+        return Number(trimmed) * 1000;
+    const when = Date.parse(trimmed);
+    if (Number.isNaN(when))
+        return null;
+    return Math.max(0, when - Date.now());
+}
+/**
+ * The response body as JSON, or `undefined` when it is empty or unparseable. A
+ * malformed body never throws a `SyntaxError` out of the client.
+ */
+async function readJson(response) {
+    const text = await response.text();
+    if (text.trim().length === 0)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A `CaysoApiError` built from a non-2xx response's `{ error, message }` body. */
+async function errorFrom(response) {
+    const body = await readJson(response);
+    let code = 'request_failed';
+    let detail;
+    if (typeof body === 'object' && body !== null) {
+        const record = body;
+        if (typeof record.error === 'string' && record.error.length > 0)
+            code = record.error;
+        if (typeof record.message === 'string')
+            detail = record.message;
+    }
+    return new CaysoApiError(code, response.status, detail);
+}
+/** A human-readable note for a network failure — never a credential. */
+function networkDetail(cause) {
+    return cause instanceof Error ? cause.message : undefined;
+}

package/dist/commercial-payment.d.ts

@@ -0,0 +1,243 @@
+/**
+ * `commercial-payment` — the request, the answer and the closed refusal union for
+ * an Organisation paying a Citizen (CAY-0079).
+ *
+ * A commercial payment is cents moving directly from an Organisation Wallet to a
+ * Citizen Wallet, for work done or a service supplied. It is not "P2P" and it is
+ * not the citizen market. The Treasury takes no part in it (CONTEXT.md, Commercial
+ * payment). This file is the Piper-facing half of CAY-0079's slices 2 and 3: the
+ * shapes a consumer sends and decodes. It is served at `ROUTES.commercialPayment`
+ * (CAY-0079 slice 6) on both routes: the mandate route first, and the Authorised-User
+ * route second (Open decision H, #284).
+ *
+ * ## One movement or nothing, so there is no status
+ *
+ * A Purchase has a lifecycle because sterling crosses the boundary and a provider
+ * can fail after authorising (CAY-0023). A commercial payment has no sterling leg
+ * and no provider, so there is nothing to authorise first and capture later
+ * (CAY-0079 §5). The answer is one of two things: a {@link CommercialPaymentMade},
+ * carrying the one movement that was written, final and append-only, or a
+ * {@link CommercialPaymentRefused}, carrying one reason and meaning nothing was
+ * written. **"Failed" means nothing moved.** There is no pending, failed or
+ * reversed payment on this surface, and nothing on these shapes can express one.
+ *
+ * ## Replay under one key
+ *
+ * The idempotency key is unique together with the paying wallet (CAY-0079 §5). A
+ * repeat with the same key, the same payee and the same cents answers the movement
+ * already written, in the same shape as the first answer, so a caller that lost
+ * the answer can ask again safely. A repeat with the same key and anything
+ * different is refused with `idempotency_key_reused_for_a_different_payment`. The
+ * two amounts cannot both be what the caller asked for, so the request is refused
+ * rather than answered at either.
+ *
+ * A refund is a NEW payment in the other direction, under the other party's
+ * authority and its own key. It is never a reversal of this one.
+ *
+ * ## The authority is declared by the caller and checked, never inferred
+ *
+ * A commercial payment is made by one of two parties and nobody else (CAY-0079
+ * §1): a mandate holder acting as the organisation, or an Authorised User under a
+ * payment allowance. The request says which with {@link
+ * CommercialPaymentRequest.authority}, and the service checks that route and only
+ * that route.
+ *
+ * It is declared rather than worked out from what the credential happens to carry
+ * for two reasons. The refusal set names each route's own failures, and
+ * `mandate_claim_absent` only means something when the mandate route was asked
+ * for. And falling back from one route to the other would let a failed mandate
+ * check become a draw against somebody's allowance limit. The movement would then
+ * be recorded under an authority the caller never invoked.
+ *
+ * Declaring the route is not a claim about who the caller is. Who they are comes
+ * from the verified assertion's subject (CAY-0021), and whether they may act for
+ * the paying wallet comes from the mandate claim or the allowance record. The
+ * field only chooses which of those two is checked.
+ *
+ * The Authorised-User route shipped after the mandate route (CAY-0079, Open decision
+ * H). Both were on the contract from the first version, so the refusal union did not
+ * grow for the second. A refusal on either route is answered as that route's, and is
+ * never tried on the other instead.
+ *
+ * ## The payee is a wallet id, never a Percayso identity
+ *
+ * A Citizen gives the organisation their wallet id, as they would give a delivery
+ * address (CAY-0079 §3). A request that named the payee by identity would turn the
+ * operator-facing handle into a directory of identities, and give anyone holding a
+ * mandate an identity oracle. So the request carries two wallet ids, and the
+ * acting party is resolved from the assertion's subject and then discarded. The
+ * answer echoes nothing about the person who acted.
+ *
+ * ## What this file must not decide
+ *
+ *   - **This direction only.** Organisation to Citizen. A Citizen paying an
+ *     Organisation shares the classification (CAY-0079 §4.3) and is not this
+ *     operation. Organisation to organisation is not proposed at all.
+ *   - **One payee.** A split between several payees is not designed (CAY-0079 §6).
+ *     Rounding, refunds of a split, tax and who sets a split are all open, so
+ *     nothing here has a list of payees.
+ *   - **No figures.** The Signatory / Authorised-User threshold lives in the canon
+ *     PRD and reaches the service as configuration. An unset threshold closes the
+ *     Authorised-User route and is a refusal, never "no limit". No amount, rate,
+ *     tier or threshold is restated here.
+ *   - **No excluded-payee reason yet.** Exclusion is decided outside this economy
+ *     and no signal of it reaches Cayso. A named case nothing can raise would be a
+ *     dormant code path, so `payee_excluded` joins the union in the slice that
+ *     delivers the signal (CAY-0079, Open decision F) and not before.
+ *   - **No unconfigured adapter.** A verifier, holders mapping or database that is
+ *     not configured refuses the REQUEST with the refusal envelope's own seam code
+ *     (`errors.ts`), not the payment. It is not a member of this union.
+ */
+import type { Cents, Millis } from './wallet.js';
+/**
+ * Which of the two authorities the caller invokes to pay from the Organisation
+ * Wallet (CAY-0079 §1).
+ *
+ *   - `'mandate'` — the caller holds the mandate for the paying wallet and acts as
+ *     the organisation. Checked against the verified assertion's mandate claim
+ *     (`AssertionClaims.mandateFor`), which Cayso accepts as Percayso ID's
+ *     attestation and never checks against a register of its own (CAY-0068).
+ *   - `'payment-allowance'` — the caller is the Authorised User named on a live
+ *     allowance over the paying wallet, and that allowance was granted for payment.
+ *     An allowance granted for spending does not convey payment and is never read
+ *     as if it did.
+ */
+export type CommercialPaymentAuthority = 'mandate' | 'payment-allowance';
+/** An Organisation paying one Citizen, in cents, under one key. */
+export interface CommercialPaymentRequest {
+    /** The route the caller invokes. Checked, and never swapped for the other on a refusal. */
+    readonly authority: CommercialPaymentAuthority;
+    /** The Organisation Wallet the cents leave. */
+    readonly payingWalletId: string;
+    /** The Citizen Wallet the cents arrive in. A wallet id, never a Percayso identity. */
+    readonly payeeWalletId: string;
+    /** Whole cents, above zero. Anything else is refused `amount_not_positive_whole_cents`. */
+    readonly cents: Cents;
+    /** Caller-generated, unique per paying wallet. The same key never moves cents twice; a repeat REPLAYS. */
+    readonly idempotencyKey: string;
+}
+/**
+ * The one movement a commercial payment wrote. Final and append-only: there is no
+ * second one, and nothing amends it.
+ *
+ * It carries no acting party. The caller is the acting party and already knows
+ * who they are, and the answer is not a place to repeat an identity or the wallet
+ * it resolved to.
+ */
+export interface CommercialPayment {
+    /** The movement that carried the cents. A handle to quote back; the movement itself is not on this surface. */
+    readonly movementId: string;
+    readonly payingWalletId: string;
+    readonly payeeWalletId: string;
+    readonly cents: Cents;
+    readonly paidAt: Millis;
+}
+/**
+ * The payment was made. Answered for the request that made it and for every
+ * replay of its key, in the same shape: a replay is not a lesser answer.
+ */
+export interface CommercialPaymentMade {
+    readonly outcome: 'paid';
+    readonly payment: CommercialPayment;
+}
+/** The payment was refused, with one member of the closed union. Nothing was written. */
+export interface CommercialPaymentRefused {
+    readonly outcome: 'refused';
+    readonly error: CommercialPaymentRefusal;
+}
+/**
+ * The ONE declared answer to a commercial payment, discriminated by `outcome`. A
+ * consumer switches on `outcome` and never sniffs which fields are present, the
+ * discipline every response union on this surface follows.
+ */
+export type CommercialPaymentResponse = CommercialPaymentMade | CommercialPaymentRefused;
+/**
+ * Why a commercial payment was refused: CAY-0079 §3's set, closed, spelled here.
+ *
+ * A consumer renders a member by its name and never pattern-matches on prose. The
+ * SET was fixed by the record when it was accepted, and this contract fixes the
+ * spelling. A new reason is a new member and a contract version, never a free-text
+ * field. Every member means the same thing about money: nothing moved.
+ *
+ * Reasons for the Authorised-User route were here before that route was served
+ * (CAY-0079, Open decision H), for the reason `founder_wallet_lapsed` was published
+ * before anything produced it: a consumer exhausting this union rendered them from
+ * the first version, and the union did not grow to admit them when the route shipped.
+ */
+export type CommercialPaymentRefusal = 
+/** Mandate route: the assertion carries no mandate claim. */
+'mandate_claim_absent'
+/** Mandate route: the mandate claim does not name the paying wallet. */
+ | 'mandate_claim_does_not_cover_the_paying_wallet'
+/**
+ * Either route: the verification method is outside the money-grade assurance
+ * profile (`ASSURANCE_POLICY['make-commercial-payment']`). `dev-bypass` is never
+ * inside it.
+ */
+ | 'assurance_not_money_grade'
+/**
+ * Either route: the verified subject resolves to no wallet. The acting party on
+ * a commercial payment is always a wallet id (CAY-0079, Open decision B), and the
+ * payment never provisions one. The caller provisions their own wallet first.
+ */
+ | 'acting_party_has_no_citizen_wallet'
+/** Allowance route: no allowance was ever granted to this caller over the paying wallet. */
+ | 'no_live_allowance'
+/**
+ * Allowance route: an allowance existed and was revoked. Kept apart from
+ * `no_live_allowance` because a revoked allowance is kept, and "it was taken
+ * away" and "you never had one" are different things to tell somebody.
+ */
+ | 'allowance_revoked'
+/** Allowance route: the live allowance was granted for spending, not for payment. */
+ | 'allowance_does_not_convey_payment'
+/** Allowance route: what was already spent plus this payment would pass the allowance's limit. */
+ | 'allowance_limit_insufficient'
+/**
+ * Allowance route: the Signatory / Authorised-User threshold, converted to cents
+ * at the published value at the moment of payment, refuses it (CAY-0079, Open
+ * decision A). The allowance is left untouched.
+ */
+ | 'payment_above_authorised_user_threshold'
+/**
+ * Allowance route: the threshold is not configured. A closed door, the same one
+ * an allowance grant meets, and never "no limit". It does not close the mandate
+ * route.
+ */
+ | 'authorised_user_threshold_not_configured'
+/** Allowance route: no published value is available to convert the threshold at. The same closed door. */
+ | 'authorised_user_threshold_published_value_unavailable'
+/**
+ * The paying wallet is a Citizen Wallet or the Treasury. This operation is never
+ * citizen to citizen, and a citizen who wants to pay a citizen uses the citizen
+ * market's own controls (CAY-0079 §7).
+ */
+ | 'paying_wallet_not_an_organisations'
+/** No wallet has the payee's id. */
+ | 'payee_wallet_not_found'
+/** The payee's wallet is an Organisation Wallet or the Treasury. */
+ | 'payee_wallet_not_a_citizens'
+/** No citizen is bound to the payee's wallet now, for example because the binding was erased. */
+ | 'payee_wallet_has_no_live_binding'
+/**
+ * The caller is paying themselves. Refused on both routes, so the record of a
+ * director's remuneration always shows two people (CAY-0079, Open decision D).
+ */
+ | 'payee_is_the_acting_party'
+/** The cents are zero, negative or not a whole number. */
+ | 'amount_not_positive_whole_cents'
+/**
+ * The paying wallet's unrestricted cents are short. Restricted cents are never
+ * counted and never drawn, so a wallet holding enough only once restricted cents
+ * are included is still short (CAY-0079 §4).
+ */
+ | 'unrestricted_cents_insufficient'
+/** A holding the payment would draw is frozen. A freeze is not restriction. */
+ | 'cents_frozen'
+/** The key was already used by this paying wallet for a different payee or a different number of cents. */
+ | 'idempotency_key_reused_for_a_different_payment'
+/**
+ * Too many concurrent draws on the paying wallet, and the retries ran out.
+ * Nothing moved, and the caller may try again under the same key.
+ */
+ | 'carve_contended';

package/dist/commercial-payment.js

@@ -0,0 +1,16 @@
+/*
+ * 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.
+ */
+export {};

package/dist/contract-schema.generated.d.ts

@@ -0,0 +1,14 @@
+/**
+ * GENERATED FILE — do not edit by hand.
+ *
+ * Produced by `scripts/generate-contract-schema.ts` from the published types
+ * (`wallet.ts`, `purchase.ts`, `assertion.ts`, `citizenship.ts`, `errors.ts`)
+ * and the
+ * package's own value exports. Regenerate with `pnpm --filter @percayso-community/cayso-contracts generate-schema`.
+ *
+ * The CI contract test (`contract-schema.test.ts`) regenerates this in memory and
+ * compares: a type changed without regenerating this file turns it red, which is the
+ * whole point — the schema cannot silently drift from the types it describes.
+ */
+import type { ContractSchema } from './schema-types.js';
+export declare const CONTRACT_SCHEMA: ContractSchema;