Files
crosscode-platform/packages/contracts/README.md
T
joshuaandClaude Opus 5.5 19f79dfb17 Monorepo set up: workspaces, contracts package, placeholders
npm workspaces (packages/*, apps/*) with shared TypeScript, ESLint and
Jest setup and `npm run check`. @crosscode/contracts builds to CommonJS
and ESM (tsup) with the crosscode.<name>/<major> schema-name helpers.
packages/ui and apps/{accounts,website,app} are placeholders.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 09:36:42 +02:00

37 lines
1.6 KiB
Markdown

# @crosscode/contracts
Everything that crosses between Cross Code products is defined once, here (ROADMAP-v3 §2):
zod schemas, generated JSON Schema, TypeScript types and sample payloads. Every product, including
Cross Events and the Hub, uses it, so the key fields are the same in every product's JSON.
| Contract | Used for | Status |
|----------|----------|--------|
| `crosscode.event/1` | The event feed every product publishes and reads | To do |
| `crosscode.church/1` | The church profile: name, logo, colours, campuses, service times, contact details | To do |
| `crosscode.identity/1` | Accounts' sign-in token claims and back-channel calls (`user.updated`, `user.deleted`, `user.export`) | To do |
| Hub protocol v3 | Register, heartbeat, licence token, AI calls, for every product | To do |
## Versioning
- Every payload carries its `schema` name: `crosscode.<name>/<major>`.
- Adding an **optional** field keeps the version. Consumers ignore fields they don't know.
- Removing or renaming a field, or changing its meaning, needs a new major (`/2`). The old one
is served alongside it until every install has updated.
```ts
import { parseSchemaName, isSchema } from "@crosscode/contracts";
parseSchemaName("crosscode.event/1"); // { name: "event", major: 1 }
isSchema(payload.schema, "event", 1); // true / false
```
## Installing
Published to Gitea's package registry. In the consuming repo's `.npmrc`:
```
@crosscode:registry=https://c-git.crosscode.co.za/api/packages/joshua/npm/
```
Works with both `require` (Cross Events backend, Hub) and `import` (Next.js apps).