@percayso-community/cayso-contracts 0.23.0 → 0.26.0

package/README.md

@@ -12,26 +12,45 @@ literal `0` to `number` — so the one structural guarantee in that surface dies
 the HTTP boundary. The fix is a single published package whose types a consumer
 imports rather than retypes.
 
-## The Piper-facing surface only
-
-Published here: the record and response types, the closed failure-reason union,
-the assertion claims and the route constants — the surface Piper reads.
-
-**Deliberately not published:** peer types, admin types, holdings and carves.
-They are not a consumer's business, and putting them on the public surface widens
-it for nothing.
+## The surface of every consumer outside this tree
+
+Published here: the record and response types, the closed failure-reason unions,
+the assertion claims and the route constants — the surface every consumer outside
+this repository reads (CAY-0026, Amendment 3). Piper is the first consumer. The
+Percayso Cloud is the second: its Contribution Store presents the settlement
+assertion to Cayso directly, and the Cloud generates its types from the `schema`
+entry point rather than typing Cayso's half by hand. The Cloud's two seams live in
+`cloud-settlement`, and the settlement path, which a registered issuer calls and
+no person does, is `CLOUD_SETTLEMENT_ROUTE`, published apart from `ROUTES`.
+
+**The operator read surface, on its own entry point** (CAY-0026, Amendment 4). Three
+reads an operator app's *server* calls — the movement list, the purchase list and the
+quickening ladder — are published at `@percayso-community/cayso-contracts/operator`:
+their paths and scopes, query inputs (wallet id, a half-open `[from, to)` window, a
+keyset cursor), rows and pages, and their closed refusal and not-configured bodies.
+Money is `Cents`, a wallet is named by its wallet id, and no Percayso identity
+appears on any row. It is not re-exported from the barrel, so Piper and the Cloud
+never import an operator vocabulary by accident, and the schema describes it under
+its own `operator` key rather than among the person-facing types. Cayso sends no
+CORS headers: these reads are for a server, never a browser. Widening the entry
+point beyond these three needs a further amendment.
+
+**Deliberately not published:** peer types, holdings and carves, and every operator
+route but those three reads. They are not a consumer's business, and putting them on
+the public surface widens it for nothing.
 
 **This package carries no numbers.** Amounts, rates, tiers, schedules and
 thresholds live in the canon PRD and are read from one place. None of them are
 restated here.
 
-## Three entry points
+## Four entry points
 
 | Import | What it gives you |
 |---|---|
 | `@percayso-community/cayso-contracts` | Types and constants. No runtime. |
 | `@percayso-community/cayso-contracts/client` | The thin client — fetch, assertion header, idempotent retry. |
 | `@percayso-community/cayso-contracts/schema` | A machine-readable descriptor of the published surface. |
+| `@percayso-community/cayso-contracts/operator` | The three operator reads' types and route constants, for an operator app's server. |
 
 The split is the point: a consumer wanting only the types takes on no runtime at
 all. The client owns the fetch, the assertion header and the idempotent retry.
@@ -63,9 +82,14 @@ describes. The thin client's `getVersion()` reads it and warns once, per client
 instance, when the server's contract *major* differs from the one the client was
 built against.
 
+After a minor bump that is additive on the wire, a deployment keeps the previous
+minor in `supportedContractVersions` for one release, so a consumer still pinned
+to it keeps working while it moves. A breaking bump drops it, and says so in the
+bump's changelog.
+
 Alongside it, `GET /api/version/schema` serves the same machine-readable
-descriptor as `@percayso-community/cayso-contracts/schema` — the Piper-facing surface only, with no
-operator, webhook or peer route. It exists for tooling and diagnostics.
+descriptor as `@percayso-community/cayso-contracts/schema` — the surface outside consumers read, with
+no operator, webhook or peer route. It exists for tooling and diagnostics.
 
 **It is not a substitute for depending on this package.** The descriptor is
 data; the guarantee is the *types*, and the types do not exist at runtime — they

package/dist/assertion.d.ts

@@ -353,15 +353,27 @@
  * checked. Neither is a second use of `'authorise-purchase'`, which brings sterling
  * in, or of `'make-commercial-payment'`, which is organisation-to-Citizen only.
  * Both are classified before they are served, and no route serves either yet.
+ *
+ * `'present-standing-authorisation'` is an owner delegating spending to their
+ * Instance on Percayso Cloud services (CMTY-0018 §1): the Instance presents the
+ * owner's standing authorisation, signed by the Instance key, under the owner's
+ * assertion, and Cayso answers with an acknowledgement the Cloud meters against.
+ * It is not a second use of `'make-commercial-payment'`: nothing moves when it is
+ * presented, and what it authorises is spending in later periods, settled by the
+ * Contribution Store's assertion, which no person presents and which therefore has
+ * no operation here. It is classified before it is served.
  */
-export type ContractOperation = 'read-own-wallet' | 'read-purchase-result' | 'authorise-purchase' | 'cancel-purchase' | 'provision-citizenship' | 'read-own-citizenship' | 'provision-organisation' | 'claim-founder-wallet' | 'make-commercial-payment' | 'place-quote' | 'withdraw-quote' | 'request-buy-back' | 'read-citizen-market' | 'read-marketplace-receipt' | 'settle-marketplace-order' | 'settle-marketplace-refund';
+export type ContractOperation = 'read-own-wallet' | 'read-purchase-result' | 'authorise-purchase' | 'cancel-purchase' | 'provision-citizenship' | 'read-own-citizenship' | 'provision-organisation' | 'claim-founder-wallet' | 'make-commercial-payment' | 'place-quote' | 'withdraw-quote' | 'request-buy-back' | 'read-citizen-market' | 'read-marketplace-receipt' | 'settle-marketplace-order' | 'settle-marketplace-refund' | 'present-standing-authorisation';
 /**
  * An operation key belonging to a deployment's OWN surfaces rather than to this
  * contract — operator work, above all. Deliberately not enumerated: this package
  * is published and carries the Piper-facing surface only (CAY-0026), and naming
  * an internal vocabulary here would publish a set of keys no consumer of this
  * contract may ever present. Where the closed set is kept instead is stated on
- * {@link ScopeKey}.
+ * {@link ScopeKey}. The three operator READ scopes are published, but on the
+ * `./operator` entry point (`OperatorReadScope`, CAY-0026 Amendment 4), for an
+ * operator app's server and not for this contract's consumers — so this type
+ * stays open, and the rest of the operator vocabulary stays unpublished.
  */
 export type InternalOperation = string;
 /**

package/dist/assurance.js

@@ -452,6 +452,27 @@ export const ASSURANCE_POLICY = {
             "Platform's signed refund decision; the assertion shows the buyer is present, and it is held " +
             'to the same bar as the sale it refunds.',
     },
+    // An owner delegating spending to their Instance (CMTY-0018 §1). Money-grade, in
+    // the pattern of the commercial payment: what is authorised is cents leaving the
+    // holder's wallet in every later period, up to a cap, without the holder present.
+    // The passkey ceremony is the assertion's verification method, and the bar is
+    // the purchase path's, so a bar no issuer can yet clear does not shut the Cloud
+    // on every deployment. What limits the spending is the cap and its canon ceiling,
+    // and neither is an assurance question.
+    'present-standing-authorisation': {
+        operation: 'present-standing-authorisation',
+        assurance: 'required',
+        decisions: {
+            // Asserts nothing; permanently refused wherever "identity-verified" is meant.
+            'dev-bypass': 'refused',
+            document: 'accepted',
+            'document-and-biometric': 'accepted',
+        },
+        rationale: "Presenting a standing authorisation delegates spending from the holder's wallet to their " +
+            'Instance, up to a cap in every period, so it is money-grade: anything but the development ' +
+            'bypass. Nothing moves when it is presented; what it authorises moves later, without the ' +
+            'holder present, which is why the bar is applied here.',
+    },
 };
 /**
  * Every operation, as a value. Derived from {@link ASSURANCE_POLICY} for the same
@@ -488,6 +509,8 @@ export const OPERATION_FOR_ROUTE = {
     placeQuote: 'place-quote',
     withdrawQuote: 'withdraw-quote',
     requestBuyBack: 'request-buy-back',
+    marketplaceOrder: 'settle-marketplace-order',
+    standingAuthorisation: 'present-standing-authorisation',
     version: null,
 };
 /**

package/dist/client.d.ts

@@ -69,7 +69,9 @@
  */
 import type { BuyBackMade, BuyBackRequest, CitizenMarketViewed, QuotePlaced, QuoteRequest, QuoteWithdrawalRequest, QuoteWithdrawn } from './citizen-market.js';
 import type { CitizenshipFounderClaimed, CitizenshipView } from './citizenship.js';
+import type { StandingAuthorisationAcknowledged, StandingAuthorisationRequest } from './cloud-settlement.js';
 import type { CommercialPaymentMade, CommercialPaymentRequest } from './commercial-payment.js';
+import type { MarketplaceOrderRequest, MarketplaceOrderSettled } from './marketplace-settlement.js';
 import type { OrganisationView } from './organisation.js';
 import type { PurchaseAuthorised, PurchaseCancelled, PurchaseRequest, PurchaseResult, PurchaseTerminal } from './purchase.js';
 import type { WalletView } from './wallet.js';
@@ -251,6 +253,30 @@ export interface CaysoClient {
      * and means nothing moved and nothing is paid.
      */
     requestBuyBack(req: BuyBackRequest): Promise<BuyBackMade>;
+    /**
+     * Present Store Platform's signed order to settle a house-publisher marketplace sale
+     * under the buyer's assertion (`settle-marketplace-order`, CAY-0082 §2, CAY-0083 §3),
+     * and receive Cayso's signed receipt — or REPLAY a sale already settled.
+     *
+     * Safe to repeat with no key of its own: the idempotency key is inside the signed
+     * order, and presenting the same order again answers the receipt already written
+     * (CAY-0082 §4). A refusal arrives as a thrown {@link CaysoApiError} whose `code` is
+     * a `MarketplaceOrderRefusal` member, one of the gate's codes, or a seam code, and
+     * means nothing moved.
+     */
+    settleMarketplaceOrder(req: MarketplaceOrderRequest): Promise<MarketplaceOrderSettled>;
+    /**
+     * Present the owner's standing authorisation, signed by the Instance key, under the
+     * owner's assertion (`present-standing-authorisation`, CMTY-0018 §1), and receive
+     * Cayso's signed acknowledgement for the Percayso Cloud.
+     *
+     * Safe to repeat: the authorisation's `jti` is its own key, and presenting the same
+     * authorisation again binds nothing twice. A refusal arrives as a thrown
+     * {@link CaysoApiError} whose `code` is a `StandingAuthorisationRefusal` member, one
+     * of the gate's codes, or a seam code, and means nothing was bound. Published before
+     * the route is served.
+     */
+    presentStandingAuthorisation(req: StandingAuthorisationRequest): Promise<StandingAuthorisationAcknowledged>;
     getVersion(): Promise<CaysoVersion>;
 }
 /**

package/dist/client.js

@@ -260,6 +260,26 @@ function buildClient(options, internals) {
                 idempotencyKey: req.idempotencyKey,
             });
         },
+        async settleMarketplaceOrder(req) {
+            return requestJson({
+                method: ROUTES.marketplaceOrder.method,
+                path: ROUTES.marketplaceOrder.path,
+                // Safe to repeat: the key is inside the signed order, and the same order
+                // presented again answers the receipt already written, never a second sale.
+                idempotent: true,
+                body: req,
+            });
+        },
+        async presentStandingAuthorisation(req) {
+            return requestJson({
+                method: ROUTES.standingAuthorisation.method,
+                path: ROUTES.standingAuthorisation.path,
+                // Safe to repeat: the authorisation's `jti` is its key, and the same
+                // authorisation presented again binds nothing twice.
+                idempotent: true,
+                body: req,
+            });
+        },
         async getPurchase(purchaseId) {
             return requestJson({
                 method: ROUTES.purchaseResult.method,