Define shared permissions and version contracts

README.md

@@ -12,3 +12,9 @@ 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.
 
+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.
+

contracts/v1/permissions.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://trixie.invalid/contracts/v1/permissions.json",
+  "title": "Trixie Permission Level",
+  "description": "The ordered permission levels used by chat commands and moderation controls.",
+  "type": "string",
+  "enum": ["everyone", "subscriber", "moderator", "broadcaster"]
+}

contracts/v1/version-negotiation.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://trixie.invalid/contracts/v1/version-negotiation.json",
+  "title": "Trixie Version Negotiation",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["api_version", "client_version", "server_version", "compatible"],
+  "properties": {
+    "api_version": { "type": "string", "const": "v1" },
+    "client_version": { "type": "string", "minLength": 1 },
+    "server_version": { "type": "string", "minLength": 1 },
+    "compatible": { "type": "boolean" },
+    "reason": { "type": "string", "minLength": 1 }
+  }
+}

docs/versioning.md

@@ -8,4 +8,10 @@
 - `GET /api/v1/server/info` publishes `minimum_client_version` and
   `maximum_client_version`; clients must use these fields to detect an
   incompatible pairing before enabling authenticated controls.
+- Permission values are shared through `contracts/v1/permissions.json`.
+  They are ordered from least to most privileged: `everyone`, `subscriber`,
+  `moderator`, and `broadcaster`.
+- The normalized result of a compatibility check is described by
+  `contracts/v1/version-negotiation.json`; an incompatible result includes a
+  human-readable `reason` while a compatible result may omit it.
 

fixtures/v1/version-negotiation.compatible.json

@@ -0,0 +1,6 @@
+{
+  "api_version": "v1",
+  "client_version": "0.1.0",
+  "server_version": "0.1.0",
+  "compatible": true
+}