Author SHA1 Message Date
joshuaandClaude Opus 5.5 53e15fdd69 Release events@2.2.0 and contracts@1.2.0
Events 2.2.0: the move into the monorepo and the crosscode script, plus
AI use in tokens and the backend under /api. Contracts 1.2.0: token
fields on the AI status. Agent phase 1d moves to contracts 1.3.0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 11:38:09 +02:00
joshua a0ab22fbf3 Merge branch 'feat/api-prefix'
# Conflicts:
#	apps/events/CHANGELOG.md
2026-11-17 11:31:34 +02:00
joshua 52099c310d Merge branch 'feat/ai-tokens' 2026-11-17 11:31:06 +02:00
joshuaandClaude Opus 5.5 61a64cf339 Docs: AI tokens and /api under Events 2.3.0 in the roadmap and handover
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 11:12:01 +02:00
joshuaandClaude Opus 5.5 afaccf79d1 Events: everything the backend serves is under /api (for 2.3.0)
The site and its API can share one address with one proxy rule (/api to
the backend, everything else to the frontend). Status page at /api (/
redirects), /api/health, /api/docs/v2, /api/uploads. Stored upload
paths stay /uploads/… and are given out as /api/uploads/…. Old paths
still answer (/health, /uploads) or redirect (/docs, /docs/v2), so
two-address sites keep working. DEPLOYMENT.md and the agent plan
describe the single rule.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 11:11:46 +02:00
29 changed files with 160 additions and 65 deletions
+9
View File
@@ -4,6 +4,15 @@ Each package and app has its own section and its own tags (`contracts@1.0.0`, `a
## Unreleased
## events@2.2.0, contracts@1.2.0 - 2026-11-17
### Events
- **Cross Events 2.2.0**, the first release from this repo (`apps/events`, ROADMAP-v3 phase 1b):
moved in with its history, npm workspaces with one root lockfile, and the `crosscode` script
(`deploy`, `status`, `install`, `adopt`) in `scripts/`. Also AI use shown in tokens instead of
rand, and everything the backend serves under `/api`. Details in `apps/events/CHANGELOG.md`.
### Contracts
- AI status (Hub protocol §3b): optional `usedInputTokens`, `usedOutputTokens`, `capInputTokens`,
+20 -2
View File
@@ -7,9 +7,19 @@ and this project follows [Semantic Versioning](https://semver.org/).
## [Unreleased]
## [2.2.0] - 2026-11-17
Cross Events moves into the `crosscode-platform` monorepo (ROADMAP-v3 phase 1b,
`docs/EVENTS-2.2-PLAN.md`). Existing installs move with `crosscode adopt`, not `deploy`.
### Changed
- **AI use is shown in tokens, not rand** (for 2.3.0; needs Hub 2.0.1 for the token figures). Site
- **Moved into the monorepo** as `apps/events`, with its git history. The backend and frontend are
npm workspaces with one root lockfile. Releases are tagged `events@x.y.z`; the older `v…` tags
stay in the archived `hope-events` repo.
- **The `crosscode` script** (`deploy`, `status`, `install`, `adopt`, in `scripts/` at the
monorepo root) replaces `scripts/deploy.sh` and `scripts/install.sh`.
- **AI use is shown in tokens, not rand** (needs Hub 2.0.1 for the token figures). Site
settings → AI shows the percentage used, the input and output tokens used this month and an
estimated allowance in tokens; the per-person, per-helper and per-day tables show tokens instead
of cost. The 80% email names tokens instead of rand. The rand amounts the Hub sends are dropped
@@ -20,6 +30,14 @@ and this project follows [Semantic Versioning](https://semver.org/).
`inputTokens` / `outputTokens` instead of `chargedCents`.
- `AiCall` keeps each call's tokens (migration `20261117120000_ai_tokens`). Calls from before it
show 0 tokens.
- **Everything the backend serves is under `/api`**, so the site and its API can share one
address (`events.church.co.za`, no `events-api.` record) with a single proxy rule: `/api` →
backend port, everything else → frontend port (DEPLOYMENT.md, "One address, one rule"). The
status page is at `/api` (`/` redirects there), health at `/api/health`, the API reference at
`/api/docs/v2` and uploaded files at `/api/uploads/…`. Stored paths stay `/uploads/…`; pictures,
logos and attachments are given out as `/api/uploads/…`, and so are WhatsApp ticket PDFs.
- The old paths keep working on the backend: `/health` and `/uploads/…` answer as before, and
`/docs` and `/docs/v2` redirect to `/api/docs/v2`. A missing file under `/api/uploads` is 404.
## [2.1.1] - 2026-11-03
@@ -2274,4 +2292,4 @@ Run `npm run prisma:deploy` in the backend when deploying. This release adds a m
[1.2.0]: https://git.crosscode.co.za/joshua/hope-events/compare/v1.1.0...v1.2.0
[1.1.0]: https://git.crosscode.co.za/joshua/hope-events/compare/v1.0.1...v1.1.0
[1.0.1]: https://git.crosscode.co.za/joshua/hope-events/compare/v1.0.0...v1.0.1
[1.0.0]: https://git.crosscode.co.za/joshua/hope-events/releases/tag/v1.0.0
[1.0.0]: https://git.crosscode.co.za/joshua/hope-events/releases/tag/v1.0.0
+22 -1
View File
@@ -38,6 +38,27 @@ visitor ──http───▶ frps (vhost_http_port) ══tunnel══▶ frp
On this server, nginx sends `/api`, `/uploads`, `/health` and `/docs` to the backend (port 5000)
and everything else to the Next.js site (port 3000), the same as a normal install.
### One address, one rule (2.2.0 and later)
From 2.2.0 everything the backend serves is under **`/api`**: the API (`/api/v2`), the status page
(`/api`), health (`/api/health`), the API reference (`/api/docs/v2`) and uploaded files
(`/api/uploads/…`). So the site and its API share one address (`events.yourchurch.org`, no
separate `events-api.` record), and a web server or panel such as FastPanel needs a single
rule:
| Path | Goes to |
|------|---------|
| `/api` and everything under it | the backend, `http://127.0.0.1:5000` |
| everything else | the frontend, `http://127.0.0.1:3000` |
Set `BACKEND_URL` (backend `.env`) and `NEXT_PUBLIC_API_URL` (frontend `.env.production`) to the
same `https://` address as `FRONTEND_URL`, then rebuild the frontend. The old paths (`/health`,
`/docs/v2`, `/uploads/…`) still answer on the backend's port, so a site with a separate API
address keeps working unchanged. With only `/api` routed, links made before 2.2.0 that point at
`https://<site>/uploads/…` stop working (they aren't stored that way, but could be in an old
email); keep the four-path rule above if that matters. Pictures, logos and attachments are all
given out as `/api/uploads/…` from 2.2.0.
## 2. Before you start
- Ubuntu 22.04 or 24.04 on this server, with `frpc` already installed and connected (it runs as
@@ -264,7 +285,7 @@ setup). If the `[hope-events-https]` section fails to start, check `journalctl -
## 6. Finish in the browser
1. Open `https://events.yourchurch.org/health` — it should answer with the version.
1. Open `https://events.yourchurch.org/api/health` (`/health` before 2.2.0) — it should answer with the version.
2. Open `https://events.yourchurch.org/setup`: create the admin account.
3. **Site settings → Licence**: enter the licence key to connect to the Hub. The site checks in
every 15 minutes from then on (outgoing HTTPS to `events-hub.crosscode.co.za`, which frp
+2 -2
View File
@@ -20,7 +20,7 @@ The backend provides a RESTful API for managing users, events, registrations, pa
- Static uploads for event images
Documentation: see Backend API Documentation and Backend README for environment setup and endpoints.
- API reference: `/docs/v2` on the running backend (OpenAPI; admin token) — ./backend/API_DOCUMENTATION.md
- API reference: `/api/docs/v2` on the running site (OpenAPI; admin token; `/docs/v2` before 2.2.0) — ./backend/API_DOCUMENTATION.md
- Moving to 2.0 (v1 API removed): ./MIGRATING-TO-2.md
- Backend README: ./backend/README.md
@@ -156,7 +156,7 @@ set names that match your PM2 apps (`pm2 ls`) and the port you use.
## Useful Links
- API reference: `/docs/v2` on the running backend (OpenAPI; admin token) — ./backend/API_DOCUMENTATION.md
- API reference: `/api/docs/v2` on the running site (OpenAPI; admin token; `/docs/v2` before 2.2.0) — ./backend/API_DOCUMENTATION.md
- Moving to 2.0 (v1 API removed): ./MIGRATING-TO-2.md
- Backend README: ./backend/README.md
- Frontend README: ./frontend/README.md
+9
View File
@@ -12,6 +12,15 @@ Write for church admins, not developers: no environment variables, endpoints or
developer log is CHANGELOG.md. A tagged version without a section here shows "No details given".
-->
## 2.2.0
- **AI use is now shown in tokens.** Site settings → AI shows how much of this month's AI allowance
your team has used, as input tokens (what's sent to the AI) and output tokens (its answers), with
an estimate of the whole allowance. The tables of who used it and for what show tokens too.
- **Behind the scenes:** Cross Events now lives alongside our other church products, so every
product is updated the same way. Your site works as before, and your data and settings stay as
they are.
## 2.1.1
- **Sending feedback forms and reminders no longer makes you wait.** "Send now" and "Remind" on the
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@crosscode/events-backend",
"version": "2.1.1",
"version": "2.2.0",
"description": "Event Management System Backend",
"main": "src/index.js",
"scripts": {
@@ -1,3 +1,3 @@
-- 2.3.0: tokens per AI call, which is what the site shows (the rand amount is the Hub's business).
-- 2.2.0: tokens per AI call, which is what the site shows (the rand amount is the Hub's business).
ALTER TABLE "AiCall" ADD COLUMN "inputTokens" INTEGER NOT NULL DEFAULT 0;
ALTER TABLE "AiCall" ADD COLUMN "outputTokens" INTEGER NOT NULL DEFAULT 0;
+2 -2
View File
@@ -2342,9 +2342,9 @@ model AiCall {
// ok, refused, incomplete, failed, cap_reached, unavailable
outcome String
// What the church was charged, in cents (fractions of a cent). Kept for the record; the site
// shows tokens (2.3.0), and only the Hub shows rand.
// shows tokens (2.2.0), and only the Hub shows rand.
chargedCents Float @default(0)
// Tokens the call used (2.3.0): input counts cached prompt tokens. 0 when the call failed.
// Tokens the call used (2.2.0): input counts cached prompt tokens. 0 when the call failed.
inputTokens Int @default(0)
outputTokens Int @default(0)
createdAt DateTime @default(now())
+2 -2
View File
@@ -1,7 +1,7 @@
/**
* AI helpers (2.0, roadmap §15). The site never holds a Claude API key: every call goes through
* the Cross Events Hub (docs/hub-protocol.md §3b), which checks the licence's monthly cap, calls
* Claude and meters the call. The site shows that use as tokens and a percentage (2.3.0); the cap's
* Claude and meters the call. The site shows that use as tokens and a percentage (2.2.0); the cap's
* rand amount stays on the Hub. This module:
* - works out what the AI buttons do (`aiStatus`): hidden, working, or disabled until the
* allowance renews — from the licence token first, then the Hub (cached for a minute);
@@ -35,7 +35,7 @@ export type HelperName = (typeof HELPERS)[number];
/**
* What the Hub says (§3b), as the site keeps it. The Hub also sends the allowance in rand
* (`capCents`, `usedCents`); the site drops those (2.3.0): people see tokens and a percentage,
* (`capCents`, `usedCents`); the site drops those (2.2.0): people see tokens and a percentage,
* and only the Hub shows rand. The token fields are null from a Hub before 2.0.1.
*/
export type HubAiStatus = {
+25 -13
View File
@@ -153,8 +153,12 @@ app.use((req, res, next) => {
// Licence suspended, revoked or missing: no new or edited events, registrations or payments (src/hub/readOnly.js).
app.use(require('./hub/readOnly').licenceReadOnly);
// Everything the backend serves is under /api (2.2.0), so the site and its API can share one
// address: the web server sends /api to the backend and everything else to the frontend. The old
// paths (/, /health, /docs/v2, /uploads) still work for sites with a separate API address.
// Health for monitoring (and the Hub): no secrets, no personal information.
app.get('/health', async (req, res) => {
app.get(['/api/health', '/health'], async (req, res) => {
const report = require('./hub/report');
let db = true;
try { await prisma.$queryRaw`SELECT 1`; } catch { db = false; }
@@ -174,11 +178,11 @@ app.use('/api/v2', linksRouter);
app.use('/api/v2', require('./v2').v2Router());
// Links in messages already sent: v1 addresses answer 308 with their v2 one.
app.use(legacyLinkRedirects);
app.use('/docs/v2', require('./v2').v2DocsRouter());
// v1 (/api/…) was removed in 2.0. Still answered: provider webhooks (above, and WAWP's old
// address) and links in messages already sent (308s above, a mail app's one-click POST here).
app.use('/api', legacyV1Router);
app.use('/api', v1Removed);
app.use('/api/docs/v2', require('./v2').v2DocsRouter());
app.get('/api/docs', (req, res) => res.redirect(301, '/api/docs/v2'));
// Before 2.2.0 the reference was at /docs/v2 (bookmarks, the old status page).
app.use('/docs/v2', (req, res) => res.redirect(301, `/api${req.originalUrl}`));
app.get('/docs', (req, res) => res.redirect(301, '/api/docs/v2'));
// Pre-warm the settings cache so synchronous helpers have DB values from startup
const { getSettingSync, warmCache } = require('./utils/settingsCache');
@@ -187,12 +191,16 @@ warmCache().catch(() => {});
// handlers. Serving them inline lets a compromised/malicious upload run script
// in the site's origin if opened directly, so pin the safe response headers
// (no inline execution, no MIME-sniffing to HTML/script) on every asset here.
app.use('/uploads', express.static('public/uploads', {
// Stored paths stay "/uploads/…"; they're given out as /api/uploads/… (v2/schemas.ts absoluteUrl).
// /uploads still answers for links made before 2.2.0.
const uploads = express.static('public/uploads', {
setHeaders: (res) => {
res.setHeader('Content-Security-Policy', "default-src 'none'; style-src 'unsafe-inline'; sandbox");
res.setHeader('X-Content-Type-Options', 'nosniff');
},
}));
});
app.use('/api/uploads', uploads, notFound); // a missing file is 404, not "API v1 removed"
app.use('/uploads', uploads);
// ── Shared page helpers ────────────────────────────────────────────────────────
@@ -268,8 +276,9 @@ app.get('/favicon.ico', (req, res) => {
res.sendFile(path.join(__dirname, '..', 'src', 'favicon.ico'));
});
// ── Root route — status page ────────────────────────────────────────────────
app.get('/', async (req, res) => {
// ── Status page, at /api (2.2.0); / sends you there ─────────────────────────
app.get('/', (req, res) => res.redirect(302, '/api'));
app.get('/api', async (req, res) => {
const mem = process.memoryUsage();
const uptimeSec = process.uptime();
const now = new Date().toISOString();
@@ -335,15 +344,18 @@ app.get('/', async (req, res) => {
</div>
<div class="note">
API documentation (OpenAPI) is at <a href="/docs/v2">/docs/v2</a> — it needs an admin account token.
API documentation (OpenAPI) is at <a href="/api/docs/v2">/api/docs/v2</a> — it needs an admin account token.
</div>
`);
res.send(html);
});
// /docs: the v1 reference went with v1 in 2.0; the API is documented at /docs/v2 (OpenAPI).
app.get('/docs', (req, res) => res.redirect(301, '/docs/v2'));
// v1 (/api/…) was removed in 2.0. Still answered: provider webhooks (above, and WAWP's old
// address) and links in messages already sent (308s above, a mail app's one-click POST here).
// Mounted after everything else under /api, since v1Removed answers 410 for any other /api path.
app.use('/api', legacyV1Router);
app.use('/api', v1Removed);
// Error middleware
app.use(notFound);
@@ -45,9 +45,10 @@ function toAbsoluteUrl(req, url) {
}
return raw; // keep as-is if already absolute and not localhost
}
// Relative path like /uploads/... => prefix with request origin
// Relative path like /uploads/... => prefix with request origin; uploads are served under
// /api/uploads (2.2.0) so they reach the backend when the site and API share one address
if (raw.startsWith('/')) {
return `${req.protocol}://${req.get('host')}${raw}`;
return `${req.protocol}://${req.get('host')}${raw.startsWith('/uploads/') ? `/api${raw}` : raw}`;
}
// Any other case, return as-is
return raw;
+1 -1
View File
@@ -269,7 +269,7 @@ async function sendPdf(toPhone, localPdfPath, filename, caption) {
`Set BACKEND_URL to your public backend URL (e.g. https://api.yourdomain.com) in your .env file.`
);
}
const pdfUrl = `${backendUrl}/uploads/tickets-temp/${tempName}`;
const pdfUrl = `${backendUrl}/api/uploads/tickets-temp/${tempName}`;
const { token, instanceId } = await getConfig();
try {
+3 -3
View File
@@ -43,7 +43,7 @@ export function v2Router(): Router {
}
/**
* /docs/v2: Swagger UI (served from swagger-ui-dist, nothing from a CDN). The page itself is
* /api/docs/v2 (2.2.0; /docs/v2 before, which now redirects): Swagger UI (served from swagger-ui-dist, nothing from a CDN). The page itself is
* public; it asks for an admin token and uses it to load openapi.json and to try requests.
*/
export function v2DocsRouter(): Router {
@@ -62,7 +62,7 @@ const DOCS_HTML = `<!doctype html>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Cross Events API v2</title>
<link rel="stylesheet" href="/docs/v2/assets/swagger-ui.css">
<link rel="stylesheet" href="/api/docs/v2/assets/swagger-ui.css">
<style>
body { margin: 0; font-family: system-ui, sans-serif; }
#login { max-width: 40rem; margin: 3rem auto; padding: 0 1rem; }
@@ -81,7 +81,7 @@ const DOCS_HTML = `<!doctype html>
<p class="err" id="err" role="alert"></p>
</main>
<div id="ui"></div>
<script src="/docs/v2/assets/swagger-ui-bundle.js"></script>
<script src="/api/docs/v2/assets/swagger-ui-bundle.js"></script>
<script>
(function () {
var params = new URLSearchParams(location.search);
+1 -1
View File
@@ -55,7 +55,7 @@ legacyV1Router.post('/privacy/unsubscribe/:token/one-click', express.urlencoded(
/** Any other v1 address: gone since 2.0 (410, pointing at v2). /api/v2 misses fall through to 404. */
export const v1Removed: RequestHandler = (req, res, next) => {
if (req.path === '/v2' || req.path.startsWith('/v2/')) return next();
res.status(410).json({ code: 'API_V1_REMOVED', message: 'API v1 was removed in Cross Events 2.0. Use /api/v2 — it is described at /docs/v2.' });
res.status(410).json({ code: 'API_V1_REMOVED', message: 'API v1 was removed in Cross Events 2.0. Use /api/v2 — it is described at /api/docs/v2.' });
};
export const legacyLinkRedirects: RequestHandler = (req, res, next) => {
+1 -1
View File
@@ -5,7 +5,7 @@ import { PATH_HELP, QUERY_HELP } from './docs';
/**
* The OpenAPI 3.1 document for /api/v2, built from the route declarations (route.ts), so it is
* always what the code does. Served at /api/v2/openapi.json, shown at /docs/v2.
* always what the code does. Served at /api/v2/openapi.json, shown at /api/docs/v2.
*/
type JsonSchema = Record<string, unknown>;
+9 -1
View File
@@ -14,12 +14,20 @@ export function iso(d: Date | string | null | undefined): string | null {
return d == null ? null : new Date(d).toISOString();
}
/**
* Where a stored upload path is served: "/uploads/…" (as stored) → "/api/uploads/…" (2.2.0), so it
* reaches the backend when the site and its API share one address. Anything else is unchanged.
*/
export function uploadPath(raw: string): string {
return /^\/uploads\//.test(raw) ? `/api${raw}` : raw;
}
/** A stored picture path ("/uploads/…") as an absolute URL on the host the request came to. */
export function absoluteUrl(req: Request, url: string | null | undefined): string | null {
const raw = String(url || '').trim();
if (!raw) return null;
if (/^https?:\/\//.test(raw)) return raw;
return `${req.protocol}://${req.get('host')}${raw.startsWith('/') ? '' : '/'}${raw}`;
return `${req.protocol}://${req.get('host')}${uploadPath(raw.startsWith('/') ? raw : `/${raw}`)}`;
}
export const campusRef = z.object({ id, name: z.string(), slug: z.string() });
+1 -1
View File
@@ -72,7 +72,7 @@ describe('status', () => {
expect(await aiStatus()).toMatchObject({ enabled: true, available: false });
});
test('the Hub\'s rand amounts never leave the site (2.3.0); a Hub before 2.0.1 sends no tokens', async () => {
test('the Hub\'s rand amounts never leave the site (2.2.0); a Hub before 2.0.1 sends no tokens', async () => {
mockPost.mockResolvedValueOnce(hubStatus());
const s = await aiStatus() as unknown as Record<string, unknown>;
expect(s).not.toHaveProperty('capCents');
+13 -3
View File
@@ -108,6 +108,7 @@ import { v2Router } from '../src/v2';
import { ServiceError } from '../src/services/errors';
import { routes } from '../src/v2/route';
import { buildOpenApi } from '../src/v2/openapi';
import { absoluteUrl, uploadPath } from '../src/v2/schemas';
const app = express();
app.use(express.json());
@@ -129,7 +130,7 @@ describe('GET /api/v2/events', () => {
expect(res.status).toBe(200);
expect(res.body.meta).toEqual({ page: 2, limit: 10, total: 31, pages: 4 });
expect(res.body.data[0]).toMatchObject({ id: 'e1', startDate: '2026-12-04T16:00:00.000Z', series: { slug: 'camps' } });
expect(res.body.data[0].pictureUrl).toMatch(/^http:\/\/127\.0\.0\.1:\d+\/uploads\/events\/camp\.jpg$/);
expect(res.body.data[0].pictureUrl).toMatch(/^http:\/\/127\.0\.0\.1:\d+\/api\/uploads\/events\/camp\.jpg$/);
const args = mockDb.event.findMany.mock.calls[0][0];
expect(args).toMatchObject({ skip: 10, take: 10 });
expect(args.where.AND).toEqual(expect.arrayContaining([{ isActive: true, isHidden: false, goLiveAt: { lte: expect.any(Date) } }, { title: { contains: 'camp', mode: 'insensitive' } }]));
@@ -424,7 +425,7 @@ describe('events (staff)', () => {
const res = await request(app).get('/api/v2/events/manage?past=true');
expect(res.status).toBe(200);
expect(res.body.data[0]).toMatchObject({ id: 'e1', isHidden: true, waitlistEnabled: true, startDate: '2026-12-04T16:00:00.000Z' });
expect(res.body.data[0].picture).toMatch(/^http:\/\/.*\/uploads\/events\/c\.jpg$/);
expect(res.body.data[0].picture).toMatch(/^http:\/\/[^/]+\/api\/uploads\/events\/c\.jpg$/);
expect(mockEvents.listManagedEvents).toHaveBeenCalledWith({ includePast: true, includeInactive: false, excludeClosed: false, campus: undefined }, expect.objectContaining({ scope: null }));
});
@@ -554,7 +555,16 @@ describe('sections, costs, image uploads', () => {
mockImage.file = { filename: 'event-123.jpg' };
const res = await request(app).post('/api/v2/uploads/event-image');
expect(res.body.data.path).toBe('/uploads/events/event-123.jpg');
expect(res.body.data.url).toMatch(/^http:\/\/.*\/uploads\/events\/event-123\.jpg$/);
expect(res.body.data.url).toMatch(/^http:\/\/[^/]+\/api\/uploads\/events\/event-123\.jpg$/);
});
test('stored uploads are given out under /api/uploads (2.2.0); other addresses are left alone', () => {
expect(uploadPath('/uploads/branding/logo.png')).toBe('/api/uploads/branding/logo.png');
expect(uploadPath('/api/uploads/x.png')).toBe('/api/uploads/x.png');
expect(uploadPath('/images/x.png')).toBe('/images/x.png');
const req = { protocol: 'https', get: () => 'events.church.co.za' } as unknown as Parameters<typeof absoluteUrl>[0];
expect(absoluteUrl(req, 'uploads/events/a.jpg')).toBe('https://events.church.co.za/api/uploads/events/a.jpg');
expect(absoluteUrl(req, 'https://cdn.example.org/uploads/a.jpg')).toBe('https://cdn.example.org/uploads/a.jpg');
});
test('branding images are for admins once accounts exist', async () => {
+7 -5
View File
@@ -1,7 +1,7 @@
import { test, expect, seed, API } from "./fixtures";
// /api/v2 (1.51.0) against the real server and database: paged public events, the v2 error
// shape, the signed-in person, and the OpenAPI reference at /docs/v2.
// shape, the signed-in person, and the OpenAPI reference at /api/docs/v2.
test.describe("API v2", () => {
test("public events come a page at a time; errors have a code", async ({ request }) => {
const res = await request.get(`${API}/api/v2/events?limit=2`);
@@ -99,9 +99,11 @@ test.describe("API v2", () => {
expect(ics.headers()["location"]).toBe(`/api/v2/events/${seed().events.conference}/calendar.ics`);
const followed = await request.get(`${API}/api/events/${seed().events.conference}/ics`);
expect(followed.headers()["content-type"]).toContain("text/calendar");
// The old API reference sends people to the v2 one.
// The old API reference addresses send people to the v2 one, under /api (2.2.0).
const docs = await request.get(`${API}/docs`, { maxRedirects: 0 });
expect(docs.headers()["location"]).toBe("/docs/v2");
expect(docs.headers()["location"]).toBe("/api/docs/v2");
const oldDocs = await request.get(`${API}/docs/v2?x=1`, { maxRedirects: 0 });
expect(oldDocs.headers()["location"]).toBe("/api/docs/v2?x=1");
});
test("staff list every event; supervisors create, change and admins deactivate", async ({ request }) => {
@@ -339,11 +341,11 @@ test.describe("API v2", () => {
expect((await request.get(`${API}/api/v2/admin/audit-log`, { headers: user })).status()).toBe(403);
});
test("an admin can read the OpenAPI reference at /docs/v2", async ({ page, request }) => {
test("an admin can read the OpenAPI reference at /api/docs/v2", async ({ page, request }) => {
const headers = { Authorization: `Bearer ${seed().users.user.token}` };
expect((await request.get(`${API}/api/v2/openapi.json`, { headers })).status()).toBe(403);
await page.goto(`${API}/docs/v2?token=${seed().users.admin.token}`);
await page.goto(`${API}/api/docs/v2?token=${seed().users.admin.token}`);
await expect(page.getByRole("heading", { name: /Cross Events API/ })).toBeVisible();
// Sections start collapsed (there are hundreds of endpoints): open Events.
await page.locator('h3.opblock-tag[data-tag="Events"]').click();
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@crosscode/events-frontend",
"version": "2.1.1",
"version": "2.2.0",
"private": true,
"scripts": {
"dev": "next dev",
+1 -1
View File
@@ -3,7 +3,7 @@ import type { V2Result } from "@/lib/apiV2";
/**
* AI helpers (2.0). The site calls AI through the Cross Events Hub, which keeps a monthly
* allowance per licence, shown here as tokens and a percentage (2.3.0). One status per page load is shared by every AI button
* allowance per licence, shown here as tokens and a percentage (2.2.0). One status per page load is shared by every AI button
* (`useAiStatus`), and every helper call refreshes it — so the buttons disable straight after the
* call that used up the allowance.
*/
+4 -1
View File
@@ -72,7 +72,10 @@ export function resolveToApiOrigin(urlOrPath: string | null | undefined): string
} catch {
// fall through to relative handling
}
return API_BASE ? `${API_BASE}${raw}` : raw;
// Stored uploads ("/uploads/…") are served under /api/uploads (2.2.0), so they reach the
// backend when the site and its API share one address.
const path = raw.startsWith("/uploads/") ? `/api${raw}` : raw;
return API_BASE ? `${API_BASE}${path}` : path;
}
// The parsed JSON body of a failed request — v1 sends `message` (some routes add a
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@crosscode/events",
"version": "2.1.1",
"version": "2.2.0",
"main": "index.js",
"scripts": {
"dev:backend": "cd backend && npm run dev",
+7 -5
View File
@@ -177,8 +177,9 @@ monorepo, listing every variable with its layer, whether it's required, and a de
itself.
- **URLs are checked before and after.** Before: the form checks that the domain's DNS points at
the central server and warns if not (the install still runs). After Joshua marks the proxy done:
the Hub checks `https://<domain>/` (frontend answers), `https://<domain>/health` (backend
answers with the right version) and that `/health` reports the `FRONTEND_URL` it was given.
the Hub checks `https://<domain>/` (frontend answers), `https://<domain>/api/health` (backend
answers with the right version; `/health` before Events 2.2.0) and that it reports the
`FRONTEND_URL` it was given.
**For Joshua to set per server before the first install:** the database settings and
`TRUST_PROXY`. Behind frp the app sees every connection from frpc on `127.0.0.1`, and the
@@ -375,7 +376,8 @@ Set up in FastPanel: events.hope.co.za (Hope Family Church, Cross Events)
1. Add the site events.hope.co.za.
2. Proxy:
/api, /uploads, /health, /docs → http://127.0.0.1:20011 (backend)
/api → http://127.0.0.1:20011 (backend; Events 2.2.0+, older
releases also need /uploads, /health, /docs)
everything else → http://127.0.0.1:20010 (frontend)
Pass the Host header and X-Forwarded-For / X-Forwarded-Proto: https.
Allow uploads up to 25 MB.
@@ -395,7 +397,7 @@ Central check: both ports are open in frps and only on 127.0.0.1.
(lib/env.sh), ports given on the command line instead of picked.
- `apps/events`: `env.template.json`, and the export (`crosscode export` calls a backend script
that writes `crosscode.church-export/1`).
- `packages/contracts` **1.2.0**: `crosscode.agent-job/1`, `crosscode.agent-report/1`,
- `packages/contracts` **1.3.0** (1.2.0 went out with Events 2.2.0): `crosscode.agent-job/1`, `crosscode.agent-report/1`,
`crosscode.agent-stats/1`, `crosscode.env-template/1`, `crosscode.church-export/1`.
**`events-hub` (Hub 2.1.0)**
@@ -439,7 +441,7 @@ Central check: both ports are open in frps and only on 127.0.0.1.
## 14. Rolling it out
1. Contracts 1.2.0 → the `crosscode` script changes (with Events 2.2.0 out first) → agent 1.0.0
1. Contracts 1.3.0 → the `crosscode` script changes (with Events 2.2.0 out first) → agent 1.0.0
→ Hub 2.1.0, each released as usual (branch → merge → tag → push).
2. On the central server: add `proxy_bind_addr = 127.0.0.1` to `frps.ini` if it's missing (check
that each FastPanel site still answers), then join the central agent.
+3 -3
View File
@@ -25,9 +25,9 @@ for each phase. They moved here from `hope-events/docs/` on 2026-11-05.
|-------|------|-------|
| 0 | contracts 1.0.0 / 1.1.0 | **Released** 2026-11-04 (`contracts@1.0.0`, `contracts@1.1.0`). Not published to a registry (decision 22): the Hub gets a packed release committed to its repo |
| 1 | Hub 2.0.0 | **Released** 2026-11-05 (`events-hub` `v2.0.0`; `docs/HUB-2.0-PLAN.md` there). **Not deployed yet:** `events-hub/deployment.md` → "Upgrading to 2.0" (run `check-hub2` first). crosscode-site's address prices are merged, **not deployed yet** |
| 1b | Cross Events 2.2.0: moves here as `apps/events`, `crosscode` script | **In progress.** Planned in [EVENTS-2.2-PLAN.md](./EVENTS-2.2-PLAN.md). **Steps 1–3 done 2026-11-12** (merged into `main`): history merged in under `apps/events` (from `hope-events` `e6c9670`), workspaces and one root lockfile with versions pinned to 2.1.1, same test results as 2.1.1 (711 backend tests, typecheck, both builds). **The `crosscode` script and `adopt` (§4–5) are written** (branch `feat/crosscode-script`, 2026-11-12; shellcheck and 47 bats tests pass, not yet run on a server). **Still to do:** VM testing (§6), the version bump and `events@2.2.0` tag, adopting each install, archiving `hope-events` (§7). Until then servers keep deploying from `hope-events` `v2.1.1`, and **Events work happens here** (`hope-events` is frozen; a hotfix there as 2.1.2 is cherry-picked into `apps/events`) |
| 1c | Cross Events 2.3.0: authenticator app 2FA (TOTP + recovery codes) | Not started (`TwoFactorMethod` enum in Events' `prisma/schema.prisma`) |
| 1d | Agent 1.0.0 + Hub 2.1.0 (+ contracts 1.2.0): server agent, installs / scheduled updates / uninstalls from the Hub, server stats | **Planned** 2026-11-12 in [AGENT-1.0-PLAN.md](./AGENT-1.0-PLAN.md) (ROADMAP decisions 27–37). Starts after 1b; can run alongside 1c |
| 1b | Cross Events 2.2.0: moves here as `apps/events`, `crosscode` script | **In progress.** Planned in [EVENTS-2.2-PLAN.md](./EVENTS-2.2-PLAN.md). **Steps 1–3 done 2026-11-12** (merged into `main`): history merged in under `apps/events` (from `hope-events` `e6c9670`), workspaces and one root lockfile with versions pinned to 2.1.1, same test results as 2.1.1 (711 backend tests, typecheck, both builds). **The `crosscode` script and `adopt` (§4–5) are written** (branch `feat/crosscode-script`, 2026-11-12; shellcheck and 47 bats tests pass, not yet run on a server). **Tagged `events@2.2.0` on 2026-11-17, before the VM testing (Joshua's call), with two additions: AI use in tokens and the backend under `/api` (Hub `v2.0.1` and crosscode-site `v1.2.0` released with them).** **Still to do:** VM testing (§6) of the tagged release, adopting each install, archiving `hope-events` (§7). Until then servers keep deploying from `hope-events` `v2.1.1`, and **Events work happens here** (`hope-events` is frozen; a hotfix there as 2.1.2 is cherry-picked into `apps/events`) |
| 1c | Cross Events 2.3.0: authenticator app 2FA (TOTP + recovery codes) | TOTP not started (`TwoFactorMethod` enum in Events' `prisma/schema.prisma`). |
| 1d | Agent 1.0.0 + Hub 2.1.0 (+ contracts 1.3.0): server agent, installs / scheduled updates / uninstalls from the Hub, server stats | **Planned** 2026-11-12 in [AGENT-1.0-PLAN.md](./AGENT-1.0-PLAN.md) (ROADMAP decisions 27–37). Starts after 1b; can run alongside 1c |
| 2 | Cross Events 2.4.0: protocol v2, Linked products, event feed, `packages/seo` | Not started. Events keeps speaking protocol 1 until then |
| 3–7 | Accounts 1.0.0 → Website 1.0.0 → Events 3.0.0 → App 1.0.0 → App 1.x | Not started |
+5 -5
View File
@@ -613,9 +613,9 @@ Planned in [AGENT-1.0-PLAN.md](./AGENT-1.0-PLAN.md). In short:
|-------|---------|------|----------------|
| 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). **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 |
| 1d | **Agent 1.0.0 + Hub 2.1.0** (contracts 1.2.0) | **Server agent** on every server (polls only, signed jobs, runs the `crosscode` script); Hub: Servers page with stats and alerts, server configuration, frp port list, New install with a choice of server, scheduled / emergency / batch updates with notice to the church, uninstall with an encrypted JSON export, emailed reports. [AGENT-1.0-PLAN.md](./AGENT-1.0-PLAN.md) | Right after 1b (it runs the `crosscode` script), so every new church from then on is installed from the Hub. Can run alongside 1c |
| 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. Planned with no feature changes; two small ones were added on 2026-11-17 (decided by Joshua): **AI use shown in tokens**, never rand, outside the Hub (needs Hub 2.0.1), and **everything the backend serves under `/api`**, so a site and its API share one address and one proxy rule. **Tagged 2026-11-17, before the VM testing** | 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 |
| 1d | **Agent 1.0.0 + Hub 2.1.0** (contracts 1.3.0) | **Server agent** on every server (polls only, signed jobs, runs the `crosscode` script); Hub: Servers page with stats and alerts, server configuration, frp port list, New install with a choice of server, scheduled / emergency / batch updates with notice to the church, uninstall with an encrypted JSON export, emailed reports. [AGENT-1.0-PLAN.md](./AGENT-1.0-PLAN.md) | Right after 1b (it runs the `crosscode` script), so every new church from then on is installed from the Hub. Can run alongside 1c |
| 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 |
| 3 | **Accounts 1.0.0** | OIDC provider, sign-in, 2FA (email, WhatsApp, authenticator app), password reset, consent and notice, export / delete fan-out, admin, install script | The Website is built on it from day one |
| 4 | **Church Website 1.0.0** | Public site with the **four templates** (§6), admin, simple events + feed, SEO (§11), Hope Family Church as the first church, then a second test church on a different template to prove it repeats | More churches need a website than an app; it also covers the "website only" case |
@@ -636,8 +636,8 @@ At the end of each phase, update it in the same sitting and deploy it (its `DEPL
|-------|--------------------------------|
| 0 contracts | Nothing |
| 1 Hub 2.0.0 | Bundle discounts (15% / 25%) and the address add-on (own domain R0 · Cross Code address R10 · domain included R25) in `src/data/pricing.mjs`, worded so it's clear the Website and App are still coming. Legal pages if billing terms change |
| 1b Events 2.2.0 | Nothing (the move doesn't change what Cross Events does) |
| 1c Events 2.3.0 | Authenticator app 2FA in the Cross Events feature list (`src/data/cross-events.mjs`) and the security / POPIA wording |
| 1b Events 2.2.0 | The AI allowance in tokens instead of rand (`src/data/cross-events.mjs`, the brochure). Done in crosscode-site 1.2.0 |
| 1c Events 2.3.0 | Authenticator app 2FA in the Cross Events feature list (`src/data/cross-events.mjs`) and the security / POPIA wording. |
| 1d Agent 1.0.0 + Hub 2.1.0 | Nothing (it changes how installs are run, not what churches buy) |
| 2 Events 2.4.0 | "Works with the Church Website and App" (event feed, Linked products) on the Cross Events page, as "coming" until those ship |
| 3 Accounts 1.0.0 | "One sign-in for all your church's products" on the Products page. Accounts isn't sold, so no page or price of its own |
+2 -2
View File
@@ -214,14 +214,14 @@ X-Hub-Install / X-Hub-Timestamp / X-Hub-Signature (as in §3)
active (suspended, revoked, or past its grace days), or the Hub's AI isn't set up.
- **`capReached: true`** — show the buttons **disabled** ("This month's AI allowance is used up — it
renews on 1 December"). Reached means there isn't room left for even a small call.
- **Churches see tokens, never rand** (Hub 2.0.1, Cross Events 2.3.0). `usedInputTokens` /
- **Churches see tokens, never rand** (Hub 2.0.1, Cross Events 2.2.0). `usedInputTokens` /
`usedOutputTokens` are this month's tokens over all the church's installs (input counts cached
prompt tokens). `capInputTokens` / `capOutputTokens` are an **estimate** of the allowance: what half
the cap buys as input and half as output, at the current model price, exchange rate and markup,
rounded down to a thousand. `usedPercent` is exact (it's worked out in rand). Installs show the
tokens and the percentage, and don't pass the cents on.
- `capCents` / `usedCents` are cents (rand) as **charged** to the church, with fractions (a call costs
a fraction of a cent), for the Hub and for installs before Cross Events 2.3.0. The month is South
a fraction of a cent), for the Hub and for installs before Cross Events 2.2.0. The month is South
African time; `renewsOn` is the 1st of the next month.
### A helper call
+3 -3
View File
@@ -44,7 +44,7 @@
},
"apps/events/backend": {
"name": "@crosscode/events-backend",
"version": "2.1.1",
"version": "2.2.0",
"hasInstallScript": true,
"dependencies": {
"@cj-tech-master/excelts": "^10.2.0",
@@ -91,7 +91,7 @@
},
"apps/events/frontend": {
"name": "@crosscode/events-frontend",
"version": "2.1.1",
"version": "2.2.0",
"dependencies": {
"@dnd-kit/core": "^6.3.1",
"@hookform/resolvers": "^5.2.1",
@@ -19633,7 +19633,7 @@
},
"packages/contracts": {
"name": "@crosscode/contracts",
"version": "1.1.0",
"version": "1.2.0",
"license": "UNLICENSED",
"dependencies": {
"zod": "^4.6.7"
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@crosscode/contracts",
"version": "1.1.0",
"version": "1.2.0",
"description": "The shared JSON formats used by every Cross Code product: zod schemas, JSON Schema, TypeScript types and sample payloads",
"license": "UNLICENSED",
"type": "commonjs",