updating api docs

apps/www/src/docs.ts

@@ -21,6 +21,11 @@ export const DOCUMENTED_SERVICES: ReadonlyArray<{ slug: string; title: string }>
 	{ slug: 'accounts', title: 'accounts — profiles & lookups' },
 	{ slug: 'match', title: 'match — matchmaking & presence' },
 	{ slug: 'econ', title: 'econ — avatar & economy' },
+	{ slug: 'clubs', title: 'clubs — clubs & clubhouses' },
+	{ slug: 'chat', title: 'chat — threads & messages' },
+	{ slug: 'img', title: 'img — image serving & resizing' },
+	{ slug: 'storage', title: 'storage — uploads to the CDN bucket' },
+	{ slug: 'playersettings', title: 'playersettings — per-player settings' },
 	{ slug: 'api', title: 'api — everything else' },
 ]
 
@@ -46,9 +51,13 @@ function overviewSpec(): Record<string, unknown> {
 		'---',
 		'',
 		'These specs are **descriptive, not enforced** — they document a protocol',
-		'reverse-engineered from the game client (the only real consumer), so a field',
-		'marked required means "the client always sends it", not "the server rejects it if',
-		'absent". Each service also serves its own spec at `https://<service>.<domain>/openapi.json`.',
+		'reverse-engineered from the game client (the only real consumer). They record',
+		'observed behaviour, not a designed contract, and the handlers are lenient: they',
+		'parse bodies defensively rather than rejecting them. So a field marked required',
+		'means "the client always sends it", not "the server rejects it if absent".',
+		'',
+		'This applies to every service below; the individual specs don’t repeat it. Each',
+		'service also serves its own spec at `https://<service>.<domain>/openapi.json`.',
 	].join('\n')
 	return {
 		openapi: '3.1.0',

apps/www/src/test/integration/api.test.ts

@@ -1,6 +1,8 @@
 import { SELF } from 'cloudflare:test'
 import { expect, it } from 'vitest'
 
+import { DOCUMENTED_SERVICES } from '../../docs'
+
 it('rejects unauthenticated account reads', async () => {
 	const res = await SELF.fetch('https://example.com/api/me')
 	expect(res.status).toBe(401)
@@ -54,7 +56,9 @@ it('serves the aggregated docs page with a source per documented service', async
 	const html = await res.text()
 	// Mounts the self-hosted Scalar bundle (not a CDN) and lists every service's spec.
 	expect(html).toContain('/docs/scalar.standalone.js')
-	for (const slug of ['auth', 'accounts', 'match', 'econ']) {
+	// Driven off the constant so adding a service can't leave the page (or this test)
+	// behind.
+	for (const { slug } of DOCUMENTED_SERVICES) {
 		expect(html).toContain(`/docs/openapi/${slug}.json`)
 	}
 })