API Evangelist enhancements for the listmonk OpenAPI

# authorship: generated by API Evangelist tooling. Stamped 2026-08-18
# on the file's own generator header (roadmap#64). An unmarked file is
# NOT assumed to be ours -- absence of evidence was never stamped.
x-method: generated
overlay: 1.0.0
info:
  title: API Evangelist enhancements for the listmonk OpenAPI
  version: 1.0.0
  x-generated: '2026-08-13'
  x-method: generated
  x-source: >-
    Generated by API Evangelist against listmonk's own OpenAPI 3.0.0
    (https://listmonk.app/docs/swagger/collections.yaml, captured verbatim to
    openapi/_original/listmonk-collections-openapi.yml). Every value added here
    is documented by listmonk in prose — at /docs/apis/apis/,
    /docs/roles-and-permissions/ and /docs/installation/ — but is absent from the
    machine-readable contract. The overlay closes that gap without mutating the
    original.
  x-rationale: >-
    Three real gaps in listmonk's published spec: (1) it declares no
    securitySchemes and no security requirement at all, so a generated client
    ships with no auth; (2) it documents only 200 responses across all 72
    operations, so no generated client knows what a failure looks like; (3) its
    only concrete server is http://localhost:9000/api, which is correct for a
    default install but does not say that a real deployment substitutes its own
    host over https.
extends: ../openapi/_original/listmonk-collections-openapi.yml
actions:
  - target: $.info
    description: Point consumers at the canonical documentation and record the application version the spec tracks.
    update:
      x-application-version: '6.2.0'
      x-api-evangelist-note: >-
        info.version in the upstream document is 1.0.0 and tracks the spec file,
        not the application. The API is not versioned independently of listmonk
        itself.
      contact:
        name: listmonk
        url: https://listmonk.app/docs/apis/apis/
      license:
        name: AGPL-3.0
        url: https://github.com/knadh/listmonk/blob/master/LICENSE

  - target: $
    description: >-
      Add the templated https server that a real deployment uses, alongside the
      upstream localhost default, and declare a default security requirement.
    update:
      externalDocs:
        description: listmonk API documentation
        url: https://listmonk.app/docs/apis/apis/
      security:
        - BasicAuth: []
        - TokenAuth: []

  - target: $.servers
    description: Append a templated self-hosted server. The upstream localhost entry is left in place.
    update:
      - url: 'https://{host}/api'
        description: >-
          Self-hosted listmonk instance. Substitute the operator's own hostname.
          listmonk operates no shared API host.
        variables:
          host:
            default: localhost:9000
            description: Hostname of the listmonk deployment.

  - target: $.components
    description: >-
      Declare the two authentication schemes listmonk documents at
      /docs/apis/apis/ but does not express in the spec.
    update:
      securitySchemes:
        BasicAuth:
          type: http
          scheme: basic
          description: >-
            HTTP Basic auth with an API user name and its generated token
            (api_user:token). Example: curl -u "api_user:token"
            http://localhost:9000/api/lists
        TokenAuth:
          type: apiKey
          in: header
          name: Authorization
          description: >-
            Authorization header in the form `token api_user:token`. Example:
            curl -H "Authorization: token api_user:token"
            http://localhost:9000/api/lists

  - target: $.components.schemas
    description: >-
      Add the error envelope listmonk documents in prose. The upstream spec
      describes no failure shape anywhere.
    update:
      Error:
        type: object
        required:
          - message
        properties:
          message:
            type: string
            description: Human-readable error message. The only guaranteed field on a failure.
            example: invalid session
          data:
            type: object
            nullable: true
            description: Optional additional payload accompanying the error.

  - target: $.paths.*[?(@.responses)]
    description: >-
      Attach the common failure responses from listmonk's published error table
      to every operation. None of these appear in the upstream spec.
    update:
      responses:
        '400':
          description: Missing or bad request parameters or values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            Session expired or invalidated; must re-authenticate. NOTE listmonk
            returns 403, not 401, for a missing or invalid API credential, and
            sends no WWW-Authenticate challenge.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Unprocessable entity — the request contains invalid data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: >-
            Too many requests (rate limiting). No RateLimit-* or Retry-After
            header accompanies this response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Something unexpected went wrong.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  - target: $.tags
    description: Cross-reference the derived API Evangelist artifacts from the tag set.
    update:
      - name: Subscribers
        x-artifacts:
          data-model: ../data-model/listmonk-data-model.yml
          conventions: ../conventions/listmonk-conventions.yml
      - name: Bounces
        x-artifacts:
          asyncapi: ../asyncapi/listmonk-bounce-webhooks-asyncapi.yml