# LivDot Shared Contracts
Central contract repository for schemas and shared API-facing types used across the LivDot platform.
## Purpose
This repository exists to keep backend, frontend, and mobile aligned on the same contract surface without coupling the codebases into a monorepo.
It is the single shared source for:
- request and response schemas
- domain enums and state constants
- canonical error codes
- shared DTOs and validation rules
- other API-boundary definitions that must remain consistent across services and clients

## Repositories That Consume This Package
- `livdot-backend`
- `livdot-frontend`
- `livdot-mobile`

## What Belongs Here 
Only cross-stack contract artifacts.
Examples:
- `CreateEventRequest`
- `BookingState`
- `EventState`
- `ApiErrorCode`
- Zod schemas for payload validation
- shared auth/token payload shapes where applicable

## What Must Not Be Added Here
This repository is **not** a dumping ground for shared code.
Do **not** add:
- backend business logic
- ORM/database models
- repositories/services/use-cases
- frontend UI components
- mobile-specific runtime code
- infrastructure or deployment logic
- utilities that are not part of a cross-stack contract
If it is not part of the contract boundary, it does not belong here.

## Ownership
The backend remains the authority on system behavior and API truth.
This repository defines the **contract shape**, not the implementation or business logic.

## Versioning
Releases are automated. `semantic-release` reads Conventional Commit messages on `main` and decides
the bump, writes `CHANGELOG.md`, tags, and publishes to npm. **Do not edit the `version` field in
`package.json` by hand** — CI owns it.

The commit prefix determines the bump:
- `fix:` → **PATCH**, backward-compatible fixes
- `feat:` → **MINOR**, backward-compatible additions
- `feat!:` or a `BREAKING CHANGE:` footer → **MAJOR**

Because the bump is derived from the commit message rather than from schema diffing, a breaking
change committed as `fix:` will ship as a patch. Field removals and renames must carry the breaking
marker.

Consumers pin a caret range and upgrade through review.

## Change Rules
Any contract change must be treated carefully because it can affect multiple codebases.
Before merging a change:
1. confirm the change is truly cross-stack
2. identify whether it is breaking or non-breaking
3. update version appropriately
4. document migration notes if consumers need code changes

## Structure
One folder per domain, each exporting `*.enums.ts`, `*.schemas.ts` and `*.types.ts` through an
`index.ts` barrel.

```text
src/
  auth/          user/          event/
  booking/       marketplace/   joblisting/
  host/          moment/        chat/
  payment/       streaming/     dispute/
  notification/  common/        errors/
  index.ts       # master barrel
```

`common/` holds `CurrencyEnum`, pagination, audit enums and `ResponseMessages`; `errors/` holds the
`ApiErrorCode` catalogue; `booking/` additionally owns `booking-state-machine.ts` — the valid
transitions, per-transition actor RBAC, and which target states require a `reason`.

Adding a domain means three edits: create the folder with its `index.ts`, re-export it from
`src/index.ts`, **and add it to the `entry` array in `tsup.config.ts`** — miss the last one and the
`@livdot-tech/contracts/<domain>` subpath resolves to nothing.

## Installation and Usage

```bash
npm install @livdot-tech/contracts zod
```

`zod` is a **peer dependency**, not bundled — the package has zero runtime dependencies, and keeping
Zod on the consumer side means there is only ever one Zod instance in play.

```ts
import { BookingState, CurrencyEnum } from '@livdot-tech/contracts';
import { VALID_BOOKING_TRANSITIONS } from '@livdot-tech/contracts/booking';
```

See [docs/README.md](./docs/README.md) for usage detail, [docs/ONBOARDING.md](./docs/ONBOARDING.md)
for setup, and [architecture/SAD.md](./architecture/SAD.md) plus
[architecture/decisions/](./architecture/decisions/) for the design decisions.

## Goal

Keep contracts explicit, versioned, and stable.

This repository exists to improve consistency across backend, frontend, and mobile while preserving clear ownership boundaries between the separate LivDot codebases.