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>
37 lines
1.6 KiB
Markdown
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).
|