Initial import with GitLab CI/CD and registry deploy flow

contracts/events/agent.state.changed.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "AgentStateChanged",
+  "type": "object",
+  "required": ["event", "agent_id", "state", "created_at"],
+  "properties": {
+    "event": { "const": "agent.state.changed" },
+    "agent_id": { "type": "string" },
+    "state": { "type": "string", "enum": ["READY", "BUSY", "BREAK", "OFFLINE"] },
+    "queue_id": { "type": ["string", "null"] },
+    "created_at": { "type": "string", "format": "date-time" }
+  }
+}

contracts/events/call.connected.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "CallConnected",
+  "type": "object",
+  "required": ["event", "call_id", "created_at"],
+  "properties": {
+    "event": { "const": "call.connected" },
+    "call_id": { "type": "string" },
+    "interaction_id": { "type": ["string", "null"] },
+    "operator_extension": { "type": ["string", "null"] },
+    "claimed_by_user": { "type": ["string", "null"] },
+    "created_at": { "type": "string", "format": "date-time" }
+  }
+}

contracts/events/call.recording.ready.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "CallRecordingReady",
+  "type": "object",
+  "required": ["event", "call_id", "recording_path", "duration_seconds", "created_at"],
+  "properties": {
+    "event": { "const": "call.recording.ready" },
+    "call_id": { "type": "string" },
+    "interaction_id": { "type": ["string", "null"] },
+    "recording_path": { "type": "string" },
+    "duration_seconds": { "type": "integer", "minimum": 0 },
+    "created_at": { "type": "string", "format": "date-time" }
+  }
+}

contracts/events/call.transferred.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "CallTransferred",
+  "type": "object",
+  "required": ["event", "call_id", "created_at"],
+  "properties": {
+    "event": { "const": "call.transferred" },
+    "call_id": { "type": "string" },
+    "interaction_id": { "type": ["string", "null"] },
+    "target_type": { "type": ["string", "null"], "enum": ["extension", "queue_code", null] },
+    "target_value": { "type": ["string", "null"] },
+    "target_extension": { "type": ["string", "null"] },
+    "actor_user": { "type": ["string", "null"] },
+    "created_at": { "type": "string", "format": "date-time" }
+  }
+}

contracts/events/interaction.assigned.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "InteractionAssigned",
+  "type": "object",
+  "required": ["event", "interaction_id", "assignee", "created_at"],
+  "properties": {
+    "event": { "const": "interaction.assigned" },
+    "interaction_id": { "type": "string" },
+    "assignee": { "type": "string" },
+    "created_at": { "type": "string", "format": "date-time" }
+  }
+}

contracts/events/interaction.closed.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "InteractionClosed",
+  "type": "object",
+  "required": ["event", "interaction_id", "resolved_first_contact", "created_at"],
+  "properties": {
+    "event": { "const": "interaction.closed" },
+    "interaction_id": { "type": "string" },
+    "resolved_first_contact": { "type": "boolean" },
+    "created_at": { "type": "string", "format": "date-time" }
+  }
+}

contracts/events/interaction.created.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "InteractionCreated",
+  "type": "object",
+  "required": ["event", "interaction_id", "channel", "created_at"],
+  "properties": {
+    "event": { "const": "interaction.created" },
+    "interaction_id": { "type": "string" },
+    "channel": { "type": "string", "enum": ["voice", "telegram", "email", "webchat"] },
+    "queue_id": { "type": ["string", "null"] },
+    "created_at": { "type": "string", "format": "date-time" }
+  }
+}

contracts/events/interaction.escalated.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "InteractionEscalated",
+  "type": "object",
+  "required": ["event", "interaction_id", "target_queue_id", "created_at"],
+  "properties": {
+    "event": { "const": "interaction.escalated" },
+    "interaction_id": { "type": "string" },
+    "target_queue_id": { "type": "string" },
+    "created_at": { "type": "string", "format": "date-time" }
+  }
+}

contracts/events/ivr.completed.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mvp-cc.local/contracts/events/ivr.completed.json",
+  "title": "ivr.completed",
+  "type": "object",
+  "required": ["event_type", "call_id", "payload"],
+  "properties": {
+    "event_type": {
+      "const": "ivr.completed"
+    },
+    "call_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "interaction_id": {
+      "type": ["string", "null"]
+    },
+    "payload": {
+      "type": "object",
+      "required": ["session_id", "flow_id", "outcome_code", "resolved_queue_id", "digits", "terminal_node_id"],
+      "properties": {
+        "session_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "flow_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "outcome_code": {
+          "type": "string",
+          "minLength": 1
+        },
+        "resolved_queue_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "digits": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[0-9]$"
+          }
+        },
+        "terminal_node_id": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true
+}

contracts/openapi/stage1-auth-users-health-audit.yaml

@@ -0,0 +1,60 @@
+openapi: 3.0.3
+info:
+  title: Stage 1 Contracts (Auth, Users, Health, Audit)
+  version: 1.0.0
+paths:
+  /health:
+    get:
+      summary: Health check
+      responses:
+        '200':
+          description: OK
+  /auth/login:
+    post:
+      summary: Login
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [username, password]
+              properties:
+                username: { type: string }
+                password: { type: string }
+      responses:
+        '200':
+          description: Token response
+  /users:
+    get:
+      summary: List users
+      responses:
+        '200':
+          description: Users list
+    post:
+      summary: Create user
+      responses:
+        '200':
+          description: User created
+  /users/{user_id}:
+    get:
+      summary: Get user by id
+      parameters:
+        - in: path
+          name: user_id
+          required: true
+          schema: { type: string }
+      responses:
+        '200':
+          description: User data
+  /audit/events:
+    get:
+      summary: List audit events
+      responses:
+        '200':
+          description: Audit list
+    post:
+      summary: Create audit event
+      responses:
+        '200':
+          description: Event created

contracts/openapi/stage2-customers-interactions-queues-integrations.yaml

@@ -0,0 +1,68 @@
+openapi: 3.0.3
+info:
+  title: Stage 2 Contracts (Operator Core)
+  version: 1.0.0
+paths:
+  /customers:
+    get: { summary: Search customers, responses: { '200': { description: OK } } }
+    post: { summary: Create customer, responses: { '200': { description: OK } } }
+  /customers/{customer_id}:
+    get:
+      summary: Get customer
+      parameters:
+        - in: path
+          name: customer_id
+          required: true
+          schema: { type: string }
+      responses:
+        '200': { description: OK }
+  /interactions:
+    get: { summary: List interactions, responses: { '200': { description: OK } } }
+    post: { summary: Create interaction, responses: { '200': { description: OK } } }
+  /interactions/{interaction_id}/assign:
+    patch:
+      summary: Assign interaction
+      parameters:
+        - in: path
+          name: interaction_id
+          required: true
+          schema: { type: string }
+      responses:
+        '200': { description: OK }
+  /interactions/{interaction_id}/status:
+    patch:
+      summary: Update interaction status
+      parameters:
+        - in: path
+          name: interaction_id
+          required: true
+          schema: { type: string }
+      responses:
+        '200': { description: OK }
+  /interactions/{interaction_id}/escalate:
+    post:
+      summary: Escalate interaction
+      parameters:
+        - in: path
+          name: interaction_id
+          required: true
+          schema: { type: string }
+      responses:
+        '200': { description: OK }
+  /queues:
+    get: { summary: List queues, responses: { '200': { description: OK } } }
+    post: { summary: Create queue, responses: { '200': { description: OK } } }
+  /queues/{queue_id}/rules:
+    patch:
+      summary: Update queue rules
+      parameters:
+        - in: path
+          name: queue_id
+          required: true
+          schema: { type: string }
+      responses:
+        '200': { description: OK }
+  /integrations/voice/events:
+    post: { summary: Ingest Asterisk event, responses: { '200': { description: OK } } }
+  /integrations/telegram/webhook:
+    post: { summary: Ingest Telegram update, responses: { '200': { description: OK } } }

contracts/openapi/stage3-kb-reporting-supervisor.yaml

@@ -0,0 +1,54 @@
+openapi: 3.0.3
+info:
+  title: Stage 3 Contracts (Supervisor, Reporting, KB-lite)
+  version: 1.0.0
+paths:
+  /knowledge/categories:
+    get: { summary: List categories, responses: { '200': { description: OK } } }
+    post: { summary: Create category, responses: { '200': { description: OK } } }
+  /knowledge/articles:
+    post: { summary: Create localized article, responses: { '200': { description: OK } } }
+  /knowledge/articles/{article_id}:
+    get:
+      summary: Get article
+      parameters:
+        - in: path
+          name: article_id
+          required: true
+          schema: { type: string }
+      responses:
+        '200': { description: OK }
+    patch:
+      summary: Update article
+      parameters:
+        - in: path
+          name: article_id
+          required: true
+          schema: { type: string }
+      responses:
+        '200': { description: OK }
+  /knowledge/search:
+    get:
+      summary: Search localized articles
+      parameters:
+        - in: query
+          name: q
+          schema: { type: string }
+        - in: query
+          name: language
+          schema: { type: string, enum: [ru, kz] }
+        - in: query
+          name: article_group_id
+          schema: { type: string }
+      responses:
+        '200': { description: OK }
+  /reports/events:
+    post: { summary: Ingest KPI event, responses: { '200': { description: OK } } }
+  /reports/kpi:
+    get: { summary: KPI snapshot, responses: { '200': { description: OK } } }
+  /reports/export:
+    get: { summary: Export CSV, responses: { '200': { description: OK } } }
+  /supervisor/agent-states:
+    post: { summary: Update agent state, responses: { '200': { description: OK } } }
+  /supervisor/realtime:
+    get: { summary: Realtime supervisor view, responses: { '200': { description: OK } } }

contracts/versioning.md

@@ -0,0 +1,8 @@
+# API Versioning
+
+Current stable baseline: `v1`.
+
+## Rules
+- Stage 1-3 may add endpoints only in scope of agreed stage.
+- Stage 4 freezes public API contracts and documentation.
+- Breaking changes require new major version (`v2`) after pilot acceptance.