openapi: 3.1.0
info:
  title: Transcode Server
  version: 0.1.0
  description: >-
    Transcodes raw per-call PCM recordings (signed 16-bit little-endian, 24 kHz,
    mono) written by the media server into compressed audio formats. Jobs run
    through a bounded queue (at most two concurrent transcodes); requests beyond
    that wait their turn and the response is returned synchronously once the job
    completes.
servers:
  - url: http://localhost:8080
    description: In-container default (PORT=8080)
  - url: http://127.0.0.1:8083
    description: Host-published port (docker-compose)

paths:
  /health:
    get:
      operationId: getHealth
      summary: Liveness/readiness probe
      description: Returns 200 while the process is up. Used by the container healthcheck.
      responses:
        "200":
          description: The server is up.
          content:
            application/json:
              schema:
                type: object
                required: [ok]
                properties:
                  ok:
                    type: boolean
                    const: true
              example:
                ok: true

  /metrics:
    get:
      operationId: getMetrics
      summary: Prometheus metrics
      description: >-
        Exposes prom-client metrics in the Prometheus text exposition format.
        Includes default Node process metrics (prefixed `jamb_`) plus
        transcode-specific series: `jamb_transcode_requests_total`,
        `jamb_transcode_duration_seconds`, `jamb_transcode_bytes_total`,
        `jamb_transcode_queue_depth`, and `jamb_transcode_jobs_running`.
      responses:
        "200":
          description: Metrics in Prometheus text format.
          content:
            text/plain:
              schema:
                type: string
              example: |
                # HELP jamb_transcode_requests_total Transcode jobs by output format and result
                # TYPE jamb_transcode_requests_total counter
                jamb_transcode_requests_total{format="mp3",result="success"} 6

  /transcode:
    post:
      operationId: transcode
      summary: Transcode a call recording
      description: >-
        Reads the raw PCM recording for `uuid` from
        `{MEDIA_SERVER_ROOT}/voip/calls2/{uuid}/mono.raw` and transcodes it to
        the requested format. The job is enqueued (bounded concurrency) and the
        encoded audio is returned in the response body once it finishes.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TranscodeRequest"
            example:
              uuid: 2f8a1c4e-9b3d-4a71-8e2f-0c1d2e3f4a5b
              format: mp3
      responses:
        "200":
          description: The transcoded audio.
          content:
            audio/mpeg:
              schema:
                type: string
                format: binary
        "400":
          description: The request body failed validation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationError"
              example:
                error: Invalid request body
                details:
                  - code: invalid_value
                    values: [mp3]
                    path: [format]
                    message: 'Invalid input: expected "mp3"'
        "404":
          description: No recording exists for the given `uuid`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: Recording not found
        "502":
          description: The recording was found but transcoding failed (e.g. ffmpeg error).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: Transcode failed

components:
  schemas:
    TranscodeRequest:
      type: object
      additionalProperties: false
      required: [uuid, format]
      properties:
        uuid:
          type: string
          minLength: 1
          description: The call recording identifier.
          example: 2f8a1c4e-9b3d-4a71-8e2f-0c1d2e3f4a5b
        format:
          type: string
          enum: [mp3]
          description: Target output format. Only `mp3` is supported for now.

    Error:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Human-readable error message.

    ValidationError:
      allOf:
        - $ref: "#/components/schemas/Error"
        - type: object
          properties:
            details:
              type: array
              description: Zod validation issues describing what failed.
              items:
                type: object
                additionalProperties: true