# @oo/shared-types

Canonical contracts for all inter-module communication. Two surfaces:

| Surface | Format | Location |
|---------|--------|----------|
| HTTP (sync) | OpenAPI / TypeScript interfaces | `src/http/` |
| Events (async) | Protocol Buffers + TS interfaces | `src/events/`, `events/` |

## HTTP types

Hand-written TypeScript interfaces generated from OpenAPI specs. Imported by
`services/api`, `apps/web`, and `ml/serving` (Python hand-mirrors).

| File | Types |
|------|-------|
| `src/http/tip.ts` | `TipCandidate`, `RecommendResponse`, `TipFeedback` |
| `src/http/auth.ts` | `SessionUser` |
| `src/http/integrations.ts` | `IntegrationsResponse`, `Integration` |
| `src/http/user.ts` | `UserProfile` |
| `src/http/signal.ts` | `Signal`, `SignalSource` |

## Event types

Protobuf schemas live in `events/oo/events/v1/`. TypeScript interfaces in
`src/events/index.ts` mirror the proto envelope and payload types.

| Proto file | Messages |
|------------|----------|
| `envelope.proto` | `Envelope` (wraps every event) |
| `signals.proto` | `TaskSyncedPayload`, `TipServedPayload`, `TipFeedbackPayload`, `TipRewardFailedPayload` |
| `integration.proto` | `IntegrationTokenExpiredPayload` |

**Schema evolution rules (ADR-0005):**
- Additive changes only within a version (new fields, new message types).
- Removed fields must be marked `reserved` — never reuse a field number.
- Breaking changes require a new package version (`oo.events.v2`) and a `schemaVersion` bump in the envelope.

## Schema registry / CI gate

`buf` enforces lint and breaking-change detection on every PR that touches `events/`:

```bash
# Lint
buf lint events/

# Breaking-change check against main
buf breaking events/ --against '.git#branch=main,subdir=packages/shared-types/events'
```

Local shortcut: `./scripts/buf-check.sh`

CI: `.gitea/workflows/buf-check.yaml` (requires a Gitea Actions runner).

Install buf: `curl -sSfL https://github.com/bufbuild/buf/releases/latest/download/buf-Linux-x86_64 -o /usr/local/bin/buf && chmod +x /usr/local/bin/buf`

## Contract

`/health` — not applicable (library package, no process).

**Extraction criteria** — always a shared library. Extract to a separate registry
service only when schema governance requires independent versioning and deployment
(e.g. external consumers, SLA divergence from the monorepo).