openapi: 3.1.0
info:
  title: Document Renaming Service
  description: Renames documents in R2 storage based on classification results and normalized data, producing standardized filenames.
  version: 1.0.0

servers:
  - url: https://document-renaming.your-subdomain.workers.dev
    description: Production

security:
  - UniversalApiKey: []

paths:
  /health:
    get:
      operationId: getHealth
      summary: Health check
      security: []
      responses:
        "200":
          description: Service is healthy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"

  /v1/renaming:
    post:
      operationId: createRenamingRun
      summary: Create a renaming run
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RenamingRequest"
      responses:
        "200":
          description: Renaming run created and queued
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RenamingResponse"
        "400":
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /v1/renaming/{renamingId}:
    get:
      operationId: getRenamingStatus
      summary: Get renaming run status
      parameters:
        - name: renamingId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Renaming run status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RenamingStatusResponse"
        "404":
          description: Renaming run not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /v1/renaming/{renamingId}/revert:
    post:
      operationId: revertRenaming
      summary: Revert a completed renaming
      parameters:
        - name: renamingId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Renaming reverted successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RevertResponse"
        "404":
          description: Renaming run not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: Renaming run cannot be reverted (not in completed state)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /v1/config:
    get:
      operationId: getConfig
      summary: Get current service configuration
      responses:
        "200":
          description: Service configuration
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConfigResponse"

components:
  securitySchemes:
    UniversalApiKey:
      type: apiKey
      in: header
      name: X-Universal-Api-Key

  schemas:
    ClassificationResult:
      type: object
      required:
        - artifactName
      properties:
        artifactName:
          type: string
          description: The classified artifact/document type name
        artifactId:
          type: string
          description: Optional artifact identifier

    RenamingRequest:
      type: object
      required:
        - documentId
        - r2Key
        - classificationResult
      properties:
        renamingId:
          type: string
          description: Optional custom renaming ID (auto-generated if omitted)
        documentId:
          type: string
          description: Unique identifier for the document
        r2Key:
          type: string
          description: Original R2 key of the document
        classificationResult:
          $ref: "#/components/schemas/ClassificationResult"
        normalizedData:
          type: object
          description: Normalized data used to build the new filename (owner, date, etc.)
          properties:
            owner:
              type: string
            date:
              type: string
              format: date
            extension:
              type: string

    RenamingResponse:
      type: object
      required:
        - ok
        - renamingId
        - documentId
        - status
      properties:
        ok:
          type: boolean
          enum:
            - true
        renamingId:
          type: string
          description: The ID of the created renaming run
        documentId:
          type: string
          description: The document ID
        status:
          type: string
          enum:
            - queued
          description: Initial status is always queued

    RenamingStatusResponse:
      type: object
      required:
        - ok
        - renamingId
        - documentId
        - status
      properties:
        ok:
          type: boolean
          enum:
            - true
        renamingId:
          type: string
        documentId:
          type: string
        status:
          type: string
          enum:
            - queued
            - processing
            - completed
            - failed
            - reverted
        originalR2Key:
          type: string
          description: The original R2 key before renaming
        newR2Key:
          type: string
          description: The new R2 key after renaming
        newFilename:
          type: string
          description: The new standardized filename
        error:
          type: string
          description: Error message if status is failed
        createdAt:
          type: string
          format: date-time
        completedAt:
          type: string
          format: date-time
        revertedAt:
          type: string
          format: date-time

    RevertResponse:
      type: object
      required:
        - ok
        - renamingId
        - status
        - restoredR2Key
      properties:
        ok:
          type: boolean
          enum:
            - true
        renamingId:
          type: string
          description: The ID of the reverted renaming run
        status:
          type: string
          enum:
            - reverted
        restoredR2Key:
          type: string
          description: The original R2 key that was restored

    ConfigResponse:
      type: object
      required:
        - ok
        - renamedPrefix
      properties:
        ok:
          type: boolean
          enum:
            - true
        renamedPrefix:
          type: string
          description: The R2 key prefix used for renamed documents

    HealthResponse:
      type: object
      required:
        - ok
        - service
      properties:
        ok:
          type: boolean
          enum:
            - true
        service:
          type: string
          enum:
            - document-renaming

    ErrorResponse:
      type: object
      required:
        - ok
        - error
      properties:
        ok:
          type: boolean
          enum:
            - false
        error:
          type: string