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.

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

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.

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

See docs/README.md for usage detail, docs/ONBOARDING.md for setup, and architecture/SAD.md plus 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.