@percayso-community/cayso-contracts 0.24.0 → 0.27.0

package/dist/routes.js

@@ -91,6 +91,14 @@
  * (CAY-0079 §2). A path that took a payee's identity would make this route a
  * directory of identities for anyone holding a mandate.
  *
+ * ## Why `citizenTransfer` names only the payee, and never the sender
+ *
+ * `POST /api/citizen-transfers` is a Citizen transferring Cayso to another Citizen
+ * (CAY-0088). The body carries the payee's wallet id, the cents and the key. The
+ * sending wallet is NOT in the request: it is the verified subject's own Citizen
+ * Wallet, resolved inside `apps/api`, because a sending wallet the caller named would
+ * be the caller's claim about whose cents these are (CAY-0021).
+ *
  * ## Why the citizen market is FOUR PATHS, and none of them names a wallet
  *
  * `citizenMarket` reads the book, `placeQuote` places a quote, and `withdrawQuote`
@@ -109,6 +117,20 @@
  * `requestBuyBack` asks the Treasury to buy back (CAY-0080 §2.2). It is a fourth path
  * for the same reason: selling to the Treasury is not a quote (Open decision G), and a
  * credential scoped to place one must not thereby cash out. It names no wallet either.
+ *
+ * ## Why `standingAuthorisation` is here, and the Cloud's settlement is not
+ *
+ * `standingAuthorisation` is an Instance presenting its owner's standing
+ * authorisation under the owner's assertion (`present-standing-authorisation`,
+ * CMTY-0018 §1). A person is behind it, so it is classified by a person's
+ * assurance like every other entry. It names no wallet: the wallet is the verified
+ * holder's own. It is published before it is served.
+ *
+ * The Contribution Store's settlement assertion is presented by no person. Its path
+ * is {@link CLOUD_SETTLEMENT_ROUTE}, outside this table, because every entry here is
+ * mapped in `OPERATION_FOR_ROUTE` to the assurance a person needs, and `null` there
+ * means "carries no identity", which is false of an assertion a registered issuer
+ * signed.
  */
 export const ROUTES = {
     wallet: { method: 'GET', path: '/api/wallet' },
@@ -120,10 +142,30 @@ export const ROUTES = {
     purchaseResult: { method: 'GET', path: '/api/purchases/:purchaseId' },
     purchaseCancel: { method: 'POST', path: '/api/purchases/:purchaseId/cancel' },
     commercialPayment: { method: 'POST', path: '/api/commercial-payments' },
+    citizenTransfer: { method: 'POST', path: '/api/citizen-transfers' },
     citizenMarket: { method: 'GET', path: '/api/citizen-market' },
     placeQuote: { method: 'POST', path: '/api/quotes' },
     withdrawQuote: { method: 'POST', path: '/api/quote-withdrawals' },
     requestBuyBack: { method: 'POST', path: '/api/buy-backs' },
     marketplaceOrder: { method: 'POST', path: '/api/marketplace/orders' },
+    standingAuthorisation: { method: 'POST', path: '/api/cloud/standing-authorisations' },
     version: { method: 'GET', path: '/api/version' },
 };
+/**
+ * Where the Percayso Cloud's Contribution Store presents one period's settlement
+ * assertion (CMTY-0018 §2, `cloud-settlement`).
+ *
+ * **Authenticated by a registered Store issuer (CAY-0030), not by a person.** The
+ * assertion is its own credential: signed by a key whose public half is a
+ * registered Cayso issuer under its own `kid`, in CAY-0072's format, and verified
+ * against a registry that is empty by default, so a Cayso never told about a Store
+ * settles nothing (CAY-0021). No person's assertion travels with it, and it is not
+ * in {@link ROUTES}, whose every entry is classified by a person's assurance. The
+ * client has no method for it, because no person's software calls it.
+ *
+ * Published before it is served.
+ */
+export const CLOUD_SETTLEMENT_ROUTE = {
+    method: 'POST',
+    path: '/api/cloud/settlement-assertions',
+};

package/dist/schema-types.d.ts

@@ -1,6 +1,6 @@
 /**
  * The shape of the machine-readable contract schema `GET /api/version/schema`
- * serves — a structural description of the Piper-facing surface, one that a
+ * serves — a structural description of the published surface, one that a
  * consumer (or the CI contract test) can read at runtime.
  *
  * ## Why this file is types-only and hand-written, while the schema VALUE is not
@@ -14,16 +14,25 @@
  * as `@percayso-community/cayso-contracts`, so the two cannot disagree, and a CI test regenerates and
  * compares — a type changed without regeneration turns that test red.
  *
- * ## Why it describes the Piper-facing surface ONLY
+ * ## Why it describes the published surface ONLY
  *
  * The descriptor covers the exported wire types, the route table, the capability
  * names and the contract version — the surface a consumer of `@percayso-community/cayso-contracts`
  * reads. It does NOT describe the internal routes (`INTERNAL_ROUTES` in
- * `apps/api`: the operator, webhook and peer endpoints): those are not Piper's
- * business, and a schema that enumerated the operator surface would have published
- * it (CAY-0026, CLAUDE.md). The generator only ever sees this package, so the
+ * `apps/api`: the operator, webhook and peer endpoints): those are no outside
+ * consumer's business, Piper's or the Percayso Cloud's, and a schema that
+ * enumerated the operator surface would have published it (CAY-0026, Amendment 3;
+ * CLAUDE.md). The Contribution Store's settlement path is published, but under
+ * `issuerRoutes`, apart from the routes a person calls. The generator only ever sees this package, so the
  * internal surface is absent by construction.
  *
+ * The one part of the operator surface that IS published — the three reads on the
+ * `./operator` entry point (CAY-0026, Amendment 4) — is described under its own
+ * key, {@link ContractSchema.operator}, with its routes and its types apart from
+ * `routes` and `types`. A consumer reading the person-facing surface therefore
+ * never meets an operator route or an operator type by accident, and the rest of
+ * the operator surface is still absent by construction.
+ *
  * ## What it deliberately omits
  *
  * `CaysoWallet` — the client capability interface carrying a `getMyWallet()`
@@ -46,7 +55,9 @@ export type ScalarKind = 'string' | 'number' | 'boolean';
  *   - `{ literal }`  — a string-literal type, e.g. the `'cayso'` audience or a
  *                      failure-reason member.
  *   - `{ null: true }` — the `null` type, as it appears in `T | null`.
- *   - `{ ref }`      — a reference to another named type in {@link ContractSchema.types}.
+ *   - `{ ref }`      — a reference to another named type in {@link ContractSchema.types}
+ *                      or, from an operator type, in {@link SchemaOperatorSurface.types}.
+ *                      The two maps share one namespace, so a name means one type.
  *   - `{ array, readonly }` — an array whose element is `array`; `readonly`
  *                      records whether the source wrote `readonly T[]`.
  *   - `{ union }`    — a union of the member nodes, in source order.
@@ -87,6 +98,23 @@ export interface SchemaRoute {
     readonly method: string;
     readonly path: string;
 }
+/** An operator read, as the descriptor reports it: a route plus the scope it requires. */
+export interface SchemaOperatorRoute {
+    readonly method: string;
+    readonly path: string;
+    readonly scope: string;
+}
+/**
+ * The published operator read surface (CAY-0026, Amendment 4): the three reads on
+ * `@percayso-community/cayso-contracts/operator` and the types declared there. A type
+ * here may refer to one in {@link ContractSchema.types} — a row's `cents` is `Cents`
+ * — but never the other way round: nothing on the person-facing surface depends on
+ * the operator one.
+ */
+export interface SchemaOperatorSurface {
+    readonly routes: Readonly<Record<string, SchemaOperatorRoute>>;
+    readonly types: Readonly<Record<string, SchemaType>>;
+}
 /**
  * The whole served schema: the contract version it describes, the package name,
  * the capability names, the route table and every named wire type. Generated from
@@ -96,6 +124,20 @@ export interface ContractSchema {
     readonly contractVersion: string;
     readonly packageName: string;
     readonly capabilities: Readonly<Record<string, string>>;
+    /** Every `ROUTES` entry: the routes a person calls, under a person's assertion. */
     readonly routes: Readonly<Record<string, SchemaRoute>>;
+    /**
+     * The routes authenticated by a registered issuer (CAY-0030) rather than by a
+     * person, and therefore not in `ROUTES`: today the Contribution Store's
+     * settlement path (`CLOUD_SETTLEMENT_ROUTE`, CMTY-0018 §2). Kept apart from
+     * {@link routes} so that no consumer reads one as the other.
+     */
+    readonly issuerRoutes: Readonly<Record<string, SchemaRoute>>;
     readonly types: Readonly<Record<string, SchemaType>>;
+    /**
+     * The operator reads an operator app's server calls, and their types — under
+     * their own key, so that neither {@link routes} nor {@link types} grows an
+     * operator entry.
+     */
+    readonly operator: SchemaOperatorSurface;
 }

package/dist/schema.d.ts

@@ -20,5 +20,5 @@
  * drive validation instead of depending on the package would re-implement, badly,
  * the guarantee the package already gives for free (CAY-0026, and the README).
  */
-export type { ContractSchema, ScalarKind, SchemaProperty, SchemaRoute, SchemaType, SchemaTypeNode, } from './schema-types.js';
+export type { ContractSchema, ScalarKind, SchemaProperty, SchemaOperatorRoute, SchemaOperatorSurface, SchemaRoute, SchemaType, SchemaTypeNode, } from './schema-types.js';
 export { CONTRACT_SCHEMA } from './contract-schema.generated.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@percayso-community/cayso-contracts",
-  "version": "0.24.0",
-  "description": "The versioned capability contract surface through which anything outside this repository reads a wallet. Published; keep it the Piper-facing surface only.",
+  "version": "0.27.0",
+  "description": "The versioned capability contract surface through which anything outside this repository reads a wallet. Published; keep it the surface of every consumer outside this tree, Piper and the Percayso Cloud, and nothing internal.",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -24,6 +24,10 @@
     "./schema": {
       "types": "./dist/schema.d.ts",
       "default": "./dist/schema.js"
+    },
+    "./operator": {
+      "types": "./dist/operator.d.ts",
+      "default": "./dist/operator.js"
     }
   },
   "files": [