openapi: 3.0.3
info:
  title: Orders API
  version: 1.0.0
  description: >
    Fixture spec for the APIFae CLI scenario tests (APIFAE-102). Small enough to
    read in one screen, large enough to carry the four drift shapes the backend
    persona cares about: an undocumented field added to an error body, an
    extended enum, a field made nullable, and a 201 quietly turned into a 200.
servers:
  - url: http://localhost:9100
    description: Local dev instance of the real implementation

paths:
  /orders:
    get:
      operationId: listOrders
      summary: List orders
      parameters:
        - name: page
          in: query
          required: false
          schema: { type: integer, default: 1 }
      responses:
        '200':
          description: A page of orders
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderPage'
    post:
      operationId: createOrder
      summary: Create an order
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewOrder'
      responses:
        '201':
          description: Order created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'

  /orders/{id}:
    get:
      operationId: getOrder
      summary: Fetch a single order
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: The order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '404':
          description: No such order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /reports/daily:
    get:
      operationId: dailyReport
      summary: Daily settlement report
      description: >
        Known-broken in dev: the report worker is not wired up, so this returns
        a 500 with the standard error envelope. Documented deliberately, because
        the error envelope is part of the contract even when the endpoint fails.
      responses:
        '500':
          description: Report generation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  schemas:
    Order:
      type: object
      required: [id, status, total, currency, customerEmail, note, createdAt]
      properties:
        id:
          type: string
          example: "ord_8f14e45fceea"
        status:
          type: string
          enum: [pending, paid, shipped]
          example: "paid"
        total:
          type: number
          example: 4250
        currency:
          type: string
          example: "EUR"
        customerEmail:
          type: string
          example: "ada@example.com"
        note:
          type: string
          description: Free-text note. Always a string; never null.
          example: "Leave with the concierge"
        createdAt:
          type: string
          format: date-time
          example: "2026-08-01T09:15:00Z"

    NewOrder:
      type: object
      required: [total, currency, customerEmail]
      properties:
        total: { type: number, example: 4250 }
        currency: { type: string, example: "EUR" }
        customerEmail: { type: string, example: "ada@example.com" }
        note: { type: string, example: "Leave with the concierge" }

    OrderPage:
      type: object
      required: [data, page, total, hasMore]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Order'
        page: { type: integer, example: 1 }
        total: { type: integer, example: 3 }
        hasMore: { type: boolean, example: false }

    Error:
      type: object
      required: [error, message]
      properties:
        error:
          type: string
          example: "report_failed"
        message:
          type: string
          example: "Report worker is not available"