# Trixie API

Shared versioned HTTP and authenticated WebSocket contracts for `trixie-server` and `trixy-linux-client`.

This repository contains schemas, shared enums, error codes, compatibility fixtures, contract tests, and API documentation only.

The API repository is the boundary between the server authority and the Linux
client presentation layer. It contains no Twitch credentials, database logic,
or UI behavior.

The first contract slice is under `contracts/v1/` and `fixtures/v1/`. It covers
server readiness, health, errors, and the transport-neutral realtime event
envelope so the client and server can be developed and tested together before
Twitch integration. It also defines the first administrator authentication
request and response envelopes; bearer values in fixtures are synthetic only.
Twitch OAuth link and completion response envelopes are also versioned here;
fixtures contain no real credentials or tokens.

`GET /api/v1/auth/session` returns `authenticated: true` and the current
`must_replace_credentials` flag from the administrator account. Restoring a
session must not bypass first-run setup. Older servers omit this flag; clients
must not interpret an absent flag as completed credential replacement.

The shared boundary vocabulary includes the ordered permission levels in
`contracts/v1/permissions.json` and the client/server compatibility result in
`contracts/v1/version-negotiation.json`. Server-owned state is delivered as
the authenticated `realtime-event.json` envelope; clients must ignore event
types they do not understand.

Guest Star channel settings are described by
`contracts/v1/guest-star-channel-settings-response.json`. The browser-source
token is a server-to-authenticated-client value and fixtures use a synthetic
placeholder only.

The Twitch-authoritative collaboration capability probe is described by
`collaboration-capabilities-response.json`; unavailable beta surfaces include
a machine-readable reason without exposing Twitch tokens.

Destructive backup recovery uses the explicit `backup-restore-request.json`
and `backup-restore-response.json` contracts; test fixtures contain no real
database paths or credentials.

The authenticated WebAssembly plugin lifecycle uses the manifest, install,
installed-response, and plugin-secret-binding-request contracts. Fixtures
contain only synthetic package metadata and no executable module or secret.

Command simulation uses `bot-command-simulate-request.json` and
`bot-command-simulate-response.json`. A sample response is the default and
real network requests require an explicit `use_real_request` flag; fixtures
contain only local synthetic data.

Named-user command rules use `bot-command-user-rule.json`; fixtures contain
only synthetic Twitch IDs and literal response templates.

Typed command arguments use `bot-command-argument-definition.json` and remain
literal validated data.