@percayso-community/cayso-contracts 0.30.0 → 2.0.0

package/dist/index.d.ts

@@ -60,10 +60,10 @@
  * This is the surface of every consumer outside this tree (CAY-0026, Amendment 3):
  * Piper first, and the Percayso Cloud second, whose two seams with Cayso arrive from
  * `cloud-settlement`. Peer types, admin types, holdings and carves are deliberately
- * not exported here; they are not a consumer's business. The three operator reads an
+ * not exported here; they are not a consumer's business. The four operator reads an
  * operator app's server calls are published, but on their own entry point,
- * `@percayso-community/cayso-contracts/operator` (CAY-0026, Amendment 4), and nothing
- * here re-exports them: none of this barrel's consumers is an operator.
+ * `@percayso-community/cayso-contracts/operator` (CAY-0026, Amendments 4 and 5), and
+ * nothing here re-exports them: none of this barrel's consumers is an operator.
  * And it carries **no numbers** — amounts, rates, tiers, schedules and thresholds
  * live in the canon PRD and are read from one place, never restated here.
  */
@@ -76,6 +76,71 @@
  * this money surface gains that Piper's own contracts lack, since theirs share
  * one global version bumped across all twenty-two together (CAY-0026).
  *
+ * From `1.0.0` the version follows ordinary semantic versioning (CAY-0101, amending
+ * CAY-0086). A minor is additive on the wire and drops nothing: Cayso keeps serving
+ * every earlier minor of the same major, so a removal waits for a major. A major is
+ * the only breaking kind, and the only time a consumer has to move. A consumer's
+ * handshake accepts a Cayso if `contractVersion` or any entry of
+ * `supportedContractVersions` is on its own line: from `1.0.0` the same major, below
+ * it the same minor.
+ *
+ * `1.0.0` → `2.0.0` SERVES the two-signer binding (CAY-0100 §4, §4a, #417), and it is
+ * a MAJOR, BREAKING ON THE WIRE, declared so under CAY-0101. It lists nothing older: a
+ * deployment of it serves `2.0.0` alone, so `1.0.0` and the `0.x` transition major 1
+ * carried are no longer served. No type in this package changed shape; the behaviour
+ * behind three routes a `1.0.0` consumer already calls did:
+ *
+ *   - **`ROUTES.organisationProvision`** reads the Organisation ID from BizID's
+ *     {@link AuthorityClaims}, sent in {@link AUTHORITY_ASSERTION_HEADER} and bound to
+ *     the identity assertion, and no longer from `organisationAuthority`. Without the
+ *     header it answers `401 authority_assertion_missing`, where it used to provision
+ *     or answer `403 no_organisation_authority`.
+ *   - **`ROUTES.commercialPayment` on the `'mandate'` route** is authorised by the bound
+ *     `AuthorityClaims`, not by `mandateFor`. The payment-allowance route is unchanged.
+ *   - **`ROUTES.purchaseAuthorise` with any `onBehalfOfWalletId`** is authorised the
+ *     same way, and the wallet named must be the one the bound Organisation is bound to;
+ *     `mandateFor` authorises no delegated purchase, into any wallet. A Citizen's own
+ *     purchase is unchanged.
+ *
+ * On those three acts the members of {@link AuthorityBindingRefusal} and
+ * `authority_issuer_not_configured` now reach the wire, which `0.31.0` declared and no
+ * route produced up to `1.0.0`. `organisationAuthority` and `mandateFor` stay declared,
+ * and are removed by a later major (#419).
+ *
+ * `0.32.0` → `1.0.0` changes nothing but the version. Its content is exactly
+ * `0.32.0`'s, and a deployment of it keeps serving `0.32.0`, `0.31.0`, `0.30.0` and
+ * `0.29.0` as a declared transition from the `0.x` line, which the next major ends. The
+ * entries below are the `0.x` history; "breaking" in them is the package's sense,
+ * under which a minor below `1.0.0` was a breaking line.
+ *
+ * `0.31.0` → `0.32.0` publishes and serves a fourth operator read on the `./operator`
+ * entry point, the economy summary, under
+ * `read-economy-summary-as-operator` (CAY-0026 Amendment 5): whole-number counts of
+ * wallets, movements and purchases, and cent totals of what is minted, cancelled and
+ * held, with its closed not-configured body. Nothing in this barrel changed, so no
+ * closed table grew: `ROUTES`, `ContractOperation` and `CaysoApiErrorCode` are as
+ * `0.31.0` published them. It is additive in the package's sense and on the wire
+ * (CAY-0086).
+ *
+ * `0.30.0` → `0.31.0` publishes BizID's authority assertion (CAY-0100), and serves
+ * nothing new: {@link AuthorityClaims}, its {@link AuthorityEnvelope} under the identity
+ * assertion's own `AssertionHeader`, and the binding's closed
+ * {@link AuthorityBindingRefusal}, which `CaysoApiErrorCode` gains by reference;
+ * {@link AUTHORITY_ASSERTION_HEADER}, the header it travels in; {@link isMandateVersion},
+ * the one check that `mandateVersion` is a JSON integer of at least 1; the seam code
+ * `authority_issuer_not_configured`, which `CaysoApiErrorCode` gains as the authority
+ * issuer's closed door and no route emits yet (#417); an optional
+ * `auth_time` on {@link AssertionClaims}, which the verifier now admits as a
+ * non-negative integer and nothing reads; and an optional per-request authority
+ * assertion provider on the thin client's three Organisation operations,
+ * `provisionOrganisation`, `makeCommercialPayment` and `authorisePurchase`, sent only
+ * when the caller passes one. `organisationAuthority` and `mandateFor` stay, retired
+ * and removed by a later breaking step (#419). BREAKING in the package's sense
+ * because a closed union grew. Additive on the wire (CAY-0086): no route a `0.30.0`
+ * consumer calls changed or answers anything new, because no route reads the header
+ * or produces the new codes yet, and a credential a `0.30.0` issuer mints, which
+ * carries no `auth_time`, verifies exactly as before.
+ *
  * `0.29.0` → `0.30.0` publishes and SERVES Cayso's authorisation acknowledgement keys
  * (CAY-0093): {@link ACKNOWLEDGEMENT_KEYS_ROUTE}, `GET /api/acknowledgement-keys`, an
  * unauthenticated read outside `ROUTES`, described in the schema under `keyRoutes`;
@@ -610,7 +675,7 @@
  * have needed a breaking bump on their own. Under semver below `1.0.0` the minor
  * is where a breaking change goes, so the minor moves and the patch does not.
  */
-export declare const CONTRACT_VERSION: "0.30.0";
+export declare const CONTRACT_VERSION: "2.0.0";
 /** The package's own name, so a consumer can name what it depends on. */
 export declare const packageName = "@percayso-community/cayso-contracts";
 /**
@@ -687,6 +752,17 @@ export { NOT_PROVISIONED } from './citizenship.js';
  * exception to keeping numbers in the canon PRD; no economic figure is here.
  */
 export { MAX_ASSERTION_LIFETIME_SECONDS, CLOCK_SKEW_TOLERANCE_SECONDS, MINIMUM_ASSERTION_USE_RETENTION_SECONDS, } from './assertion.js';
+/**
+ * The request header BizID's authority assertion travels in, beside the identity
+ * assertion's `Authorization` (CAY-0100 §4). A value so a consumer and the service
+ * spell it from one place; the reasoning behind the name is on the constant.
+ */
+export { AUTHORITY_ASSERTION_HEADER } from './authority.js';
+/**
+ * Whether a value is a well-formed `AuthorityClaims.mandateVersion`: a JSON integer of at
+ * least 1, BizID's mandate version counter (CAY-0100 §5). The one check of the shape.
+ */
+export { isMandateVersion } from './authority.js';
 /**
  * The assurance profile (CAY-0029): what each `VerificationMethod` asserts, which
  * methods each operation accepts, and the version a claim is minted under.
@@ -775,5 +851,6 @@ export type { StoreSignedStatement, MarketplaceOrderRequest, MarketplaceRefundRe
 export type { InstanceKeyId, SettlementPeriodRule, SettlementPeriodId, NodeId, ContributionStoreIssuer, PercaysoCloudAudience, StandingAuthorisationClaims, StandingAuthorisationRequest, AuthorisationAcknowledgementClaims, AcknowledgementKeyId, AcknowledgementPublicKey, AcknowledgementKeySet, StandingAuthorisationAcknowledged, StandingAuthorisationRefused, StandingAuthorisationResponse, StandingAuthorisationRefusal, StandingAuthorisationRevocationRequest, StandingAuthorisationRevoked, StandingAuthorisationRevocationRefused, StandingAuthorisationRevocationResponse, StandingAuthorisationRevocationRefusal, NodePresentationClaims, NodeBindingRequest, NodeBound, NodeBindingRefused, NodeBindingResponse, NodeBindingRefusal, NodeBindingQueryClaims, NodeBindingQueryRequest, NodeBindingStatus, NodeBindingQueryRefused, NodeBindingQueryRefusal, ContributionType, SettlementPeriod, ContributionWithheldReason, ContributionQualified, ContributionWithheld, ContributionQualification, ContributionRow, ConsumptionRow, SettlementTotals, SettlementAssertionClaims, SettlementAssertionRequest, SettlementAssertionSettled, SettlementAssertionRefused, ContributionRowRefused, ConsumptionRowRefused, SettlementAssertionResponse, SettlementAssertionLevelRefusal, ContributionRowRefusal, ConsumptionRowRefusal, SettlementAssertionRefusal, } from './cloud-settlement.js';
 export type { PurchaseRequest, PurchaseAuthorised, PurchaseTerminal, PurchaseUnresolved, PurchaseRefused, PurchaseAuthorisationResponse, PurchaseFailureReason, PurchaseStatus, LivePurchaseStatus, TerminalPurchaseStatus, PurchaseCancelRefusalReason, PurchaseCancelled, PurchaseCancelRefused, PurchaseCancelResponse, PurchaseResult, } from './purchase.js';
 export type { VerificationMethod, VerificationStatus, SubjectPersonhood, AssertionClaims, AssertionHeader, AssertionEnvelope, ContractOperation, InternalOperation, ScopeKey, } from './assertion.js';
+export type { AuthorityClaims, AuthorityEnvelope, AuthorityBindingRefusal } from './authority.js';
 export type { VerificationEvidence, EvidenceStatement, MethodDecision, MethodDecisions, AssuranceRequired, AssuranceNotRequired, OperationAssurance, AssuranceRefusalReason, AssuranceAssessment, } from './assurance.js';
 export type { Restriction, HoldingKind, HoldingCapability, PermittedStanding, RefusedStanding, OpenStanding, CapabilityStanding, CapabilityCell, CapabilityCoordinate, CapabilityPolicy, ArrivalAndExpiry, } from './restriction.js';

package/dist/index.js

@@ -75,10 +75,10 @@
  * This is the surface of every consumer outside this tree (CAY-0026, Amendment 3):
  * Piper first, and the Percayso Cloud second, whose two seams with Cayso arrive from
  * `cloud-settlement`. Peer types, admin types, holdings and carves are deliberately
- * not exported here; they are not a consumer's business. The three operator reads an
+ * not exported here; they are not a consumer's business. The four operator reads an
  * operator app's server calls are published, but on their own entry point,
- * `@percayso-community/cayso-contracts/operator` (CAY-0026, Amendment 4), and nothing
- * here re-exports them: none of this barrel's consumers is an operator.
+ * `@percayso-community/cayso-contracts/operator` (CAY-0026, Amendments 4 and 5), and
+ * nothing here re-exports them: none of this barrel's consumers is an operator.
  * And it carries **no numbers** — amounts, rates, tiers, schedules and thresholds
  * live in the canon PRD and are read from one place, never restated here.
  */
@@ -92,6 +92,71 @@
  * this money surface gains that Piper's own contracts lack, since theirs share
  * one global version bumped across all twenty-two together (CAY-0026).
  *
+ * From `1.0.0` the version follows ordinary semantic versioning (CAY-0101, amending
+ * CAY-0086). A minor is additive on the wire and drops nothing: Cayso keeps serving
+ * every earlier minor of the same major, so a removal waits for a major. A major is
+ * the only breaking kind, and the only time a consumer has to move. A consumer's
+ * handshake accepts a Cayso if `contractVersion` or any entry of
+ * `supportedContractVersions` is on its own line: from `1.0.0` the same major, below
+ * it the same minor.
+ *
+ * `1.0.0` → `2.0.0` SERVES the two-signer binding (CAY-0100 §4, §4a, #417), and it is
+ * a MAJOR, BREAKING ON THE WIRE, declared so under CAY-0101. It lists nothing older: a
+ * deployment of it serves `2.0.0` alone, so `1.0.0` and the `0.x` transition major 1
+ * carried are no longer served. No type in this package changed shape; the behaviour
+ * behind three routes a `1.0.0` consumer already calls did:
+ *
+ *   - **`ROUTES.organisationProvision`** reads the Organisation ID from BizID's
+ *     {@link AuthorityClaims}, sent in {@link AUTHORITY_ASSERTION_HEADER} and bound to
+ *     the identity assertion, and no longer from `organisationAuthority`. Without the
+ *     header it answers `401 authority_assertion_missing`, where it used to provision
+ *     or answer `403 no_organisation_authority`.
+ *   - **`ROUTES.commercialPayment` on the `'mandate'` route** is authorised by the bound
+ *     `AuthorityClaims`, not by `mandateFor`. The payment-allowance route is unchanged.
+ *   - **`ROUTES.purchaseAuthorise` with any `onBehalfOfWalletId`** is authorised the
+ *     same way, and the wallet named must be the one the bound Organisation is bound to;
+ *     `mandateFor` authorises no delegated purchase, into any wallet. A Citizen's own
+ *     purchase is unchanged.
+ *
+ * On those three acts the members of {@link AuthorityBindingRefusal} and
+ * `authority_issuer_not_configured` now reach the wire, which `0.31.0` declared and no
+ * route produced up to `1.0.0`. `organisationAuthority` and `mandateFor` stay declared,
+ * and are removed by a later major (#419).
+ *
+ * `0.32.0` → `1.0.0` changes nothing but the version. Its content is exactly
+ * `0.32.0`'s, and a deployment of it keeps serving `0.32.0`, `0.31.0`, `0.30.0` and
+ * `0.29.0` as a declared transition from the `0.x` line, which the next major ends. The
+ * entries below are the `0.x` history; "breaking" in them is the package's sense,
+ * under which a minor below `1.0.0` was a breaking line.
+ *
+ * `0.31.0` → `0.32.0` publishes and serves a fourth operator read on the `./operator`
+ * entry point, the economy summary, under
+ * `read-economy-summary-as-operator` (CAY-0026 Amendment 5): whole-number counts of
+ * wallets, movements and purchases, and cent totals of what is minted, cancelled and
+ * held, with its closed not-configured body. Nothing in this barrel changed, so no
+ * closed table grew: `ROUTES`, `ContractOperation` and `CaysoApiErrorCode` are as
+ * `0.31.0` published them. It is additive in the package's sense and on the wire
+ * (CAY-0086).
+ *
+ * `0.30.0` → `0.31.0` publishes BizID's authority assertion (CAY-0100), and serves
+ * nothing new: {@link AuthorityClaims}, its {@link AuthorityEnvelope} under the identity
+ * assertion's own `AssertionHeader`, and the binding's closed
+ * {@link AuthorityBindingRefusal}, which `CaysoApiErrorCode` gains by reference;
+ * {@link AUTHORITY_ASSERTION_HEADER}, the header it travels in; {@link isMandateVersion},
+ * the one check that `mandateVersion` is a JSON integer of at least 1; the seam code
+ * `authority_issuer_not_configured`, which `CaysoApiErrorCode` gains as the authority
+ * issuer's closed door and no route emits yet (#417); an optional
+ * `auth_time` on {@link AssertionClaims}, which the verifier now admits as a
+ * non-negative integer and nothing reads; and an optional per-request authority
+ * assertion provider on the thin client's three Organisation operations,
+ * `provisionOrganisation`, `makeCommercialPayment` and `authorisePurchase`, sent only
+ * when the caller passes one. `organisationAuthority` and `mandateFor` stay, retired
+ * and removed by a later breaking step (#419). BREAKING in the package's sense
+ * because a closed union grew. Additive on the wire (CAY-0086): no route a `0.30.0`
+ * consumer calls changed or answers anything new, because no route reads the header
+ * or produces the new codes yet, and a credential a `0.30.0` issuer mints, which
+ * carries no `auth_time`, verifies exactly as before.
+ *
  * `0.29.0` → `0.30.0` publishes and SERVES Cayso's authorisation acknowledgement keys
  * (CAY-0093): {@link ACKNOWLEDGEMENT_KEYS_ROUTE}, `GET /api/acknowledgement-keys`, an
  * unauthenticated read outside `ROUTES`, described in the schema under `keyRoutes`;
@@ -626,7 +691,7 @@
  * have needed a breaking bump on their own. Under semver below `1.0.0` the minor
  * is where a breaking change goes, so the minor moves and the patch does not.
  */
-export const CONTRACT_VERSION = '0.30.0';
+export const CONTRACT_VERSION = '2.0.0';
 /** The package's own name, so a consumer can name what it depends on. */
 export const packageName = '@percayso-community/cayso-contracts';
 /**
@@ -703,6 +768,17 @@ export { NOT_PROVISIONED } from './citizenship.js';
  * exception to keeping numbers in the canon PRD; no economic figure is here.
  */
 export { MAX_ASSERTION_LIFETIME_SECONDS, CLOCK_SKEW_TOLERANCE_SECONDS, MINIMUM_ASSERTION_USE_RETENTION_SECONDS, } from './assertion.js';
+/**
+ * The request header BizID's authority assertion travels in, beside the identity
+ * assertion's `Authorization` (CAY-0100 §4). A value so a consumer and the service
+ * spell it from one place; the reasoning behind the name is on the constant.
+ */
+export { AUTHORITY_ASSERTION_HEADER } from './authority.js';
+/**
+ * Whether a value is a well-formed `AuthorityClaims.mandateVersion`: a JSON integer of at
+ * least 1, BizID's mandate version counter (CAY-0100 §5). The one check of the shape.
+ */
+export { isMandateVersion } from './authority.js';
 /**
  * The assurance profile (CAY-0029): what each `VerificationMethod` asserts, which
  * methods each operation accepts, and the version a claim is minted under.

package/dist/operator.d.ts

@@ -1,11 +1,14 @@
 /**
  * `@percayso-community/cayso-contracts/operator` — the operator READ surface, on its
- * own entry point: three reads and nothing else (CAY-0026, Amendment 4).
+ * own entry point: four reads and nothing else (CAY-0026, Amendments 4 and 5).
  *
  *   - `GET /api/operator/movements`  — the movement list, under `list-movements-as-operator`.
  *   - `GET /api/operator/purchases`  — the purchase list, under `list-purchases-as-operator`.
  *   - `GET /api/operator/quickenings` — the quickening ladder, under
  *     `read-quickening-ladder-as-operator`.
+ *   - `GET /api/operator/summary` — the economy summary, under
+ *     `read-economy-summary-as-operator` (Amendment 5): whole-number counts and cent
+ *     totals, and never a row.
  *
  * ## Who calls this, and from where
  *
@@ -25,7 +28,7 @@
  *
  * ## What it carries, and what it deliberately does not
  *
- *   - **The three reads only.** The operator surface is larger than this — the wallet
+ *   - **The four reads only.** The operator surface is larger than this — the wallet
  *     lookup, the resolver, the market alarms, the founder lapse — and all of it stays
  *     unpublished. Widening this entry point is a further amendment to CAY-0026, not
  *     an edit to this file.
@@ -44,7 +47,7 @@
  * ## The API is the source of truth
  *
  * Every shape here is the one `apps/api` serves, and a test in `apps/api` drives the
- * three routes and fails on any field the service sends that this file does not
+ * four routes and fails on any field the service sends that this file does not
  * describe. Where an earlier hand-written client disagreed with the service, the
  * service won.
  */
@@ -55,14 +58,14 @@ import type { Cents } from './wallet.js';
  * here refuses a credential that does not name what it is about to do, exactly as a
  * contract-surface route does (`403 assertion_scope_refused`).
  */
-export type OperatorReadScope = 'list-movements-as-operator' | 'list-purchases-as-operator' | 'read-quickening-ladder-as-operator';
+export type OperatorReadScope = 'list-movements-as-operator' | 'list-purchases-as-operator' | 'read-quickening-ladder-as-operator' | 'read-economy-summary-as-operator';
 /** One published operator read: its method, its path and the scope it requires. */
 export interface OperatorReadRoute {
     readonly method: 'GET';
     readonly path: string;
     readonly scope: OperatorReadScope;
 }
-/** The three reads, by name. The paths and scopes are the service's own. */
+/** The four reads, by name. The paths and scopes are the service's own. */
 export declare const OPERATOR_READ_ROUTES: {
     readonly movements: {
         readonly method: "GET";
@@ -79,6 +82,11 @@ export declare const OPERATOR_READ_ROUTES: {
         readonly path: "/api/operator/quickenings";
         readonly scope: "read-quickening-ladder-as-operator";
     };
+    readonly summary: {
+        readonly method: "GET";
+        readonly path: "/api/operator/summary";
+        readonly scope: "read-economy-summary-as-operator";
+    };
 };
 /**
  * What a movement is, declared by the act before the draw (CAY-0075). Closed: the
@@ -236,6 +244,120 @@ export interface QuickeningLadder {
     readonly live: LiveQuickeningBand | null;
     readonly activeCitizens: number;
 }
+/**
+ * How many wallets exist, by holder kind, and how many were created recently.
+ *
+ * `citizenWallets + organisationWallets` is `total`: the two holder kinds are the only
+ * two (CONTEXT.md, *Wallet*). `founderWallets` counts the Founder wallets among the
+ * Citizen Wallets, claimed or not, so it is a part of `citizenWallets` and not a third
+ * kind. The two windows end at `asOf` and include it: `createdInLast7Days` counts
+ * wallets created in `(asOf − 7 days, asOf]`.
+ */
+export interface OperatorWalletCounts {
+    readonly total: number;
+    readonly citizenWallets: number;
+    readonly organisationWallets: number;
+    readonly founderWallets: number;
+    readonly createdInLast7Days: number;
+    readonly createdInLast30Days: number;
+}
+/**
+ * The cents this economy has minted, cancelled and holds, and where the held cents sit.
+ *
+ * Conservation is the identity `heldCents = totalMintedCents − cancelledCents`
+ * (migration `0005`); both sides are reported as read, and a disagreement is reported,
+ * never repaired (CAY-0028). `heldCents` is the system-wide sum of holdings — the cents
+ * in circulation — and is never a stored total: a balance is derived (CAY-0019).
+ *
+ *   - `restrictedCents + unrestrictedCents` is `heldCents`.
+ *   - `inCitizenWalletsCents + inOrganisationWalletsCents` is `heldCents`.
+ *   - `inFounderWalletsCents` is a part of `inCitizenWalletsCents`, and
+ *     `inTreasuryCents` a part of `inOrganisationWalletsCents`: the Treasury is an
+ *     Organisation Wallet. `inTreasuryCents` is null when this deployment has no
+ *     Treasury configured, which is not the same as a Treasury holding nothing.
+ *
+ * Every figure is an integer number of cents (₡1 = 100 cents) and never sterling: the
+ * sterling value of a cent is the published value's, and it is not carried here.
+ */
+export interface OperatorSupplySummary {
+    readonly totalMintedCents: Cents;
+    readonly cancelledCents: Cents;
+    readonly heldCents: Cents;
+    readonly restrictedCents: Cents;
+    readonly unrestrictedCents: Cents;
+    readonly inCitizenWalletsCents: Cents;
+    readonly inOrganisationWalletsCents: Cents;
+    readonly inFounderWalletsCents: Cents;
+    readonly inTreasuryCents: Cents | null;
+}
+/**
+ * How many movements there are of each {@link MovementKind}. Every kind is present, at
+ * zero when none has happened: a missing key would read as "not counted", which is a
+ * different statement from "none". `operator.test.ts` pins the keys to the union.
+ */
+export interface OperatorMovementCountsByKind {
+    readonly issuance: number;
+    readonly purchase: number;
+    readonly grant: number;
+    readonly charge: number;
+    readonly payout: number;
+    readonly transfer: number;
+    readonly burn: number;
+    readonly forfeit: number;
+    readonly commercial_payment: number;
+    readonly quoted_sale: number;
+    readonly buy_back: number;
+    readonly quoted_sale_compensation: number;
+    readonly marketplace_settlement: number;
+    readonly contribution_settlement: number;
+    readonly consumption_settlement: number;
+}
+/**
+ * How many movements there are, how many happened recently, and of which kind. A
+ * movement is final and append-only (CAY-0023), so there is no status to count by.
+ * The windows are the wallet counts' windows, on `occurredAt`.
+ */
+export interface OperatorMovementCounts {
+    readonly total: number;
+    readonly inLast7Days: number;
+    readonly inLast30Days: number;
+    readonly byKind: OperatorMovementCountsByKind;
+}
+/**
+ * How many purchases are in each {@link PurchaseStatus}, every status present, at zero
+ * when none is in it. `operator.test.ts` pins the keys to the union.
+ */
+export interface OperatorPurchaseCountsByStatus {
+    readonly pending: number;
+    readonly issued_uncaptured: number;
+    readonly succeeded: number;
+    readonly failed: number;
+    readonly cancelled: number;
+}
+/** How many purchases there are, and in which status. */
+export interface OperatorPurchaseCounts {
+    readonly total: number;
+    readonly byStatus: OperatorPurchaseCountsByStatus;
+}
+/**
+ * The economy summary: aggregate counts and cent totals over the whole deployment,
+ * read in one snapshot at `asOf` (CAY-0026, Amendment 5).
+ *
+ * **Aggregates only.** No wallet id, no Percayso identity, no Handle, no name and no
+ * row of any kind appears here, and nothing in it can be narrowed to one wallet: the
+ * read takes no query. A per-wallet question is the wallet detail's, audited against
+ * that wallet (CAY-0027).
+ *
+ * `asOf` is the instant the read was made, as an ISO-8601 UTC instant, and the instant
+ * every "last N days" window ends at.
+ */
+export interface OperatorEconomySummary {
+    readonly asOf: string;
+    readonly wallets: OperatorWalletCounts;
+    readonly supply: OperatorSupplySummary;
+    readonly movements: OperatorMovementCounts;
+    readonly purchases: OperatorPurchaseCounts;
+}
 /**
  * `401` — no credential, or one the verifier refused. Every member is also a
  * {@link import('./errors.js').CaysoApiErrorCode}: the gate is the one every route
@@ -285,12 +407,16 @@ export type OperatorPurchasesUnavailable = 'operator_purchases_reader_not_config
  * seeded. Kept apart so an operator can tell a wiring fault from an empty table.
  */
 export type QuickeningLadderUnavailable = 'quickening_ladder_reader_not_configured' | 'quickening_ladder_not_configured';
+/** `503` — this deployment has no economy summary reader wired. */
+export type OperatorEconomySummaryUnavailable = 'operator_summary_reader_not_configured';
 /** Every `{ error }` code the movement list answers. */
 export type OperatorMovementsErrorCode = OperatorMovementsQueryRefusal | OperatorAuthenticationRefusal | OperatorAccessRefusal | OperatorRateLimited | OperatorReadUnavailable | OperatorMovementsUnavailable | OperatorReadFailed;
 /** Every `{ error }` code the purchase list answers. */
 export type OperatorPurchasesErrorCode = OperatorPurchasesQueryRefusal | OperatorAuthenticationRefusal | OperatorAccessRefusal | OperatorRateLimited | OperatorReadUnavailable | OperatorPurchasesUnavailable | OperatorReadFailed;
 /** Every `{ error }` code the ladder answers. It takes no query, so nothing is a `400`. */
 export type QuickeningLadderErrorCode = OperatorAuthenticationRefusal | OperatorAccessRefusal | OperatorRateLimited | OperatorReadUnavailable | QuickeningLadderUnavailable | OperatorReadFailed;
+/** Every `{ error }` code the economy summary answers. It takes no query, so nothing is a `400`. */
+export type OperatorEconomySummaryErrorCode = OperatorAuthenticationRefusal | OperatorAccessRefusal | OperatorRateLimited | OperatorReadUnavailable | OperatorEconomySummaryUnavailable | OperatorReadFailed;
 export interface OperatorMovementsError {
     readonly error: OperatorMovementsErrorCode;
 }
@@ -300,9 +426,14 @@ export interface OperatorPurchasesError {
 export interface QuickeningLadderError {
     readonly error: QuickeningLadderErrorCode;
 }
+export interface OperatorEconomySummaryError {
+    readonly error: OperatorEconomySummaryErrorCode;
+}
 /** Everything `GET /api/operator/movements` answers: `200`, or one refusal body. */
 export type OperatorMovementsResponse = OperatorMovementsPage | OperatorVerificationRefused | OperatorMovementsError;
 /** Everything `GET /api/operator/purchases` answers: `200`, or one refusal body. */
 export type OperatorPurchasesResponse = OperatorPurchasesPage | OperatorVerificationRefused | OperatorPurchasesError;
 /** Everything `GET /api/operator/quickenings` answers: `200`, or one refusal body. */
 export type QuickeningLadderResponse = QuickeningLadder | OperatorVerificationRefused | QuickeningLadderError;
+/** Everything `GET /api/operator/summary` answers: `200`, or one refusal body. */
+export type OperatorEconomySummaryResponse = OperatorEconomySummary | OperatorVerificationRefused | OperatorEconomySummaryError;

package/dist/operator.js

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-/** The three reads, by name. The paths and scopes are the service's own. */
+/** The four reads, by name. The paths and scopes are the service's own. */
 export const OPERATOR_READ_ROUTES = {
     movements: {
         method: 'GET',
@@ -30,6 +30,11 @@ export const OPERATOR_READ_ROUTES = {
         path: '/api/operator/quickenings',
         scope: 'read-quickening-ladder-as-operator',
     },
+    summary: {
+        method: 'GET',
+        path: '/api/operator/summary',
+        scope: 'read-economy-summary-as-operator',
+    },
 };
 /** Every {@link MovementKind}, in the service's order — for a filter a person picks from. */
 export const MOVEMENT_KINDS = [

package/dist/schema-types.d.ts

@@ -27,8 +27,8 @@
  * under `keyRoutes`. 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
+ * The one part of the operator surface that IS published — the four reads on the
+ * `./operator` entry point (CAY-0026, Amendments 4 and 5) — 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
@@ -106,7 +106,7 @@ export interface SchemaOperatorRoute {
     readonly scope: string;
 }
 /**
- * The published operator read surface (CAY-0026, Amendment 4): the three reads on
+ * The published operator read surface (CAY-0026, Amendments 4 and 5): the four 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@percayso-community/cayso-contracts",
-  "version": "0.30.0",
+  "version": "2.0.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": {