@xenon-device-management/xenon 2.12.0 → 2.13.0

package/lib/src/app/swagger-docs.js

@@ -1,1701 +0,0 @@
-"use strict";
-/**
- * @swagger
- * /api/devices:
- *   get:
- *     summary: Get all connected devices
- *     description: Retrieve a list of all connected devices with their current status
- *     tags: [Devices]
- *     responses:
- *       200:
- *         description: List of devices
- *         content:
- *           application/json:
- *             schema:
- *               type: array
- *               items:
- *                 $ref: '#/components/schemas/Device'
- *       401: { $ref: '#/components/responses/Unauthorized' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-/**
- * @swagger
- * /api/config:
- *   get:
- *     summary: Get current configuration
- *     description: Retrieve the current runtime configuration of the Xenon plugin
- *     tags: [Configuration]
- *     responses:
- *       200:
- *         description: Current configuration object
- *         content:
- *           application/json:
- *             schema:
- *               type: object
- *       401: { $ref: '#/components/responses/Unauthorized' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- *   put:
- *     summary: Update configuration
- *     description: Update plugin configuration properties. Changes are persisted. Some changes may require a server restart.
- *     tags: [Configuration]
- *     requestBody:
- *       required: true
- *       content:
- *         application/json:
- *           schema:
- *             type: object
- *             description: Partial configuration object
- *             example:
- *               deviceAvailabilityTimeoutMs: 60000
- *               maxSessions: 5
- *     responses:
- *       200:
- *         description: Configuration updated
- *         content:
- *           application/json:
- *             schema:
- *               type: object
- *               properties:
- *                 success:
- *                   type: boolean
- *                 restartRequired:
- *                   type: boolean
- *                   description: True if the updated properties require a server restart
- *                 message:
- *                   type: string
- *       401: { $ref: '#/components/responses/Unauthorized' }
- *       403: { $ref: '#/components/responses/Forbidden' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- */
-/**
- * @swagger
- * /api/sessions/active:
- *   get:
- *     summary: Get active sessions
- *     description: Get statistics and list of currently active sessions in memory
- *     tags: [Sessions]
- *     responses:
- *       200:
- *         description: Active session information
- *         content:
- *           application/json:
- *             schema:
- *               type: object
- *               properties:
- *                 stats:
- *                   type: object
- *                   properties:
- *                     total:
- *                       type: number
- *                       description: Total number of active sessions
- *                     byType:
- *                       type: object
- *                       properties:
- *                         local:
- *                           type: number
- *                         remote:
- *                           type: number
- *                         cloud:
- *                           type: number
- *                 sessions:
- *                   type: array
- *                   items:
- *                     type: object
- *                     properties:
- *                       id:
- *                         type: string
- *                       type:
- *                         type: string
- *                         enum: [local, remote, cloud]
- *                       deviceUdid:
- *                         type: string
- *                       deviceName:
- *                         type: string
- *                       platform:
- *                         type: string
- *       401: { $ref: '#/components/responses/Unauthorized' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- */
-/**
- * @swagger
- * /api/logs/requests:
- *   get:
- *     summary: Get HTTP request logs
- *     description: Retrieve recent HTTP request logs for debugging hub-node communication
- *     tags: [Observability]
- *     parameters:
- *       - in: query
- *         name: limit
- *         schema:
- *           type: integer
- *           default: 50
- *         description: Maximum number of logs to return
- *       - in: query
- *         name: method
- *         schema:
- *           type: string
- *           enum: [GET, POST, PUT, DELETE]
- *         description: Filter by HTTP method
- *       - in: query
- *         name: url
- *         schema:
- *           type: string
- *         description: Filter by URL pattern (substring match)
- *       - in: query
- *         name: hasError
- *         schema:
- *           type: boolean
- *         description: Filter by error status (true = only errors, false = only success)
- *     responses:
- *       200:
- *         description: Request logs and statistics
- *         content:
- *           application/json:
- *             schema:
- *               type: object
- *               properties:
- *                 stats:
- *                   type: object
- *                   properties:
- *                     totalLogged:
- *                       type: number
- *                       description: Total requests in buffer
- *                     errorCount:
- *                       type: number
- *                       description: Number of failed requests
- *                     avgDurationMs:
- *                       type: number
- *                       description: Average request duration in milliseconds
- *                     byMethod:
- *                       type: object
- *                       additionalProperties:
- *                         type: number
- *                     byStatusCode:
- *                       type: object
- *                       additionalProperties:
- *                         type: number
- *                 logs:
- *                   type: array
- *                   items:
- *                     type: object
- *                     properties:
- *                       timestamp:
- *                         type: string
- *                         format: date-time
- *                       direction:
- *                         type: string
- *                         enum: [outgoing, incoming]
- *                       method:
- *                         type: string
- *                       url:
- *                         type: string
- *                       statusCode:
- *                         type: number
- *                       durationMs:
- *                         type: number
- *                       error:
- *                         type: string
- *                         nullable: true
- *                       requestBody:
- *                         type: string
- *                         description: Sanitized request body (sensitive data redacted)
- *                       responseBody:
- *                         type: string
- *                         description: Truncated response body
- *       401: { $ref: '#/components/responses/Unauthorized' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- */
-/**
- * @swagger
- * tags:
- *   - name: Observability
- *     description: Debugging and monitoring endpoints
- */
-/**
- * @swagger
- * /api/healing/selector/state:
- *   post:
- *     summary: Apply a lifecycle action to a selector
- *     description: |
- *       Mutates the SelectorState row for a (strategy, selector) tuple and
- *       records the change, with the person, in SelectorEvent. Actions are
- *       bounded — `mark_fixed`, `mute`, `unmute`, `cancel_verification`.
- *       Members and admins may act on a selector healed in a session they
- *       can see; any other answers 404, as an unknown one. Needs the
- *       `sessions` scope (`admin` implies it). `original_strategy` may be
- *       empty, for heals recorded with no strategy. Returns 409 with
- *       `currentStatus` if the action is incompatible with the row's
- *       current state (e.g. mark_fixed on a muted selector).
- *     tags: [Selector Health]
- *     security:
- *       - apiKey: []
- *     requestBody:
- *       required: true
- *       content:
- *         application/json:
- *           schema:
- *             type: object
- *             required: [original_strategy, original_selector, action]
- *             properties:
- *               original_strategy:
- *                 type: string
- *                 example: accessibility id
- *               original_selector:
- *                 type: string
- *                 example: login-btn
- *               action:
- *                 type: string
- *                 enum: [mark_fixed, mute, unmute, cancel_verification]
- *               reason: { type: string, maxLength: 500, description: 'Why the selector is muted; mute only' }
- *     responses:
- *       200:
- *         description: Updated SelectorState row
- *       400:
- *         description: Missing fields, unknown action, or a reason over 500 characters
- *       403:
- *         description: The caller lacks the `sessions` scope
- *       404:
- *         description: '`{ error: "not_found", message: "Selector not found" }`'
- *       409:
- *         description: Action conflicts with current state (returns currentStatus)
- *       401: { $ref: '#/components/responses/Unauthorized' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- */
-/**
- * @swagger
- * /api/healing/state/muted:
- *   get:
- *     summary: List muted selectors
- *     description: |
- *       Returns muted selectors sourced directly from SelectorState
- *       (not the hotspot aggregator), so silenced-but-not-recently-healed
- *       rows still surface. Each row is enriched with the most recent
- *       `is_healed=true` SessionLog timestamp for the tuple.
- *     tags: [Selector Health]
- *     parameters:
- *       - in: query
- *         name: limit
- *         schema: { type: integer, default: 50, maximum: 200 }
- *       - in: query
- *         name: offset
- *         schema: { type: integer, default: 0 }
- *     responses:
- *       200:
- *         description: Paginated muted selectors
- *         content:
- *           application/json:
- *             schema:
- *               type: object
- *               properties:
- *                 muted: { type: array }
- *                 total: { type: integer }
- *                 limit: { type: integer }
- *                 offset: { type: integer }
- *       401: { $ref: '#/components/responses/Unauthorized' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- */
-/**
- * @swagger
- * /api/healing/state/{strategy}/{value}:
- *   get:
- *     summary: Look up SelectorState for a single tuple
- *     description: |
- *       URL-encoded strategy + value. Returns `{ state: null }` when no
- *       row exists — null is meaningful (the selector is implicitly Active).
- *     tags: [Selector Health]
- *     parameters:
- *       - in: path
- *         name: strategy
- *         required: true
- *         schema: { type: string }
- *       - in: path
- *         name: value
- *         required: true
- *         schema: { type: string }
- *     responses:
- *       200:
- *         description: SelectorState row, or null
- *       401: { $ref: '#/components/responses/Unauthorized' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- */
-/**
- * @swagger
- * /api/healing/hotspots:
- *   get:
- *     summary: List the most-healed selectors (with lifecycle filter)
- *     description: |
- *       Status filter is `active` (default), `pending`, `resolved`, `muted`,
- *       or `all`. The default value transparently hides muted/pending/
- *       resolved selectors from the live list, the CI gate, and the digest.
- *     tags: [Selector Health]
- *     parameters:
- *       - in: query
- *         name: windowDays
- *         schema: { type: integer, default: 30 }
- *       - in: query
- *         name: limit
- *         schema: { type: integer, default: 10 }
- *       - in: query
- *         name: status
- *         schema: { type: string, enum: [active, pending, resolved, muted, all], default: active }
- *       - in: query
- *         name: tier
- *         schema: { type: string }
- *       - in: query
- *         name: platform
- *         schema: { type: string }
- *     responses:
- *       200:
- *         description: Hotspots with state overlay
- *       401: { $ref: '#/components/responses/Unauthorized' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- */
-// =============================================================================
-// Health & Operations
-// =============================================================================
-/**
- * @swagger
- * /api/health:
- *   get:
- *     summary: Liveness probe
- *     description: |
- *       Public, unauthenticated, not rate-limited. Returns `{ ok: true }` as soon
- *       as the Express stack is up — does not check database or device state.
- *       Suitable for Kubernetes/load-balancer liveness probes.
- *     tags: [Health & Ops]
- *     security: []
- *     responses:
- *       200:
- *         description: Server is up
- *         content:
- *           application/json:
- *             schema:
- *               type: object
- *               properties:
- *                 ok: { type: boolean, example: true }
- */
-/**
- * @swagger
- * /api/ping:
- *   get:
- *     summary: Authenticated ping with build version
- *     description: Returns `{ pong, version }`. Use to confirm an API key is valid and read the running plugin version.
- *     tags: [Health & Ops]
- *     responses:
- *       200:
- *         description: Pong with version
- *         content:
- *           application/json:
- *             schema:
- *               type: object
- *               properties:
- *                 pong: { type: boolean, example: true }
- *                 version: { type: string, example: '1.5.0' }
- *       401: { $ref: '#/components/responses/Unauthorized' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- */
-/**
- * @swagger
- * /api/metrics:
- *   get:
- *     summary: Prometheus-format metrics
- *     description: |
- *       Returns scrape-friendly Prometheus exposition format (`text/plain; version=0.0.4`).
- *       Auth-gated to avoid operational reconnaissance — point your scraper at this
- *       endpoint with a `read`-scope token in the `(x-xenon-access-key, x-xenon-token)` pair.
- *     tags: [Health & Ops]
- *     responses:
- *       200:
- *         description: Prometheus metrics
- *         content:
- *           text/plain:
- *             schema: { type: string }
- *       401: { $ref: '#/components/responses/Unauthorized' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- */
-/**
- * @swagger
- * /api/cliArgs:
- *   get:
- *     summary: Read the plugin CLI arguments in effect
- *     description: |
- *       Returns the resolved plugin arguments (host, hub URL, platform, intervals, etc.)
- *       this process was started with. Requires the ADMIN role and `admin` scope.
- *       Values are redacted the way the logger redacts them: any key that looks
- *       secret (database URL, API key, token, password, auth…) reads
- *       `***REDACTED***`, and so do provider-key-shaped strings.
- *     tags: [Health & Ops]
- *     responses:
- *       200:
- *         description: Resolved plugin arguments
- *         content:
- *           application/json:
- *             schema: { type: object, additionalProperties: true }
- *       401: { $ref: '#/components/responses/Unauthorized' }
- *       403: { $ref: '#/components/responses/Forbidden' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- */
-// =============================================================================
-// Authentication
-// =============================================================================
-/**
- * @swagger
- * /api/auth/dashboard-session:
- *   post:
- *     summary: Exchange an API key for a browser dashboard session cookie
- *     description: |
- *       Used by the dashboard UI to convert a one-time API key paste into a
- *       short-lived session cookie. Public endpoint — no API key header is
- *       required because the body itself carries the credential. On success,
- *       sets `xenon_dashboard_session` (HttpOnly, Secure, SameSite=Strict, 24 h
- *       max-age). Subsequent dashboard requests use the cookie instead of the
- *       header. CSRF protection: cookie-authed callers must send a matching
- *       `Origin`/`Referer`.
- *     tags: [Authentication]
- *     security: []
- *     requestBody:
- *       required: true
- *       content:
- *         application/json:
- *           schema:
- *             type: object
- *             required: [apiKey]
- *             properties:
- *               apiKey: { type: string, description: 'Plain-text API key' }
- *     responses:
- *       200:
- *         description: Session cookie set
- *         content:
- *           application/json:
- *             schema:
- *               type: object
- *               properties:
- *                 ok: { type: boolean, example: true }
- *                 scopes:
- *                   type: array
- *                   items: { type: string, enum: [read, sessions, devices, admin] }
- *       400: { description: 'Missing apiKey field' }
- *       401: { description: 'Invalid API key' }
- */
-// =============================================================================
-// Admin — API Keys
-// =============================================================================
-/**
- * @swagger
- * /api/apikeys:
- *   get:
- *     summary: List all API keys
- *     description: Returns metadata only — the plain-text key value is never returned after creation. Requires `admin` scope.
- *     tags: [Admin]
- *     responses:
- *       200:
- *         description: List of API key records
- *         content:
- *           application/json:
- *             schema:
- *               type: array
- *               items:
- *                 type: object
- *                 properties:
- *                   id: { type: string }
- *                   name: { type: string }
- *                   scopes:
- *                     type: array
- *                     items: { type: string, enum: [read, sessions, devices, admin] }
- *                   rateLimit: { type: integer, nullable: true }
- *                   teamId: { type: string, nullable: true }
- *                   createdAt: { type: string, format: date-time }
- *                   lastUsedAt: { type: string, format: date-time, nullable: true }
- *       401: { $ref: '#/components/responses/Unauthorized' }
- *       403: { $ref: '#/components/responses/Forbidden' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- *   post:
- *     summary: Mint a new API key
- *     description: |
- *       Returns the plain-text key **once** in the response. Store it immediately —
- *       it cannot be retrieved later. Requires `admin` scope.
- *     tags: [Admin]
- *     requestBody:
- *       required: true
- *       content:
- *         application/json:
- *           schema:
- *             type: object
- *             required: [name, scopes]
- *             properties:
- *               name: { type: string, example: 'CI runner' }
- *               scopes:
- *                 type: array
- *                 minItems: 1
- *                 items: { type: string, enum: [read, sessions, devices, admin] }
- *               rateLimit:
- *                 type: integer
- *                 description: 'Per-window quota override; null inherits the plugin default'
- *               teamId:
- *                 type: string
- *                 nullable: true
- *                 description: 'Bind this key to a team (so it sees team-owned devices only)'
- *     responses:
- *       200:
- *         description: Key created
- *         content:
- *           application/json:
- *             schema:
- *               type: object
- *               properties:
- *                 id: { type: string }
- *                 key: { type: string, description: 'Plain-text key — shown once' }
- *       400: { description: 'Missing name or empty scopes array' }
- *       401: { $ref: '#/components/responses/Unauthorized' }
- *       403: { $ref: '#/components/responses/Forbidden' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- */
-/**
- * @swagger
- * /api/apikeys/{id}:
- *   delete:
- *     summary: Revoke an API key
- *     description: Hard-deletes the key. In-flight requests already authenticated continue until completion; subsequent requests with the revoked key get 401. Requires `admin` scope.
- *     tags: [Admin]
- *     parameters:
- *       - in: path
- *         name: id
- *         required: true
- *         schema: { type: string }
- *     responses:
- *       200:
- *         description: Key revoked
- *         content:
- *           application/json:
- *             schema: { $ref: '#/components/schemas/Success' }
- *       401: { $ref: '#/components/responses/Unauthorized' }
- *       403: { $ref: '#/components/responses/Forbidden' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- */
-// =============================================================================
-// Admin — Teams
-// =============================================================================
-/**
- * @swagger
- * /api/teams:
- *   get:
- *     summary: List all teams
- *     description: Requires `admin` scope.
- *     tags: [Admin]
- *     responses:
- *       200:
- *         description: List of teams
- *         content:
- *           application/json:
- *             schema:
- *               type: array
- *               items:
- *                 type: object
- *                 properties:
- *                   id: { type: string }
- *                   name: { type: string }
- *                   createdAt: { type: string, format: date-time }
- *       401: { $ref: '#/components/responses/Unauthorized' }
- *       403: { $ref: '#/components/responses/Forbidden' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- *   post:
- *     summary: Create a team
- *     description: Team names must be unique. Requires `admin` scope.
- *     tags: [Admin]
- *     requestBody:
- *       required: true
- *       content:
- *         application/json:
- *           schema:
- *             type: object
- *             required: [name]
- *             properties:
- *               name: { type: string, example: 'Mobile Platform' }
- *     responses:
- *       200:
- *         description: Team created
- *       400: { description: 'Missing name' }
- *       409: { description: 'Team name already exists' }
- *       401: { $ref: '#/components/responses/Unauthorized' }
- *       403: { $ref: '#/components/responses/Forbidden' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- */
-/**
- * @swagger
- * /api/teams/{id}:
- *   delete:
- *     summary: Delete a team
- *     description: Cascades to membership rows. Devices owned by the team revert to shared (null) ownership. Requires `admin` scope.
- *     tags: [Admin]
- *     parameters:
- *       - in: path
- *         name: id
- *         required: true
- *         schema: { type: string }
- *     responses:
- *       200:
- *         description: Team deleted
- *         content:
- *           application/json:
- *             schema: { $ref: '#/components/schemas/Success' }
- *       401: { $ref: '#/components/responses/Unauthorized' }
- *       403: { $ref: '#/components/responses/Forbidden' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- */
-/**
- * @swagger
- * /api/teams/{id}/members:
- *   get:
- *     summary: List team members
- *     description: Returns the API keys bound to this team. Requires `admin` scope.
- *     tags: [Admin]
- *     parameters:
- *       - in: path
- *         name: id
- *         required: true
- *         schema: { type: string }
- *     responses:
- *       200:
- *         description: List of members
- *         content:
- *           application/json:
- *             schema:
- *               type: array
- *               items:
- *                 type: object
- *                 properties:
- *                   apiKeyId: { type: string }
- *                   role: { type: string, enum: [member, owner] }
- *       401: { $ref: '#/components/responses/Unauthorized' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- *   post:
- *     summary: Add a member to a team
- *     description: Adds an existing API key as a team member. Defaults to `member` role. Requires `admin` scope.
- *     tags: [Admin]
- *     parameters:
- *       - in: path
- *         name: id
- *         required: true
- *         schema: { type: string }
- *     requestBody:
- *       required: true
- *       content:
- *         application/json:
- *           schema:
- *             type: object
- *             required: [apiKeyId]
- *             properties:
- *               apiKeyId: { type: string }
- *               role: { type: string, enum: [member, owner], default: member }
- *     responses:
- *       200: { description: 'Member added' }
- *       400: { description: 'Missing apiKeyId' }
- *       401: { $ref: '#/components/responses/Unauthorized' }
- *       403: { $ref: '#/components/responses/Forbidden' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- */
-/**
- * @swagger
- * /api/teams/{id}/members/{apiKeyId}:
- *   delete:
- *     summary: Remove a member from a team
- *     description: Does not revoke the API key itself — only unbinds it from the team. Requires `admin` scope.
- *     tags: [Admin]
- *     parameters:
- *       - in: path
- *         name: id
- *         required: true
- *         schema: { type: string }
- *       - in: path
- *         name: apiKeyId
- *         required: true
- *         schema: { type: string }
- *     responses:
- *       200:
- *         description: Member removed
- *         content:
- *           application/json:
- *             schema: { $ref: '#/components/schemas/Success' }
- *       401: { $ref: '#/components/responses/Unauthorized' }
- *       403: { $ref: '#/components/responses/Forbidden' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- */
-// =============================================================================
-// Admin — Process snapshot
-// =============================================================================
-/**
- * @swagger
- * /api/processes:
- *   get:
- *     summary: Snapshot of long-running child processes
- *     description: |
- *       Lists the long-lived workers Xenon is currently supervising — Appium-driven
- *       sessions, ADB log tails, MJPEG stream encoders, etc. Useful when triaging
- *       why a host is hot or a device is wedged. Requires `admin` scope.
- *     tags: [Admin]
- *     responses:
- *       200:
- *         description: List of supervised processes
- *         content:
- *           application/json:
- *             schema:
- *               type: array
- *               items:
- *                 type: object
- *                 properties:
- *                   id: { type: string }
- *                   sessionId: { type: string, nullable: true }
- *                   udid: { type: string, nullable: true }
- *                   kind: { type: string, example: 'mjpeg-stream' }
- *                   pid: { type: integer }
- *                   uptimeMs: { type: integer }
- *       401: { $ref: '#/components/responses/Unauthorized' }
- *       403: { $ref: '#/components/responses/Forbidden' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- */
-// =============================================================================
-// Network Interceptor
-// =============================================================================
-/**
- * @swagger
- * /api/interceptor/sessions/{sessionId}/requests:
- *   get:
- *     summary: List intercepted HTTP requests for a session
- *     description: |
- *       Returns the full list of requests captured by the per-session interceptor.
- *       If the session is still active, results are read live; otherwise the
- *       archived `requests.json` from the session asset directory is replayed.
- *       Returns 404 when neither a live interceptor nor an archive exists.
- *     tags: [Network Interceptor]
- *     parameters:
- *       - in: path
- *         name: sessionId
- *         required: true
- *         schema: { type: string }
- *     responses:
- *       200:
- *         description: Request list
- *         content:
- *           application/json:
- *             schema:
- *               type: object
- *               properties:
- *                 requests:
- *                   type: array
- *                   items: { type: object, additionalProperties: true }
- *       404: { description: 'Interceptor inactive and no archive on disk' }
- *       401: { $ref: '#/components/responses/Unauthorized' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- */
-/**
- * @swagger
- * /api/interceptor/sessions/{sessionId}/requests/{requestId}:
- *   get:
- *     summary: Get a single intercepted request with full body
- *     description: |
- *       Hydrates the request detail, including any response body that was
- *       offloaded to disk (`bodyPath`). Use this from the dashboard's request
- *       drawer or for HAR-equivalent single-record export.
- *     tags: [Network Interceptor]
- *     parameters:
- *       - in: path
- *         name: sessionId
- *         required: true
- *         schema: { type: string }
- *       - in: path
- *         name: requestId
- *         required: true
- *         schema: { type: string }
- *     responses:
- *       200:
- *         description: Single request entry
- *         content:
- *           application/json:
- *             schema: { type: object, additionalProperties: true }
- *       404: { description: 'Request not found in live or archived state' }
- *       401: { $ref: '#/components/responses/Unauthorized' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- */
-/**
- * @swagger
- * /api/interceptor/sessions/{sessionId}/har:
- *   get:
- *     summary: Export session traffic as a HAR file
- *     description: |
- *       Returns a HAR 1.2 archive (`application/json`, with `Content-Disposition:
- *       attachment`). Falls back to the on-disk archive if the session has ended.
- *     tags: [Network Interceptor]
- *     parameters:
- *       - in: path
- *         name: sessionId
- *         required: true
- *         schema: { type: string }
- *     responses:
- *       200:
- *         description: HAR file
- *         content:
- *           application/json:
- *             schema: { type: object, additionalProperties: true }
- *       404: { description: 'No live interceptor and no archived HAR' }
- *       401: { $ref: '#/components/responses/Unauthorized' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- */
-/**
- * @swagger
- * /api/interceptor/sessions/{sessionId}/mocks:
- *   get:
- *     summary: List mock rules for a session
- *     description: Mock rules apply only while the session is live — there is no archive fallback.
- *     tags: [Network Interceptor]
- *     parameters:
- *       - in: path
- *         name: sessionId
- *         required: true
- *         schema: { type: string }
- *     responses:
- *       200:
- *         description: Mock list
- *         content:
- *           application/json:
- *             schema:
- *               type: object
- *               properties:
- *                 mocks:
- *                   type: array
- *                   items: { type: object, additionalProperties: true }
- *       404: { description: 'Interceptor not active for this session' }
- *       401: { $ref: '#/components/responses/Unauthorized' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- *   post:
- *     summary: Add a mock rule
- *     description: |
- *       Mock rules match by URL pattern and method, then either return a static
- *       response, rewrite the upstream response, or delay it. Only valid while
- *       the target session is live.
- *     tags: [Network Interceptor]
- *     parameters:
- *       - in: path
- *         name: sessionId
- *         required: true
- *         schema: { type: string }
- *     requestBody:
- *       required: true
- *       content:
- *         application/json:
- *           schema: { type: object, additionalProperties: true }
- *     responses:
- *       201:
- *         description: Mock created
- *         content:
- *           application/json:
- *             schema:
- *               type: object
- *               properties:
- *                 id: { type: string }
- *       400: { description: 'Invalid mock rule' }
- *       404: { description: 'Interceptor not active' }
- *       401: { $ref: '#/components/responses/Unauthorized' }
- *       403: { $ref: '#/components/responses/Forbidden' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- *   delete:
- *     summary: Clear all mock rules for a session
- *     tags: [Network Interceptor]
- *     parameters:
- *       - in: path
- *         name: sessionId
- *         required: true
- *         schema: { type: string }
- *     responses:
- *       200:
- *         description: Mocks cleared
- *         content:
- *           application/json:
- *             schema: { $ref: '#/components/schemas/Success' }
- *       404: { description: 'Interceptor not active' }
- *       401: { $ref: '#/components/responses/Unauthorized' }
- *       403: { $ref: '#/components/responses/Forbidden' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- */
-/**
- * @swagger
- * /api/interceptor/sessions/{sessionId}/mocks/{mockId}:
- *   delete:
- *     summary: Remove a single mock rule
- *     tags: [Network Interceptor]
- *     parameters:
- *       - in: path
- *         name: sessionId
- *         required: true
- *         schema: { type: string }
- *       - in: path
- *         name: mockId
- *         required: true
- *         schema: { type: string }
- *     responses:
- *       200:
- *         description: Mock removed
- *         content:
- *           application/json:
- *             schema:
- *               type: object
- *               properties:
- *                 removed: { type: boolean }
- *       404: { description: 'Interceptor not active or mock not found' }
- *       401: { $ref: '#/components/responses/Unauthorized' }
- *       403: { $ref: '#/components/responses/Forbidden' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- */
-// =============================================================================
-// Hub-Node channel (pair auth)
-// =============================================================================
-/**
- * @swagger
- * /api/register:
- *   post:
- *     summary: Node→Hub device inventory push
- *     description: |
- *       Hub-node only. Authenticates with the per-node
- *       `(x-xenon-access-key, x-xenon-token)` pair the node was provisioned
- *       with on the hub. Nodes call this on startup and on a recurring
- *       interval (`sendNodeDevicesToHubIntervalMs`, default 30 s) to publish
- *       their device list. The `type` query param selects the operation:
- *
- *       | type          | effect                                                        |
- *       |---------------|---------------------------------------------------------------|
- *       | `add`         | Insert / refresh the supplied devices                         |
- *       | `remove`      | Drop the supplied devices (e.g. USB unplug)                   |
- *       | `unregister`  | Drop every device for the calling host (used on graceful exit) |
- *
- *       Not intended for end-user automation. Document here for transparency.
- *     tags: [Hub-Node]
- *     security:
- *       - AccessKeyAuth: []
- *         TokenAuth: []
- *     parameters:
- *       - in: query
- *         name: type
- *         required: true
- *         schema: { type: string, enum: [add, remove, unregister] }
- *       - in: query
- *         name: host
- *         schema: { type: string }
- *         description: 'Required for `unregister`'
- *     requestBody:
- *       content:
- *         application/json:
- *           schema:
- *             oneOf:
- *               - type: array
- *                 items: { $ref: '#/components/schemas/Device' }
- *               - type: object
- *     responses:
- *       200:
- *         description: Inventory accepted
- *         content:
- *           application/json:
- *             schema: { $ref: '#/components/schemas/Success' }
- *       401: { description: 'Missing or invalid (accessKey, token) pair' }
- *       403: { $ref: '#/components/responses/Forbidden' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- */
-/**
- * @swagger
- * /api/unblock:
- *   post:
- *     summary: Node→Hub release of a manually-blocked device
- *     description: |
- *       Hub-node only. Authenticates with the per-node
- *       `(x-xenon-access-key, x-xenon-token)` pair. Nodes call this to
- *       re-enter a device into the pool after a maintenance lock or a
- *       blocked state lifted on the node side. Returns 404 if the
- *       (udid, host) tuple is not in the registry.
- *     tags: [Hub-Node]
- *     security:
- *       - AccessKeyAuth: []
- *         TokenAuth: []
- *     requestBody:
- *       required: true
- *       content:
- *         application/json:
- *           schema:
- *             type: object
- *             required: [udid, host]
- *             properties:
- *               udid: { type: string }
- *               host: { type: string }
- *     responses:
- *       200:
- *         description: Device unblocked
- *         content:
- *           application/json:
- *             schema: { $ref: '#/components/schemas/Success' }
- *       404: { description: 'Device not found in registry' }
- *       401: { description: 'Missing or invalid (accessKey, token) pair' }
- *       403: { $ref: '#/components/responses/Forbidden' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- */
-// =============================================================================
-// Grid — previously-undocumented routes
-// =============================================================================
-/**
- * @swagger
- * /api/device/tags:
- *   post:
- *     summary: Replace the tag list on a device
- *     description: Tags are user-defined free-form labels (e.g. `flaky`, `lab-row-3`). Replaces — does not append. Requires `devices` scope.
- *     tags: [Devices]
- *     requestBody:
- *       required: true
- *       content:
- *         application/json:
- *           schema:
- *             type: object
- *             required: [udid, host, tags]
- *             properties:
- *               udid: { type: string }
- *               host: { type: string }
- *               tags:
- *                 type: array
- *                 items: { type: string }
- *     responses:
- *       200:
- *         description: Tags updated
- *         content:
- *           application/json:
- *             schema: { $ref: '#/components/schemas/Success' }
- *       400: { description: 'Missing udid, host, or tags array' }
- *       401: { $ref: '#/components/responses/Unauthorized' }
- *       403: { $ref: '#/components/responses/Forbidden' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- */
-/**
- * @swagger
- * /api/device/{udid}/team:
- *   put:
- *     summary: Assign (or clear) a device's team ownership
- *     description: |
- *       Pass `teamId: null` to unassign the device (it returns to the shared
- *       pool, visible to all keys). Pass a string id to bind it. The team must
- *       already exist. Requires `admin` scope.
- *     tags: [Devices]
- *     parameters:
- *       - in: path
- *         name: udid
- *         required: true
- *         schema: { type: string }
- *     requestBody:
- *       required: true
- *       content:
- *         application/json:
- *           schema:
- *             type: object
- *             required: [teamId]
- *             properties:
- *               teamId: { type: string, nullable: true }
- *     responses:
- *       200:
- *         description: Team ownership updated
- *         content:
- *           application/json:
- *             schema:
- *               type: object
- *               properties:
- *                 ok: { type: boolean }
- *                 updated: { type: integer }
- *       404: { description: 'Team or device not found' }
- *       401: { $ref: '#/components/responses/Unauthorized' }
- *       403: { $ref: '#/components/responses/Forbidden' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- */
-/**
- * @swagger
- * /api/queue/status/{capability_id}:
- *   get:
- *     summary: Status of a single queued session request
- *     description: |
- *       Returns the queue position and ETA for a pending session keyed by the
- *       capability id you submitted. 404 if the request has already been
- *       allocated or expired, or is one the caller can't see in
- *       `GET /api/queue`: the same answer as for an unknown id.
- *     tags: [Grid]
- *     parameters:
- *       - in: path
- *         name: capability_id
- *         required: true
- *         schema: { type: string }
- *     responses:
- *       200:
- *         description: Queue status
- *         content:
- *           application/json:
- *             schema: { type: object, additionalProperties: true }
- *       404: { description: 'Pending session not found' }
- *       401: { $ref: '#/components/responses/Unauthorized' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- */
-/**
- * @swagger
- * /api/node/{host}/status:
- *   get:
- *     summary: ADB / device status for a specific node
- *     description: |
- *       If `host` matches the node serving the request, the response is built
- *       locally. Otherwise the hub proxies the call to that node's
- *       `/api/node/status` endpoint and returns the result. Returns 404 if no
- *       devices are registered for the requested host.
- *     tags: [Grid]
- *     parameters:
- *       - in: path
- *         name: host
- *         required: true
- *         schema: { type: string }
- *         description: 'Node host (URL or hostname as registered with the hub)'
- *     responses:
- *       200:
- *         description: Per-device status
- *         content:
- *           application/json:
- *             schema:
- *               type: array
- *               items:
- *                 type: object
- *                 properties:
- *                   udid: { type: string }
- *                   host: { type: string }
- *                   state: { type: string }
- *                   platform: { type: string, enum: [ios, android] }
- *       404: { description: 'No devices registered for that host' }
- *       401: { $ref: '#/components/responses/Unauthorized' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- */
-// =============================================================================
-// Selector Health — previously-undocumented routes
-// =============================================================================
-/**
- * @swagger
- * /api/healing/events:
- *   get:
- *     summary: Recent healing events
- *     description: |
- *       Returns the most recent self-healing events along with a `todayCount`
- *       used by the dashboard "today" badge. Newest first; clamped to 1–200.
- *     tags: [Selector Health]
- *     parameters:
- *       - in: query
- *         name: limit
- *         schema: { type: integer, minimum: 1, maximum: 200, default: 50 }
- *     responses:
- *       200:
- *         description: Recent events
- *         content:
- *           application/json:
- *             schema:
- *               type: object
- *               properties:
- *                 events:
- *                   type: array
- *                   items:
- *                     type: object
- *                     properties:
- *                       id: { type: string }
- *                       sessionId: { type: string }
- *                       deviceUdid: { type: string }
- *                       deviceName: { type: string }
- *                       devicePlatform: { type: string, enum: [ios, android] }
- *                       commandName: { type: string }
- *                       originalSelector: { type: string }
- *                       healedSelector: { type: string }
- *                       confidence: { type: number }
- *                       tier: { type: string }
- *                       isSuccess: { type: boolean }
- *                       createdAt: { type: string, format: date-time }
- *                 todayCount: { type: integer }
- *       401: { $ref: '#/components/responses/Unauthorized' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- */
-/**
- * @swagger
- * /api/healing/summary:
- *   get:
- *     summary: Selector-health KPI summary with prior-period comparison
- *     description: |
- *       Aggregates over `windowDays` (clamped 1–365, default 30) and emits a
- *       parallel "prior" object covering the equivalent immediately-preceding
- *       window — use the diff for week-over-week / month-over-month deltas.
- *     tags: [Selector Health]
- *     parameters:
- *       - in: query
- *         name: windowDays
- *         schema: { type: integer, minimum: 1, maximum: 365, default: 30 }
- *       - in: query
- *         name: tz
- *         schema: { type: integer, minimum: -840, maximum: 840, default: 0 }
- *         description: "The caller's offset from UTC in minutes (east positive), so `trend` days are theirs"
- *     responses:
- *       200:
- *         description: KPI summary
- *         content:
- *           application/json:
- *             schema:
- *               type: object
- *               properties:
- *                 windowDays: { type: integer }
- *                 current:
- *                   type: object
- *                   properties:
- *                     totalHeals: { type: integer }
- *                     distinctSelectors: { type: integer }
- *                     sessionsTouched: { type: integer }
- *                     byTier: { type: object, additionalProperties: { type: integer } }
- *                     timeSpentMs: { type: integer, description: 'Total duration of the commands that needed healing' }
- *                 prior:
- *                   type: object
- *                   description: 'Same shape as `current` for the immediately preceding window'
- *                 resolvedCount: { type: integer }
- *                 pendingCount: { type: integer }
- *                 trend:
- *                   type: array
- *                   description: 'Heals per day of the period, in the caller''s time zone, days with none included'
- *                   items:
- *                     type: object
- *                     properties:
- *                       t: { type: integer, description: 'When the day began, epoch ms' }
- *                       heals: { type: integer }
- *                       aiHeals: { type: integer, description: 'Heals by Visual AI or an LLM' }
- *       401: { $ref: '#/components/responses/Unauthorized' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- */
-/**
- * @swagger
- * /api/healing/selectors:
- *   get:
- *     summary: One tab of the Selector Health list
- *     description: |
- *       `fix` groups the period's heals by selector and leaves out selectors
- *       being verified, fixed or muted; the other tabs list the selectors with
- *       that status (`fixed`: verified within the period). Only selectors
- *       healed, at any time, in sessions the caller can see. `counts` follow
- *       the period, not the search or filters. A page past the end answers the
- *       last page.
- *     tags: [Selector Health]
- *     parameters:
- *       - { in: query, name: tab, schema: { type: string, enum: [fix, verifying, fixed, muted], default: fix } }
- *       - { in: query, name: days, schema: { type: integer, minimum: 1, maximum: 365, default: 30 } }
- *       - { in: query, name: q, schema: { type: string }, description: 'Text in the selector, or (fix) in its suggested fix' }
- *       - { in: query, name: platform, schema: { type: string }, description: 'fix only' }
- *       - { in: query, name: method, schema: { type: string }, description: 'Healing method, e.g. LLM; fix only' }
- *       - { in: query, name: sort, schema: { type: string, enum: [heals, recent, time], default: heals }, description: 'fix only' }
- *       - { in: query, name: page, schema: { type: integer, minimum: 1, default: 1 } }
- *       - { in: query, name: pageSize, schema: { type: integer, minimum: 1, maximum: 100, default: 50 } }
- *     responses:
- *       200: { description: '`{ tab, days, page, pageSize, total, counts, canAct, items }`' }
- *       401: { $ref: '#/components/responses/Unauthorized' }
- */
-/**
- * @swagger
- * /api/healing/selectors/detail:
- *   get:
- *     summary: Everything the Selector Health side panel shows for one selector
- *     description: |
- *       Its heals in the period (suggested fixes with their share, methods and
- *       confidence; heals per day; platforms, builds and devices; the latest 20
- *       heals), its status, the latest 50 status changes with who made them,
- *       and whether the caller may act. A selector no session the caller can
- *       see has healed answers 404, exactly as an unknown one.
- *     tags: [Selector Health]
- *     parameters:
- *       - { in: query, name: selector, required: true, schema: { type: string } }
- *       - { in: query, name: strategy, schema: { type: string }, description: "Empty for heals recorded with no strategy" }
- *       - { in: query, name: days, schema: { type: integer, minimum: 1, maximum: 365, default: 30 } }
- *       - { in: query, name: tz, schema: { type: integer, minimum: -840, maximum: 840, default: 0 } }
- *     responses:
- *       200: { description: 'The panel for one selector' }
- *       400: { description: 'No selector given' }
- *       404: { description: '`{ error: "not_found", message: "Selector not found" }`' }
- *       401: { $ref: '#/components/responses/Unauthorized' }
- */
-/**
- * @swagger
- * /api/healing/digest/send:
- *   post:
- *     summary: On-demand selector-health digest webhook
- *     description: |
- *       Manually fires the digest that the scheduler normally sends on a fixed
- *       cadence. Useful for pre-release "is the selector landscape healthy
- *       enough to ship?" gates. Requires `admin` scope.
- *     tags: [Selector Health]
- *     requestBody:
- *       content:
- *         application/json:
- *           schema:
- *             type: object
- *             properties:
- *               windowDays: { type: integer }
- *               limit: { type: integer }
- *               minHealCount: { type: integer }
- *     responses:
- *       200:
- *         description: Digest dispatched
- *         content:
- *           application/json:
- *             schema:
- *               type: object
- *               properties:
- *                 sent: { type: integer, description: 'Number of webhook subscribers fired' }
- *                 windowDays: { type: integer }
- *                 hotspotsIncluded: { type: integer }
- *       401: { $ref: '#/components/responses/Unauthorized' }
- *       403: { $ref: '#/components/responses/Forbidden' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- */
-// =============================================================================
-// Control — previously-undocumented routes
-// =============================================================================
-/**
- * @swagger
- * /api/control/{udid}/logs:
- *   get:
- *     summary: Pull recent device logs
- *     description: |
- *       Android: `adb logcat -d` style snapshot. iOS: recent syslog buffer.
- *       Returns plain text wrapped in a JSON `logs` field.
- *     tags: [Control]
- *     parameters:
- *       - in: path
- *         name: udid
- *         required: true
- *         schema: { type: string }
- *     responses:
- *       200:
- *         description: Device logs
- *         content:
- *           application/json:
- *             schema:
- *               type: object
- *               properties:
- *                 logs: { type: string }
- *       404: { description: 'Device not found' }
- *       401: { $ref: '#/components/responses/Unauthorized' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- */
-// =============================================================================
-// Bug Report — one-click bundling of session artifacts
-// =============================================================================
-/**
- * @swagger
- * /api/sessions/{sessionId}/bug-report:
- *   post:
- *     summary: Generate a bug-report bundle for a session
- *     description: |
- *       Streams a zip archive containing the session's video, logs, HAR, AI
- *       summary, and a manifest.json. In `slice` mode the video is trimmed to
- *       the last `windowSec` seconds (default 60). In `full` mode the entire
- *       session is included verbatim.
- *     tags: [Sessions]
- *     parameters:
- *       - in: path
- *         name: sessionId
- *         required: true
- *         schema: { type: string }
- *       - in: query
- *         name: mode
- *         required: true
- *         schema: { type: string, enum: [slice, full] }
- *       - in: query
- *         name: windowSec
- *         required: false
- *         schema: { type: integer, minimum: 5, maximum: 600, default: 60 }
- *         description: Slice window length in seconds. Ignored when mode=full.
- *     responses:
- *       200:
- *         description: zip archive
- *         content:
- *           application/zip:
- *             schema: { type: string, format: binary }
- *       400: { $ref: '#/components/responses/BadRequest' }
- *       401: { $ref: '#/components/responses/Unauthorized' }
- *       403: { $ref: '#/components/responses/Forbidden' }
- *       404: { $ref: '#/components/responses/NotFound' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- */
-/**
- * @swagger
- * /api/recordings:
- *   post:
- *     summary: Start a multi-device recording group
- *     description: Start free-form recording on one or more devices. Atomic — if any UDID is busy or the concurrency cap is exceeded, nothing is started.
- *     tags: [Recordings]
- *     requestBody:
- *       required: true
- *       content:
- *         application/json:
- *           schema:
- *             type: object
- *             required: [udids]
- *             properties:
- *               udids:
- *                 type: array
- *                 items: { type: string }
- *                 description: Device UDIDs to record
- *               sessionId:
- *                 type: string
- *                 description: Optional session ID to associate
- *               note:
- *                 type: string
- *                 description: Optional label for the recording group
- *     responses:
- *       202:
- *         description: Recording started
- *         content:
- *           application/json:
- *             schema:
- *               type: object
- *               properties:
- *                 groupId: { type: string }
- *                 recordings:
- *                   type: array
- *                   items:
- *                     type: object
- *                     properties:
- *                       id: { type: string }
- *                       udid: { type: string }
- *                       status: { type: string }
- *                 startedAt: { type: string, format: date-time }
- *       409:
- *         description: Device busy or concurrency cap reached
- *         content:
- *           application/json:
- *             schema:
- *               type: object
- *               properties:
- *                 error: { type: string, enum: [device_busy, concurrency_cap] }
- *                 busyDevices:
- *                   type: array
- *                   items:
- *                     type: object
- *                     properties:
- *                       udid: { type: string }
- *                       reason: { type: string }
- *                       sessionId: { type: string }
- *                       blockId: { type: string }
- *                 limit: { type: integer }
- *                 active: { type: integer }
- *                 message: { type: string }
- *       401: { $ref: '#/components/responses/Unauthorized' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- */
-/**
- * @swagger
- * /api/recordings/{groupId}/add-device:
- *   post:
- *     summary: Add a device to a running recording group
- *     description: Add a single device to an existing, active recording group. Atomic — if the device is busy or the cap is exceeded, nothing is started.
- *     tags: [Recordings]
- *     parameters:
- *       - in: path
- *         name: groupId
- *         required: true
- *         schema: { type: string }
- *         description: Recording group ID
- *     requestBody:
- *       required: true
- *       content:
- *         application/json:
- *           schema:
- *             type: object
- *             required: [udid]
- *             properties:
- *               udid:
- *                 type: string
- *                 description: Device UDID to add
- *     responses:
- *       201:
- *         description: Device added to recording group
- *         content:
- *           application/json:
- *             schema:
- *               type: object
- *               properties:
- *                 recording:
- *                   type: object
- *                   properties:
- *                     id: { type: string }
- *                     udid: { type: string }
- *                     status: { type: string }
- *       409:
- *         description: Device busy or concurrency cap reached
- *       401: { $ref: '#/components/responses/Unauthorized' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- */
-/**
- * @swagger
- * /api/recordings/{groupId}/stop:
- *   post:
- *     summary: Stop all recordings in a group
- *     description: Stop all active recordings in the specified group. Each recording is finalized independently.
- *     tags: [Recordings]
- *     parameters:
- *       - in: path
- *         name: groupId
- *         required: true
- *         schema: { type: string }
- *     responses:
- *       200:
- *         description: Recordings stopped
- *         content:
- *           application/json:
- *             schema:
- *               type: object
- *               properties:
- *                 groupId: { type: string }
- *                 recordings:
- *                   type: array
- *                   items:
- *                     type: object
- *                     properties:
- *                       id: { type: string }
- *                       udid: { type: string }
- *                       status: { type: string }
- *                       durationMs: { type: integer }
- *                       sizeBytes: { type: integer }
- *       401: { $ref: '#/components/responses/Unauthorized' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- */
-/**
- * @swagger
- * /api/recordings/{groupId}/bookmark:
- *   post:
- *     summary: Add a bookmark to a recording
- *     description: Drop a time-stamped bookmark on a recording, optionally with a note.
- *     tags: [Recordings]
- *     parameters:
- *       - in: path
- *         name: groupId
- *         required: true
- *         schema: { type: string }
- *     requestBody:
- *       required: true
- *       content:
- *         application/json:
- *           schema:
- *             type: object
- *             required: [recordingId, timecodeMs, label]
- *             properties:
- *               recordingId: { type: string }
- *               timecodeMs: { type: integer }
- *               label: { type: string }
- *               note: { type: string }
- *     responses:
- *       201:
- *         description: Bookmark created
- *       401: { $ref: '#/components/responses/Unauthorized' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- */
-/**
- * @swagger
- * /api/recordings/{groupId}/annotation:
- *   post:
- *     summary: Add an annotation to a recording
- *     description: Persist a normalized annotation (shape, geometry, color) on a recording frame.
- *     tags: [Recordings]
- *     parameters:
- *       - in: path
- *         name: groupId
- *         required: true
- *         schema: { type: string }
- *     requestBody:
- *       required: true
- *       content:
- *         application/json:
- *           schema:
- *             type: object
- *             required: [recordingId, timecodeMs, shape, geometry, color]
- *             properties:
- *               recordingId: { type: string }
- *               timecodeMs: { type: integer }
- *               shape: { type: string, enum: [RECT, CIRCLE, ARROW, TEXT, FREEHAND] }
- *               geometry: { type: string, description: JSON string with normalized coordinates }
- *               color: { type: string }
- *               text: { type: string }
- *               author: { type: string }
- *     responses:
- *       201:
- *         description: Annotation created
- *       401: { $ref: '#/components/responses/Unauthorized' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- */
-/**
- * @swagger
- * /api/recordings/{groupId}:
- *   get:
- *     summary: Get recording group details
- *     description: Retrieve all recordings, bookmarks, and annotations for a recording group.
- *     tags: [Recordings]
- *     parameters:
- *       - in: path
- *         name: groupId
- *         required: true
- *         schema: { type: string }
- *     responses:
- *       200:
- *         description: Recording group details
- *         content:
- *           application/json:
- *             schema:
- *               type: object
- *               properties:
- *                 groupId: { type: string }
- *                 recordings: { type: array }
- *       401: { $ref: '#/components/responses/Unauthorized' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- */
-/**
- * @swagger
- * /api/recordings/{groupId}/bundle.zip:
- *   get:
- *     summary: Download proof bundle
- *     description: Download a self-contained zip containing videos, bookmarks, annotations, and device metadata.
- *     tags: [Recordings]
- *     parameters:
- *       - in: path
- *         name: groupId
- *         required: true
- *         schema: { type: string }
- *     responses:
- *       200:
- *         description: Zip archive stream
- *         content:
- *           application/zip:
- *             schema: { type: string, format: binary }
- *       401: { $ref: '#/components/responses/Unauthorized' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- */
-/**
- * @swagger
- * /api/recordings/{groupId}/exports/annotated.mp4:
- *   get:
- *     summary: Download annotated MP4
- *     description: Generate and stream an MP4 with annotations burned into the video pixels. Lazy — only rendered on demand.
- *     tags: [Recordings]
- *     parameters:
- *       - in: path
- *         name: groupId
- *         required: true
- *         schema: { type: string }
- *       - in: query
- *         name: recordingId
- *         required: true
- *         schema: { type: string }
- *         description: The specific recording to render
- *     responses:
- *       200:
- *         description: Annotated MP4 stream
- *         content:
- *           video/mp4:
- *             schema: { type: string, format: binary }
- *       400:
- *         description: Missing recordingId query param
- *       401: { $ref: '#/components/responses/Unauthorized' }
- *       429: { $ref: '#/components/responses/RateLimited' }
- */