majestic-api-contracts

Purpose

This repository defines the wire contract. It does not define server behavior.

It defines API response shapes only for Majestic. Response shapes are versioned here so that majestic-server and clients share a single contract. Silent drift becomes impossible; CI can enforce parity.

Scope

Shapes only. This package exports:

• Types and discriminated unions
• JSON schemas
• Versioning rules

Non-Responsibilities

This repository must NOT include:

• Database logic
• Streaming logic
• ffmpeg logic
• Prewarm orchestration
• Business logic
• HTTP handlers

Only types, schemas, discriminated unions, and versioning rules.

Exports

Module	Contents
version	CONTRACT_VERSION, API_CONTRACT_VERSION
playbackPrediction	PlaybackPrediction union
incompatibility	Incompatibility, IncompatibilityType
prewarm	PrewarmGetResponse, PrewarmDeleteResponse
apiError	ApiError discriminated union
responseEnvelope	ApiSuccessEnvelope, ApiErrorEnvelope

Contract Versioning Rules

No URL versioning. Server and client move together. contract_version exists for visibility and guardrails only.

SemVer Bump Rules

Change	Bump
Major	Field removed, field renamed, type changed incompatibly, enum value removed, additionalProperties tightened
Minor	New optional field added, new enum value added
Patch	Description changes, documentation-only changes

Compatibility Guarantees

• Removing a field → breaking
• Renaming a field → breaking
• Changing a discriminant value → breaking
• Adding a new optional field → allowed (minor)
• Adding a new required field → breaking

Breaking-Change Rules

1. Removed fields require a major version bump.
2. Renamed fields require a major version bump.
3. Discriminant changes (e.g. adding/removing union members, changing status or type values) require a major version bump.
4. New required fields require a major version bump.
5. Optional new fields are allowed in minor versions.

Contract Hash Enforcement

CI enforces that schema changes require a version bump. No exceptions.

How It Works

1. pnpm run generate produces dist/contract.bundle.json — a canonical, deterministic aggregate of all schemas (sorted keys, no whitespace variance).
2. pnpm run check:hash computes SHA-256 of the bundle and compares against contract-hashes.json.
3. If CONTRACT_VERSION exists in the hash map and the computed hash differs → CI fails.
4. If CONTRACT_VERSION does not exist in the hash map → CI fails (add the new version and hash manually).

When You Bump the Version

1. Update CONTRACT_VERSION in src/version.ts.
2. Run pnpm run generate.
3. Run pnpm run check:hash — it will fail and print the hash to add.
4. Add the entry to contract-hashes.json:

   "1.1.0": "sha256-<hash-from-output>"

CONTRACT_VERSION is no longer ceremonial. It is enforced identity.

Contract-critical: scripts/generate.mjs canonicalization logic is part of contract identity. Changes to key ordering, array handling, or determinism rules will change the hash. Review changes carefully. tests/canonicalization.test.ts enforces determinism in CI.

Pre-commit Hook

A husky pre-commit hook runs check:hash, stages generated/, contract.json, and contract.bundle.json, then runs check and test. This ensures generated artifacts are always fresh before commit. Runs automatically after pnpm install (via prepare script).

Contract Manifest and Site

generate also produces contract.json (version, hash, schema index, endpoint map) and copies contract.bundle.json to root. These power the contract authority site at majesticcore.dev, which surfaces identity, endpoint mapping, schema descriptions, and bundle download.

Endpoint map is derived from x-endpoints in each schema. Add "x-endpoints": ["GET /path", "DELETE /path"] to a schema to declare which endpoints return that shape. No manual manifest maintenance.

Warning Against Logic Creep

Do not add logic to this package. It defines shapes only. If you need to:

• Validate at runtime → use the JSON schemas in your consumer.
• Compute playback prediction → implement in majestic-server.
• Evaluate compatibility → implement in majestic-server.

This package is consumed; it does not orchestrate.

Relationship to majestic-server

• majestic-server implements the API and returns responses that conform to these shapes.
• Server consumes this package; it does not define shapes inline.
• When extracting new shapes from server, reconstruct shapes manually by inspecting server code. Do not import server code into this package.

Relationship to Client Apps

• majestic-appletv, majestic-roku, majestic-tizen, etc. consume these types for type-safe API handling.
• Clients must consume from this package; no ad-hoc types.
• All clients and server share the same contract version.

Structure

majestic-api-contracts/
├── src/
│   ├── version.ts
│   ├── playbackPrediction.ts
│   ├── incompatibility.ts
│   ├── prewarm.ts
│   ├── apiError.ts
│   ├── responseEnvelope.ts
│   ├── index.ts
├── schemas/
│   ├── incompatibility.schema.json
│   ├── prewarm.schema.json
│   ├── apiError.schema.json
│   └── ...
├── scripts/
│   ├── generate.mjs
│   └── check-hash.mjs
├── .husky/
│   └── pre-commit
├── contract-hashes.json    # SHA-256 per CONTRACT_VERSION (CI enforcement)
├── contract.json           # Manifest for site (version, hash, schemas, endpoint map)
├── contract.bundle.json    # Canonical bundle for site download
├── index.html              # Contract authority site
├── package.json
├── tsconfig.json
└── README.md

Dependencies

None (leaf contract package). Dev dependencies: TypeScript, Vitest, Ajv.

Usage

import {
  CONTRACT_VERSION,
  type PlaybackPrediction,
  type Incompatibility,
  type PrewarmGetResponse,
  type ApiError
} from 'majestic-api-contracts';

Roadmap

1. API v1 stabilization

   • Maintain strict backward compatibility
   • Expand schema coverage tests
   • Improve cross-client validation

2. Schema completeness

   • JSON schema coverage for all exported types
   • Validation parity between TypeScript and JSON schema
   • Formal compatibility test suite growth

3. Versioning discipline

   • Major version for breaking shape changes
   • Minor version for additive optional fields
   • Explicit deprecation strategy for future changes

4. Cross-platform contract enforcement

   • Client-side validation (Apple TV, future Roku/Tizen)
   • Tooling to validate responses against schema in CI

5. Future API v2 considerations (non-committal)

   • Optional response envelope standardization
   • Formalized error taxonomy expansion
   • Explicit capability negotiation versioning