openapi.yaml

openapi: 3.0.3

info:
  title: ELMS — Electronic Locker Management System
  version: 1.0.0
  description: |
    Contract for the ELMS backend. This document is the source of truth: it
    generates the Go server interface (oapi-codegen) and the TypeScript client
    (openapi-typescript), so the SPA and the API cannot drift apart.

    Three audiences share one API:

    - **Agents** store packages and read locker availability.
    - **Admins** manage stations, lockers and pricing, and read the dashboard.
    - **Customers** use the kiosk. They have no account: the locker label plus
      the 6-digit pickup code *is* the credential, which is why `/pickup/*` is
      unauthenticated and rate-limited instead (TDD §9).

    Conventions:

    - Money is always an integer count of **minor units** (cents) in the named
      currency. No floating point appears anywhere in this contract.
    - Timestamps are RFC 3339 in UTC.
    - Every failure is an RFC 7807 `application/problem+json` document.
    - Operations that need a session carry `x-required-role`. `agent` means any
      logged-in operator (admins included); `admin` means admins only.

servers:
  - url: /api/v1

# Session by default. Public endpoints opt out with `security: []` — an explicit
# decision each time, never an omission.
security:
  - sessionCookie: []

tags:
  - name: auth
    description: Login, logout and the current principal (FR-13).
  - name: stations
    description: Station management (FR-1).
  - name: lockers
    description: Locker management, availability, maintenance and fit preview (FR-2..4, FR-16).
  - name: catalogs
    description: The cell sizes and box templates everything else measures against (FR-15).
  - name: packages
    description: Storing packages (FR-5..7).
  - name: pickup
    description: Public kiosk retrieval — quote, pay, open (FR-8..10).
  - name: admin
    description: Pricing and the occupancy dashboard (FR-11, FR-14).
  - name: system
    description: Liveness.

paths:
  ## -------------------------------------------------------------- auth

  /auth/login:
    post:
      operationId: login
      tags: [auth]
      summary: Exchange credentials for a session cookie
      description: |
        A failed login never says which half was wrong (FR-13), and an unknown
        username costs the same time as a wrong password.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      responses:
        '200':
          description: Signed in. The session cookie is set on this response.
          headers:
            Set-Cookie:
              description: '`elms_session=<token>; HttpOnly; SameSite=Lax; Secure; Path=/` (TDD §8.2).'
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          description: Invalid credentials — deliberately not saying which field.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        default:
          $ref: '#/components/responses/Unexpected'

  /auth/logout:
    post:
      operationId: logout
      tags: [auth]
      summary: Destroy the current session
      description: The session is deleted server-side; the cookie is cleared.
      x-required-role: agent
      responses:
        '204':
          description: Signed out.
          headers:
            Set-Cookie:
              description: Expired `elms_session` cookie.
              schema:
                type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /auth/me:
    get:
      operationId: getCurrentUser
      tags: [auth]
      summary: The principal behind the current session
      description: The SPA's route guards are built on this (TDD §10).
      x-required-role: agent
      responses:
        '200':
          description: The signed-in operator.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  ## -------------------------------------------------------------- stations

  /stations:
    get:
      operationId: listStations
      tags: [stations]
      summary: List stations
      description: |
        Public, like the rest of the kiosk path. A customer has no account and
        must still choose which locker bank they are standing at (US-C1), so
        this is the one station operation that carries no role.

        Nothing here is a secret: a station's name and address are painted on
        the building. Knowing a station id buys nothing on its own — a pickup
        still needs the locker label and the 6-digit code, rate-limited to five
        attempts (FR-8). Creating, changing and deleting stations stay admin.
      security: []
      responses:
        '200':
          description: All stations, ordered by name — this is a list a person reads.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Station'
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

    post:
      operationId: createStation
      tags: [stations]
      summary: Create a station
      x-required-role: admin
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StationInput'
      responses:
        '201':
          description: Station created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Station'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        default:
          $ref: '#/components/responses/Unexpected'

  /stations/{stationId}:
    parameters:
      - $ref: '#/components/parameters/StationId'

    patch:
      operationId: updateStation
      tags: [stations]
      summary: Rename or re-address a station
      x-required-role: admin
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StationInput'
      responses:
        '200':
          description: Station updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Station'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/Unexpected'

    delete:
      operationId: deleteStation
      tags: [stations]
      summary: Delete an empty station
      description: A station that still has lockers cannot be deleted (FR-1).
      x-required-role: admin
      responses:
        '204':
          description: Station deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        default:
          $ref: '#/components/responses/Unexpected'

  ## -------------------------------------------------------------- lockers

  /stations/{stationId}/lockers:
    parameters:
      - $ref: '#/components/parameters/StationId'

    get:
      operationId: listLockers
      tags: [lockers]
      summary: List a station's lockers with live status
      description: |
        Powers the agent's availability grid and the admin's locker table
        (FR-3). Filters combine.
      x-required-role: agent
      parameters:
        - name: status
          in: query
          required: false
          description: Only lockers in this status.
          schema:
            $ref: '#/components/schemas/LockerStatus'
        - name: locker_type_id
          in: query
          required: false
          description: Only lockers of this cell type.
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Lockers, ordered by label.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Locker'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/Unexpected'

    post:
      operationId: createLocker
      tags: [lockers]
      summary: Add a locker to a station
      description: |
        Labels are unique within a station (FR-2); a duplicate is a 409. The
        admin UI proposes `<first letter of the type name>-<seq>` (`M-03`) and
        the operator may type anything else — the label is what a customer reads
        off the door, so the server never invents one.
      x-required-role: admin
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LockerCreate'
      responses:
        '201':
          description: Locker created, available for allocation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Locker'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        default:
          $ref: '#/components/responses/Unexpected'

  /stations/{stationId}/fit:
    parameters:
      - $ref: '#/components/parameters/StationId'

    get:
      operationId: previewFit
      tags: [lockers]
      summary: Ask what this station would do with a package of these measurements
      description: |
        The agent's form calls this while the numbers are still being typed
        (FR-16). It claims nothing: the fit rule lives on the server so it is
        not reimplemented in the browser, where no cross-check test can reach
        it, and the binding decision still happens when the store is submitted.
      x-required-role: agent
      parameters:
        - name: length_mm
          in: query
          required: true
          schema: { type: integer, minimum: 1, maximum: 5000 }
        - name: width_mm
          in: query
          required: true
          schema: { type: integer, minimum: 1, maximum: 5000 }
        - name: height_mm
          in: query
          required: true
          schema: { type: integer, minimum: 1, maximum: 5000 }
      responses:
        '200':
          description: What the station would do right now.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FitPreview'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/Unexpected'

  /lockers/{lockerId}:
    parameters:
      - $ref: '#/components/parameters/LockerId'

    patch:
      operationId: updateLocker
      tags: [lockers]
      summary: Relabel a locker, change its type, or move it in and out of service
      description: |
        The maintenance toggle lives here: `status: out_of_service` removes the
        locker from allocation. An occupied locker cannot be taken out of
        service, relabelled or retyped — that would strand a stored package
        (FR-4), so it answers 409.
      x-required-role: admin
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LockerUpdate'
      responses:
        '200':
          description: Locker updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Locker'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        default:
          $ref: '#/components/responses/Unexpected'

    delete:
      operationId: deleteLocker
      tags: [lockers]
      summary: Delete an empty locker
      x-required-role: admin
      responses:
        '204':
          description: Locker deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        default:
          $ref: '#/components/responses/Unexpected'

  ## -------------------------------------------------------------- catalogs

  /locker-types:
    get:
      operationId: listLockerTypes
      tags: [catalogs]
      summary: The cell sizes lockers are built from
      description: |
        Ordered by interior volume, smallest first — the same order allocation
        reasons in, so a Tower XL sits between Medium and Large whatever its
        name suggests. Agents may read it: the availability grid names types.
      x-required-role: agent
      responses:
        '200':
          description: The catalog.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LockerType'
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

    post:
      operationId: createLockerType
      tags: [catalogs]
      summary: Add a cell size
      x-required-role: admin
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LockerTypeInput'
      responses:
        '201':
          description: Type created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LockerType'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        default:
          $ref: '#/components/responses/Unexpected'

  /locker-types/{lockerTypeId}:
    parameters:
      - $ref: '#/components/parameters/LockerTypeId'

    patch:
      operationId: updateLockerType
      tags: [catalogs]
      summary: Correct a cell size
      description: |
        Editing is unrestricted: a package's dimensions are frozen when it is
        stored, so no correction here can rewrite history, and allocation asks
        the fit question afresh on every store (US-A7).
      x-required-role: admin
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LockerTypeUpdate'
      responses:
        '200':
          description: Type updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LockerType'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        default:
          $ref: '#/components/responses/Unexpected'

    delete:
      operationId: deleteLockerType
      tags: [catalogs]
      summary: Delete a cell size no locker is built from
      description: |
        A type the estate references answers 409: it is not the admin's to
        remove while lockers depend on it (US-A7).
      x-required-role: admin
      responses:
        '204':
          description: Type deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        default:
          $ref: '#/components/responses/Unexpected'

  /package-templates:
    get:
      operationId: listPackageTemplates
      tags: [catalogs]
      summary: The standard boxes the agent picks from
      description: Ordered by volume, smallest first.
      x-required-role: agent
      parameters:
        - name: active
          in: query
          required: false
          description: |
            `true` returns only the offered templates — what the agent's form
            asks for. Omitted, the whole catalog comes back, which is what the
            admin screen needs.
          schema:
            type: boolean
      responses:
        '200':
          description: The catalog.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PackageTemplate'
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

    post:
      operationId: createPackageTemplate
      tags: [catalogs]
      summary: Add a box template
      x-required-role: admin
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PackageTemplateInput'
      responses:
        '201':
          description: Template created, and offered.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PackageTemplate'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        default:
          $ref: '#/components/responses/Unexpected'

  /package-templates/{packageTemplateId}:
    parameters:
      - $ref: '#/components/parameters/PackageTemplateId'

    patch:
      operationId: updatePackageTemplate
      tags: [catalogs]
      summary: Correct or retire a box template
      description: |
        `active: false` retires it: the template leaves the agent's form and the
        packages measured from it keep their dimensions and their name (FR-15).
      x-required-role: admin
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PackageTemplateUpdate'
      responses:
        '200':
          description: Template updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PackageTemplate'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/Unexpected'

    delete:
      operationId: deletePackageTemplate
      tags: [catalogs]
      summary: Delete a box template nothing was measured from
      description: |
        A template a stored package names answers 409 — retire it instead, which
        is what keeps a receipt readable a year later (FR-15).
      x-required-role: admin
      responses:
        '204':
          description: Template deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        default:
          $ref: '#/components/responses/Unexpected'

  ## -------------------------------------------------------------- packages

  /packages:
    post:
      operationId: storePackage
      tags: [packages]
      summary: Store a package in the smallest fitting locker
      description: |
        Allocates the smallest available locker at the station that fits the
        package, lowest label first (FR-5), and returns the pickup code **once**
        (FR-6). The code is bcrypt-hashed before it is stored; nothing can show
        it again.

        A station with no fitting free locker answers 409 with no side effects
        (FR-7). Concurrent stores each get a different locker or a clean 409 —
        never the same locker twice (FR-12).
      x-required-role: agent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StorePackageRequest'
      responses:
        '201':
          description: Stored. This response is the only place the code appears.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoredPackage'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          description: |
            No available locker at that station fits the package — including
            the case of a station that does not exist, which is indistinguishable
            from a station with nothing free.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        default:
          $ref: '#/components/responses/Unexpected'

  ## -------------------------------------------------------------- pickup

  /pickup/quotes:
    post:
      operationId: quotePickup
      tags: [pickup]
      summary: Price a pickup and hold the quote
      description: |
        Public: the locker label plus the pickup code is the credential.

        Every failure — unknown station, unknown label, wrong code, package
        already collected — answers the same 404 (FR-8). After 5 failed
        attempts against one package, further attempts are refused with 429 for
        15 minutes.

        The quote freezes the amount for 15 minutes; a later rate change does
        not rewrite it (FR-11). Re-quoting while a pending payment exists
        returns that same quote rather than a second one.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuoteRequest'
      responses:
        '200':
          description: The charge, its per-tier breakdown, and the payment to confirm.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Quote'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          description: |
            Invalid pickup. Intentionally identical for every cause — the kiosk
            must never reveal whether the label or the code was wrong (§9).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          $ref: '#/components/responses/PickupBlocked'
        default:
          $ref: '#/components/responses/Unexpected'

  /pickup/payments/{paymentId}/confirm:
    parameters:
      - $ref: '#/components/parameters/PaymentId'

    post:
      operationId: confirmPickup
      tags: [pickup]
      summary: Pay the quote and open the locker
      description: |
        Mock payment. One transaction marks the payment paid, the package
        retrieved and the locker available again (FR-9).

        Confirming twice replays the receipt with `already_paid: true` instead
        of charging again — kiosk buttons get double-tapped. An expired quote
        answers 409 and is closed on the way out, so the customer can re-quote
        immediately.
      security: []
      responses:
        '200':
          description: Paid. The locker is open and the package is released.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Receipt'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          description: No such payment, or the package is no longer collectable.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '409':
          description: The quote expired before it was paid — quote again (FR-9).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        default:
          $ref: '#/components/responses/Unexpected'

  ## -------------------------------------------------------------- admin

  /admin/dashboard:
    get:
      operationId: getDashboard
      tags: [admin]
      summary: Occupancy, dwell time and accrued charges for a station
      description: |
        Accrued amounts are what a pickup would cost right now, at the current
        rate — they are live figures, not quotes, and nothing here is frozen
        (FR-14).
      x-required-role: admin
      parameters:
        - name: station_id
          in: query
          required: true
          description: The station to report on.
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: The station's current state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dashboard'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/Unexpected'

  /admin/audit-events:
    get:
      operationId: listAuditEvents
      tags: [admin]
      summary: The audit log, newest first
      description: |
        Every state-changing action, recorded in the transaction of the change
        itself (FR-17): stores, retrievals, failed and blocked pickup attempts,
        and every admin mutation. Newest first; insertion order breaks
        same-instant ties, so pages never flap. Both time bounds are inclusive
        — they arrive as day boundaries, and a boundary event belongs to the
        range. Pickup codes never appear in `details`, attempted or real.
      x-required-role: admin
      parameters:
        - name: event_type
          in: query
          required: false
          description: Only events of this type, e.g. `package_stored`.
          schema:
            type: string
        - name: station_id
          in: query
          required: false
          description: Only events concerning this station.
          schema:
            type: string
            format: uuid
        - name: from
          in: query
          required: false
          description: Only events at or after this instant.
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          required: false
          description: Only events at or before this instant.
          schema:
            type: string
            format: date-time
        - name: limit
          in: query
          required: false
          description: Page size; the server default is 50.
          schema:
            type: integer
            minimum: 1
            maximum: 200
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
      responses:
        '200':
          description: One page of the log, with the filtered total for paging.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditEventPage'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        default:
          $ref: '#/components/responses/Unexpected'

  /pricing-config:
    get:
      operationId: getPricingConfig
      tags: [admin]
      summary: Read the base daily rate
      x-required-role: admin
      responses:
        '200':
          description: The single pricing row.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PricingConfig'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        default:
          $ref: '#/components/responses/Unexpected'

    put:
      operationId: setPricingConfig
      tags: [admin]
      summary: Change the base daily rate X
      description: |
        Tiers stay fixed at 1×/2×/3×; only X and the currency are editable
        (FR-11). Quotes already issued keep the amount they were given.
      x-required-role: admin
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PricingConfigUpdate'
      responses:
        '200':
          description: Pricing updated; the next quote uses it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PricingConfig'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        default:
          $ref: '#/components/responses/Unexpected'

  ## -------------------------------------------------------------- system

  /healthz:
    get:
      operationId: getHealth
      tags: [system]
      summary: Liveness and database reachability
      security: []
      responses:
        '200':
          description: The API is up and the database answered a ping.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Health'
        '503':
          description: The database did not answer.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        default:
          $ref: '#/components/responses/Unexpected'

components:
  securitySchemes:
    sessionCookie:
      type: apiKey
      in: cookie
      name: elms_session
      description: |
        Server-side session: a random 256-bit token whose SHA-256 hash is what
        the database holds, valid 24 hours. Set by `POST /auth/login`, cleared
        by `POST /auth/logout` (TDD §8.2).

  parameters:
    StationId:
      name: stationId
      in: path
      required: true
      description: Station identifier.
      schema:
        type: string
        format: uuid

    LockerId:
      name: lockerId
      in: path
      required: true
      description: Locker identifier.
      schema:
        type: string
        format: uuid

    LockerTypeId:
      name: lockerTypeId
      in: path
      required: true
      description: Locker type identifier.
      schema:
        type: string
        format: uuid

    PackageTemplateId:
      name: packageTemplateId
      in: path
      required: true
      description: Package template identifier.
      schema:
        type: string
        format: uuid

    PaymentId:
      name: paymentId
      in: path
      required: true
      description: Payment identifier returned with the quote.
      schema:
        type: string
        format: uuid

  responses:
    BadRequest:
      description: The request failed validation — malformed body, unknown enum value.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'

    Unauthorized:
      description: No session, or the session expired.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'

    Forbidden:
      description: Signed in, but this operation is admin-only.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'

    NotFound:
      description: No such resource.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'

    Conflict:
      description: |
        The request conflicts with current state — a station that still has
        lockers, a locker that still holds a package, a duplicate label.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'

    PickupBlocked:
      description: |
        Too many failed pickup attempts against this package. Attempts are
        refused until the block expires (FR-8).
      headers:
        Retry-After:
          description: Seconds until attempts are accepted again.
          schema:
            type: integer
            minimum: 0
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'

    Unexpected:
      description: |
        An unhandled failure. Logged with the same `request_id` the body
        carries, so a customer can quote it and the line can be found.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'

  schemas:
    ## ------------------------------------------------------------ errors

    Problem:
      type: object
      description: RFC 7807 problem document — the shape of every failure (TDD §8.3).
      required: [type, title, status]
      properties:
        type:
          type: string
          format: uri
          description: Stable identifier for the kind of failure; clients switch on this.
          example: https://elms.dev/errors/no-locker-available
        title:
          type: string
          description: Short, human-readable summary.
          example: No suitable locker available
        status:
          type: integer
          description: The HTTP status, repeated in the body.
          example: 409
        detail:
          type: string
          description: What went wrong in this specific case.
          example: No available locker fits size large at station Central Mall.
        request_id:
          type: string
          description: Correlates this response with the server log line.
          example: 01JBWX8V3K7Q1YQ0M6C9F2D5TN

    ## ------------------------------------------------------------ vocabulary

    Dimensions:
      type: object
      description: |
        Three sides in millimetres. Which number is which does not matter: a
        parcel can be turned, so the fit test sorts both triples and compares
        them, which covers all six axis-aligned orientations. Every side needs
        20 mm of clearance inside the cell.
      required: [length_mm, width_mm, height_mm]
      properties:
        length_mm:
          type: integer
          minimum: 1
          maximum: 5000
          example: 330
        width_mm:
          type: integer
          minimum: 1
          maximum: 5000
          example: 250
        height_mm:
          type: integer
          minimum: 1
          maximum: 5000
          example: 180

    LockerStatus:
      type: string
      description: |
        `available` can take a package, `occupied` holds one, `out_of_service`
        is excluded from allocation (FR-4).
      enum: [available, occupied, out_of_service]

    Role:
      type: string
      description: Operator role. Admins may do everything an agent may.
      enum: [admin, agent]

    ## ------------------------------------------------------------ auth

    LoginRequest:
      type: object
      required: [username, password]
      properties:
        username:
          type: string
          minLength: 1
        password:
          type: string
          format: password
          minLength: 1

    User:
      type: object
      required: [id, username, role]
      properties:
        id:
          type: string
          format: uuid
        username:
          type: string
        role:
          $ref: '#/components/schemas/Role'

    ## ------------------------------------------------------------ stations

    Station:
      type: object
      required: [id, name, address, created_at]
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        address:
          type: string
        created_at:
          type: string
          format: date-time

    StationInput:
      type: object
      required: [name]
      properties:
        name:
          type: string
          minLength: 1
        address:
          type: string

    ## ------------------------------------------------------------ catalogs

    LockerType:
      type: object
      description: |
        A named cell size (FR-15). Lockers reference a type rather than carrying
        their own three numbers: real banks are built from a few standard cells
        repeated. The measurements are the **interior**, not the door.
      required: [id, name, width_mm, height_mm, depth_mm]
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          example: Medium
        width_mm:
          type: integer
          minimum: 1
          maximum: 5000
          example: 450
        height_mm:
          type: integer
          minimum: 1
          maximum: 5000
          example: 400
        depth_mm:
          type: integer
          minimum: 1
          maximum: 5000
          example: 600

    LockerTypeInput:
      type: object
      required: [name, width_mm, height_mm, depth_mm]
      properties:
        name:
          type: string
          minLength: 1
          example: Tower XL
        width_mm:
          type: integer
          minimum: 1
          maximum: 5000
        height_mm:
          type: integer
          minimum: 1
          maximum: 5000
        depth_mm:
          type: integer
          minimum: 1
          maximum: 5000

    LockerTypeUpdate:
      type: object
      description: Every field is optional; send only what changes.
      properties:
        name:
          type: string
          minLength: 1
        width_mm:
          type: integer
          minimum: 1
          maximum: 5000
        height_mm:
          type: integer
          minimum: 1
          maximum: 5000
        depth_mm:
          type: integer
          minimum: 1
          maximum: 5000

    PackageTemplate:
      type: object
      description: |
        A standard box the agent can pick instead of typing three numbers
        (FR-15). Measurements are the **outer** ones, as the carrier sells it.
        Retiring one — `active: false` — takes it out of the agent's form
        without orphaning the packages that name it.
      required: [id, name, length_mm, width_mm, height_mm, active]
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          example: Shoebox
        length_mm:
          type: integer
          minimum: 1
          maximum: 5000
          example: 330
        width_mm:
          type: integer
          minimum: 1
          maximum: 5000
          example: 250
        height_mm:
          type: integer
          minimum: 1
          maximum: 5000
          example: 180
        active:
          type: boolean

    PackageTemplateInput:
      type: object
      description: A new template is always offered; retiring it is a later, deliberate act.
      required: [name, length_mm, width_mm, height_mm]
      properties:
        name:
          type: string
          minLength: 1
        length_mm:
          type: integer
          minimum: 1
          maximum: 5000
        width_mm:
          type: integer
          minimum: 1
          maximum: 5000
        height_mm:
          type: integer
          minimum: 1
          maximum: 5000

    PackageTemplateUpdate:
      type: object
      description: Every field is optional; send only what changes. `active` is the retire toggle.
      properties:
        name:
          type: string
          minLength: 1
        length_mm:
          type: integer
          minimum: 1
          maximum: 5000
        width_mm:
          type: integer
          minimum: 1
          maximum: 5000
        height_mm:
          type: integer
          minimum: 1
          maximum: 5000
        active:
          type: boolean

    FitPreview:
      type: object
      description: |
        What the station would do with this package if it were submitted now
        (FR-16). Nothing is claimed and nothing is locked, so the answer can be
        contradicted by the very next store — the binding decision belongs to
        the allocation query, under `FOR UPDATE ... SKIP LOCKED`.

        The verdict is computed here, never in the client (T-98). "Perfect" is
        class-relative, not a slack threshold: the cell it would claim is the
        tightest in-service class this station has for it. Occupied cells count
        toward the estate; out-of-service cells do not exist.
      required: [fits, verdict, available_count]
      properties:
        fits:
          type: boolean
          description: Whether any free locker here takes it.
        verdict:
          type: string
          enum: [perfect_fit, oversize_cell, station_full, too_big]
          description: |
            `perfect_fit` — it would land in the tightest class that exists for
            it here. `oversize_cell` — it fits, but only a bigger-than-needed
            cell is free; storing is still allowed, the agent is just told.
            `station_full` — a class here takes it, but no such cell is free
            right now. `too_big` — no in-service cell at this station takes it,
            free or not.
        available_count:
          type: integer
          minimum: 0
          description: How many free lockers take it.
          example: 4
        smallest_type:
          allOf:
            - $ref: '#/components/schemas/LockerType'
          nullable: true
          description: The cell the store would claim; null when nothing free fits.
        tightest_type:
          allOf:
            - $ref: '#/components/schemas/LockerType'
          nullable: true
          description: |
            The smallest in-service class here that takes it, occupied or not —
            the standard the claim is judged against. Null when the verdict is
            `too_big`.
        largest_type:
          allOf:
            - $ref: '#/components/schemas/LockerType'
          nullable: true
          description: |
            The biggest class the station runs at all — what a `too_big` parcel
            is measured against, so the refusal carries a number. Null only when
            the station has nothing in service.

    ## ------------------------------------------------------------ lockers

    Locker:
      type: object
      required: [id, station_id, label, locker_type, status, created_at, updated_at]
      properties:
        id:
          type: string
          format: uuid
        station_id:
          type: string
          format: uuid
        label:
          type: string
          description: What a customer reads off the door. Unique within the station.
          example: M-03
        locker_type:
          $ref: '#/components/schemas/LockerType'
        status:
          $ref: '#/components/schemas/LockerStatus'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    LockerCreate:
      type: object
      required: [label, locker_type_id]
      properties:
        label:
          type: string
          minLength: 1
          example: M-03
        locker_type_id:
          type: string
          format: uuid

    LockerUpdate:
      type: object
      description: |
        Every field is optional; send only what changes. `status` is the
        maintenance toggle and may not be combined with a relabel or a change of
        type.
      properties:
        label:
          type: string
          minLength: 1
        locker_type_id:
          type: string
          format: uuid
        status:
          $ref: '#/components/schemas/LockerStatus'

    ## ------------------------------------------------------------ packages

    StorePackageRequest:
      type: object
      description: |
        The package is measured exactly one way: `template_id` names a standard
        box from the catalog, or `dimensions` carries the agent's own three
        numbers. Both together, or neither, is a 400 — two answers to one
        question can disagree, so neither is preferred over the other.

        The constraint is stated here rather than as a `oneOf` because a `oneOf`
        generates a union type in both clients for a rule the server has to
        enforce anyway; the server is the one place it can be enforced.
      required: [station_id, customer_name, customer_contact]
      properties:
        station_id:
          type: string
          format: uuid
        template_id:
          type: string
          format: uuid
          description: A box from `GET /package-templates`. Its measurements are frozen onto the package.
        dimensions:
          $ref: '#/components/schemas/Dimensions'
        customer_name:
          type: string
          minLength: 1
          description: |
            Who the package is for. Required — a package with nobody attached
            cannot be found again, on the dashboard or at the counter.
        customer_contact:
          type: string
          minLength: 1
          description: Required phone or email; the notification channel to come depends on it.

    StoredPackage:
      type: object
      required: [package_id, locker_label, pickup_code, dimensions, stored_at]
      properties:
        package_id:
          type: string
          format: uuid
        locker_label:
          type: string
          description: Tell the customer this, together with the code.
          example: M-03
        pickup_code:
          type: string
          pattern: '^[0-9]{6}$'
          description: |
            Shown exactly once. Only a bcrypt hash is stored, so no later
            request — by anyone, including an admin — can retrieve it (FR-6).
          example: '407312'
        dimensions:
          $ref: '#/components/schemas/Dimensions'
        template_name:
          type: string
          nullable: true
          description: The box that was picked; null when the agent measured by hand.
          example: Shoebox
        stored_at:
          type: string
          format: date-time
          description: When the clock started for charging (FR-10).

    ## ------------------------------------------------------------ pickup

    QuoteRequest:
      type: object
      required: [station_id, locker_label, pickup_code]
      properties:
        station_id:
          type: string
          format: uuid
        locker_label:
          type: string
          example: M-03
        pickup_code:
          type: string
          pattern: '^[0-9]{6}$'
          example: '407312'

    Quote:
      type: object
      required: [payment_id, package_id, locker_label, stored_at, amount_minor, currency, charge, expires_at, dimensions]
      properties:
        payment_id:
          type: string
          format: uuid
          description: Confirm this to pay and open the locker.
        package_id:
          type: string
          format: uuid
        locker_label:
          type: string
          example: M-03
        stored_at:
          type: string
          format: date-time
        amount_minor:
          type: integer
          format: int64
          description: Frozen total in minor units — what the customer will pay.
          example: 7000
        currency:
          $ref: '#/components/schemas/Currency'
        charge:
          $ref: '#/components/schemas/Charge'
        expires_at:
          type: string
          format: date-time
          description: The quote holds for 15 minutes; after that, quote again.
        dimensions:
          $ref: '#/components/schemas/Dimensions'
        template_name:
          type: string
          nullable: true
          description: |
            What the customer is collecting, so the kiosk can name the box
            rather than only the locker. Null when it was measured by hand, and
            the three numbers answer instead.
          example: Shoebox

    Charge:
      type: object
      description: |
        How the total was reached. Days are started 24-hour periods —
        `max(1, ceil(elapsed / 24h))`, so day one always bills (FR-10).
      required: [days, total_minor, lines]
      properties:
        days:
          type: integer
          minimum: 1
          example: 6
        total_minor:
          type: integer
          format: int64
          example: 7000
        lines:
          type: array
          description: One line per tier the stay reached.
          items:
            $ref: '#/components/schemas/ChargeLine'

    ChargeLine:
      type: object
      description: One pricing tier's contribution — days 1–5 at 1×, 6–10 at 2×, 11+ at 3×.
      required: [from_day, to_day, days, rate_minor, amount_minor]
      properties:
        from_day:
          type: integer
          minimum: 1
          example: 6
        to_day:
          type: integer
          minimum: 0
          description: Inclusive end of the band; `0` marks the open-ended final tier.
          example: 10
        days:
          type: integer
          minimum: 1
          description: Days of this stay that fell in the band.
          example: 1
        rate_minor:
          type: integer
          format: int64
          description: Per-day rate in this band — the tier multiplier times X.
          example: 2000
        amount_minor:
          type: integer
          format: int64
          description: '`days × rate_minor`.'
          example: 2000

    Receipt:
      type: object
      description: |
        Proof of a completed pickup. The amount is the frozen quote total, not a
        recomputation: the breakdown the customer agreed to came with the quote.
      required: [locker_opened, package_id, payment_id, locker_label, stored_at, retrieved_at, amount_minor, currency]
      properties:
        locker_opened:
          type: boolean
          description: Always true on a 200 — payment and release commit together.
          example: true
        package_id:
          type: string
          format: uuid
        payment_id:
          type: string
          format: uuid
        locker_label:
          type: string
          example: M-03
        stored_at:
          type: string
          format: date-time
        retrieved_at:
          type: string
          format: date-time
        amount_minor:
          type: integer
          format: int64
          example: 7000
        currency:
          $ref: '#/components/schemas/Currency'
        already_paid:
          type: boolean
          description: True when this confirm replayed an earlier one; nothing was charged twice.

    ## ------------------------------------------------------------ admin

    PricingConfig:
      type: object
      required: [x_rate_minor, currency, updated_at]
      properties:
        x_rate_minor:
          type: integer
          format: int64
          description: Base daily rate X in minor units — 1000 is 10.00 USD.
          example: 1000
        currency:
          $ref: '#/components/schemas/Currency'
        updated_by:
          type: string
          format: uuid
          nullable: true
          description: The admin who last changed it; null for the seeded default.
        updated_at:
          type: string
          format: date-time

    PricingConfigUpdate:
      type: object
      required: [x_rate_minor, currency]
      properties:
        x_rate_minor:
          type: integer
          format: int64
          minimum: 0
          example: 1000
        currency:
          $ref: '#/components/schemas/Currency'

    Dashboard:
      type: object
      required: [station_id, station_name, lockers, packages, accrued_minor, currency, as_of]
      properties:
        station_id:
          type: string
          format: uuid
        station_name:
          type: string
        lockers:
          $ref: '#/components/schemas/LockerCounts'
        packages:
          type: array
          description: Everything currently stored here, longest-standing first.
          items:
            $ref: '#/components/schemas/DashboardPackage'
        accrued_minor:
          type: integer
          format: int64
          description: What every stored package here would cost if collected now.
          example: 12000
        currency:
          $ref: '#/components/schemas/Currency'
        as_of:
          type: string
          format: date-time
          description: The instant the accrued figures were computed.

    LockerCounts:
      type: object
      required: [total, available, occupied, out_of_service]
      properties:
        total:
          type: integer
          minimum: 0
        available:
          type: integer
          minimum: 0
        occupied:
          type: integer
          minimum: 0
        out_of_service:
          type: integer
          minimum: 0

    DashboardPackage:
      type: object
      required: [package_id, locker_label, dimensions, stored_at, dwell_seconds, accrued_minor]
      properties:
        package_id:
          type: string
          format: uuid
        locker_label:
          type: string
          example: M-03
        dimensions:
          $ref: '#/components/schemas/Dimensions'
        template_name:
          type: string
          nullable: true
          description: The box it was measured from; null for a package measured by hand.
          example: Shoebox
        customer_name:
          type: string
          nullable: true
        stored_at:
          type: string
          format: date-time
        dwell_seconds:
          type: integer
          format: int64
          minimum: 0
          description: How long the package has been sitting there.
          example: 93600
        accrued_minor:
          type: integer
          format: int64
          description: What collecting it right now would cost.
          example: 2000

    AuditEvent:
      type: object
      description: |
        One recorded action. The entity references are nullable twice over —
        kiosk actions have no actor, and deleting an entity nulls the events
        that name it (`ON DELETE SET NULL`) — which is why `details` carries
        the human-readable snapshot: labels, names, and `{"old", "new"}` pairs
        for edits. It stays meaningful after everything it references is gone.
      required: [id, event_type, details, occurred_at]
      properties:
        id:
          type: integer
          format: int64
          description: Insertion order — the feed's stable tie-break.
        event_type:
          type: string
          example: package_stored
        actor_user_id:
          type: string
          format: uuid
          nullable: true
          description: Who acted, from their session; null for kiosk actions.
        station_id:
          type: string
          format: uuid
          nullable: true
        locker_id:
          type: string
          format: uuid
          nullable: true
        package_id:
          type: string
          format: uuid
          nullable: true
        details:
          type: object
          additionalProperties: true
          example: {"locker_label": "M-03", "customer_name": "Ada Lovelace"}
        occurred_at:
          type: string
          format: date-time

    AuditEventPage:
      type: object
      required: [events, total, limit, offset]
      properties:
        events:
          type: array
          description: One page, newest first.
          items:
            $ref: '#/components/schemas/AuditEvent'
        total:
          type: integer
          format: int64
          description: How many events match the filters, across all pages.
        limit:
          type: integer
          description: The page size actually applied.
        offset:
          type: integer

    ## ------------------------------------------------------------ system

    Currency:
      type: string
      description: ISO 4217 code. Every amount beside it is in that currency's minor units.
      minLength: 3
      maxLength: 3
      example: USD

    Health:
      type: object
      required: [status, database]
      properties:
        status:
          type: string
          enum: [ok]
        database:
          type: string
          enum: [up]