u

docs/api/routes/agent/events.md

@@ -0,0 +1,30 @@
+# `GET /agent/events`
+
+Protected. Requires a valid session cookie (`credentials: 'include'`).
+
+Printer agent SSE stream
+
+Authorized Server-Sent Events stream for connected printer agents.
+Maintains a persistent connection with regular heartbeats (`: heartbeat\n\n`) and updates `lastseen_at` and `agentversion`.
+
+
+## Query parameters
+
+| Param | Required | Type | Description |
+|-------|----------|------|-------------|
+| `token` | no | string | Agent auth token if not provided via Authorization header |
+| `agentversion` | no | string | Current agent version |
+
+## Response `200`
+
+Event stream established
+
+## Errors
+
+| Status | Description |
+|--------|-------------|
+| 401 | Unauthorized |
+
+---
+
+_Generated from `@openapi` JSDoc. Do not edit by hand — run `npm run docs:api`._

docs/api/routes/agent/pair.get.md

@@ -0,0 +1,31 @@
+# `GET /agent/pair`
+
+Public. No cookie required.
+
+Pair printer agent via query parameters
+
+Alternative GET endpoint for devices that pair via query parameters.
+
+## Query parameters
+
+| Param | Required | Type | Description |
+|-------|----------|------|-------------|
+| `authCode` | no | string | Pairing PIN (or pairingpin) |
+| `pairingpin` | no | string |  |
+| `serial` | no | string |  |
+| `model` | no | string |  |
+| `version` | no | string |  |
+
+## Response `200`
+
+Pairing successful
+
+## Errors
+
+| Status | Description |
+|--------|-------------|
+| 400 | Missing or invalid pairing PIN |
+
+---
+
+_Generated from `@openapi` JSDoc. Do not edit by hand — run `npm run docs:api`._

docs/api/routes/agent/pair.post.md

@@ -0,0 +1,55 @@
+# `POST /agent/pair`
+
+Public. No cookie required.
+
+Pair printer agent
+
+Public, unauthorized endpoint used by the printer agent to complete pairing using a 6-digit PIN.
+Updates `clientserial`, `clientmodel`, and `agentversion`, clears the pairing PIN, and returns a device authentication token.
+
+
+## Body (JSON)
+
+| Field | Required | Type | Description |
+|-------|----------|------|-------------|
+| `pairingpin` | yes | string |  |
+| `clientserial` | no | string |  |
+| `clientmodel` | no | string |  |
+| `agentversion` | no | string |  |
+
+```json
+{
+  "pairingpin": "123456",
+  "clientserial": "SN-987654321",
+  "clientmodel": "Epson TM-T88VI",
+  "agentversion": "1.0.0"
+}
+```
+
+## Response `200`
+
+Pairing successful
+
+```json
+{
+  "id": 1,
+  "name": "…",
+  "companyId": 1,
+  "token": "…",
+  "pairedAt": "…",
+  "clientserial": "…",
+  "clientmodel": "…",
+  "agentversion": "…",
+  "sort": 1
+}
+```
+
+## Errors
+
+| Status | Description |
+|--------|-------------|
+| 400 | Missing or invalid pairing PIN — `{"error":"…"}` |
+
+---
+
+_Generated from `@openapi` JSDoc. Do not edit by hand — run `npm run docs:api`._

docs/api/routes/agent/state.md

@@ -0,0 +1,55 @@
+# `POST /agent/state`
+
+Protected. Requires a valid session cookie (`credentials: 'include'`).
+
+Post agent state
+
+Authorized endpoint for the printer agent to report its operational status/telemetry.
+
+
+## Body (JSON)
+
+| Field | Required | Type | Description |
+|-------|----------|------|-------------|
+| `state` | no |  | Status text or status object |
+
+```json
+{
+  "state": "…"
+}
+```
+
+## Response `200`
+
+State recorded
+
+```json
+{
+  "success": true,
+  "agent": {
+    "id": 1,
+    "companyId": 1,
+    "name": "…",
+    "token": "…",
+    "pairingpin": "…",
+    "pairedAt": "…",
+    "clientserial": "…",
+    "clientmodel": "…",
+    "clientstate": "…",
+    "agentversion": "…",
+    "lastseenAt": "…",
+    "updatedAt": "…",
+    "sort": 1
+  }
+}
+```
+
+## Errors
+
+| Status | Description |
+|--------|-------------|
+| 401 | Unauthorized |
+
+---
+
+_Generated from `@openapi` JSDoc. Do not edit by hand — run `npm run docs:api`._