- 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>
430 lines
27 KiB
Markdown
430 lines
27 KiB
Markdown
# Cross Events 2.4.0 — protocol v2, Linked products, the event feed and `packages/seo`
|
||
|
||
Phase **2** of [ROADMAP-v3.md](./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](#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](#before-starting)
|
||
2. [Protocol v2](#1-protocol-v2)
|
||
3. [Linked products and Connect](#2-linked-products-and-connect)
|
||
4. [Publishing: the feed](#3-publishing-the-feed)
|
||
5. [Showing events from linked products](#4-showing-events-from-linked-products)
|
||
6. [`packages/seo`](#5-packagesseo)
|
||
7. [Settings, audit log and help](#6-settings-audit-log-and-help)
|
||
8. [What changes in each repo](#7-what-changes-in-each-repo)
|
||
9. [Testing](#8-testing)
|
||
10. [Releasing and rolling it out](#9-releasing-and-rolling-it-out)
|
||
11. [Changes while building](#changes-while-building)
|
||
12. [Decisions](#decisions)
|
||
13. [Still open](#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](./hub-protocol.md#6-protocol-version-2-hub-20)).
|
||
|
||
**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`:
|
||
|
||
```prisma
|
||
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:
|
||
|
||
```prisma
|
||
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.
|
||
|
||
```prisma
|
||
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](#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.
|