@vessyl/vessyl-app-contracts

Canonical API contract for the Vessyl application: the Zod schemas and TypeScript types shared by the Vessyl API (vessyl~vessyl-app-api) and every client that talks to it. This package is the single source of truth for wire shapes — a change here is a change to the public contract.

Extracted from the pre-rebuild Vessyl monorepo, where it lived as the private workspace package @packages/contracts.

The repository and package are public. Consumers can install the package from the Vessyl public Forgejo registry without an access token.

Structure

src/
  index.ts            Barrel re-export of the consumer-facing surface
  admin.ts            Admin surface, kept out of the consumer barrel on purpose
  auth/               Authentication flows: login, register, OAuth, email
  booking/            Visit reservations and availability
  catalog/            Static catalog data: themes, reports, connections, transits, locales
  charts/             Chart CRUD, chapters, bodygraph, runtime, key events
  common/             Canonical transport primitives: Problem Details, correlation,
                      ResourceRef/SourceRef, Operation, idempotency, cursor pages,
                      locale/timezone/temporal/money/version laws
  contract-example/   Worked example for new contributors
  events/             Domain and canonical event types
  fixtures/           Consumer/admin/operator compile-isolation fixtures
  home/               Home dashboard, compute state, sections, advice
  identity/           Identity and profile shapes
  journal/            Calendar entries, notes, events
  notifications/      Notification payloads
  onboarding/         Onboarding flow, context, city suggestions
  ops/                Operational surfaces
  premium/            Premium reports, purchases, entitlements, webhooks
  progress/           Reading progress overview and detail cards
  relationships/      Relationship CRUD, picker, overview, detail
  search/             Search queries and results
  tarot/              Tarot spreads, cards, interpretation, history
  transits/           Transit details, overlays, surface navigation

Conventions

• Types use export interface or export type with JSDoc descriptions and field-level comments.
• Schemas use strict Zod runtime validation; canonical TypeScript types are inferred from those schemas.
• Naming: *.types.ts for TypeScript types, *.schemas.ts for Zod schemas, index.ts for barrel re-exports.
• Canonical imports: audience contracts import shared primitives from the package root and never import another audience's operations.
• Migration boundary: permissive predecessor types and helpers stay out of the package root and must not enter generated artifacts.

Usage

The package ships TypeScript sources and is consumed by Bun directly. zod is a peer dependency — the consumer owns the version.

import { type CreateChartRequest, createChartRequestSchema } from '@vessyl/vessyl-app-contracts'

// API: validate an incoming request
const body = createChartRequestSchema.parse(request.body)

// Client: type-safe calls
const response = await api.post('/api/ui/charts', data satisfies CreateChartRequest)

Subpaths resolve to modules under src/:

import { canonicalEventTypes } from '@vessyl/vessyl-app-contracts/events/canonical-event-types'
import { consumerFixture } from '@vessyl/vessyl-app-contracts/fixtures/consumer.fixture'

Commands

bun run verify        # test + typecheck + lint
bun run test
bun run typecheck
bun run lint
bun run lint:fix