From 015495ab56701db9327aa7a8e30ca41a26a87283 Mon Sep 17 00:00:00 2001 From: Joshua Oosthuizen Date: Thu, 5 Nov 2026 09:10:33 +0200 Subject: [PATCH] Docs: Hub 2.0.0 released (phase 1); hub-protocol.md with protocol v2 Co-Authored-By: Claude Opus 5.5 --- apps/events/docs/HANDOVER.md | 21 ++++++++------ apps/events/docs/ROADMAP-v3.md | 2 +- apps/events/docs/hub-protocol.md | 47 ++++++++++++++++++++++++++++---- 3 files changed, 55 insertions(+), 15 deletions(-) diff --git a/apps/events/docs/HANDOVER.md b/apps/events/docs/HANDOVER.md index ab7aa16..1baaba4 100644 --- a/apps/events/docs/HANDOVER.md +++ b/apps/events/docs/HANDOVER.md @@ -1,7 +1,8 @@ # Handover — where things stand and how to carry on -Last updated: 2026-11-04, after **2.1.1** (deployed), Hub **1.7.0** and **contracts 1.0.0**; -ROADMAP-v3 updated for the monorepo move and the `crosscode` deploy script (decisions 21–24). **The plan from here is +Last updated: 2026-11-05, after **2.1.1** (deployed), **Hub 2.0.0** (released, not deployed yet), +**contracts 1.1.0** and the crosscode-site address prices (not deployed yet); ROADMAP-v3 updated for +the monorepo move and the `crosscode` deploy script (decisions 21–24). **The plan from here is [ROADMAP-v3.md](./ROADMAP-v3.md)** (Accounts, Church Website, Church App, Cross Code Hub; decisions table near the end). How Cross Events got to 2.x is in [ROADMAP-v2.md](./ROADMAP-v2.md); the round before that in [FEATURES-ROUND-1.md](./FEATURES-ROUND-1.md). @@ -95,13 +96,15 @@ encrypted settings unreadable or break existing installs. crosscode.co.za, with prices) is live. Build order (§9): - **0 — contracts 1.0.0: released 2026-11-04** (`../crosscode-platform`, tag `contracts@1.0.0`): `crosscode.event/1`, `crosscode.church/1`, `crosscode.identity/1`, Hub protocol v2, generated - JSON Schema in `packages/contracts/schemas/`. Not published to Gitea's package registry, and - won't be (decision 22). - - **1 — Hub 2.0.0** (`../events-hub`): Cross Code Hub — products, one licence per product, - **one install of each product per customer**, domain per customer, bundles, sibling discovery, - **releases per product** (Events from `crosscode-platform` `events@…` tags, keeping the - `hope-events` `v…` releases) **with requirements** (`— requires accounts 1.2.0`, Request update - disabled until met). Contracts as `vendor/crosscode-contracts-1.0.0.tgz` (ROADMAP-v3 §2, §5). + JSON Schema in `packages/contracts/schemas/`. **1.1.0** (2026-11-04) adds `requires` on Hub + releases. Not published to Gitea's package registry, and won't be (decision 22). + - **1 — Hub 2.0.0: released 2026-11-05** (`../events-hub`, tag `v2.0.0`; plan and what each step + did in its `docs/HUB-2.0-PLAN.md` and CHANGELOG): products and one licence per product, protocol + v2 next to v1 (Linked products), releases per product with requirements, billing per church + (bundles, founding, Website storage, App tiers, prorating), the church's address, AI per church, + dashboard per product. **Deploying it:** `events-hub/deployment.md` → "Upgrading to 2.0" (run + `check-hub2` first). crosscode-site has the address prices (merged, deploy it too). Then + installs show up per product; Cross Events 2.1.x keeps speaking protocol 1 until 2.4.0. - **1b — Cross Events 2.2.0: moves into the monorepo** as `apps/events` with its history, and the **`crosscode` script** (`deploy [events] [website] [app]` — Accounts always —, `status`, `install`, `adopt`) replaces `scripts/deploy.sh` / `install.sh`. Run diff --git a/apps/events/docs/ROADMAP-v3.md b/apps/events/docs/ROADMAP-v3.md index 6bd0fa9..4dcaf01 100644 --- a/apps/events/docs/ROADMAP-v3.md +++ b/apps/events/docs/ROADMAP-v3.md @@ -562,7 +562,7 @@ place. | Phase | Version | What | Why this order | |-------|---------|------|----------------| | 0 | contracts 1.0.0 | `crosscode.event/1`, `crosscode.church/1`, `crosscode.identity/1`, Hub protocol v2: schemas, generated JSON Schema, docs, sample payloads, the monorepo set up. **Released 2026-11-04** | Everything else depends on them | -| 1 | **Hub 2.0.0** | Cross Code Hub: products, licence per product, per-customer billing with bundles, protocol v2 (v1 still accepted), sibling discovery, AI usage per product, **releases per product with requirements** (§5), contracts as a committed file (§2) | Must exist before a second product is sold, and before Events releases come from the monorepo | +| 1 | **Hub 2.0.0** | Cross Code Hub: products, licence per product, per-customer billing with bundles, protocol v2 (v1 still accepted), sibling discovery, AI usage per product, **releases per product with requirements** (§5), contracts as a committed file (§2). **Released 2026-11-05** (crosscode-site address prices merged) | Must exist before a second product is sold, and before Events releases come from the monorepo | | 1b | **Cross Events 2.2.0** | **Moves into the monorepo** as `apps/events`, with its git history (merged in, not copied); its packages become workspaces; the **`crosscode` script** (`deploy`, `status`, `install`, `adopt`; §8) replaces `scripts/deploy.sh` and `scripts/install.sh`; every install moved with `crosscode adopt`; `hope-events` archived. No feature changes, so a problem is clearly the move | Before more products, so every product is released and deployed the same way from the start | | 1c | **Cross Events 2.3.0** | **Authenticator app 2FA** (TOTP) next to email and WhatsApp, with recovery codes; admins can see which method each staff account uses | Independent and useful now; the Accounts migration later carries it over | | 2 | **Cross Events 2.4.0** | Reports `product: "events"` (protocol v2), **Linked products**, the event feed (publish + show events from siblings), `packages/seo` (§11) with canonical links for imported events | Small; ready for when the Website exists | diff --git a/apps/events/docs/hub-protocol.md b/apps/events/docs/hub-protocol.md index a30ae63..cbf2c64 100644 --- a/apps/events/docs/hub-protocol.md +++ b/apps/events/docs/hub-protocol.md @@ -1,9 +1,13 @@ -# Hub protocol (version 1) +# Hub protocol (versions 1 and 2) -The contract between a **Cross Events install** (the church's site) and the **Cross Events -Hub** (`events-hub.crosscode.co.za`). A copy of this file lives in both repositories -(`joshua/hope-events` → `docs/hub-protocol.md`, `joshua/events-hub` → `docs/hub-protocol.md`); -change both together. +The contract between an **install** (one of a church's products: Cross Events, Accounts, Church +Website, Church App) and **Cross Code Hub** (`hub.crosscode.co.za`; `events-hub.crosscode.co.za` +keeps working as an alias). Sections 1–5 describe **version 1**, which Cross Events 2.1 speaks; +**[version 2](#6-protocol-version-2-hub-20)** (every product, Hub 2.0) is section 6. A copy of this +file lives in both repositories (`joshua/hope-events` → `docs/hub-protocol.md`, +`joshua/events-hub` → `docs/hub-protocol.md`); change both together. From Hub 2.0 the formats are +defined once, in `@crosscode/contracts` (`crosscode-platform/packages/contracts`, `src/hub.ts`, +with JSON Schema and samples). Principles: @@ -288,3 +292,36 @@ grace starts). Blocking the Hub can't keep a suspended licence active for more t fields to a heartbeat or a token doesn't need a new version — both sides ignore fields they don't know. - The Hub accepts protocol `N` and `N-1`; anything else is `400 UNSUPPORTED_PROTOCOL`. + +## 6. Protocol version 2 (Hub 2.0) + +The formats are in `@crosscode/contracts` (`hub.registerRequestSchema`, `hub.heartbeatRequestSchema`, +… with JSON Schema in `schemas/hub-*.json` and samples in `samples/hub-*.json`). The Hub accepts +versions 1 and 2 (`/api/public-key` lists `[1, 2]`); a v1 request is treated as Cross Events and +answered exactly as in sections 1–5. Signing, offline licence checks, update requests and AI calls +are as in version 1. + +What version 2 changes: + +| | Version 1 | Version 2 | +|---|---|---| +| Who | Cross Events | Every product: `product` is `events`, `accounts`, `website` or `app` | +| Licence keys | `CEH-…` | `CEH-` Events, `CCA-` Accounts, `CCW-` Website, `CCP-` App | +| Register | as §2 | adds `product` (must match the licence: `409 WRONG_PRODUCT`) and `install.publicKey` (the install's Ed25519 public key, PEM) | +| Heartbeat | as §3 | adds `product` (must match the install: `409 WRONG_PRODUCT`); `stats` per product (Events as v1; Website: pages, messages, events, editors, `storage`; App: `activeMembers90d` band, modules, prayer coverage; Accounts: accounts, 2FA methods) | +| Replies | as §2, §3 | add `linkedProducts`: the church's other installs in use that have a public key, as `{ product, installId, url, publicKey }`, nothing else. Releases carry `requires` (below) | +| Bodies | checked by hand | checked against the contract schemas: `400 INVALID_REQUEST` with the field that's wrong; unknown fields are dropped | +| Licence token | as §4 | also `customerId` and `product` (still `v: 1`; a v1 install ignores them). `limits.aiMonthlyCapCents` is the church's cap | + +**Releases per product.** An install is told its own product's releases and latest version. A +release can need a minimum version of a sibling (`— requires accounts 1.2.0` in its WHATS-NEW.md +heading): v2 replies carry it as `requires: [{ product, version }]`, and an update request answers +`409 REQUIREMENT_NOT_MET` (with `requirements: [{ product, version, current }]` and a message saying +what's needed) until the church's install of that product runs that version or later. + +**AI.** The monthly cap and markup are the church's, shared by all its installs: a call from any of +them counts what all of them used this month. + +**Moving an install to v2** (e.g. Cross Events 2.4.0): register again with `protocolVersion: 2`, +the product and a public key (same licence and address: same install id, new secret), then send v2 +heartbeats. Nothing on the Hub needs changing.