@percayso-community/cayso-contracts 0.23.0

package/dist/errors.d.ts

@@ -0,0 +1,171 @@
+/**
+ * The refusal envelope, and the closed set of codes that may travel in it
+ * (CAY-0058 §5).
+ *
+ * Every refusal this service answers a Piper-facing request with is the same
+ * shape: a JSON object carrying one machine-readable `error` and nothing else. A
+ * consumer renders a refusal by switching on that code, which is only safe if the
+ * code set is closed and published — a union that lived privately inside `apps/api`
+ * would make every consumer either pattern-match on prose or keep a retyped copy
+ * that goes stale the first time a refusal is added.
+ *
+ * ## Why the envelope is published rather than described
+ *
+ * The rest of this package publishes the shapes of things that SUCCEED. The
+ * refusal is the other half of the same contract, and it is the half a consumer is
+ * most likely to get wrong: a wallet page that treats an unrecognised refusal as an
+ * outage, or as a success with missing fields, misleads the person reading it. So
+ * the envelope is a type here, the codes are a closed union here, and a consumer
+ * exhausting {@link CaysoApiErrorCode} is told by its own compiler when this
+ * surface grows a refusal it has not thought about.
+ *
+ * ## The codes of the internal verifier are NOT a separate vocabulary
+ *
+ * The gate that checks a credential has its own refusal codes inside
+ * `@cayso/identity`, and most of them appear here under the same spelling because
+ * they already crossed this boundary. That is a mapping and not an identity: the
+ * service holds a total map from its internal codes onto this union, so a code
+ * added privately cannot reach the wire without a decision being taken about what
+ * it is called in public. The throttle is the case that proves the map is doing
+ * work — see {@link REQUEST_RATE_LIMITED}.
+ *
+ * ## Some of these codes travel in a richer body
+ *
+ * A purchase refusal and a cancellation refusal carry a discriminant beside the
+ * code (`{ "outcome": "refused", "error": … }`) because a caller polling a purchase
+ * needs to tell a refusal from a result at the top level. Their reasons are still
+ * part of this union — it is the set of codes that cross the boundary, not the set
+ * that happen to arrive in the bare envelope — and they are included BY REFERENCE
+ * to the unions that own them, so neither can grow a member this union does not
+ * carry. The founder claim's refusals are included the same way, and so are the
+ * commercial payment's, the citizen market's, the marketplace status read's and the
+ * two marketplace settlements'.
+ */
+import type { FounderClaimRefusal } from './citizenship.js';
+import type { BuyBackRefusal, QuotePlacementRefusal, QuoteWithdrawalRefusal } from './citizen-market.js';
+import type { CommercialPaymentRefusal } from './commercial-payment.js';
+import type { MarketplaceReceiptReadRefusal } from './marketplace-receipt.js';
+import type { MarketplaceOrderRefusal, MarketplaceRefundRefusal } from './marketplace-settlement.js';
+import type { PurchaseCancelRefusalReason, PurchaseFailureReason } from './purchase.js';
+/**
+ * The single public code for a request refused by a request-rate limit, published
+ * as a value so a consumer compares a refusal against the contract's own string
+ * rather than a retyped copy of it (the reason `NOT_PROVISIONED` is a value too).
+ *
+ * It is `request_rate_limited` rather than anything naming a credential, and that
+ * is deliberate (CAY-0058 §5): the two limits that can produce it refuse at
+ * different moments — one of them before any credential has been read, and so on a
+ * request that carries none at all — and a code that named a credential would be a
+ * lie on half the refusals and a hint about the shape of the other half on the
+ * rest. One code, one body, one status, from both origins.
+ */
+export declare const REQUEST_RATE_LIMITED: "request_rate_limited";
+/**
+ * Every code that may cross this HTTP boundary in a refusal.
+ *
+ * Grouped below by what a consumer does about each: the gate's refusals mean
+ * *present a different credential*, the unconfigured-seam refusals mean *this
+ * deployment is not finished, try later*, and the operation refusals mean *this
+ * particular request cannot be served as asked*.
+ */
+export type CaysoApiErrorCode = 
+/** No credential was presented, or the header carrying it was not readable. */
+'unauthenticated'
+/** The credential did not parse, or its shape was not the declared envelope. */
+ | 'assertion_invalid'
+/** The credential is past `exp`, or outside the skew allowed around it. */
+ | 'assertion_expired'
+/** The credential names an issuer this deployment does not trust. */
+ | 'assertion_issuer_refused'
+/** The credential names a key its issuer does not publish. */
+ | 'assertion_key_refused'
+/** The credential is signed with an algorithm this gate does not accept. */
+ | 'assertion_algorithm_refused'
+/** The subject is not in the namespace this deployment serves. */
+ | 'assertion_subject_refused'
+/** This exact credential has been presented before. It is single-use. */
+ | 'assertion_replayed'
+/** The credential is valid and does not carry the scope this operation needs. */
+ | 'assertion_scope_refused'
+/** The request was refused by a request-rate limit. See {@link REQUEST_RATE_LIMITED}. */
+ | 'request_rate_limited'
+/** No verifier is configured, so no credential can be checked at all. */
+ | 'verifier_not_configured'
+/** A verifier exists and has been told about no issuer, so it trusts nobody. */
+ | 'issuer_registry_not_configured' | 'wallet_store_not_configured' | 'balance_reader_not_configured' | 'citizenship_store_not_configured'
+/** No founder claim store is wired, so no founder wallet can be claimed. */
+ | 'founder_claim_store_not_configured' | 'sign_up_grant_not_configured'
+/**
+ * No per-band grant-envelope schedule is configured, so a grant cannot be priced
+ * against the envelope its band allows. Distinct from
+ * `sign_up_grant_not_configured` on purpose: "nobody set the grant" and "no
+ * schedule to price the grant against" are different facts for an operator to
+ * read — the same distinction `allowance_ceiling_published_value_unavailable`
+ * draws for the Signatory threshold.
+ */
+ | 'sign_up_grant_envelope_policy_not_configured'
+/**
+ * The configured grant exceeds the total reward envelope the band in force
+ * allows. A policy refusal rather than a caller's mistake: the envelope tapers,
+ * so a figure approved for a lower band over-grants once a quickening has passed.
+ * It is the quickening being visible instead of silent.
+ */
+ | 'sign_up_grant_exceeds_tier_envelope' | 'purchase_store_not_configured' | 'purchase_result_reader_not_configured' | 'purchase_cancel_store_not_configured' | 'published_value_not_configured' | 'gateway_not_configured' | 'schema_version_reader_not_configured'
+/**
+ * No commercial payment store is wired, or this deployment has not been told
+ * which wallet is the Treasury. Both close the route: a payment the service
+ * could not hold to "the Treasury takes no part" is not one it may make
+ * (CAY-0079 §3).
+ */
+ | 'commercial_payment_store_not_configured'
+/**
+ * The citizen market is shut on this deployment: no store is wired, or a figure
+ * the book needs is not set in the canon and so not configured here (CAY-0080,
+ * *Figures*). An unset figure is a closed door and never "no limit", and it is
+ * not a member of the market's refusal unions, because it describes the
+ * deployment and not the quote.
+ */
+ | 'citizen_market_not_configured'
+/**
+ * The Treasury's buy-back is shut on this deployment: no buy-back store is wired,
+ * or one of the buy-back's own figures — the limit per holder, the
+ * recent-acquisition window — is not set in the canon and so not configured here
+ * (CAY-0080, *Figures*). The book may still be open. An unset limit is never "no
+ * limit".
+ */
+ | 'buy_back_not_configured'
+/**
+ * No sterling observation has ever been recorded, so there is no eligible sterling
+ * to measure the request against. It says nothing about the request, which may be
+ * retried unchanged once somebody observes. The purchase path answers it when there
+ * is no backing ceiling to measure against, and the buy-back when there is no
+ * eligible sterling to reserve from (CAY-0080).
+ */
+ | 'sterling_not_observed'
+/**
+ * This deployment holds no key it may sign a marketplace receipt with, so it
+ * cannot write a marketplace sale or refund: Store Platform grants nothing on a
+ * receipt it cannot verify, and a sale with no receipt is cents moved for nothing
+ * the buyer can use (CAY-0083 §1). Published before the marketplace checkout that
+ * answers it is served, so a consumer exhausting this union renders it from the
+ * start.
+ */
+ | 'receipt_signing_not_configured'
+/** The request body or parameters did not satisfy the declared schema. */
+ | 'invalid_request'
+/** There is no such purchase under this caller's wallet. */
+ | 'not_found'
+/** Something failed on the way and the refusal discloses nothing further. */
+ | 'internal_error' | PurchaseFailureReason | PurchaseCancelRefusalReason | FounderClaimRefusal | CommercialPaymentRefusal | QuotePlacementRefusal | QuoteWithdrawalRefusal | BuyBackRefusal | MarketplaceReceiptReadRefusal | MarketplaceOrderRefusal | MarketplaceRefundRefusal;
+/**
+ * The body of every refusal on this surface: one code, and nothing beside it.
+ *
+ * Nothing else is in this shape on purpose. A refusal that carried a message would
+ * invite a consumer to render prose it does not control and cannot translate; a
+ * refusal that carried counts, windows or a moment to try again would describe the
+ * control that produced it to whoever was probing it. The code is the whole of the
+ * contract, and the service answers exactly this object.
+ */
+export interface CaysoErrorResponse {
+    readonly error: CaysoApiErrorCode;
+}

package/dist/errors.js

@@ -0,0 +1,28 @@
+/*
+ * 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 single public code for a request refused by a request-rate limit, published
+ * as a value so a consumer compares a refusal against the contract's own string
+ * rather than a retyped copy of it (the reason `NOT_PROVISIONED` is a value too).
+ *
+ * It is `request_rate_limited` rather than anything naming a credential, and that
+ * is deliberate (CAY-0058 §5): the two limits that can produce it refuse at
+ * different moments — one of them before any credential has been read, and so on a
+ * request that carries none at all — and a code that named a credential would be a
+ * lie on half the refusals and a hint about the shape of the other half on the
+ * rest. One code, one body, one status, from both origins.
+ */
+export const REQUEST_RATE_LIMITED = 'request_rate_limited';