openapi: "3.1.0"
info:
  title: HelixForge Telegram Publishing
  version: "R-1"
  description: |
    Publishes hall-of-helix entries to a Telegram channel.

    The interface takes an entry as it was written and is responsible for
    everything about how it becomes a Telegram post. A caller should never need
    to know Telegram's constraints.

    Publication is idempotent on entry_id: publishing the same entry twice
    yields one publication. This matters because the caller is usually
    automation that may be retried.

paths:
  /v1/hall-entries:
    post:
      operationId: publishEntry
      summary: Publish a hall-of-helix entry
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [entry_id, title, body]
              additionalProperties: false
              properties:
                entry_id:
                  type: string
                  minLength: 1
                  maxLength: 128
                  description: |
                    The hall entry's own id, from its frontmatter. Publication
                    is idempotent on this value.
                title:
                  type: string
                  minLength: 1
                  maxLength: 256
                body:
                  type: string
                  minLength: 1
                  description: |
                    The entry body as Markdown, frontmatter removed.

                    Deliberately unbounded. Telegram's 4096-character message
                    limit is this interface's problem, not the caller's, and a
                    maxLength here would push it back onto them.
                display_name:
                  type: string
                  maxLength: 128
                worker_kind:
                  type: string
                  enum: [human, agent-session]
                recorded_at:
                  type: string
                  format: date
                source_url:
                  type: string
                  description: Canonical location of the entry in hall-of-helix.
      responses:
        "201":
          description: Published
        "200":
          description: Already published; the existing publication is returned
        "400":
          description: The entry cannot be published faithfully
        "502":
          description: Telegram was unreachable or refused the message

    get:
      operationId: listPublications
      summary: List publications, newest first
      parameters:
        - name: limit
          in: query
          required: false
          schema: {type: integer, minimum: 1, maximum: 100}
        - name: state
          in: query
          required: false
          schema:
            type: string
            enum: [pending, published, failed, superseded]
      responses:
        "200":
          description: Publications

  /v1/hall-entries/{entry_id}:
    get:
      operationId: getPublication
      summary: Publication state for one entry
      parameters:
        - name: entry_id
          in: path
          required: true
          schema: {type: string, minLength: 1}
      responses:
        "200":
          description: Publication state
        "404":
          description: This entry has not been published