Files
crosscode-platform/docs/EVENTS-2.4-PLAN.md
T
joshuaandClaude Opus 5.5 716d47242a Events 2.4.0 frontend, deploy and docs: Linked products, linked events, seo
- Site settings → Linked products (Connect, Show events from, Publish my
  events), help, command palette.
- Events from linked products on /events, the home and campus pages, and
  /events/linked/<product>/<id> (markdown with HTML off, canonical to the
  origin, no JSON-LD, not in the sitemap).
- Event page JSON-LD from @crosscode/seo; lib/eventSchema.ts removed.
- Readiness check for linked products' sync; e2e spec with a fake
  Church Website (not run yet: needs the e2e Postgres).
- crosscode: install and build the shared packages Events uses first
  (an older tag still builds as before); scripts/tests/events.bats.
- Release notes, changelogs, handovers, hub-protocol.md, and the plan's
  "Changes while building".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 12:58:50 +02:00

27 KiB
Raw Permalink Blame History

Cross Events 2.4.0 — protocol v2, Linked products, the event feed and packages/seo

Phase 2 of ROADMAP-v3.md (§4, §5 "Sibling discovery", §9, §11; decisions 5, 20). Written 2026-11-18. Built 2026-11-18 on branches (contracts 1.4.0 and Events 2.4.0 on feat/events-2.4 here, Hub 2.2.0 on feat/link-public-key, crosscode-site on feat/linked-products); not tagged yet. The decisions below were taken as proposed. Where the build differs from this plan, see Changes while building.

What 2.4.0 is: Cross Events becomes a full member of a church stack. It reports to the Hub as product: "events" (protocol v2), shows the church's other products under Settings → Linked products with a Connect button, publishes its public events as a crosscode.event-feed/1 feed, shows events from linked products, and builds its SEO data with the new shared packages/seo. Nothing changes for a church that has only Cross Events, apart from a new settings page that says "No other products yet".

The Website and App don't exist yet, so the "show events from" side is built and tested against sample feeds (§8). It's ready for the Website (phase 4) without another Events release.

Done when:

  • events@2.4.0, contracts@1.4.0 and Hub v2.2.0 are tagged and pushed.
  • An Events install updated to 2.4.0 moves itself to protocol v2 with no admin action, and the Hub shows it as v2 with a public key.
  • The feed passes the contract (parseEventFeed with nothing rejected) for every event in the e2e seed, and a sample Website feed shows up in Events with a canonical link to its origin.
  • crosscode-site says "Works with the Church Website and App (coming)" on the Cross Events page (ROADMAP §9, "Updating crosscode-site").

Contents

  1. Before starting
  2. Protocol v2
  3. Linked products and Connect
  4. Publishing: the feed
  5. Showing events from linked products
  6. packages/seo
  7. Settings, audit log and help
  8. What changes in each repo
  9. Testing
  10. Releasing and rolling it out
  11. Changes while building
  12. Decisions
  13. Still open

Before starting

  • The rollout (ROLLOUT-1.0.md) is at least past step 1, so production runs Hub 2.1.x. 2.4.0 needs Hub 2.2.0 (§1) and is released after it, but neither depends on the church servers being adopted.
  • apps/events builds and tests clean on main (npm run check), as the baseline.
  • Events uses @crosscode/contracts as a workspace dependency for the first time (backend and frontend). The backend is CommonJS with some TypeScript; the package ships both builds, so require('@crosscode/contracts') works as it is.

1. Protocol v2

Today src/hub/client.js speaks protocol 1 (PROTOCOL_VERSION = 1). v2 is in @crosscode/contracts (hub.*) and the Hub has accepted it since 2.0.0 (hub-protocol.md §6).

The problem: hub-protocol.md says an install moves to v2 by registering again with its licence key and a public key. Events never stored the licence key (it's only sent once, from /setup or "Connect to Hub"), so every church admin would have to find and retype it. The v2 heartbeat also has no way to send a public key.

The fix (Hub 2.2.0, contracts 1.4.0): the v2 heartbeat gets an optional publicKey (PEM). The heartbeat is already signed with the install secret, so the Hub knows it's that install. The Hub saves the key when the install has none, and refuses a different key (409 PUBLIC_KEY_MISMATCH) unless Joshua clears it on the install's page (for a restored server that lost its key). An optional field keeps the protocol at version 2 and the contract at /1 (ROADMAP §2, "Versioning").

What Events does:

Step Detail
Key pair On first start of 2.4.0, generate an Ed25519 key pair (generateEd25519 from @crosscode/contracts/signing). Private key encrypted in AppSetting hub_private_key (same encrypt as the install secret), public key in hub_public_key. Both added to HUB_KEYS, so the generic settings endpoints never show them. Never regenerated unless missing
Heartbeat protocolVersion: 2, product: "events", publicKey until the Hub has acknowledged it (hub_public_key_ack), Events stats as in v1. Body checked with hub.heartbeatRequestSchema before sending (a bug shows in tests, not as a 400 in production)
Register /setup and "Connect to Hub" register with v2 straight away (product, install.publicKey)
Reply Reads linkedProducts (§2) and the licence's customerId / product; everything else as v1
Falling back If the Hub answers 400 UNSUPPORTED_PROTOCOL (a Hub older than 2.0), send v1 and keep trying v2 once a day. Not expected in production; it keeps a restored old Hub from cutting installs off

hub-protocol.md §6 "Moving an install to v2" is rewritten to describe this (both copies).

2. Linked products and Connect

Settings → Linked products (site admins only) lists the church's other installs from the last heartbeat's linkedProducts (cached in AppSetting hub_linked_products, so a Hub outage changes nothing; ROADMAP §5). For each: product name, address, and its state: Not connected · Connected (since when, by whom) · Connected, last sync failed (when, why).

With Events only, the page says the church has no other Cross Code products yet, with a link to crosscode.co.za.

Connect

The Hub tells each install which siblings exist and their public keys. Connect turns that into a working link: a shared secret for signed calls between the two, and the feed settings. New contract: crosscode.link/1 in packages/contracts/src/link.ts.

A (Events)                                            B (e.g. Website)
  admin clicks Connect
  makes a 32-byte secret S
  POST {B.url}/api/links/v1/connect ───────────────►  1. A is in B's own cached linkedProducts
  {                                                      (same Hub customer), by installId
    schema: "crosscode.link/1",                       2. the Ed25519 signature checks out against
    type: "link.connect",                                the publicKey the Hub listed for A
    from: { product, installId, url },                3. `to.installId` is B; issuedAt within
    to: { installId },                                   5 minutes; nonce not seen before
    secret: S,                                        4. stores S (encrypted), marks A connected
    issuedAt, nonce,                                  ◄── 200 { schema, type: "link.connected",
    signature: <Ed25519 over the canonical JSON>          from: {…B}, publicKey check, signature }
  }
  checks B's signed reply with B's Hub-listed key
  stores S (encrypted), marks B connected
  • Trust comes from the Hub's list on both sides. B accepts A only if A appears in B's linkedProducts with that exact key, so only installs of the same church can link, and only ones the Hub knows. The Hub is still not on the path at the time of the call (rule 2): both sides use their cached lists.
  • No approval step on B. Both installs belong to the same church; whoever is admin on either side can connect. B's Linked products page shows "Connected by Cross Events on 18 Nov" and either side can Disconnect (a signed link.disconnect; both drop the secret).
  • Connecting again replaces the secret (e.g. after a restored backup lost it).
  • After Connect, every call between the two (the event.changed webhook now, Accounts' back-channel later) uses LINK_HEADERS HMAC with S, as @crosscode/contracts/signing already defines.
  • Errors are crosscode.link/1 { message, code }: NOT_LINKED (A isn't in B's list: "Wait for the next Hub heartbeat, up to 15 minutes, or check the Hub"), BAD_SIGNATURE, STALE_REQUEST, REPLAYED, WRONG_INSTALL.
  • Key format: the Hub lists keys as PEM, while the agent helpers in signing.ts take raw base64url. contracts 1.4.0 adds ed25519PublicFromPem / signLink / verifyLink so no product converts by hand.
  • Events also answers Connect, since a Website will usually be the one clicking it. POST /api/links/v1/connect and /disconnect are public routes, rate-limited per IP, outside /api/v2 (they're a cross-product contract, like the feed).

Stored per link in a new table, not in AppSetting:

model ProductLink {
  installId     String    @id          // the sibling's Hub install id
  product       String                 // website | app | accounts
  url           String
  publicKey     String                 // as listed by the Hub when connected
  secret        String                 // encrypted
  connectedAt   DateTime
  connectedBy   String?                // a user id when connected here, null when the sibling did it
  showEvents    Boolean   @default(false)  // "Show events from" (§4)
  lastSyncAt    DateTime?
  lastSyncError String?
  lastGoodAt    DateTime?
}

If a sibling disappears from linkedProducts (uninstalled, or the licence moved), the link stays but shows No longer listed by the Hub. Its events keep showing until an admin removes the link, so a Hub mistake can't empty the church's event list.

3. Publishing: the feed

GET /api/feed/v1/events?updatedSince=<ISO> → crosscode.event-feed/1 (ROADMAP §4, "Transport"). Public, no sign-in: it only carries what the public event pages already show. It answers only when Publish my events is on (default on; otherwise 404 FEED_OFF).

Which events

The same rule as the public pages, publicEventWhere() in src/utils/series.js: isActive, not isHidden, goLiveAt passed. Plus:

  • Events that ended more than 30 days ago are left out of a full fetch (no updatedSince). An event that ends doesn't go into deleted: siblings keep their copy and drop it from "upcoming" themselves.
  • An event's campus goes out as campus: { slug, name }, null for all campuses.
  • Never in the feed: kids check-in and volunteer options, contact name/phone/email (the church's contact for an event can be a person), the attendee form, prices of staff-only options.

updatedAt and deleted that are actually right

An event's public face changes without its row changing: it goes live when goLiveAt passes, registration closes at the deadline, and it fills up as tickets sell. Event.updatedAt misses all three, and Events never deletes an event (deleteEvent deactivates it). So the feed is kept in a table of what was last published:

model FeedEntry {
  eventId     String    @id
  hash        String              // sha256 of the canonical crosscode.event/1 payload
  payload     Json
  changedAt   DateTime            // the event's `updatedAt` in the feed
  removedAt   DateTime?           // set when it stops being public: goes into `deleted`
}
  • A feed-refresh job (pg-boss, every 5 minutes, and queued straight after an event, option, session or registration change through the existing Prisma extension in config/db.js) builds each candidate event's crosscode.event/1, compares the hash and bumps changedAt only when something a sibling would see has changed. An event that stopped being public gets removedAt.
  • The feed answers from this table: events = rows with changedAt > updatedSince and no removedAt; deleted = rows with removedAt > updatedSince. With no updatedSince, every row without removedAt. Rows removed more than 90 days ago are cleaned up.
  • When the job changes anything, it sends event.changed (eventChangedSchema, at most 100 ids) to every connected link, signed with that link's secret, using the retries and SSRF rules of utils/webhooks.js (1 min, 5 min, 30 min, 2 h, then give up; the 15-minute poll catches up).

Building crosscode.event/1 from an Event

A new src/feed/toCrosscodeEvent.ts, checked against eventSchema in tests for every e2e seed event:

Field From
id Event.id (already a UUID)
origin { product: "events", installId: hub_install_id, url: <APP_URL>/events/<id> }
status published (Events has no "cancelled" state today: cancelling is deactivating, so it goes into deleted)
summary null (no such field yet)
description The plain-text description with markdown characters escaped, so it reads the same when rendered as markdown
imageUrl picture, made absolute
timezone The site timezone (TIMEZONE)
startsAt / endsAt / allDay / sessions utils/sessions.js (already keeps start/end in step with the sessions); allDay: false
location { name: location, address: null, onlineUrl: null }, or null
series { id, name }
tags [] (no tags in Events yet)
registration mode: origin when requiresRegistration, else contact; url the event page; status from the same rules as the event page (not_open before go-live, closed after the deadline or late-join cut-off, full when every limited main option is sold out, waitlist when full with a waitlist); priceFrom = the lowest current public price (early-bird and variants as in eventSchema.ts today), null when free

4. Showing events from linked products

Per connected link: Show events from this product (off by default; ROADMAP §4 "Show events from"). When on:

  • Sync: a feed-sync job per link every 15 minutes, and straight away on a valid event.changed (POST /api/feed/v1/changed, verified with LINK_HEADERS and that link's secret). It fetches ?updatedSince=<lastGoodAt minus 5 minutes>, 15 s timeout, parses with parseEventFeed (rejected events are logged, never block the rest), and upserts into ImportedEvent. One failing link never holds up another (separate jobs).
  • The last good copy stays. A failed sync only sets lastSyncError; admins see "Last synced 2 hours ago" on Linked products and on the dashboard's event list.
  • Read-only, keyed by origin.product + id (eventKey), and never re-published: the feed only ever reads Event, so no loops (ROADMAP §4 rules).
  • Turning Show events from off, or removing the link, deletes that link's imported events.
model ImportedEvent {
  key        String   @id     // eventKey(): "<product>:<id>"
  linkId     String           // ProductLink.installId
  payload    Json             // the crosscode.event/1 as received
  startsAt   DateTime         // copied out for sorting and "upcoming"
  endsAt     DateTime
  campusSlug String?
  updatedAt  DateTime
  @@index([linkId])
  @@index([startsAt])
}

Where they show: on the public Events list, the home page's upcoming events and campus pages (by campus.slug, when it matches one of Events' campuses; otherwise under all campuses), mixed in by date, with a small "From the church website" label. Not in the dashboard's event tools, reports, check-in or anything that registers people.

Their page: /events/linked/<product>/<id>: title, dates, sessions, place, image, the description rendered as markdown with HTML off (react-markdown, new dependency), and one button by registration.mode: More details / Register linking to the origin (origin / external), or the contact instructions (contact). The page has <link rel="canonical"> to origin.url (ROADMAP §11, "Imported events"), is left out of sitemap.xml, and has no Event JSON-LD (the origin's page carries it, so search engines see one event).

5. packages/seo

A new workspace, @crosscode/seo (ROADMAP §11): the schema.org builders and meta helpers every product will use, built on @crosscode/contracts. Pure functions, no framework, ESM + CJS like contracts, its own Jest tests.

Export What
eventJsonLd(event: CrosscodeEvent, opts) Event JSON-LD from crosscode.event/1: eventStatus (EventCancelled for cancelled), attendance mode (OnlineEventAttendanceMode / Mixed… from location.onlineUrl), Place or VirtualLocation, offers from registration (SoldOut for full, validFrom from opensAt), sessions as subEvent
churchJsonLd(church: Church) Church (a schema.org Organization subtype): name, logo, address, geo, phone, service times as openingHoursSpecification-style Event entries, sameAs social links. Used for the Website's home page later; Events uses it as the event organizer
canonicalUrl(base, path) Drops tracking parameters (src, utm_*, fbclid, gclid) and the trailing slash rule in one place
pageMeta({ title, description, … }) Title length and description trimming rules (60 / 155 characters), used for the Website's warnings later

Events moves onto it: frontend/src/lib/eventSchema.ts is replaced. The public event detail answer gains crosscodeEvent (the same builder as the feed, §3), and the page calls eventJsonLd with it. Nothing gets worse for Google: today's JSON-LD gives a price range (AggregateOffer low–high); crosscode.event/1 only has priceFrom. eventJsonLd takes an optional priceRange for the origin's own page, so Events keeps sending the high price. A snapshot test compares the old and new JSON-LD for each seed event; the only allowed differences are additions (subEvent, organizer as a Church).

The organizer comes from a crosscode.church/1 that Events builds from its own site settings (name, logo, colours, contact email). Sharing that profile with siblings is not part of 2.4.0 (see Still open).

6. Settings, audit log and help

  • Settings → Linked products (new page): the list, Connect / Disconnect, Show events from, last sync. Settings → Site → Publish my events (on by default) with one line on what it shares ("Your public events, as they appear on your events page. Never anyone's details.").
  • Audit log (utils/adminAudit.js): product_link_connected, product_link_disconnected, feed_publish_toggled, feed_show_toggled. Connections made by the sibling are logged with no user.
  • Help: a "Linked products" help article, and the setting descriptions. What's new for 2.4.0: "Ready for the Church Website and App: your events can show on them, and theirs here. Nothing changes until you have them."
  • Readiness checks (utils/readiness.js): warn when a link's last sync failed for more than a day.

7. What changes in each repo

Repo Change Version
crosscode-platform packages/contracts crosscode.link/1 (link.ts: connect, connected, disconnect, errors), optional publicKey on the v2 heartbeat, ed25519PublicFromPem / signLink / verifyLink, JSON Schema and samples for each contracts@1.4.0
crosscode-platform packages/seo New (§5) Not tagged on its own: a workspace, versioned with its first user like ui
crosscode-platform apps/events §1–§6. Migrations: ProductLink, FeedEntry, ImportedEvent. New deps: @crosscode/contracts, @crosscode/seo (workspace), react-markdown events@2.4.0
crosscode-platform docs/ hub-protocol.md §6 (heartbeat publicKey, moving to v2), ROADMAP §9 phase 2 marked done, HANDOVER —
events-hub v2 heartbeat accepts and saves publicKey (409 PUBLIC_KEY_MISMATCH for a different one), Clear public key button on the install page (2FA again, audited), vendored contracts-1.4.0.tgz, its copy of hub-protocol.md Hub v2.2.0
crosscode-site "Works with the Church Website and App" on the Cross Events page, marked coming (src/data/cross-events.mjs) v1.4.0

New .env variables: none planned. If one turns up, it goes in all three templates (HANDOVER, "Things to remember").

8. Testing

Unit and integration (Jest, in npm run check):

  • contracts: crosscode.link/1 samples parse; signLink / verifyLink refuse a changed body, another key, a stale issuedAt and a replayed nonce.
  • seo: eventJsonLd / churchJsonLd for every contract sample; the old-vs-new snapshot (§5).
  • Events, Hub client: the v2 heartbeat body passes hub.heartbeatRequestSchema; the key pair is made once; publicKey stops being sent after the ack; falling back to v1 on UNSUPPORTED_PROTOCOL.
  • Events, feed: every e2e seed event passes eventSchema; hidden, inactive, not-yet-live and kids/volunteer data never appear; updatedSince returns exactly what changed, including go-live, deadline and selling out with no Event row change; deactivating puts it in deleted; feed off → 404 FEED_OFF.
  • Events, Connect: accepted from a listed sibling; refused when not listed, with a key other than the listed one, stale, replayed or for another install; disconnect from either side.
  • Events, sync: a sample Website feed with one invalid event (the rest import, the bad one is logged); the source down (last copy kept, error shown); event.changed with a bad signature refused; imported events never in our own feed.
  • Hub (events-hub): v2 heartbeat with a key saves it; the same key is fine; a different one is 409; Clear lets a new one in.

e2e (Playwright, apps/events/e2e): a small fake "Website" (a fixture server in the e2e setup serving samples/event-feed.json and answering Connect) to click through Linked products → Connect → Show events from → the imported event on /events → its page with the canonical link and the origin's button; sitemap.xml doesn't list it. The §11 checks (title, description, canonical, og:image, one <h1>, JSON-LD parses) on the event page and the imported event page.

On the VM (as in AGENT-1.0-PLAN §13), before tagging: two installs of Events can't be linked (one per product per customer), so the VM run uses the fake Website from e2e as a second site behind frp, against Hub 2.2.0. Check: an existing 2.3.x install updated through the agent moves itself to v2 and appears with a key on the Hub; Connect works across the two servers; turning the fake Website off keeps its events showing with "last synced".

9. Releasing and rolling it out

Order, each with its CHANGELOG entry and npm run check first:

  1. contracts@1.4.0 (platform), then the packed .tgz into events-hub/backend/vendor/.
  2. Hub v2.2.0, deployed (events-hub/deployment.md).
  3. events@2.4.0 (its WHATS-NEW.md heading needs no requires: against a Hub before 2.2.0 it still works, only Linked products stays empty).
  4. crosscode-site v1.4.0, deployed.
  5. Each church updated through the Hub (a scheduled update, ROLLOUT-1.0 §5).

Changes while building

  1. A different public key never fails the heartbeat (§1 said 409 PUBLIC_KEY_MISMATCH): the heartbeat also refreshes the licence, so failing it could lock a church out after 30 days. The Hub keeps the saved key, answers publicKeyStatus: "mismatch" and opens an alert on the install; the site keeps sending its key until it gets saved or matches, so it's saved right after Joshua clears the old one. Events shows the mismatch on Linked products.
  2. Update requests and AI calls stay on protocol 1 (every Hub accepts them); only register and heartbeat move to v2. A Hub that refuses a v2 body (UNSUPPORTED_PROTOCOL or INVALID_REQUEST) gets the same heartbeat again as v1, and v1 is used for a day. The v2 health fills in what v1 could leave empty (jobs, pendingMigrations), and the body is checked against the contract before it's sent.
  3. event.changed is tried once more after a minute, then left to the 15-minute poll (§3 said the webhooks' 1 min … 12 h schedule): retrying longer than the poll interval adds nothing.
  4. The feed is also refreshed before it's served when the last refresh is over a minute old, so it's right even with the jobs switched off (e2e, FEED_JOBS_ENABLED=false).
  5. Imported events must come from that link's install (origin.installId and product), so one product can't publish events as another. Others are skipped and counted.
  6. JSON-LD: organizer stays an Organization (the snapshot rule allowed only additions); Church JSON-LD is in @crosscode/seo for the Website. The price range is now from main tickets only (before, an add-on such as a T-shirt could set the lowest price). The description goes in as plain text, not the feed's markdown-escaped copy.
  7. The deploy builds the shared packages: scripts/products/events.sh installs and builds packages/contracts and packages/seo before Events when the checkout's Events uses them (an older tag still builds as before; scripts/tests/events.bats).
  8. FEED_JOBS_ENABLED (optional, default true) switches the feed and feed-sync jobs, like the other job flags (in .env.example and SETTINGS.md, not the env templates).
  9. The readiness check is on the existing readiness page; contracts 1.4.0 also adds FEED_PATHS and typesVersions (so @crosscode/contracts/signing has types under the Events backend's moduleResolution: node).
  10. Not run yet: the e2e spec (e2e/linked-products.spec.ts, needs the e2e Postgres) and the VM test (§8): this machine has neither Postgres nor WSL. Both before tagging.

Decisions

Proposed in this plan, to confirm before building:

  1. Moving to v2 needs no admin action: the v2 heartbeat carries the install's public key (optional field), instead of re-registering with the licence key (§1). Needs Hub 2.2.0.
  2. Connect needs no approval on the other side, and trust comes from each side's own cached Hub list (§2).
  3. Publish my events is on by default (it only shares what the public pages already show); Show events from is off by default per link.
  4. The feed is built from a FeedEntry table, not straight from Event, so go-live, deadlines and selling out are reported as changes (§3).
  5. Imported events get their own page in Events with a canonical link to the origin, rather than linking straight out from the list (§4).
  6. Ended events stay out of deleted; a full fetch covers events that ended up to 30 days ago.

Still open

  • Who owns the church profile (crosscode.church/1) once there's more than one product? Events builds one from its own settings for its JSON-LD in 2.4.0, but doesn't serve it to siblings. The Website (phase 4) is the natural owner; decide before phase 4.
  • Event summary and tags go out empty because Events has no such fields. Add them in a later 2.x if the Website's event cards need them.
  • A "cancelled" state in Events (shown as cancelled rather than disappearing) would map to status: "cancelled". Not in 2.4.0.