@igo/platform-contracts

Shared event contracts and REST API request/response types for the IGO Platform. This is the single source of truth igo-platform-api, igo-platform-web, and igo-platform-admin all consume — when an endpoint or event payload changes, the version here bumps and every consumer upgrades explicitly, per the platform's repo-isolation rule (frontends never import backend code; this package is the only thing that crosses the boundary).

Structure

src/
  events/             Zod-validated domain event envelopes/payloads (in-process EventEmitter2 today,
                       a real broker later — this package doesn't change either way)
  api/
    tenancy/          Wire types for the tenancy module's REST endpoints (auth, tenants, businesses)

Each future backend module (accounting, hrms, billing, platform) gets its own src/api/<module>/ namespace here as it's built — never duplicated across modules, per the platform's module-uniqueness rule.

Why Zod for events, plain types for API DTOs

Events cross a process/transport boundary with no compiler in between, so a malformed or stale-version payload needs a runtime check — Zod gives that in the same place the type is defined. REST DTOs are checked at the boundary by the server's own class-validator DTOs (which must stay structurally compatible with these) and by TypeScript at the call site in each frontend, so a second runtime validation layer here isn't buying anything extra.

Consuming this package

Not yet published to a real registry — publishConfig.access: "restricted" is set for when it is (a private npm org, per the platform's infra decisions), but until then, consumers use a local file/link dependency pointing at this sibling folder:

{ "dependencies": { "@igo/platform-contracts": "file:../igo-platform-contracts" } }

Run pnpm build here after any change — consumers resolve dist/, not src/, so a local-link consumer won't see an edit until it's rebuilt (pnpm dev runs tsc --watch for this while you're actively changing contracts alongside a consumer).

Versioning

Bump version in package.json for any breaking change to an existing type or event payload; additive changes (a new optional field, a new event) don't require a bump but should still get one to keep consumers' lockfiles honest about what they're actually running against once this is on a real registry.