@sesionario/media-contracts

Shared types, Zod schemas, JSON Schema, and OpenAPI for the Sesionario media platform (live streaming + VOD).

Published to npm as @sesionario/media-contracts (public registry).

Install

pnpm add @sesionario/media-contracts

Local development (before first publish)

In media or media-svc, link the package from this repo:

pnpm add file:../media-contracts

Build

pnpm install
pnpm run build   # emits dist/ + regenerates schemas/*.json
pnpm run test

Releases

Releases are automated via semantic-release on push to main or dev. Use Conventional Commits to drive version bumps:

• feat: — minor bump
• fix: — patch bump
• feat!: or BREAKING CHANGE: — major bump

Channels

| Branch | npm dist-tag | Install | | ------ | ------------ | ----------------------------------------- | | dev | rc | pnpm add @sesionario/media-contracts@rc | | main | latest | pnpm add @sesionario/media-contracts |

RC versions look like 1.4.0-rc.1; stable versions like 1.4.0.

Git flow

1. Open feature PRs against dev.
2. Merging into dev publishes a release candidate to the rc dist-tag.
3. When ready, open a PR from dev → main to promote to a stable release on latest.

npm trusted publishing (one-time setup)

Publishing uses OIDC trusted publishing from GitHub Actions — no long-lived NPM_TOKEN is stored in the repo.

1. Create the package on npmjs (first publish) or ensure @sesionario/media-contracts exists under the @sesionario scope.
2. On npmjs.com → package → Settings → Trusted publishing, add:
   • Provider: GitHub Actions
   • Repository: docufacil/media-contracts
   • Workflow filename: release.yml (exact match, case-sensitive)
3. Ensure the dev branch exists on GitHub before the first RC release.

Exports

• @sesionario/media-contracts — TypeScript types + Zod schemas
• @sesionario/media-contracts/schemas/* — JSON Schema files
• @sesionario/media-contracts/openapi.yaml — public API spec for media-svc

Domain model

Live stream (kind: "live")

A real-time RTMP ingest → ABR HLS broadcast.

Status flow: provisioning → ingest_ready → preview → live → ended | error

VOD item (kind: "vod")

An uploaded video file transcoded to ABR HLS.

Status flow: awaiting_upload → queued → transcoding → ready | error

MediaItem

A discriminated union of LiveStream | VodItem, used by the unified /media listing endpoint.

TypeScript ↔ Python correspondence (media-engine)

| TypeScript (@sesionario/media-contracts) | Python (media-engine) | | ------------------------------------------ | ---------------------------- | | LiveStreamStatus | LiveStreamStatus (Literal) | | LiveStream | LiveStream (Pydantic) | | VodStatus | VodStatus (Literal) | | VodItem | VodItem (Pydantic) | | MediaItem | MediaItem (Union type) | | SpawnRequest | SpawnRequest | | SpawnResponse | SpawnResponse | | StopRequest | StopRequest | | StopResponse | StopResponse | | IngestReadyWebhook | IngestReadyWebhook | | AuthorizeRequest | AuthorizeRequest | | AuthorizeResponse | AuthorizeResponse | | R2Credentials | R2Credentials | | TranscodeVodRequest | TranscodeVodRequest | | TranscodeVodResponse | TranscodeVodResponse | | VodReadyWebhook | VodReadyWebhook |

Keep Python models in media-engine/src/models.py manually synchronized when contracts change.

License

MIT