swagger.yaml

openapi: 3.0.0
info:
  title: Navin Backend API
  version: 1.0.0
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  description: |
    Navin Backend is the logistics / supply-chain HTTP API for shipment lifecycle management,
    IoT telemetry ingest and anomaly detection, Stellar-backed settlements/payments, and
    organization administration.

    ## Authentication
    ### JWT Bearer (`bearerAuth`)
    Most protected endpoints require `Authorization: Bearer <JWT>`. Tokens are issued by
    `/api/auth/login`, `/api/auth/signup`, `/api/auth/register/company`, or `/api/auth/refresh`. Claims include `userId`,
    `role` (`SUPER_ADMIN` | `ADMIN` | `MANAGER` | `VIEWER` | `CUSTOMER`), optional
    `organizationId` / `organizationType` (`ENTERPRISE` | `LOGISTICS`), and `jti` (used for
    logout / revocation). Role permissions and frontend persona mapping are documented in
    `docs/auth-model.md`.

    ### API key (`apiKeyAuth`)
    Machine / IoT clients authenticate with the `x-api-key` header on selected webhook
    endpoints (notably `POST /api/webhooks/iot`). API keys are managed under `/api/auth/api-keys`
    by ADMIN / SUPER_ADMIN users.

    ### Stellar webhook signature (`stellarSignature`)
    `POST /api/webhooks/stellar` requires an HMAC-SHA256 digest in `x-stellar-signature`,
    computed over the raw body with `STELLAR_WEBHOOK_SECRET`.

    ## Response envelope
    Successful JSON handlers use a standard envelope via `sendResponse`:

    ```json
    {
      "success": true,
      "message": "...",
      "data": { },
      "meta": { }
    }
    ```

    `meta` is optional and holds pagination cursors / totals. A few endpoints intentionally
    diverge (for example shipment CSV/JSON export and SSE event streams).

    ## Pagination
    Use **cursor** pagination (`cursor`, `limit` → `meta.nextCursor`, `meta.hasMore`) for large
    collections (telemetry, anomalies, payments/settlements, audit logs, users). Use **offset**
    pagination (`page`, `limit` → `meta.page`, `meta.limit`, `meta.total`) for bounded admin
    lists (shipments). Telemetry additionally accepts legacy `page` for dashboard clients, but
    `cursor` and `page` must not be combined. Pagination fields always live in `meta`, never in
    `data`. See `docs/PAGINATION.md`.

    ## Error handling
    Errors return JSON with `success: false`, a human-readable `message`, `data: null`, and an
    `error.code` string (plus optional `details` for validation failures). Common HTTP statuses
    include 400 (validation / bad request), 401 (missing or invalid credentials), 403
    (insufficient role), 404 (resource not found), and 409 (conflict such as duplicate email).
  contact:
    name: Navin Backend Maintainers
    url: https://github.com/Navin-xmr/navin-backend
servers:
  - url: http://localhost:3000
    description: Local development server (default PORT=3000)
  - url: https://{productionHost}
    description: Production API host (placeholder — set productionHost to your deployed API base URL; no canonical production URL is published in this repository)
    variables:
      productionHost:
        default: api.example.com
        description: Replace with the real production API hostname when deploying
x-rate-limit:
  standard:
    limit: 100
    window: 15 minutes
  strict:
    limit: 20
    window: 15 minutes
  login:
    limit: 5
    window: 15 minutes
paths:
  /api/webhooks/iot:
    post:
      operationId: webhooks_post_webhooks_iot
      tags:
        - Webhooks
      summary: IoT webhook — ingest telemetry into the anchoring pipeline
      description: |
        Receives telemetry from IoT sensors/gateways and kicks off the async ingestion pipeline:

        1. **Normalize** — union payload → canonical fields (`normalizeIotWebhookBody`)
        2. **Persist** — MongoDB telemetry with `anchorStatus=PENDING_ANCHOR` and `dataHash`
        3. **Queue** — enqueue BullMQ job on `transaction_queue` (`anchor_telemetry`)
        4. **Emit socket** — `location:update` to the shipment room
        5. **Detect anomaly** (async `setImmediate` → `detectTelemetryAnomalies`) — org/shipment thresholds default to **maxTemp=25°C / maxHumidity=80% / minBatteryLevel=20%**; types `TEMPERATURE_BREACH` / `HUMIDITY_BREACH` / `SHOCK_EVENT` / `GPS_LOST` / `BATTERY_LOW` at severity `HIGH`
        6. **Alert** — on detection, emit `anomaly:detected` and push to `alert_queue`

        Returns **202 Accepted** as soon as the record is stored and the anchor job is queued.
        Stellar anchoring is completed by `stellar.worker` consuming `transaction_queue`.

        See `docs/telemetry-pipeline.md` for the full sequence diagram.
      security:
        - apiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IotWebhookBody'
            examples:
              normalizedShipmentPayload:
                summary: Shipment-centric (normalized) payload
                value:
                  shipmentId: '507f1f77bcf86cd799439011'
                  temperature: 22.5
                  humidity: 55
                  latitude: 12.34
                  longitude: 56.78
                  batteryLevel: 88
                  timestamp: '2026-01-15T12:30:00.000Z'
              sensorCentricPayload:
                summary: Sensor-centric payload (temp + location)
                value:
                  sensorId: 'SENSOR-42'
                  temp: 22.5
                  humidity: 55
                  location:
                    lat: 12.34
                    lng: 56.78
                  batteryLevel: 88
                  timestamp: '2026-01-15T12:30:00.000Z'
      responses:
        '202':
          description: >
            Telemetry accepted and queued for Stellar anchoring.
            Anomaly detection runs asynchronously after this response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IotWebhookAcceptedResponse'
              example:
                success: true
                message: Telemetry received and queued for Stellar anchoring
                data:
                  _id: t1
                  shipmentId: '507f1f77bcf86cd799439011'
                  sensorId: 'SENSOR-42'
                  temperature: 22.5
                  humidity: 55
                  latitude: 12.34
                  longitude: 56.78
                  batteryLevel: 88
                  timestamp: '2026-01-15T12:30:00.000Z'
                  dataHash: 'a1b2c3...'
                  anchorStatus: PENDING_ANCHOR
        '400':
          description: Invalid request payload (Zod validation failure or unresolvable shipmentId)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: No active shipment found for the given sensorId
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/webhooks/stellar:
    post:
      operationId: webhooks_post_webhooks_stellar
      tags:
        - Webhooks
      summary: Stellar proof-of-delivery / settlement webhook
      description: |
        Receives Stellar settlement callbacks for proof-of-delivery and escrow events
        (`release`, `escrow`, `failed`). This is the settlement side of the telemetry
        pipeline — distinct from BullMQ `transaction_queue` hash anchoring.

        Requires a valid HMAC-SHA256 signature in the `x-stellar-signature` header,
        computed over the raw request body using `STELLAR_WEBHOOK_SECRET`.

        On `release`, payment status becomes RELEASED and a `SETTLEMENT_COMPLETED`
        ledger block may be written. See `docs/telemetry-pipeline.md`.
      security:
        - stellarSignature: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StellarWebhookPayload'
            example:
              id: evt_01HXYZ
              type: release
              paymentId: '507f1f77bcf86cd799439022'
              transactionHash: 'a1b2c3d4e5f6...'
              amount: 1500
              timestamp: '2026-01-15T13:00:00.000Z'
      responses:
        '200':
          description: Stellar webhook received and processed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StellarWebhookResponse'
        '400':
          description: Invalid Stellar webhook payload or unknown event type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid x-stellar-signature header
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/health:
    get:
      operationId: health_get_health
      tags:
        - Health
      summary: Health check
      description: Public health endpoint used by load balancers and uptime monitors.
      security: []
      responses:
        '200':
          description: Service health metadata
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: OK
                  data:
                    type: object
                    properties:
                      status:
                        type: string
                        example: active
                      uptime:
                        type: number
                        description: Process uptime in seconds
                      timestamp:
                        type: string
                        format: date-time
                        description: Current UTC timestamp
        '400':
          description: Invalid request (should not occur for this endpoint)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/notifications:
    get:
      operationId: notifications_get_notifications
      tags: [Notifications]
      summary: List notifications
      description: >
        Returns the authenticated user's notifications, newest first, with
        offset pagination. Optionally filtered by type and full-text search.
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: page
          schema:
            type: integer
            minimum: 1
            default: 1
          description: Page number (1-based).
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
          description: Notifications per page.
        - in: query
          name: type
          schema:
            type: string
            enum: [shipments, settlements, system]
          description: Filter by notification category.
        - in: query
          name: q
          schema:
            type: string
          description: Search title/description text (case-insensitive substring).
      responses:
        '200':
          description: Notifications retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Notifications retrieved successfully
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Notification'
                  meta:
                    type: object
                    properties:
                      page:
                        type: integer
                      limit:
                        type: integer
                      total:
                        type: integer
        '401':
          description: Missing or invalid authorization token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/notifications/unread-count:
    get:
      operationId: notifications_get_notifications_unread_count
      tags: [Notifications]
      summary: Get unread notifications count
      description: Returns the number of unread notifications for the authenticated user.
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Unread count retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Unread count retrieved successfully
                  data:
                    type: object
                    properties:
                      count:
                        type: integer
        '401':
          description: Missing or invalid authorization token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/notifications/read-all:
    post:
      operationId: notifications_post_notifications_read_all
      tags: [Notifications]
      summary: Mark all notifications as read
      description: Marks every unread notification of the authenticated user as read.
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Notifications marked as read
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: 3 notifications marked as read
                  data:
                    type: object
                    properties:
                      count:
                        type: integer
                        description: Number of notifications updated.
        '401':
          description: Missing or invalid authorization token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/notifications/{id}/read:
    patch:
      operationId: notifications_patch_notifications_id_read
      tags: [Notifications]
      summary: Mark a notification as read
      description: Marks the specified notification as read. Only the owning user can update it.
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: Notification ObjectId.
      responses:
        '200':
          description: Notification marked as read
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Notification marked as read
                  data:
                    $ref: '#/components/schemas/Notification'
        '401':
          description: Missing or invalid authorization token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Notification not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/notifications/{id}:
    delete:
      operationId: notifications_delete_notifications_id
      tags: [Notifications]
      summary: Delete a notification
      description: Soft-deletes the specified notification. Only the owning user can delete it.
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: Notification ObjectId.
      responses:
        '200':
          description: Notification deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Notification deleted successfully
                  data:
                    $ref: '#/components/schemas/Notification'
        '401':
          description: Missing or invalid authorization token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Notification not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/notifications/preferences:
    get:
      operationId: notifications_get_notifications_preferences
      tags: [Notifications]
      summary: Get notification channel preferences
      description: Returns all notification preferences for the authenticated user.
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Notification preferences retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Notification preferences retrieved successfully
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/NotificationPreference'
        '401':
          description: Missing or invalid authorization token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    patch:
      operationId: notifications_patch_notifications_preferences
      tags: [Notifications]
      summary: Update a notification preference
      description: >
        Creates or updates the preference for the given event/channel pair
        (upsert). Only the enabled flag can be toggled per pair.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [event, channel, enabled]
              properties:
                event:
                  type: string
                  enum:
                    [
                      shipment_created,
                      status_changed,
                      delivery_confirmed,
                      payment_received,
                      dispute_opened,
                      dispute_resolved,
                    ]
                channel:
                  type: string
                  enum: [email, sms]
                enabled:
                  type: boolean
      responses:
        '200':
          description: Notification preference updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Notification preference updated successfully
                  data:
                    $ref: '#/components/schemas/NotificationPreference'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid authorization token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/notifications/phone/send-otp:
    post:
      operationId: notifications_post_notifications_phone_send_otp
      tags: [Notifications]
      summary: Send an SMS OTP to a phone number
      description: >
        Generates a 6-digit OTP, stores its hash in Redis (5-minute TTL) and
        delivers it via Twilio (production) or logs it (dev/test). Rate limited
        to 5 requests per 15 minutes per IP.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [phone]
              properties:
                phone:
                  type: string
                  pattern: '^\+?[1-9]\d{9,14}$'
                  minLength: 10
                  maxLength: 15
                  description: Phone number in E.164-ish format (e.g. +15551234567).
      responses:
        '200':
          description: OTP sent successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: OTP sent successfully
                  data:
                    type: string
                    nullable: true
                    example: null
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid authorization token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many OTP requests, please try again later.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  retryAfter:
                    type: integer
                  data:
                    type: string
                    nullable: true
  /api/notifications/phone/verify-otp:
    post:
      operationId: notifications_post_notifications_phone_verify_otp
      tags: [Notifications]
      summary: Verify an SMS OTP
      description: >
        Checks the submitted OTP against the stored hash, then marks the user's
        phone as verified. Rate limited to 5 requests per 15 minutes per IP.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [phone, otp]
              properties:
                phone:
                  type: string
                  pattern: '^\+?[1-9]\d{9,14}$'
                  minLength: 10
                  maxLength: 15
                otp:
                  type: string
                  pattern: '^\d{6}$'
                  minLength: 6
                  maxLength: 6
                  description: The 6-digit code received via SMS.
      responses:
        '200':
          description: Phone verified successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Phone verified successfully
                  data:
                    type: object
                    properties:
                      _id:
                        type: string
                      email:
                        type: string
                      name:
                        type: string
                      role:
                        type: string
                      phone:
                        type: string
                        nullable: true
                      phoneVerified:
                        type: boolean
                      organizationId:
                        type: string
                        nullable: true
                      createdAt:
                        type: string
                        format: date-time
                      updatedAt:
                        type: string
                        format: date-time
        '400':
          description: Invalid or expired OTP
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid authorization token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many OTP requests, please try again later.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  retryAfter:
                    type: integer
                  data:
                    type: string
                    nullable: true

  /api/public/tracking/{trackingNumber}:
    get:
      operationId: public_tracking_get_public_tracking_trackingnumber
      tags: [Public Tracking]
      summary: Public shipment tracking by tracking number
      description: |
        Unauthenticated public tracking endpoint. Returns a safe subset of shipment
        data suitable for public tracking pages. No authentication required.
        Rate limited to prevent abuse.
      x-implemented: true
      x-required-role: none
      security: []
      parameters:
        - in: path
          name: trackingNumber
          required: true
          schema:
            type: string
            pattern: '^[A-Za-z0-9_-]+$'
            maxLength: 64
          description: Carrier tracking number (e.g., NVN-123456)
      responses:
        '200':
          description: Shipment tracking information retrieved successfully
          content:
            application/json:
              schema:
                type: object
                required: [success, message, data]
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Shipment tracking retrieved
                  data:
                    $ref: '#/components/schemas/PublicTrackingResponse'
        '404':
          description: Shipment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: Invalid tracking number parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/events:
    get:
      operationId: events_get_events
      summary: Real-time event stream (SSE)
      description: |
        Status: implemented (x-implemented: true). Listed in API-QA #398 for completeness.
        Opens a Server-Sent Events stream for the authenticated user. Events are scoped
        per user via Redis pub/sub channels and include shipment, settlement, anomaly,
        and location updates. A heartbeat comment is sent every 30 seconds.

        Authentication accepts either `Authorization: Bearer <token>` or `?token=<jwt>`
        for EventSource clients that cannot set custom headers.
      tags:
        - Events
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: token
          required: false
          schema:
            type: string
          description: JWT for EventSource clients that cannot send Authorization headers
      responses:
        '200':
          description: SSE stream opened
          content:
            text/event-stream:
              schema:
                type: string
                description: |
                  Stream of SSE messages. Event types: shipment:status, shipment:milestone,
                  settlement:status, notification:new, anomaly:detected, location:update.
              examples:
                shipmentStatus:
                  summary: Shipment status change
                  value: |
                    event: shipment:status
                    data: {"type":"shipment:status","shipmentId":"671000000000000000000001","newStatus":"IN_TRANSIT","timestamp":"2026-01-15T12:00:00.000Z"}
                heartbeat:
                  summary: Keep-alive heartbeat (every 30s)
                  value: |
                    : heartbeat
        '401':
          description: Missing, invalid, or revoked JWT
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/auth/api-keys:
    post:
      operationId: api_keys_post_auth_api_keys
      tags:
        - API Keys
      x-required-role: [ADMIN, SUPER_ADMIN]
      summary: Create a new API key
      description: Generates a new API key for machine-to-machine authentication. The raw API key is returned only once.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - organizationId
              properties:
                name:
                  type: string
                  description: Descriptive name for the API key
                organizationId:
                  type: string
                  description: MongoDB ObjectId of the organization
                shipmentId:
                  type: string
                  description: Optional MongoDB ObjectId of a specific shipment
      responses:
        '201':
          description: API key created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      apiKey:
                        type: string
                        description: Raw API key (shown only once)
                      id:
                        type: string
                      name:
                        type: string
                      organizationId:
                        type: string
                      shipmentId:
                        type: string
                      createdAt:
                        type: string
                        format: date-time
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/auth/sessions:
    get:
      operationId: auth_get_auth_sessions
      summary: List active sessions
      description: |
        Returns all active session records for the authenticated user (one per device/login).
        Sessions are ordered newest-first.
      tags:
        - Auth
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Session list retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Sessions retrieved
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Session'
        '401':
          description: Missing or invalid authorization token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/auth/sessions/{jti}:
    delete:
      operationId: auth_delete_auth_sessions_jti
      summary: Revoke a session
      description: |
        Blocklists the token identified by `jti` in Redis and removes the session record.
        The token will be rejected immediately by `requireAuth` on subsequent requests.

        - Returns **403** if the session belongs to a different user (cross-user revocation).
        - Returns **404** if no session with that `jti` exists.
      tags:
        - Auth
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: jti
          required: true
          schema:
            type: string
          description: The JWT ID (`jti` claim) of the session to revoke
      responses:
        '200':
          description: Session revoked successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Session revoked successfully
                  data:
                    type: string
                    nullable: true
                    example: null
        '401':
          description: Missing or invalid authorization token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden — cannot revoke another user's session
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Session not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/auth/signup:
    post:
      operationId: auth_post_auth_signup
      tags:
        - Auth
      summary: Register a new user
      security: []
      description: Creates a new user account. organizationId is optional. Public signup does not allow privileged role assignment.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - name
                - password
              properties:
                email:
                  type: string
                  format: email
                  description: User email address
                name:
                  type: string
                  minLength: 1
                  description: User full name
                password:
                  type: string
                  minLength: 8
                  description: Password (minimum 8 characters)
                organizationId:
                  type: string
                  description: Optional organization ID to associate with user
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      user:
                        type: object
                      token:
                        type: string
                  meta:
                    type: object
        '400':
          description: Validation error (e.g., password too short, missing required fields)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: string
                    nullable: true
  /api/auth/register/company:
    post:
      operationId: auth_post_auth_register_company
      summary: Self-service company registration
      description: |
        Creates both an Organization (type: ENTERPRISE) and its first admin user in a single atomic operation.

        This endpoint enables self-service company onboarding without requiring a SUPER_ADMIN to pre-provision organizations.
        It creates:
        1. An Organization with type ENTERPRISE and company settings (industry, country, company size)
        2. An admin user (role: ADMIN) linked to the new organization
        3. Returns a JWT token with organization context included
      security: []
      tags:
        - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - companyName
                - industry
                - country
                - companySize
                - adminName
                - email
                - password
              properties:
                companyName:
                  type: string
                  minLength: 1
                  description: Name of the company
                industry:
                  type: string
                  minLength: 1
                  description: Industry classification (e.g., Logistics, Tech, Healthcare)
                country:
                  type: string
                  minLength: 1
                  description: Country code or name
                companySize:
                  type: string
                  minLength: 1
                  description: Company size category (e.g., 10-50, 50-100, 100+, 500+)
                adminName:
                  type: string
                  minLength: 1
                  description: Full name of the first admin user
                email:
                  type: string
                  format: email
                  description: Email address for the admin user (must be unique)
                password:
                  type: string
                  minLength: 8
                  description: Admin password (minimum 8 characters)
      responses:
        '201':
          description: Company and admin user created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      user:
                        type: object
                        properties:
                          id:
                            type: string
                            description: Admin user ID
                          email:
                            type: string
                            description: Admin user email
                          name:
                            type: string
                            description: Admin user name
                          role:
                            type: string
                            enum:
                              - ADMIN
                      token:
                        type: string
                        description: JWT bearer token with organization context
                  meta:
                    type: object
        '400':
          description: Validation error (missing fields, weak password, invalid email)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict - email already in use or company name already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/company/api-keys:
    post:
      operationId: api_keys_post_company_api_keys
      x-required-role: [ADMIN, SUPER_ADMIN]
      summary: Create a new API key
      description: |
        Generates a new API key for machine-to-machine authentication.
        The API key is derived from the caller's organization (taken from JWT claims).
        The raw API key secret is returned exactly once and should be stored securely.

        This endpoint replaces the deprecated `/api/auth/api-keys` route.
      tags:
        - API Keys
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 200
                  description: Descriptive name for this API key
      responses:
        '201':
          description: API key created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: API key created successfully
                  data:
                    type: object
                    properties:
                      _id:
                        type: string
                        description: API Key document ID
                      key:
                        type: string
                        description: Base64-encoded API key (shown only once)
                      secret:
                        type: string
                        description: Raw secret key (shown only once)
                      name:
                        type: string
                      organizationId:
                        type: string
                      isActive:
                        type: boolean
                      createdAt:
                        type: string
                        format: date-time
        '400':
          description: Validation error - missing or invalid name
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid authorization token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Insufficient permissions - only ADMIN or SUPER_ADMIN can create API keys
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      operationId: api_keys_get_company_api_keys
      x-required-role: [ADMIN, SUPER_ADMIN]
      summary: List all active API keys
      description: |
        Returns all active API keys for the caller's organization.
        organizationId is derived from the JWT — no query parameter needed.

        This endpoint replaces the deprecated `/api/auth/api-keys/{organizationId}` route.
      tags:
        - API Keys
      security:
        - bearerAuth: []
      responses:
        '200':
          description: API keys list retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: API keys retrieved
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        _id:
                          type: string
                        name:
                          type: string
                        organizationId:
                          type: string
                        isActive:
                          type: boolean
                        createdAt:
                          type: string
                          format: date-time
                        lastUsedAt:
                          type: string
                          format: date-time
                          nullable: true
        '401':
          description: Missing or invalid authorization token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Insufficient permissions - only ADMIN or SUPER_ADMIN can list API keys
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/company/api-keys/{apiKeyId}:
    delete:
      operationId: api_keys_delete_company_api_keys_apikeyid
      x-required-role: [ADMIN, SUPER_ADMIN]
      summary: Revoke an API key
      description: |
        Soft-revokes an API key by setting `isActive = false`.
        The key cannot be used after revocation, but the record is retained for audit purposes.
        Only API keys belonging to the caller's organization can be revoked.

        This endpoint replaces the deprecated `/api/auth/api-keys/{apiKeyId}` route.
      tags:
        - API Keys
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: apiKeyId
          required: true
          schema:
            type: string
          description: MongoDB ObjectId of the API key to revoke
      responses:
        '200':
          description: API key revoked successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: API key revoked
                  data:
                    type: string
                    nullable: true
        '401':
          description: Missing or invalid authorization token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Insufficient permissions or API key belongs to a different organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: API key not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/company/invitations:
    post:
      operationId: invitations_post_company_invitations
      x-required-role: [ADMIN, SUPER_ADMIN]
      summary: Create and send invitation
      description: Send an invitation to a new team member (requires ADMIN role).
      security:
        - bearerAuth: []
      tags:
        - Invitations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - role
              properties:
                email:
                  type: string
                  format: email
                  description: Email address to invite
                role:
                  type: string
                  enum:
                    - ADMIN
                    - MANAGER
                    - DRIVER
                    - VIEWER
                    - CUSTOMER
                  description: Role to assign to invitee
                message:
                  type: string
                  description: Optional custom message in invitation
      responses:
        '201':
          description: Invitation sent successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        description: Invitation ID
                      token:
                        type: string
                        description: Invitation token for frontend
                      email:
                        type: string
                      expiresAt:
                        type: string
                        format: date-time
        '409':
          description: Email already in use or invitation already pending
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      operationId: invitations_get_company_invitations
      x-required-role: [ADMIN, SUPER_ADMIN]
      summary: List organization invitations
      description: Get all invitations for the organization (requires ADMIN role).
      security:
        - bearerAuth: []
      tags:
        - Invitations
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - in: query
          name: cursor
          schema:
            type: string
          description: Cursor for pagination
        - in: query
          name: status
          schema:
            type: string
            enum:
              - PENDING
              - ACCEPTED
              - EXPIRED
              - REVOKED
          description: Filter by invitation status
      responses:
        '200':
          description: Invitations retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        email:
                          type: string
                        role:
                          type: string
                        status:
                          type: string
                        expiresAt:
                          type: string
                          format: date-time
                        createdAt:
                          type: string
                          format: date-time
                  meta:
                    type: object
                    properties:
                      total:
                        type: integer
                      hasMore:
                        type: boolean
                      nextCursor:
                        type: string
        '401':
          description: Missing, invalid, or revoked JWT
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - insufficient role (requires ADMIN)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/company/invitations/{id}/resend:
    post:
      operationId: invitations_post_company_invitations_id_resend
      x-required-role: [ADMIN, SUPER_ADMIN]
      summary: Resend invitation
      description: Resend an invitation with a new token and refresh expiry (requires ADMIN role).
      security:
        - bearerAuth: []
      tags:
        - Invitations
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: Invitation ID
      responses:
        '200':
          description: Invitation resent successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      token:
                        type: string
                      expiresAt:
                        type: string
                        format: date-time
        '401':
          description: Missing, invalid, or revoked JWT
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - insufficient role (requires ADMIN)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Invitation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/company/invitations/{id}:
    delete:
      operationId: invitations_delete_company_invitations_id
      x-required-role: [ADMIN, SUPER_ADMIN]
      summary: Revoke invitation
      description: Revoke an invitation preventing further acceptance (requires ADMIN role).
      security:
        - bearerAuth: []
      tags:
        - Invitations
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: Invitation ID
      responses:
        '200':
          description: Invitation revoked successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
        '401':
          description: Missing, invalid, or revoked JWT
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - insufficient role (requires ADMIN)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Invitation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/company/invitations/info:
    get:
      operationId: invitations_get_company_invitations_info
      summary: Get invitation info from token
      description: Get invitation details without authentication (public endpoint).
      security: []
      tags:
        - Invitations
      parameters:
        - in: query
          name: token
          required: true
          schema:
            type: string
          description: Invitation token
      responses:
        '200':
          description: Invitation info retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      invitationId:
                        type: string
                      email:
                        type: string
                      role:
                        type: string
                      companyName:
                        type: string
                      expiresAt:
                        type: string
                        format: date-time
        '401':
          description: Invalid or expired token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/company/invitations/accept:
    post:
      operationId: invitations_post_company_invitations_accept
      summary: Accept invitation and create account
      description: Accept an invitation and create a user account (public endpoint).
      security: []
      tags:
        - Invitations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - token
                - name
                - password
              properties:
                token:
                  type: string
                  description: Invitation token
                name:
                  type: string
                  description: User display name
                password:
                  type: string
                  minLength: 8
                  description: User password
      responses:
        '201':
          description: Invitation accepted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      user:
                        type: object
                        properties:
                          id:
                            type: string
                          email:
                            type: string
                          name:
                            type: string
                          role:
                            type: string
        '400':
          description: Invalid or expired token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/audit-logs:
    get:
      operationId: audit_logs_get_audit_logs
      tags:
        - Audit Logs
      x-required-role: [SUPER_ADMIN, ADMIN]
      summary: Retrieve compliance audit logs
      description: Returns audit history for compliance and traceability with filter and cursor pagination support.
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: cursor
          schema:
            type: string
          description: Cursor for pagination
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - in: query
          name: userId
          schema:
            type: string
          description: Filter by actor user id
        - in: query
          name: action
          schema:
            type: string
          description: Filter by action name
        - in: query
          name: resource
          schema:
            type: string
          description: Filter by resource category
        - in: query
          name: from
          schema:
            type: string
            format: date-time
          description: Start of timestamp range (inclusive)
        - in: query
          name: to
          schema:
            type: string
            format: date-time
          description: End of timestamp range (inclusive)
      responses:
        '200':
          description: Audit logs retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        _id:
                          type: string
                        userId:
                          type: string
                        action:
                          type: string
                        resource:
                          type: string
                        resourceId:
                          type: string
                        timestamp:
                          type: string
                          format: date-time
                        metadata:
                          type: object
                  meta:
                    type: object
                    properties:
                      nextCursor:
                        type: string
                        nullable: true
                      hasMore:
                        type: boolean
                      total:
                        type: integer
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/activity:
    get:
      operationId: audit_logs_get_activity
      tags:
        - Audit Logs
      x-required-role: [ADMIN, MANAGER, VIEWER, SUPER_ADMIN]
      summary: Get activity feed
      description: |
        Returns a paginated activity feed of platform-wide events ordered
        newest-first. Accessible to ADMIN, MANAGER, and VIEWER roles.

        **Pagination** uses the `before` parameter (ISO 8601 date-time string).
        Pass the `meta.before` value from the previous response as the next
        `before` to walk backwards through history.

        **Action types** currently emitted:
        `SHIPMENT_CREATED`, `SHIPMENT_STATUS_CHANGED`, `PROOF_UPLOADED`,
        `DISPUTE_OPENED`, `TELEMETRY_ANCHORED`, `SETTLEMENT_RELEASED`,
        `ANOMALY_DETECTED`, `USER_INVITED`, `RBAC_ROLE_MODIFIED`,
        `API_KEY_GENERATED`.
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: before
          schema:
            type: string
            format: date-time
          description: >
            Return only events whose timestamp is strictly older than this
            ISO 8601 date-time. Omit to fetch the most recent events.
          example: '2026-06-01T12:00:00.000Z'
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
          description: Maximum number of events to return (1–100).
        - in: query
          name: userId
          schema:
            type: string
          description: Filter by the actor's user ID.
        - in: query
          name: action
          schema:
            type: string
            enum:
              - SHIPMENT_CREATED
              - SHIPMENT_STATUS_CHANGED
              - PROOF_UPLOADED
              - DISPUTE_OPENED
              - TELEMETRY_ANCHORED
              - SETTLEMENT_RELEASED
              - ANOMALY_DETECTED
              - USER_INVITED
              - RBAC_ROLE_MODIFIED
              - API_KEY_GENERATED
          description: Filter by action type.
        - in: query
          name: resource
          schema:
            type: string
            enum:
              - SHIPMENT
              - TELEMETRY
              - PAYMENT
              - ANOMALY
              - USER
              - API_KEY
          description: Filter by resource category.
      responses:
        '200':
          description: Activity feed retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - message
                  - data
                  - meta
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Activity retrieved
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ActivityEvent'
                  meta:
                    type: object
                    required:
                      - limit
                      - total
                      - hasMore
                      - before
                    properties:
                      limit:
                        type: integer
                        example: 20
                      total:
                        type: integer
                        description: Total matching events (unfiltered by before).
                        example: 142
                      hasMore:
                        type: boolean
                        description: Whether older events exist beyond this page.
                        example: true
                      before:
                        type: string
                        format: date-time
                        nullable: true
                        description: >
                          Pass this value as the `before` query parameter to
                          fetch the next page. Null when no more pages exist.
                        example: '2026-05-31T08:43:21.000Z'
        '400':
          description: Validation error (invalid `before` format or `limit` out of range).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: >
            Insufficient role. Requires ADMIN, MANAGER, or VIEWER.
            CUSTOMER and unauthenticated callers are rejected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/shipment-templates:
    get:
      operationId: shipment_templates_get_shipment_templates
      tags:
        - Shipment Templates
      x-required-role: [ADMIN, MANAGER, VIEWER]
      summary: List all shipment templates for the caller's organization
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Templates retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ShipmentTemplate'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
    post:
      operationId: shipment_templates_post_shipment_templates
      tags:
        - Shipment Templates
      x-required-role: [ADMIN, MANAGER]
      summary: Create a new shipment template
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateShipmentTemplateRequest'
      responses:
        '201':
          description: Template created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/ShipmentTemplate'
        '400':
          description: Validation error
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  /api/shipment-templates/{id}:
    get:
      operationId: shipment_templates_get_shipment_templates_id
      tags:
        - Shipment Templates
      x-required-role: [ADMIN, MANAGER, VIEWER]
      summary: Get a shipment template by ID
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Template retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/ShipmentTemplate'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Template not found
    patch:
      operationId: shipment_templates_patch_shipment_templates_id
      tags:
        - Shipment Templates
      x-required-role: [ADMIN, MANAGER]
      summary: Update a shipment template
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateShipmentTemplateRequest'
      responses:
        '200':
          description: Template updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/ShipmentTemplate'
        '400':
          description: Validation error
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Template not found
    delete:
      operationId: shipment_templates_delete_shipment_templates_id
      tags:
        - Shipment Templates
      x-required-role: [ADMIN, MANAGER]
      summary: Soft-delete a shipment template
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Template deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/ShipmentTemplate'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Template not found
  /api/auth/login:
    post:
      operationId: auth_post_auth_login
      tags:
        - Auth
      summary: Authenticate a user
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - password
              properties:
                email:
                  type: string
                  format: email
                password:
                  type: string
      responses:
        '200':
          description: Login successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                  meta:
                    type: object
        '401':
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                message: Invalid email or password
                data: null
                error:
                  code: ERR_AUTH_INVALID
        '429':
          description: Too many login attempts
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  retryAfter:
                    type: integer
                  data:
                    type: string
                    nullable: true
  /api/auth/refresh:
    post:
      operationId: auth_post_auth_refresh
      summary: Refresh authentication token
      description: |
        Refreshes an expired or expiring JWT by providing the old token.
        The old token's `jti` is blocklisted, preventing reuse.

        Returns a new JWT valid for 7 days with fresh claims (userId, organizationId, role).
        Useful for maintaining user sessions without requiring re-login.
      tags:
        - Auth
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - token
              properties:
                token:
                  type: string
                  description: Expired or expiring JWT token to refresh
      responses:
        '200':
          description: Token refreshed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Token refreshed
                  data:
                    type: object
                    properties:
                      userId:
                        type: string
                        description: User ID
                      email:
                        type: string
                        description: User email
                      token:
                        type: string
                        description: New JWT token (valid 7 days from now)
                      organizationId:
                        type: string
                        description: Organization ID from token claims
                      role:
                        type: string
                        enum: [SUPER_ADMIN, ADMIN, MANAGER, VIEWER, DRIVER, CUSTOMER]
                        description: User role from token claims
        '400':
          description: Validation error - missing or invalid token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Token invalid, expired, or already revoked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                message: Token has expired or is invalid
                data: null
                error:
                  code: ERR_AUTH_INVALID
  /api/auth/logout:
    post:
      operationId: auth_post_auth_logout
      tags:
        - Auth
      summary: Logout current user
      description: Invalidates the current JWT (server-side revocation). Requires Authorization header.
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Logout successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                    nullable: true
        '401':
          description: Missing or invalid auth token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/auth/forgot-password:
    post:
      operationId: auth_post_auth_forgot_password
      summary: Request a password reset email
      description: >-
        Sends a password reset email to the specified address. Always returns a
        success response to prevent email enumeration.
      tags:
        - Auth
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
              properties:
                email:
                  type: string
                  format: email
                  description: Registered email address
      responses:
        '200':
          description: Reset email sent (or silently ignored for unknown emails)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: string
                    nullable: true
        '400':
          description: Invalid email format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/auth/reset-password:
    post:
      summary: Reset a password with a reset token
      description: >-
        Completes the password-reset flow started by
        `POST /api/auth/forgot-password`. Exchanges the emailed reset token for
        a new password and invalidates the token. Public route (no bearer token
        required); rate-limited per IP.
      tags:
        - Auth
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - token
                - newPassword
              properties:
                token:
                  type: string
                  minLength: 1
                  description: Reset token from the password-reset email link
                newPassword:
                  type: string
                  minLength: 8
                  description: Replacement password (at least 8 characters)
      responses:
        '200':
          description: Password reset successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Password reset successfully
                  data:
                    type: string
                    nullable: true
        '400':
          description: >-
            Validation error (missing/short token or password) or invalid,
            expired, or wrong-type reset token (`ERR_AUTH_INVALID_RESET_TOKEN`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many reset attempts — rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/auth/2fa/setup:
    post:
      operationId: auth_post_auth_2fa_setup
      summary: Initiate TOTP 2FA setup
      description: |
        Generates a TOTP secret for the authenticated user and returns an `otpauth://` URI
        for QR-code rendering. 2FA is NOT yet active — the user must call
        `POST /api/auth/2fa/verify` with a valid code to enable it.
      tags:
        - Auth
      security:
        - bearerAuth: []
      responses:
        '200':
          description: 2FA setup initiated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      otpauthUrl:
                        type: string
                        description: otpauth:// URI to encode as QR code
                      secret:
                        type: string
                        description: Raw TOTP secret for manual entry
        '401':
          description: Missing or invalid auth token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: 2FA is already enabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/auth/2fa/verify:
    post:
      operationId: auth_post_auth_2fa_verify
      summary: Verify first TOTP code and enable 2FA
      description: |
        Validates the first TOTP code after setup. On success, enables 2FA and returns
        10 single-use backup codes (plaintext, shown exactly once — store them safely).
      tags:
        - Auth
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - code
              properties:
                code:
                  type: string
                  pattern: '^\d{6}$'
                  description: 6-digit TOTP code from the authenticator app
      responses:
        '200':
          description: 2FA enabled successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      backupCodes:
                        type: array
                        items:
                          type: string
                        description: 10 single-use backup codes (shown once only)
        '400':
          description: Invalid or wrong TOTP code, or setup not initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid auth token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: 2FA already enabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many verification attempts (rate-limited)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  retryAfter:
                    type: integer
                  data:
                    type: string
                    nullable: true
  /api/auth/2fa:
    delete:
      operationId: auth_delete_auth_2fa
      summary: Disable 2FA
      description: |
        Disables 2FA on the account after verifying the user's current password.
        Clears the TOTP secret and all backup codes.
      tags:
        - Auth
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - password
              properties:
                password:
                  type: string
                  description: Current account password
      responses:
        '200':
          description: 2FA disabled successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: string
                    nullable: true
        '400':
          description: 2FA is not enabled on this account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Incorrect password or missing/invalid auth token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/auth/2fa/backup-codes/regenerate:
    post:
      operationId: auth_post_auth_2fa_backup_codes_regenerate
      summary: Regenerate backup codes
      description: |
        Invalidates all existing backup codes and issues 10 new single-use codes.
        Requires 2FA to be enabled.
      tags:
        - Auth
      security:
        - bearerAuth: []
      responses:
        '200':
          description: New backup codes generated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      backupCodes:
                        type: array
                        items:
                          type: string
                        description: 10 new single-use backup codes (shown once only)
        '400':
          description: 2FA is not enabled on this account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid auth token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/auth/api-keys/{organizationId}:
    get:
      operationId: api_keys_get_auth_api_keys_id
      summary: List API keys for an organization
      description: >-
        Deprecated alias of `GET /api/company/api-keys`. Returns all active API
        keys for the specified organization (without exposing the raw keys).
        Requires JWT auth plus ADMIN or SUPER_ADMIN role.
      tags:
        - API Keys
      security:
        - bearerAuth: []
      x-required-role: [ADMIN, SUPER_ADMIN]
      parameters:
        - in: path
          name: organizationId
          required: true
          schema:
            type: string
          description: MongoDB ObjectId of the organization
      responses:
        '200':
          description: List of API keys
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        _id:
                          type: string
                        name:
                          type: string
                        organizationId:
                          type: string
                        shipmentId:
                          type: string
                        isActive:
                          type: boolean
                        lastUsedAt:
                          type: string
                          format: date-time
                        createdAt:
                          type: string
                          format: date-time
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Insufficient role permissions (ADMIN / SUPER_ADMIN required)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/auth/api-keys/{apiKeyId}:
    delete:
      operationId: api_keys_delete_auth_api_keys_id
      summary: Revoke an API key
      description: >-
        Deprecated alias of `DELETE /api/company/api-keys/{apiKeyId}`.
        Deactivates an API key, preventing it from being used for
        authentication. Requires JWT auth plus ADMIN or SUPER_ADMIN role.
      tags:
        - API Keys
      security:
        - bearerAuth: []
      x-required-role: [ADMIN, SUPER_ADMIN]
      parameters:
        - in: path
          name: apiKeyId
          required: true
          schema:
            type: string
          description: MongoDB ObjectId of the API key
      responses:
        '200':
          description: API key revoked successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Insufficient role permissions (ADMIN / SUPER_ADMIN required)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: API key not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/users/me:
    get:
      operationId: users_get_users_me
      summary: Get current authenticated user's profile
      description: Returns the profile of the authenticated user (excluding passwordHash). Requires valid JWT.
      security:
        - bearerAuth: []
      tags:
        - Users
      responses:
        '200':
          description: User profile retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: User profile retrieved successfully
                  data:
                    type: object
                    properties:
                      _id:
                        type: string
                      email:
                        type: string
                      name:
                        type: string
                      role:
                        type: string
                      organizationId:
                        type: string
                      createdAt:
                        type: string
                        format: date-time
        '401':
          description: Missing or invalid authorization token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    patch:
      operationId: users_patch_users_me
      summary: Update current authenticated user's profile
      description: >-
        Updates the authenticated user's profile. Supports updating name, email,
        and (for ADMIN/SUPER_ADMIN users) the linked organization's name.
        All fields are optional — only provided fields are updated.
      security:
        - bearerAuth: []
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                fullName:
                  type: string
                  description: New display name (optional).
                  example: John Doe
                email:
                  type: string
                  format: email
                  description: New email address (optional).
                  example: john@example.com
                companyName:
                  type: string
                  description: >-
                    New organization name (optional). Only allowed for ADMIN
                    and SUPER_ADMIN users.
                  example: Acme Corp
      responses:
        '200':
          description: User profile updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: User profile updated successfully
                  data:
                    type: object
                    properties:
                      _id:
                        type: string
                      email:
                        type: string
                      name:
                        type: string
                      role:
                        type: string
                      organizationId:
                        type: string
        '401':
          description: Missing or invalid authorization token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden — non-admin attempting to update companyName
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Email already in use
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: users_delete_users_me
      summary: Delete current authenticated user
      description: >-
        Soft-deletes the authenticated user by setting deletedAt and blocklists
        the current JWT so subsequent requests with the same token are rejected.
      security:
        - bearerAuth: []
      tags:
        - Users
      responses:
        '200':
          description: User deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: User deleted successfully
                  data:
                    type: object
                    properties:
                      _id:
                        type: string
                      email:
                        type: string
                      name:
                        type: string
                      deletedAt:
                        type: string
                        format: date-time
        '401':
          description: Missing or invalid authorization token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/users/invitations:
    post:
      operationId: users_post_users_invitations
      tags:
        - Users
      x-required-role: [ADMIN, SUPER_ADMIN]
      summary: Generate user invitation link
      description: >-
        Creates a signed 48-hour invitation token bound to the inviter
        organization and target role, and sends an invitation email to the
        target address.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - role
              properties:
                email:
                  type: string
                  format: email
                role:
                  type: string
                  enum: [ADMIN, MANAGER, VIEWER, CUSTOMER]
      responses:
        '201':
          description: Invitation generated
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/users/invitations/verify:
    get:
      operationId: users_get_users_invitations_verify
      tags:
        - Users
      summary: Verify invitation token
      security: []
      parameters:
        - in: query
          name: token
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Invitation token is valid
        '401':
          description: Invalid or expired invitation token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/users/invitations/accept:
    post:
      operationId: users_post_users_invitations_accept
      tags:
        - Users
      summary: Accept invitation and create account
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - token
                - name
                - password
              properties:
                token:
                  type: string
                name:
                  type: string
                password:
                  type: string
                  minLength: 8
                  description: Password (minimum 8 characters)
      responses:
        '201':
          description: Invitation accepted
        '401':
          description: Invalid or expired invitation token
        '409':
          description: Email already in use
  /api/users/{id}:
    delete:
      operationId: users_delete_users_id
      tags:
        - Users
      x-required-role: [ADMIN, SUPER_ADMIN]
      summary: Delete a user (soft delete)
      description: Soft-deletes a user by setting deletedAt. Requires ADMIN or SUPER_ADMIN role.
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: MongoDB ObjectId of the user to delete
      responses:
        '200':
          description: User deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: User deleted successfully
                  data:
                    type: object
                    properties:
                      _id:
                        type: string
                      email:
                        type: string
                      name:
                        type: string
                      role:
                        type: string
                      organizationId:
                        type: string
                      deletedAt:
                        type: string
                        format: date-time
        '400':
          description: Invalid or missing id parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid auth token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden – insufficient role
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/users:
    post:
      operationId: users_post_users
      x-required-role: [ADMIN, SUPER_ADMIN]
      summary: Create a new user (admin only)
      description: >
        Creates a new user within the authenticated admin's organization.
        Requires ADMIN or SUPER_ADMIN role. The organizationId is always
        taken from the authenticated JWT token — it cannot be supplied in
        the request body, preventing cross-organisation user creation.
      security:
        - bearerAuth: []
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, name]
              properties:
                email:
                  type: string
                  format: email
                  description: User email address
                name:
                  type: string
                  minLength: 1
                  description: User full name
                role:
                  type: string
                  enum: [ADMIN, MANAGER, VIEWER, CUSTOMER]
                  default: VIEWER
                  description: Role to assign to the new user
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: User registered successfully
                  data:
                    type: object
                    properties:
                      _id:
                        type: string
                      email:
                        type: string
                      name:
                        type: string
                      role:
                        type: string
                      organizationId:
                        type: string
        '400':
          description: Validation error — missing or invalid fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden — insufficient role (must be ADMIN or SUPER_ADMIN)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      operationId: users_get_users
      tags:
        - Users
      x-required-role: [ADMIN, MANAGER, SUPER_ADMIN]
      summary: List users
      description: >-
        Returns a paginated list of users within the caller's organization.
        Requires authentication and ADMIN / MANAGER / SUPER_ADMIN role.

        **Pagination modes** (mutually exclusive — sending both `cursor` and `page` is a 400):

        * **Cursor mode** (`cursor` + `limit`) → `meta: { nextCursor, hasMore }`
        * **Offset mode** (`page` + `limit`)   → `meta: { page, limit, total }`

        **Filters** (`search`, `role`) work in both modes.
        Unknown query params are silently ignored and do **not** cause a 400.
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
          description: Maximum number of users per page
        - in: query
          name: cursor
          schema:
            type: string
          description: >-
            Cursor for the next page in cursor mode (ObjectId of the last user
            from the previous page). Mutually exclusive with `page`.
        - in: query
          name: page
          schema:
            type: integer
            minimum: 1
          description: >-
            1-based page number for offset pagination. Mutually exclusive with `cursor`.
        - in: query
          name: search
          schema:
            type: string
          description: Case-insensitive substring search on `name` and `email`.
        - in: query
          name: role
          schema:
            type: string
            enum: [SUPER_ADMIN, ADMIN, MANAGER, DRIVER, VIEWER, CUSTOMER]
          description: Filter results to users with this exact role.
      responses:
        '200':
          description: Users retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        _id:
                          type: string
                        email:
                          type: string
                        name:
                          type: string
                        role:
                          type: string
                        organizationId:
                          type: string
                        createdAt:
                          type: string
                          format: date-time
                  meta:
                    oneOf:
                      - description: Cursor mode meta
                        type: object
                        properties:
                          nextCursor:
                            type: string
                            nullable: true
                          hasMore:
                            type: boolean
                      - description: Offset mode meta
                        type: object
                        properties:
                          page:
                            type: integer
                          limit:
                            type: integer
                          total:
                            type: integer
        '400':
          description: Validation error (e.g. cursor and page both provided)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid authorization token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden – insufficient role (must be ADMIN / MANAGER / SUPER_ADMIN)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/users/team:
    post:
      operationId: users_post_users_team
      tags:
        - Users
      x-required-role: [ADMIN, SUPER_ADMIN]
      summary: Create a user as a team member (admin only)
      description: Create a user within the organization. Requires ADMIN or SUPER_ADMIN role.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, name]
              properties:
                email:
                  type: string
                  format: email
                name:
                  type: string
                role:
                  type: string
                  enum: [ADMIN, MANAGER, VIEWER, CUSTOMER]
      responses:
        '201':
          description: Team member created
        '403':
          description: Forbidden
  /api/analytics/performance:
    get:
      operationId: analytics_get_analytics_performance
      tags:
        - Analytics
      x-required-role: [ADMIN, MANAGER]
      summary: Get analytics performance dashboard
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: startDate
          required: true
          schema:
            type: string
            format: date-time
        - in: query
          name: endDate
          required: true
          schema:
            type: string
            format: date-time
        - in: query
          name: granularity
          required: false
          schema:
            type: string
            enum: [daily, weekly, monthly]
      responses:
        '200':
          description: Performance dashboard
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Analytics retrieved
                  data:
                    type: object
                    properties:
                      startDate:
                        type: string
                        format: date-time
                      endDate:
                        type: string
                        format: date-time
                      shipmentsByStatus:
                        type: array
                        items:
                          type: object
                          properties:
                            status:
                              type: string
                            total:
                              type: integer
                      averageDeliveryTimeByLogisticsId:
                        type: array
                        items:
                          type: object
                          properties:
                            logisticsId:
                              type: string
                            averageDeliveryTimeMs:
                              type: number
                      totalDelayedShipments:
                        type: integer
                      timeSeries:
                        type: array
                        items:
                          type: object
                          properties:
                            date:
                              type: string
                              format: date-time
                            shipmentCount:
                              type: integer
                            deliveredCount:
                              type: integer
                            anomalyCount:
                              type: integer
        '400':
          description: Invalid query parameters (e.g., invalid date format, startDate after endDate)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing, invalid, or revoked JWT
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - insufficient role (must be ADMIN / MANAGER / SUPER_ADMIN)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/analytics/summary:
    get:
      operationId: analytics_get_analytics_summary
      x-required-role: [ADMIN, MANAGER]
      summary: Get KPI summary with 30-day sparklines
      description: |
        Returns dashboard KPIs with 30-day sparklines for visualization.
        Aggregates the last 60 days of shipments into current (last 30 days) vs previous (30-60 days ago) periods.
        Results are cached for 5 minutes.
      security:
        - bearerAuth: []
      tags:
        - Analytics
      parameters:
        - in: query
          name: organizationId
          schema:
            type: string
          description: Optional organization ID for scoped analytics
      responses:
        '200':
          description: KPI summary with sparklines
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Summary retrieved
                  data:
                    type: object
                    properties:
                      onTimeDeliveryRate:
                        type: number
                        description: Current 30-day on-time delivery rate (0-100)
                        example: 85.5
                      onTimeDeliveryRatePrev:
                        type: number
                        description: Previous 30-day period on-time delivery rate (0-100)
                        example: 82.3
                      onTimeDeliverySparkline:
                        type: array
                        minItems: 30
                        maxItems: 30
                        items:
                          type: integer
                          minimum: 0
                          maximum: 100
                        description: 30-day sparkline of on-time rates (one value per day)
                        example:
                          [
                            85,
                            86,
                            84,
                            87,
                            85,
                            86,
                            85,
                            84,
                            85,
                            86,
                            87,
                            85,
                            84,
                            86,
                            85,
                            86,
                            85,
                            87,
                            86,
                            85,
                            84,
                            85,
                            86,
                            85,
                            84,
                            85,
                            86,
                            87,
                            85,
                            86,
                          ]
                      averageTransitDays:
                        type: number
                        description: Current 30-day average transit time in days
                        example: 4.2
                      averageTransitDaysPrev:
                        type: number
                        description: Previous 30-day average transit time in days
                        example: 4.1
                      averageTransitSparkline:
                        type: array
                        minItems: 30
                        maxItems: 30
                        items:
                          type: number
                        description: 30-day sparkline of average transit days
                      totalShipmentsThisMonth:
                        type: integer
                        description: Total shipments in current 30-day period
                        example: 450
                      totalShipmentsPrevMonth:
                        type: integer
                        description: Total shipments in previous 30-day period
                        example: 430
                      shipmentsSparkline:
                        type: array
                        minItems: 30
                        maxItems: 30
                        items:
                          type: integer
                          minimum: 0
                        description: 30-day sparkline of shipment counts
                      disputeRate:
                        type: number
                        description: Current 30-day dispute rate (0-100)
                        example: 3.2
                      disputeRatePrev:
                        type: number
                        description: Previous 30-day dispute rate (0-100)
                        example: 3.5
                      disputesSparkline:
                        type: array
                        minItems: 30
                        maxItems: 30
                        items:
                          type: integer
                          minimum: 0
                        description: 30-day sparkline of dispute counts
                      lastUpdated:
                        type: string
                        format: date-time
                        description: Timestamp when data was last calculated
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/payments:
    get:
      operationId: payments_get_payments
      tags:
        - Payments
      summary: Get payments history (legacy — prefer /api/settlements)
      description: Returns settlement records for the authenticated user's organization. Both `/api/payments` and `/api/settlements` resolve to the same router.
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: status
          schema:
            type: string
            enum: [Pending, Escrowed, Released, Failed, Disputed]
          description: Filter payments by status.
        - in: query
          name: organizationId
          schema:
            type: string
          description: Optional organization filter (validated by GetPaymentsQuerySchema).
        - in: query
          name: shipmentId
          schema:
            type: string
          description: Filter payments by shipment ID.
        - in: query
          name: sortBy
          schema:
            type: string
            enum: [amount, status, createdAt]
            default: createdAt
          description: Field to sort payments by.
        - in: query
          name: sortOrder
          schema:
            type: string
            enum: [asc, desc]
            default: desc
          description: Sort direction.
        - in: query
          name: cursor
          schema:
            type: string
          description: Cursor for pagination.
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
          description: Maximum number of records to return.
        - in: query
          name: page
          schema:
            type: integer
            minimum: 1
          description: Page number for offset-based pagination.
      responses:
        '200':
          description: Payments retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Settlement'
                  meta:
                    type: object
                    properties:
                      total:
                        type: integer
                      hasMore:
                        type: boolean
                      nextCursor:
                        type: string
                        nullable: true
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid authorization token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Insufficient role permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: payments_post_payments
      tags:
        - Payments
      x-required-role: [ADMIN, SUPER_ADMIN]
      summary: Create a payment / settlement
      description: |
        Creates a settlement record tied to a shipment. Both `/api/payments` and
        `/api/settlements` share this router. Requires JWT auth and ADMIN or SUPER_ADMIN.
        Provide `token` (preferred) or legacy `tokenType` (`XLMN` | `USDC` | `Other`).
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - shipmentId
                - amount
              properties:
                shipmentId:
                  type: string
                  minLength: 1
                  description: MongoDB ObjectId of the related shipment.
                amount:
                  type: number
                  minimum: 0
                  exclusiveMinimum: true
                  description: Positive settlement amount.
                token:
                  type: string
                  enum: [XLMN, USDC, Other]
                  description: Preferred on-chain asset field.
                tokenType:
                  type: string
                  enum: [XLMN, USDC, Other]
                  description: Deprecated alias for token (backward compatibility).
                payerAddress:
                  type: string
                payeeAddress:
                  type: string
                status:
                  type: string
                  enum: [Pending, Escrowed, Released, Failed, Disputed]
                  default: Pending
      responses:
        '201':
          description: Payment created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                    example: Payment created successfully
                  data:
                    $ref: '#/components/schemas/Settlement'
        '400':
          description: Validation error (e.g. missing token/tokenType, non-positive amount)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid authorization token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Insufficient role permissions (ADMIN / SUPER_ADMIN required)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/payments/summary:
    get:
      summary: Get settlement summary (legacy payments alias)
      description: |
        Legacy alias of `GET /api/settlements/summary` — both `/api/payments` and
        `/api/settlements` resolve to the same router. Returns aggregated
        settlement totals and a per-day sparkline array for the chosen period.
        Results are cached in Redis for 5 minutes.
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: period
          schema:
            type: string
            enum: [week, month, quarter]
            default: week
          description: Aggregation window. `week`=7 days, `month`=30 days, `quarter`=90 days.
      responses:
        '200':
          description: Summary retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      totalReleased:
                        type: number
                        description: Sum of released settlement amounts in the period.
                      totalInEscrow:
                        type: number
                        description: Sum of escrowed settlement amounts in the period.
                      totalPending:
                        type: number
                        description: Sum of pending settlement amounts in the period.
                      sparkline:
                        type: array
                        items:
                          type: number
                        description: One entry per day in the period (released amounts per day).
                      period:
                        type: string
                        enum: [week, month, quarter]
        '400':
          description: Invalid period value
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /api/payments/{id}:
    get:
      operationId: payments_get_payments_id
      tags:
        - Payments
      summary: Get payment / settlement by ID
      description: |
        Returns a single settlement (same handler as `GET /api/settlements/{id}`).
        Requires JWT authentication. No additional role gate beyond `requireAuth`.
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            minLength: 1
          description: Payment / settlement ObjectId.
      responses:
        '200':
          description: Settlement retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                    example: Settlement retrieved successfully
                  data:
                    $ref: '#/components/schemas/Settlement'
        '401':
          description: Missing or invalid authorization token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Settlement not found (`ERR_PAYMENT_NOT_FOUND`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/payments/{id}/status:
    patch:
      operationId: payments_patch_payments_id_status
      tags:
        - Payments
      x-required-role: [ADMIN, SUPER_ADMIN]
      summary: Update payment / settlement status
      description: |
        Advances settlement lifecycle status and optionally records `stellarTxHash`.
        Requires JWT auth and ADMIN or SUPER_ADMIN.
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            minLength: 1
          description: Payment / settlement ObjectId.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - status
              properties:
                status:
                  type: string
                  enum: [Pending, Escrowed, Released, Failed, Disputed]
                stellarTxHash:
                  type: string
                  description: Optional on-chain transaction hash for audit.
      responses:
        '200':
          description: Payment status updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                    example: Payment status updated successfully
                  data:
                    $ref: '#/components/schemas/Settlement'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid authorization token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Insufficient role permissions (ADMIN / SUPER_ADMIN required)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Payment not found (`ERR_PAYMENT_NOT_FOUND`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/payments/{id}/dispute:
    post:
      summary: Dispute a payment / settlement (legacy payments alias)
      description: |
        Legacy alias of `POST /api/settlements/{id}/dispute` — both `/api/payments`
        and `/api/settlements` resolve to the same router. Transitions the
        settlement status to `Disputed` and records dispute metadata
        (`disputedAt`, `disputeReason`, `additionalNotes`) in `escrowRelease`.
        Requires JWT auth and ADMIN or MANAGER role.
      security:
        - bearerAuth: []
      x-required-role: [ADMIN, MANAGER]
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            minLength: 1
          description: Payment / settlement ObjectId.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - reason
              properties:
                reason:
                  type: string
                  minLength: 1
                  description: Reason for the dispute.
                notes:
                  type: string
                  description: Optional additional context.
      responses:
        '200':
          description: Settlement disputed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/Settlement'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Forbidden — requires ADMIN or MANAGER role
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Payment not found (`ERR_PAYMENT_NOT_FOUND`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/settlements:
    get:
      operationId: settlements_get_settlements
      tags:
        - Settlements
      summary: List settlements
      description: Returns settlement records for the authenticated user's organization (cursor-paginated).
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: status
          schema:
            type: string
            enum: [Pending, Escrowed, Released, Failed, Disputed]
          description: Filter by status.
        - in: query
          name: organizationId
          schema:
            type: string
          description: Optional organization filter.
        - in: query
          name: shipmentId
          schema:
            type: string
          description: Filter settlements by shipment ID.
        - in: query
          name: sortBy
          schema:
            type: string
            enum: [amount, status, createdAt]
            default: createdAt
          description: Field to sort settlements by.
        - in: query
          name: sortOrder
          schema:
            type: string
            enum: [asc, desc]
            default: desc
          description: Sort direction.
        - in: query
          name: cursor
          schema:
            type: string
          description: Cursor for next-page pagination.
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - in: query
          name: page
          schema:
            type: integer
            minimum: 1
          description: Page number for offset-based pagination.
      responses:
        '200':
          description: Settlements retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Settlement'
                  meta:
                    type: object
                    properties:
                      total:
                        type: integer
                      hasMore:
                        type: boolean
                      nextCursor:
                        type: string
                        nullable: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

    post:
      summary: Create a settlement
      description: |
        Creates a settlement record tied to a shipment. Canonical settlement
        creation endpoint — `/api/payments` shares this router, so this operation
        is contract-identical to `POST /api/payments`.
        Requires JWT auth and ADMIN or SUPER_ADMIN.
        Provide `token` (preferred) or legacy `tokenType` (`XLMN` | `USDC` | `Other`).
      security:
        - bearerAuth: []
      x-required-role: [ADMIN, SUPER_ADMIN]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - shipmentId
                - amount
              properties:
                shipmentId:
                  type: string
                  minLength: 1
                  description: MongoDB ObjectId of the related shipment.
                amount:
                  type: number
                  minimum: 0
                  exclusiveMinimum: true
                  description: Positive settlement amount.
                token:
                  type: string
                  enum: [XLMN, USDC, Other]
                  description: Preferred on-chain asset field.
                tokenType:
                  type: string
                  enum: [XLMN, USDC, Other]
                  description: Deprecated alias for token (backward compatibility).
                payerAddress:
                  type: string
                payeeAddress:
                  type: string
                status:
                  type: string
                  enum: [Pending, Escrowed, Released, Failed, Disputed]
                  default: Pending
      responses:
        '201':
          description: Settlement created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                    example: Payment created successfully
                  data:
                    $ref: '#/components/schemas/Settlement'
        '400':
          description: Validation error (e.g. missing token/tokenType, non-positive amount)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Insufficient role permissions (ADMIN / SUPER_ADMIN required)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/settlements/summary:
    get:
      operationId: settlements_get_settlements_summary
      tags:
        - Settlements
      summary: Get settlement summary with sparkline
      description: |
        Returns aggregated settlement totals and a per-day sparkline array for the chosen period.
        Results are cached in Redis for 5 minutes.
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: period
          schema:
            type: string
            enum: [week, month, quarter]
            default: week
          description: Aggregation window. `week`=7 days, `month`=30 days, `quarter`=90 days.
      responses:
        '200':
          description: Summary retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      totalReleased:
                        type: number
                        description: Sum of released settlement amounts in the period.
                      totalInEscrow:
                        type: number
                        description: Sum of escrowed settlement amounts in the period.
                      totalPending:
                        type: number
                        description: Sum of pending settlement amounts in the period.
                      sparkline:
                        type: array
                        items:
                          type: number
                        description: One entry per day in the period (released amounts per day).
                      period:
                        type: string
                        enum: [week, month, quarter]
        '400':
          description: Invalid period value
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /api/settlements/{id}:
    get:
      operationId: settlements_get_settlements_id
      tags:
        - Settlements
      summary: Get settlement detail
      description: Returns full settlement detail including escrowRelease subdocument.
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: Settlement ObjectId.
      responses:
        '200':
          description: Settlement retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/Settlement'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Settlement not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/settlements/{id}/status:
    patch:
      summary: Update settlement status
      description: |
        Canonical settlement status transition — contract-identical to
        `PATCH /api/payments/{id}/status` (both paths share the payments router).
        Advances settlement lifecycle status and optionally records
        `stellarTxHash`. Requires JWT auth and ADMIN or SUPER_ADMIN.
      security:
        - bearerAuth: []
      x-required-role: [ADMIN, SUPER_ADMIN]
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            minLength: 1
          description: Settlement ObjectId.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - status
              properties:
                status:
                  type: string
                  enum: [Pending, Escrowed, Released, Failed, Disputed]
                stellarTxHash:
                  type: string
                  description: Optional on-chain transaction hash for audit.
      responses:
        '200':
          description: Settlement status updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                    example: Payment status updated successfully
                  data:
                    $ref: '#/components/schemas/Settlement'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Insufficient role permissions (ADMIN / SUPER_ADMIN required)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Settlement not found (`ERR_PAYMENT_NOT_FOUND`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/settlements/{id}/dispute:
    post:
      operationId: settlements_post_settlements_id_dispute
      tags:
        - Settlements
      x-required-role: [ADMIN, MANAGER]
      summary: Dispute a settlement
      description: |
        Transitions the settlement status to `Disputed` and records dispute metadata
        (`disputedAt`, `disputeReason`, `additionalNotes`) in `escrowRelease`.
        Restricted to ADMIN and MANAGER roles.
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: Settlement ObjectId.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - reason
              properties:
                reason:
                  type: string
                  minLength: 1
                  description: Reason for the dispute.
                notes:
                  type: string
                  description: Optional additional context.
      responses:
        '200':
          description: Settlement disputed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/Settlement'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Forbidden — VIEWER role cannot dispute
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Settlement not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/telemetry:
    get:
      operationId: telemetry_get_telemetry
      tags:
        - Telemetry
      summary: Get telemetry records
      description: Retrieve telemetry time-series points with optional shipment filtering and pagination.
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: shipmentId
          schema:
            type: string
          description: Filter telemetry records by shipment ID.
        - in: query
          name: from
          schema:
            type: string
            format: date-time
          description: Return telemetry recorded at or after this timestamp.
        - in: query
          name: to
          schema:
            type: string
            format: date-time
          description: Return telemetry recorded at or before this timestamp.
        - in: query
          name: cursor
          schema:
            type: string
          description: Cursor for cursor-based pagination.
        - in: query
          name: page
          schema:
            type: integer
            minimum: 1
          description: >
            Legacy offset page number. Prefer cursor pagination for telemetry.
            Cannot be combined with `cursor` (400 if both are sent).
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
          description: Number of records to return.
      responses:
        '200':
          description: Telemetry retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        _id:
                          type: string
                        shipmentId:
                          type: string
                        sensorId:
                          type: string
                        temperature:
                          type: number
                        humidity:
                          type: number
                        latitude:
                          type: number
                        longitude:
                          type: number
                        batteryLevel:
                          type: number
                        timestamp:
                          type: string
                          format: date-time
                        dataHash:
                          type: string
                        stellarTxHash:
                          type: string
                        stellarTxLedger:
                          type: integer
                          nullable: true
                        verified:
                          type: boolean
                        confirmationMetadata:
                          type: object
                          nullable: true
                          properties:
                            ledger:
                              type: integer
                            confirmations:
                              type: integer
                              minimum: 0
                            verified:
                              type: boolean
                            indexedAt:
                              type: string
                              format: date-time
                        anchorStatus:
                          type: string
                          enum: [PENDING_ANCHOR, ANCHORED, ANCHOR_FAILED, VERIFIED]
                        anchorError:
                          type: string
                        createdAt:
                          type: string
                          format: date-time
                        updatedAt:
                          type: string
                          format: date-time
                  meta:
                    type: object
                    properties:
                      nextCursor:
                        type: string
                        nullable: true
                      hasMore:
                        type: boolean
                      page:
                        type: integer
        '400':
          description: Invalid query parameters (e.g., invalid date format, both cursor and page provided)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing, invalid, or revoked JWT
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/telemetry/bulk:
    post:
      operationId: telemetry_post_telemetry_bulk
      tags:
        - Telemetry
      summary: Bulk ingest telemetry readings
      description: |
        Authenticated batch ingest of sensor readings (JWT). Batch size is 1–1000 items
        (`BulkTelemetryBodySchema`). Unlike `POST /api/webhooks/iot` (API key), this path
        requires Bearer auth and has no additional role gate beyond `requireAuth`.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - items
              properties:
                items:
                  type: array
                  minItems: 1
                  maxItems: 1000
                  items:
                    type: object
                    required:
                      - shipmentId
                      - temperature
                      - humidity
                      - latitude
                      - longitude
                      - batteryLevel
                      - timestamp
                    properties:
                      shipmentId:
                        type: string
                        minLength: 1
                      temperature:
                        type: number
                        minimum: -50
                        maximum: 100
                      humidity:
                        type: number
                      latitude:
                        type: number
                      longitude:
                        type: number
                      batteryLevel:
                        type: number
                        minimum: 0
                        maximum: 100
                      timestamp:
                        type: string
                        format: date-time
                      sensorId:
                        type: string
      responses:
        '201':
          description: Bulk telemetry ingested
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                    example: Bulk telemetry ingested
                  data:
                    type: object
                    properties:
                      insertedCount:
                        type: integer
                      insertedIds:
                        type: array
                        items:
                          type: string
        '400':
          description: Validation error or bad request (`ERR_BAD_REQUEST` / `VALIDATION_ERROR`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid authorization token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Related shipment/sensor not found (`ERR_NOT_FOUND`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/organizations:
    post:
      operationId: organizations_post_organizations
      tags:
        - Organizations
      x-required-role: [SUPER_ADMIN]
      summary: Create an organization
      description: Creates a new organization. Requires SUPER_ADMIN role.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, type]
              properties:
                name:
                  type: string
                  description: Organization name
                type:
                  type: string
                  enum: [ENTERPRISE, LOGISTICS]
                  description: Organization type
                settings:
                  type: object
                  description: Optional organization settings
      responses:
        '201':
          description: Organization created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organization'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - not SUPER_ADMIN
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Organization already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      operationId: organizations_get_organizations
      tags:
        - Organizations
      x-required-role: [SUPER_ADMIN]
      summary: List all organizations
      description: Lists all organizations. Requires SUPER_ADMIN role.
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Organizations retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Organization'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - not SUPER_ADMIN
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/organizations/{id}:
    get:
      operationId: organizations_get_organizations_id
      tags:
        - Organizations
      x-required-role: [ADMIN, SUPER_ADMIN]
      summary: Get organization by ID
      description: Get a single organization. ADMIN can read own; SUPER_ADMIN can read any.
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Organization retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organization'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - insufficient role or cross-org access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Organization not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    patch:
      operationId: organizations_patch_organizations_id
      tags:
        - Organizations
      x-required-role: [ADMIN, SUPER_ADMIN]
      summary: Update organization
      description: Update organization details. ADMIN can update own; SUPER_ADMIN can update any. ADMIN cannot modify type.
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                settings:
                  type: object
      responses:
        '200':
          description: Organization updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organization'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - insufficient role or cross-org access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Organization not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: deleteOrganization
      tags:
        - Organizations
      x-required-role: [SUPER_ADMIN]
      summary: Delete an organization
      description: Soft-delete an organization. Requires SUPER_ADMIN role.
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Organization deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/Organization'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - not SUPER_ADMIN
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Organization not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/shipments/export:
    get:
      operationId: shipments_get_shipments_export
      x-required-role: [ADMIN, MANAGER]
      summary: Export shipments as CSV or JSON
      description: |
        Downloads filtered shipments as a CSV or JSON attachment.
        Requires JWT and ADMIN or MANAGER role. Result set capped at 10,000 records.
      tags:
        - Shipments
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: format
          schema:
            type: string
            enum: [csv, json]
            default: json
          description: Output format
        - in: query
          name: status
          schema:
            type: string
          description: Filter by shipment status
        - in: query
          name: origin
          schema:
            type: string
          description: Filter by origin (partial match)
        - in: query
          name: destination
          schema:
            type: string
          description: Filter by destination (partial match)
        - in: query
          name: startDate
          schema:
            type: string
            format: date-time
          description: Include shipments created at or after this timestamp
        - in: query
          name: endDate
          schema:
            type: string
            format: date-time
          description: Include shipments created at or before this timestamp
      responses:
        '200':
          description: Shipments exported successfully
          content:
            text/csv:
              schema:
                type: string
                description: CSV file attachment
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Shipment'
        '400':
          description: Validation error or export too large (>10,000 records)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden — insufficient role
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/auth/password:
    patch:
      operationId: auth_patch_auth_password
      summary: Change authenticated user's password
      description: |
        Verifies `currentPassword` against the stored hash. If correct, hashes
        `newPassword` and updates the user. The current JWT is blocklisted to
        force re-login with the new credentials.
      tags:
        - Auth
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - currentPassword
                - newPassword
              properties:
                currentPassword:
                  type: string
                  description: The user's current plaintext password
                newPassword:
                  type: string
                  minLength: 8
                  description: New password (minimum 8 characters)
      responses:
        '200':
          description: Password changed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Password changed successfully
                  data:
                    type: string
                    nullable: true
                    example: null
        '400':
          description: Validation error (e.g. newPassword too short)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing/invalid token or incorrect currentPassword
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/shipments:
    get:
      operationId: shipments_get_shipments
      tags:
        - Shipments
      x-required-role: [ADMIN, MANAGER, VIEWER]
      summary: Get paginated shipments with offset-based pagination
      description: Returns a paginated list of shipments. Uses offset-based pagination with page and limit parameters.
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: status
          schema:
            type: string
          description: >
            Filter by status. Single value or comma-separated list
            (e.g. CREATED,IN_TRANSIT).
          example: CREATED,IN_TRANSIT
        - in: query
          name: priority
          schema:
            type: string
          description: >
            Filter by priority. Single value or comma-separated list
            (e.g. URGENT,STANDARD).
          example: URGENT,STANDARD
        - in: query
          name: page
          schema:
            type: integer
            minimum: 1
            default: 1
          description: Page number (starts at 1)
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
          description: Number of items per page (max 100)
        - in: query
          name: origin
          schema:
            type: string
          description: Filter by origin location (case-insensitive partial match)
        - in: query
          name: destination
          schema:
            type: string
          description: Filter by destination location (case-insensitive partial match)
        - in: query
          name: trackingNumber
          schema:
            type: string
          description: Filter by tracking number (case-insensitive partial match)
        - in: query
          name: q
          schema:
            type: string
          description: >
            Full-text search across trackingNumber, origin, and destination
            (MongoDB text index).
          example: NVN-123
        - in: query
          name: from
          schema:
            type: string
            format: date-time
          description: Include shipments created at or after this timestamp
        - in: query
          name: to
          schema:
            type: string
            format: date-time
          description: Include shipments created at or before this timestamp
        - in: query
          name: sortBy
          schema:
            type: string
            enum: [createdAt, priority, expectedDelivery]
          description: Field to sort by
        - in: query
          name: sortOrder
          schema:
            type: string
            enum: [asc, desc]
            default: desc
          description: Sort order
      responses:
        '200':
          description: Paginated shipments retrieved successfully
          headers:
            X-Request-ID:
              description: Unique request identifier for tracking and debugging
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: 'Shipments retrieved'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Shipment'
                  meta:
                    type: object
                    properties:
                      page:
                        type: integer
                        description: Current page number
                        example: 1
                      limit:
                        type: integer
                        description: Items per page
                        example: 20
                      total:
                        type: integer
                        description: Total number of shipments matching the query
                        example: 150
        '400':
          description: Invalid query parameters (e.g., page < 1, limit > 100)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                message: Validation failed - limit must be between 1 and 100
                data: null
                error:
                  code: VALIDATION_ERROR
                details:
                  - path: limit
                    message: limit must be between 1 and 100
                    code: too_big
    post:
      operationId: shipments_post_shipments
      tags:
        - Shipments
      x-required-role: [MANAGER, ADMIN]
      summary: Create a shipment
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateShipmentRequest'
      responses:
        '201':
          description: Shipment created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Shipment created
                  data:
                    $ref: '#/components/schemas/Shipment'
        '400':
          description: Validation error - invalid request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing, invalid, or revoked JWT
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - insufficient role (requires ADMIN / MANAGER)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Duplicate tracking number
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/shipments/{id}:
    get:
      operationId: shipments_get_shipments_id
      tags:
        - Shipments
      x-required-role: [SUPER_ADMIN, ADMIN, MANAGER, VIEWER]
      summary: Get a single shipment by ID
      description: |
        Returns a single shipment wrapped in the standard API envelope
        `{ success, message, data }`. Requires JWT and one of
        SUPER_ADMIN / ADMIN / MANAGER / VIEWER. Non–super-admin callers are
        limited to shipments in their organization.
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            minLength: 1
          description: Shipment ObjectId.
      responses:
        '200':
          description: Shipment retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/Shipment'
        '400':
          description: Invalid path parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden — insufficient role or organization access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Shipment not found (`ERR_SHIPMENT_NOT_FOUND`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    patch:
      operationId: shipments_patch_shipments_id
      tags:
        - Shipments
      x-required-role: [ADMIN, MANAGER]
      summary: Update off-chain metadata
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                offChainMetadata:
                  type: object
      responses:
        '200':
          description: Shipment updated
        '400':
          description: Validation error - invalid request body or path parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing, invalid, or revoked JWT
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - insufficient role (requires ADMIN / MANAGER)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Shipment not found (`ERR_SHIPMENT_NOT_FOUND`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: shipments_delete_shipments_id
      tags:
        - Shipments
      x-required-role: [ADMIN, MANAGER]
      summary: Delete a shipment
      description: Soft-delete a shipment. Requires ADMIN or MANAGER role.
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Shipment deleted
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/shipments/{id}/timeline:
    get:
      operationId: shipments_get_shipments_id_timeline
      x-required-role: [ADMIN, MANAGER, VIEWER]
      tags:
        - Shipments
      summary: Get unified shipment activity timeline
      description: |
        Returns a cursor-paginated, chronologically sorted activity timeline for a shipment.
        Events are aggregated from milestones, delivery proof, anchored telemetry, and anomalies.

        Query contract mirrors `ShipmentTimelineQuerySchema`:
        - `cursor` (optional opaque string from a previous `meta.nextCursor`)
        - `limit` (1–100, default 20)

        Response envelope: `{ success, message, data: ShipmentTimelineEvent[], meta: { nextCursor, hasMore } }`.
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: Shipment ObjectId
        - in: query
          name: cursor
          required: false
          schema:
            type: string
          description: Opaque cursor from a previous page (`timestamp|suffix`)
        - in: query
          name: limit
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
          description: Maximum number of timeline events to return
      responses:
        '200':
          description: Chronological shipment events
          content:
            application/json:
              schema:
                type: object
                required: [success, message, data, meta]
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                    example: Shipment timeline retrieved
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ShipmentTimelineEvent'
                  meta:
                    type: object
                    required: [nextCursor, hasMore]
                    properties:
                      nextCursor:
                        type: string
                        nullable: true
                        description: Cursor for the next page, or null when hasMore is false
                      hasMore:
                        type: boolean
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Shipment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/shipments/{id}/proof:
    post:
      operationId: shipments_post_shipments_id_proof
      tags:
        - Shipments
      x-required-role: [ADMIN, MANAGER]
      summary: Upload proof of delivery for a shipment
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/UploadProofRequest'
      responses:
        '200':
          description: Proof uploaded successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      deliveryProof:
                        type: object
                        properties:
                          url:
                            type: string
                          recipientSignatureName:
                            type: string
                          notes:
                            type: string
                          uploadedAt:
                            type: string
                            format: date-time
        '400':
          description: Missing file or invalid payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Storage unavailable
  /api/shipments/{id}/documents:
    post:
      operationId: shipments_post_shipments_id_documents
      tags:
        - Shipments
      x-required-role: [ADMIN, MANAGER]
      summary: Upload a document to a shipment
      description: >
        Upload a document (PDF or image) for a shipment. Maximum file size is 10MB.
        Accepted MIME types: application/pdf, image/jpeg, image/png, image/webp.
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/UploadDocumentRequest'
      responses:
        '201':
          description: Document uploaded successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/ShipmentDocument'
        '400':
          description: Missing file or invalid type enum
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '413':
          description: File too large (max 10MB)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '415':
          description: Invalid MIME type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Storage unavailable
  /api/shipments/{id}/photos:
    post:
      operationId: shipments_post_shipments_id_photos
      tags:
        - Shipments
      x-required-role: [ADMIN, MANAGER]
      summary: Upload a photo to a shipment
      description: >
        Upload a photo (image only) for a shipment. Maximum file size is 5MB.
        Maximum 10 photos per shipment. Accepted MIME types: image/jpeg, image/png, image/webp, image/heic, image/heif.
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/UploadPhotoRequest'
      responses:
        '201':
          description: Photo uploaded successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/ShipmentPhoto'
        '400':
          description: Missing file, invalid type, or photo limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '413':
          description: File too large (max 5MB)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '415':
          description: Invalid MIME type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Storage unavailable
  /api/shipments/{id}/disputes:
    post:
      operationId: shipments_post_shipments_id_disputes
      tags:
        - Shipments
      x-required-role: [ADMIN, MANAGER]
      summary: Create a dispute with evidence
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - type
                - description
              properties:
                type:
                  type: string
                  enum: [WRONG_GOODS, DAMAGED, NOT_DELIVERED, PAYMENT_DISAGREEMENT, OTHER]
                description:
                  type: string
                evidence:
                  type: string
                  format: binary
      responses:
        '201':
          description: Dispute created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      referenceNumber:
                        type: string
                      status:
                        type: string
                      type:
                        type: string
                      description:
                        type: string
                      evidenceUrl:
                        type: string
                      createdAt:
                        type: string
                        format: date-time
                      updatedAt:
                        type: string
                        format: date-time
        '400':
          description: Missing or invalid payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Shipment not found
        '413':
          description: Payload too large
        '503':
          description: Storage unavailable
  /api/shipments/{id}/eta:
    get:
      operationId: shipments_get_shipments_id_eta
      tags:
        - Shipments
      summary: Get shipment ETA from recent telemetry
      description: Returns ETA, distance remaining, average speed, and confidence when shipment is in transit.
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Shipment ETA retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    # Mirrors the `ShipmentEtaPayload` discriminated union in
                    # src/modules/shipments/shipmentsEta.cache.ts. The two
                    # branches are mutually exclusive: each closes its object
                    # (`additionalProperties: false`) and requires a property
                    # the other branch forbids, so no response can satisfy
                    # both.
                    oneOf:
                      - title: Estimated arrival (shipment is in transit)
                        type: object
                        additionalProperties: false
                        required:
                          - estimatedArrival
                          - distanceRemaining
                          - averageSpeed
                          - confidence
                        properties:
                          estimatedArrival:
                            type: string
                            format: date-time
                          distanceRemaining:
                            type: number
                            description: Kilometres remaining to the destination.
                          averageSpeed:
                            type: number
                            description: Average speed in km/h over the telemetry window.
                          confidence:
                            type: string
                            enum: [LOW, MEDIUM, HIGH]
                      - title: ETA unavailable (shipment is not in transit)
                        type: object
                        additionalProperties: false
                        required:
                          - estimatedArrival
                          - reason
                        properties:
                          estimatedArrival:
                            type: string
                            nullable: true
                            description: Always `null` in this branch.
                          reason:
                            type: string
                            description: Human-readable explanation of why no ETA was computed.
        '400':
          description: Missing destination coordinates or invalid request data
        '401':
          description: Unauthorized
        '404':
          description: Shipment or telemetry data not found
  /api/shipments/{id}/status:
    patch:
      operationId: shipments_patch_shipments_id_status
      tags:
        - Shipments
      x-required-role: [ADMIN, MANAGER]
      summary: Update shipment status
      description: Update the current shipment status (e.g., IN_TRANSIT, DELIVERED). Requires ADMIN or MANAGER role.
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateShipmentStatusRequest'
      responses:
        '200':
          description: Shipment status updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Shipment status updated
                  data:
                    $ref: '#/components/schemas/Shipment'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - insufficient role
  /api/shipments/bulk/status:
    patch:
      operationId: shipments_patch_shipments_bulk_status
      tags:
        - Shipments
      x-required-role: [ADMIN, MANAGER]
      summary: Bulk update shipment status
      description: Update status for multiple shipments at once. Requires ADMIN or MANAGER role. Accepts up to 50 shipment IDs.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [shipmentIds, status]
              properties:
                shipmentIds:
                  type: array
                  minItems: 1
                  maxItems: 50
                  items:
                    type: string
                  description: Array of shipment IDs to update (max 50)
                status:
                  type: string
                  enum:
                    [
                      CREATED,
                      PICKUP_CONFIRMED,
                      IN_TRANSIT,
                      CUSTOMS_CLEARED,
                      OUT_FOR_DELIVERY,
                      DELIVERED,
                      SETTLEMENT_INITIATED,
                      SETTLEMENT_COMPLETED,
                      CANCELLED,
                    ]
      responses:
        '200':
          description: Bulk status update completed
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      updated:
                        type: integer
                        description: Number of shipments successfully updated
                      failed:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              description: Shipment ID that failed to update
                            reason:
                              type: string
                              enum: [NOT_FOUND, WRONG_ORG, INVALID_TRANSITION, UPDATE_FAILED]
                              description: Reason for failure
        '400':
          description: Invalid request (empty array or exceeds 50 items)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - insufficient role
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/telemetry/thresholds:
    get:
      operationId: telemetry_get_telemetry_thresholds
      tags:
        - Telemetry
      x-required-role: [SUPER_ADMIN, ADMIN, MANAGER, VIEWER]
      summary: Get organization telemetry anomaly thresholds
      description: |
        Returns effective anomaly thresholds for the caller's organization
        (`{ shipmentType, thresholds }`). Optional `shipmentType` selects a
        category profile; otherwise DEFAULT is used. Requires JWT and
        SUPER_ADMIN / ADMIN / MANAGER / VIEWER. Callers without `organizationId`
        receive 403.
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: shipmentType
          schema:
            type: string
            minLength: 1
          description: Shipment category key (defaults to DEFAULT)
      responses:
        '200':
          description: Threshold configuration retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                    example: Telemetry thresholds retrieved
                  data:
                    type: object
                    properties:
                      shipmentType:
                        type: string
                      thresholds:
                        type: object
                        properties:
                          maxTemp:
                            type: number
                          minTemp:
                            type: number
                          maxHumidity:
                            type: number
                          minHumidity:
                            type: number
                          minBatteryLevel:
                            type: number
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden — insufficient role or missing organization context
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      operationId: telemetry_put_telemetry_thresholds
      tags:
        - Telemetry
      x-required-role: [SUPER_ADMIN, ADMIN]
      summary: Update organization telemetry anomaly thresholds
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                shipmentType:
                  type: string
                maxTemp:
                  type: number
                  nullable: true
                minTemp:
                  type: number
                  nullable: true
                maxHumidity:
                  type: number
                  nullable: true
                minHumidity:
                  type: number
                  nullable: true
                minBatteryLevel:
                  type: number
                  nullable: true
      responses:
        '200':
          description: Threshold configuration updated
        '401':
          description: Unauthorized
        '403':
          description: Forbidden — admin role required
        '422':
          description: Validation error
  /api/anomalies/stats:
    get:
      operationId: anomalies_get_anomalies_stats
      x-required-role: [ADMIN, MANAGER]
      summary: Get anomaly statistics
      description: |
        Returns aggregated anomaly statistics for the organization, including:
        - Total active (unresolved) anomalies
        - Total anomalies (all time)
        - Total resolved anomalies
        - Breakdown by severity (LOW, MEDIUM, HIGH)
        - Breakdown by type (TEMPERATURE_EXCEEDED, HUMIDITY_EXCEEDED, etc.)

        Results are cached for 5 minutes. Requires ADMIN or MANAGER role.
      tags:
        - Anomalies
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Anomaly statistics retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Anomaly stats retrieved
                  data:
                    type: object
                    properties:
                      totalActive:
                        type: integer
                        description: Count of unresolved anomalies
                        example: 12
                      totalAll:
                        type: integer
                        description: Total count of all anomalies (resolved + unresolved)
                        example: 156
                      resolved:
                        type: integer
                        description: Count of resolved anomalies
                        example: 144
                      bySeverity:
                        type: object
                        description: Count of active anomalies grouped by severity
                        properties:
                          LOW:
                            type: integer
                            example: 5
                          MEDIUM:
                            type: integer
                            example: 4
                          HIGH:
                            type: integer
                            example: 3
                      byType:
                        type: object
                        description: Count of active anomalies grouped by type
                        properties:
                          TEMPERATURE_EXCEEDED:
                            type: integer
                            example: 3
                          TEMPERATURE_BELOW_MIN:
                            type: integer
                            example: 1
                          HUMIDITY_EXCEEDED:
                            type: integer
                            example: 2
                          HUMIDITY_BELOW_MIN:
                            type: integer
                            example: 1
                          BATTERY_LOW:
                            type: integer
                            example: 5
        '401':
          description: Missing or invalid authorization token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Insufficient permissions - only ADMIN or MANAGER can view stats
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/anomalies:
    get:
      operationId: anomalies_get_anomalies
      tags:
        - Anomalies
      x-required-role: [ADMIN, MANAGER]
      summary: Get anomalies with pagination and filtering
      description: Retrieve a paginated list of anomalies, sorted by timestamp descending. Supports filtering by severity and shipmentId. Requires ADMIN or MANAGER role.
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: cursor
          schema:
            type: string
          description: Cursor for pagination
        - in: query
          name: limit
          schema:
            type: integer
            default: 20
          description: Number of items per page
        - in: query
          name: shipmentId
          schema:
            type: string
          description: Filter by shipment ID
        - in: query
          name: severity
          schema:
            type: string
            enum: [LOW, MEDIUM, HIGH]
          description: Filter by severity
        - in: query
          name: type
          schema:
            type: string
            enum:
              [
                TEMPERATURE_EXCEEDED,
                TEMPERATURE_BELOW_MIN,
                HUMIDITY_EXCEEDED,
                HUMIDITY_BELOW_MIN,
                BATTERY_LOW,
              ]
          description: Filter by anomaly type
        - in: query
          name: resolved
          schema:
            type: boolean
          description: Filter by whether an anomaly has been resolved
      responses:
        '200':
          description: Paginated anomalies
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Anomaly'
                  meta:
                    type: object
                    properties:
                      nextCursor:
                        type: string
                        nullable: true
                      hasMore:
                        type: boolean
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - insufficient role
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/anomalies/{id}/resolve:
    patch:
      operationId: anomalies_patch_anomalies_id_resolve
      tags:
        - Anomalies
      x-required-role: [ADMIN, MANAGER]
      summary: Resolve an anomaly
      description: Mark an anomaly as resolved. Requires ADMIN or MANAGER role.
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: Anomaly ID
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                note:
                  type: string
                  maxLength: 1000
                  description: Optional resolution note
      responses:
        '200':
          description: Anomaly resolved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/Anomaly'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - insufficient role
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Anomaly not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/ledger/blocks:
    get:
      operationId: ledger_get_ledger_blocks
      x-required-role: [ADMIN, MANAGER, VIEWER]
      summary: List ledger blocks
      description: Returns a cursor-paginated list of ledger blocks, optionally filtered by shipment or event type.
      tags:
        - Ledger
      security:
        - bearerAuth: []
      parameters:
        - name: shipmentId
          in: query
          schema:
            type: string
          description: Filter by shipment ObjectId
        - name: milestoneEvent
          in: query
          schema:
            $ref: '#/components/schemas/MilestoneEvent'
          description: Filter by milestone event type
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
          description: Maximum number of blocks to return
        - name: cursor
          in: query
          schema:
            type: string
          description: Cursor for the next page
      responses:
        '200':
          description: Ledger blocks retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/LedgerBlock'
                  meta:
                    type: object
                    properties:
                      total:
                        type: integer
                      hasMore:
                        type: boolean
                      nextCursor:
                        type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                message: Missing or invalid token
                data: null
                error:
                  code: ERR_AUTH_INVALID
        '403':
          description: Forbidden - insufficient role
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                message: Insufficient permissions
                data: null
                error:
                  code: ERR_PERMISSION_DENIED
  /api/ledger/blocks/{id}:
    get:
      operationId: ledger_get_ledger_blocks_id
      x-required-role: [ADMIN, MANAGER, VIEWER]
      summary: Get a ledger block by ID
      description: Retrieves a single ledger block by its ObjectId.
      tags:
        - Ledger
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Ledger block ObjectId
      responses:
        '200':
          description: Ledger block retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/LedgerBlock'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - insufficient role
        '404':
          description: Ledger block not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/ledger/blocks/{id}/verification:
    get:
      operationId: ledger_get_ledger_blocks_id_verification
      x-required-role: [ADMIN, MANAGER, VIEWER]
      summary: Get client-side verification material for a ledger block
      description: |
        Returns everything a client needs to independently verify a ledger block
        without trusting the API, in three steps:

        1. Fetch `canonicalPayload`, `dataHash` and `txHash` from this endpoint.
        2. Recompute `sha256(canonicalPayload)` client-side (Web Crypto) and compare
           it with `dataHash`.
        3. Query Horizon (`memo_hash` / `manageData` value) or Soroban RPC
           (`getTransaction` + `getEvents`) for `txHash` and confirm the on-chain
           digest equals `dataHash`.

        See `docs/blockchain.md` for the copy-pasteable browser implementation.
      tags:
        - Ledger
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Ledger block ObjectId
      responses:
        '200':
          description: Verification material retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/LedgerVerificationBundle'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - insufficient role
        '404':
          description: Ledger block not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/events/poll:
    get:
      operationId: events_get_events_poll
      tags:
        - Events
      summary: Poll for recent real-time events (polling fallback)
      description: |
        Returns an array of `RealtimeEvent` objects published after the
        client's `since` timestamp.  Intended for clients that cannot use
        EventSource / SSE.

        **Window:** The server retains events for up to 60 seconds in a
        Redis-backed list (capped at 500 entries).  Clients should poll
        every 5–15 seconds and advance `since` to the `publishedAt` of the
        last received event on each response.

        Returns an empty array when no new events exist — this is the normal
        steady-state response.
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: since
          required: false
          schema:
            type: string
            format: date-time
          description: |
            ISO 8601 UTC timestamp.  Only events with `publishedAt` strictly
            after this value are returned.  Defaults to 15 seconds ago when
            omitted (useful for first-time callers).
          example: '2026-07-26T10:00:00.000Z'
      responses:
        '200':
          description: Events retrieved (may be an empty array)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Events retrieved
                  data:
                    type: array
                    description: >
                      Array of RealtimeEvent objects ordered oldest-first.
                      Each element is a discriminated union on the `type` field.
                    items:
                      oneOf:
                        - $ref: '#/components/schemas/TelemetryUpdateEvent'
                        - $ref: '#/components/schemas/AnomalyDetectedEvent'
                        - $ref: '#/components/schemas/StatusUpdateEvent'
                        - $ref: '#/components/schemas/PaymentStatusChangedEvent'
        '400':
          description: Invalid `since` value (not a valid ISO 8601 datetime)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid authorization token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: Redis event store unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  schemas:
    Session:
      type: object
      description: A per-device session record created on login or signup.
      properties:
        _id:
          type: string
          description: Session MongoDB ObjectId
        userId:
          type: string
          description: Owner user ObjectId
        jti:
          type: string
          description: JWT ID (UUID v4) — use this as the path param for DELETE /api/auth/sessions/:jti
        ip:
          type: string
          description: Client IP address at time of login (optional)
        userAgent:
          type: string
          description: HTTP User-Agent string at time of login (optional)
        createdAt:
          type: string
          format: date-time
          description: When the session was created (ISO 8601)
        lastUsedAt:
          type: string
          format: date-time
          description: When the session was last active (ISO 8601)
    TelemetryUpdateEvent:
      type: object
      description: Real-time telemetry reading from an IoT sensor.
      required:
        [
          type,
          publishedAt,
          telemetryId,
          shipmentId,
          sensorId,
          temperature,
          humidity,
          latitude,
          longitude,
          batteryLevel,
          timestamp,
          dataHash,
          anchorStatus,
        ]
      properties:
        type:
          type: string
          enum: [telemetry_update]
        publishedAt:
          type: integer
          description: Epoch milliseconds when the event was pushed to the Redis store.
        telemetryId:
          type: string
        shipmentId:
          type: string
        sensorId:
          type: string
        temperature:
          type: number
        humidity:
          type: number
        latitude:
          type: number
        longitude:
          type: number
        batteryLevel:
          type: number
        timestamp:
          type: string
          format: date-time
        dataHash:
          type: string
        anchorStatus:
          type: string
          enum: [PENDING_ANCHOR, ANCHORED, ANCHOR_FAILED]
        stellarTxHash:
          type: string
          nullable: true
    IotWebhookNormalizedPayload:
      type: object
      description: >
        Shipment-centric telemetry payload. `batteryLevel` defaults to 100 when omitted.
        Temperature range enforced by Zod: -50..100 °C.
      additionalProperties: false
      required:
        - shipmentId
        - temperature
        - humidity
        - latitude
        - longitude
        - timestamp
      properties:
        sensorId:
          type: string
          minLength: 1
          description: Optional sensor identifier
        shipmentId:
          type: string
          minLength: 1
          description: MongoDB ObjectId of the shipment
        temperature:
          type: number
          minimum: -50
          maximum: 100
          description: Temperature in Celsius
        humidity:
          type: number
          description: Humidity percentage
        latitude:
          type: number
          description: GPS latitude
        longitude:
          type: number
          description: GPS longitude
        batteryLevel:
          type: number
          minimum: 0
          maximum: 100
          description: Battery level percentage (optional; defaults to 100)
        timestamp:
          type: string
          format: date-time
          description: Timestamp of the telemetry reading
    IotWebhookSensorPayload:
      type: object
      description: >
        Sensor-centric telemetry payload. `temp` maps to temperature;
        `location.lat` / `location.lng` map to latitude / longitude during normalize.
      additionalProperties: false
      required:
        - sensorId
        - temp
        - humidity
        - location
        - timestamp
      properties:
        sensorId:
          type: string
          minLength: 1
          description: Sensor identifier used to resolve the active shipment
        temp:
          type: number
          minimum: -50
          maximum: 100
          description: Temperature in Celsius (normalized to `temperature`)
        humidity:
          type: number
          description: Humidity percentage
        location:
          type: object
          additionalProperties: false
          required:
            - lat
            - lng
          properties:
            lat:
              type: number
              description: GPS latitude
            lng:
              type: number
              description: GPS longitude
        batteryLevel:
          type: number
          minimum: 0
          maximum: 100
          description: Battery level percentage (optional; defaults to 100)
        timestamp:
          type: string
          format: date-time
          description: Timestamp of the telemetry reading
    IotWebhookBody:
      description: >
        Union of shipment-centric and sensor-centric IoT webhook payloads
        (`IotWebhookBodySchema` in `iot.validation.ts`).
      oneOf:
        - $ref: '#/components/schemas/IotWebhookNormalizedPayload'
        - $ref: '#/components/schemas/IotWebhookSensorPayload'
    IotWebhookTelemetryData:
      type: object
      description: Persisted telemetry document returned in the 202 response `data` field
      properties:
        _id:
          type: string
        shipmentId:
          type: string
        sensorId:
          type: string
        temperature:
          type: number
        humidity:
          type: number
        latitude:
          type: number
        longitude:
          type: number
        batteryLevel:
          type: number
        timestamp:
          type: string
          format: date-time
        dataHash:
          type: string
        anchorStatus:
          type: string
          enum: [PENDING_ANCHOR, ANCHORED, ANCHOR_FAILED]
        stellarTxHash:
          type: string
          nullable: true

    AnomalyDetectedEvent:
      type: object
      description: Anomaly detected in shipment telemetry.
      required: [type, publishedAt, anomalyId, shipmentId, severity, message, timestamp, resolved]
      properties:
        type:
          type: string
          enum: [anomaly_detected]
        publishedAt:
          type: integer
          description: Epoch milliseconds when the event was pushed to the Redis store.
        anomalyId:
          type: string
        shipmentId:
          type: string
        severity:
          type: string
          enum: [LOW, MEDIUM, HIGH]
        message:
          type: string
        timestamp:
          type: string
          format: date-time
        resolved:
          type: boolean

    StatusUpdateEvent:
      type: object
      description: Shipment status change event.
      required: [type, publishedAt, shipmentId, status]
      properties:
        type:
          type: string
          enum: [status_update]
        publishedAt:
          type: integer
          description: Epoch milliseconds when the event was pushed to the Redis store.
        shipmentId:
          type: string
        status:
          type: string
          enum: [CREATED, IN_TRANSIT, DELIVERED, CANCELLED]
        milestones:
          type: array
          nullable: true
          items:
            type: object
            properties:
              name:
                type: string
              timestamp:
                type: string
                format: date-time
              description:
                type: string
                nullable: true
        updatedAt:
          type: string
          format: date-time
          nullable: true

    PaymentStatusChangedEvent:
      type: object
      description: Payment status change event for a shipment.
      required: [type, publishedAt, paymentId, shipmentId, oldStatus, newStatus, amount, timestamp]
      properties:
        type:
          type: string
          enum: [payment_status_changed]
        publishedAt:
          type: integer
          description: Epoch milliseconds when the event was pushed to the Redis store.
        paymentId:
          type: string
        shipmentId:
          type: string
        oldStatus:
          type: string
        newStatus:
          type: string
        amount:
          type: number
        timestamp:
          type: string
          format: date-time

          description: Deterministic SHA-256 hash of the raw payload
        anchorStatus:
          type: string
          enum: [PENDING_ANCHOR, ANCHORED, ANCHOR_FAILED]
          description: Starts as PENDING_ANCHOR until the Stellar worker completes
        stellarTxHash:
          type: string
          description: Present after successful anchoring on Stellar
    IotWebhookAcceptedResponse:
      type: object
      required:
        - success
        - message
        - data
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: Telemetry received and queued for Stellar anchoring
        data:
          $ref: '#/components/schemas/IotWebhookTelemetryData'
    StellarWebhookPayload:
      type: object
      required:
        - id
        - type
        - paymentId
        - transactionHash
        - amount
        - timestamp
      properties:
        id:
          type: string
          description: Unique Stellar webhook event identifier
        type:
          type: string
          enum: [release, escrow, failed]
          description: Stellar webhook event type
        paymentId:
          type: string
          description: Payment identifier linked to the shipment
        transactionHash:
          type: string
          description: Stellar transaction hash for the settlement event
        amount:
          type: number
          description: Amount associated with the Stellar event
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp for the webhook event
        signature:
          type: string
          description: Optional HMAC signature value for webhook verification
    StellarWebhookResponse:
      type: object
      required:
        - success
        - message
        - data
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: Webhook processed successfully
        data:
          type: object
          properties:
            event:
              type: string
              enum: [release, escrow, failed]
            paymentId:
              type: string
            status:
              type: string
              description: Resulting payment status (e.g. RELEASED, ESCROWED, FAILED)
            transactionHash:
              type: string
              description: Present for release and escrow events
    ActivityEvent:
      type: object
      required:
        - _id
        - userId
        - action
        - resource
        - resourceId
        - timestamp
      properties:
        _id:
          type: string
          description: MongoDB ObjectId of the audit log entry.
        userId:
          type: string
          description: ID of the user who triggered the event, or "system" for automated events.
        action:
          type: string
          description: The action that occurred.
          enum:
            - SHIPMENT_CREATED
            - SHIPMENT_STATUS_CHANGED
            - PROOF_UPLOADED
            - DISPUTE_OPENED
            - TELEMETRY_ANCHORED
            - SETTLEMENT_RELEASED
            - ANOMALY_DETECTED
            - USER_INVITED
            - RBAC_ROLE_MODIFIED
            - API_KEY_GENERATED
        resource:
          type: string
          description: The resource category affected.
          enum:
            - SHIPMENT
            - TELEMETRY
            - PAYMENT
            - ANOMALY
            - USER
            - API_KEY
        resourceId:
          type: string
          description: ID of the affected resource document.
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 UTC timestamp when the event occurred.
        metadata:
          type: object
          nullable: true
          description: Action-specific contextual data (varies by action type).
          additionalProperties: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ShipmentTemplateFields:
      type: object
      properties:
        origin:
          type: string
        destination:
          type: string
        itemDescription:
          type: string
        weight:
          type: number
        recipientName:
          type: string
        recipientContact:
          type: string
    ShipmentTemplate:
      type: object
      properties:
        _id:
          type: string
        name:
          type: string
        fields:
          $ref: '#/components/schemas/ShipmentTemplateFields'
        organizationId:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    CreateShipmentTemplateRequest:
      type: object
      required:
        - name
        - fields
      properties:
        name:
          type: string
          maxLength: 200
        fields:
          $ref: '#/components/schemas/ShipmentTemplateFields'
    UpdateShipmentTemplateRequest:
      type: object
      properties:
        name:
          type: string
          maxLength: 200
        fields:
          $ref: '#/components/schemas/ShipmentTemplateFields'
    EscrowRelease:
      type: object
      properties:
        conditionDescription:
          type: string
        releasedAt:
          type: string
          format: date-time
          nullable: true
        releasedBy:
          type: string
          nullable: true
        disputedAt:
          type: string
          format: date-time
          nullable: true
        disputeReason:
          type: string
          nullable: true
        additionalNotes:
          type: string
          nullable: true
    Settlement:
      type: object
      properties:
        _id:
          type: string
        shipmentId:
          type: string
        organizationId:
          type: string
        amount:
          type: number
        token:
          type: string
          enum: [XLMN, USDC, Other]
        tokenType:
          type: string
          description: Deprecated alias for token — kept for backward compatibility.
        payerAddress:
          type: string
          nullable: true
        payeeAddress:
          type: string
          nullable: true
        status:
          type: string
          enum: [Pending, Escrowed, Released, Failed, Disputed]
        stellarTxHash:
          type: string
          nullable: true
        stellarTxLedger:
          type: integer
          nullable: true
        confirmations:
          type: integer
          minimum: 0
          description: Confirmed ledger depth for the Stellar transaction.
        explorerUrl:
          type: string
          nullable: true
          description: Stellar explorer URL for the transaction (computed).
        escrowRelease:
          # OAS 3.0 has no `oneOf: [{$ref}, null]`, and a `nullable` sibling
          # next to `$ref` is ignored per JSON Reference semantics. Wrapping the
          # reference in `allOf` and declaring `type` keeps the nullability
          # meaningful for generated clients and validators.
          type: object
          description: >-
            Escrow release outcome; `null` while the escrow has not been
            released, disputed, or otherwise finalised.
          nullable: true
          allOf:
            - $ref: '#/components/schemas/EscrowRelease'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ErrorResponse:
      type: object
      required:
        - success
        - message
        - data
        - error
      properties:
        success:
          type: boolean
          example: false
          description: Always false for error responses
        message:
          type: string
          example: Validation failed
          description: Human-readable error message describing why the request failed.
        data:
          type: object
          nullable: true
          example: null
          description: Null payload for error responses.
        error:
          type: object
          required:
            - code
          properties:
            code:
              $ref: '#/components/schemas/ErrorCode'
              description: |
                Machine-readable error code for programmatic handling.
                See docs/ERROR_CODES.md for the complete registry.
          description: Error details container with machine-readable code
        details:
          type: array
          nullable: true
          description: Optional field-level validation details (present for 400/422 validation errors)
          items:
            type: object
            properties:
              path:
                type: string
                example: email
                description: JSON path to the field that failed validation
              message:
                type: string
                example: Invalid email format
                description: Human-readable validation error message
              code:
                type: string
                example: invalid_string
                description: Zod validation error code (see Zod documentation)
      example:
        success: false
        message: Validation failed - email must be a valid email address
        data: null
        error:
          code: VALIDATION_ERROR
        details:
          - path: email
            message: Invalid email format
            code: invalid_string
    CreateShipmentRequest:
      type: object
      required:
        - origin
        - destination
        - enterpriseId
        - logisticsId
      properties:
        trackingNumber:
          type: string
          description: Optional tracking number. If not provided, a unique tracking number will be auto-generated.
        origin:
          type: string
          description: The shipment origin address or location.
        destination:
          type: string
          description: The shipment destination address or location.
        enterpriseId:
          type: string
          description: The organization ID of the enterprise requesting the shipment.
        logisticsId:
          type: string
          description: The organization ID of the logistics provider handling the shipment.
        offChainMetadata:
          type: object
          description: Optional key-value store for unstructured off-chain data.
    UpdateShipmentStatusRequest:
      type: object
      required:
        - status
      properties:
        status:
          type: string
          enum:
            [
              CREATED,
              PICKUP_CONFIRMED,
              IN_TRANSIT,
              CUSTOMS_CLEARED,
              OUT_FOR_DELIVERY,
              DELIVERED,
              SETTLEMENT_INITIATED,
              SETTLEMENT_COMPLETED,
              CANCELLED,
            ]
          description: The new status of the shipment.
        milestoneData:
          type: object
          description: Optional metadata/context to attach to the generated milestone.
    UploadProofRequest:
      type: object
      required:
        - file
      properties:
        file:
          type: string
          format: binary
          description: The delivery proof image or document file (PDF, JPG, PNG).
        recipientSignatureName:
          type: string
          description: The name of the recipient who signed for the delivery.
        notes:
          type: string
          description: Optional notes regarding the delivery signature.
    UploadDocumentRequest:
      type: object
      required:
        - file
        - type
      properties:
        file:
          type: string
          format: binary
          description: Document file (PDF, JPG, PNG, WebP). Max 10MB.
        type:
          type: string
          enum:
            [
              BILL_OF_LADING,
              CUSTOMS_DECLARATION,
              INSURANCE_CERTIFICATE,
              PACKING_LIST,
              INVOICE,
              OTHER,
            ]
          description: Document classification type.
    UploadPhotoRequest:
      type: object
      required:
        - file
      properties:
        file:
          type: string
          format: binary
          description: Photo image file (JPEG, PNG, WebP, HEIC, HEIF). Max 5MB.
        caption:
          type: string
          maxLength: 500
          description: Optional photo caption.
    ShipmentDocument:
      type: object
      properties:
        url:
          type: string
          description: Storage URL of the uploaded document.
        fileName:
          type: string
          description: Original file name.
        mimeType:
          type: string
          description: MIME type of the uploaded file.
        type:
          type: string
          enum:
            [
              BILL_OF_LADING,
              CUSTOMS_DECLARATION,
              INSURANCE_CERTIFICATE,
              PACKING_LIST,
              INVOICE,
              OTHER,
            ]
          description: Document classification type.
        size:
          type: integer
          description: File size in bytes.
        uploadedAt:
          type: string
          format: date-time
    ShipmentPhoto:
      type: object
      properties:
        url:
          type: string
          description: Storage URL of the uploaded photo.
        fileName:
          type: string
          description: Original file name.
        mimeType:
          type: string
          description: MIME type of the uploaded file.
        caption:
          type: string
          description: Optional photo caption.
        size:
          type: integer
          description: File size in bytes.
        uploadedAt:
          type: string
          format: date-time
    Shipment:
      type: object
      description: >
        Shipment resource returned by GET /api/shipments/:id (and list endpoints).
        Includes frontend-contract fields from backend-integration-requirements.md §5.1.
        Fields marked x-implemented: false are expected by the frontend but not yet
        persisted on the Shipment model.
      properties:
        _id:
          type: string
          description: MongoDB ObjectId of the shipment.
        trackingNumber:
          type: string
          description: Unique tracking number for the shipment.
        origin:
          type: string
          description: Human-readable origin address or location name.
        destination:
          type: string
          description: Human-readable destination address or location name.
        enterpriseId:
          type: string
          description: Organization ID of the enterprise customer.
        logisticsId:
          type: string
          description: Organization ID of the logistics provider.
        status:
          type: string
          enum:
            [
              CREATED,
              PICKUP_CONFIRMED,
              IN_TRANSIT,
              CUSTOMS_CLEARED,
              OUT_FOR_DELIVERY,
              DELIVERED,
              SETTLEMENT_INITIATED,
              SETTLEMENT_COMPLETED,
              CANCELLED,
            ]
          description: Current lifecycle status of the shipment.
        priority:
          type: string
          enum: [URGENT, STANDARD, ECONOMY]
          description: >
            Shipment priority used for filtering and sorting on GET /api/shipments.
            Implemented on the Shipment model (default STANDARD).
          default: STANDARD
          x-implemented: true
        expectedDelivery:
          type: string
          format: date-time
          description: >
            Expected delivery timestamp. Implemented on the Shipment model and
            available for sorting via sortBy=expectedDelivery.
          x-implemented: true
        originLat:
          type: number
          format: double
          description: >
            [TODO] Frontend-expected origin latitude. Not yet persisted on the
            Shipment model — clients currently geocode `origin` as a fallback
            (see backend-integration-requirements.md §5.1).
          x-implemented: false
        originLng:
          type: number
          format: double
          description: >
            [TODO] Frontend-expected origin longitude. Not yet persisted on the
            Shipment model — clients currently geocode `origin` as a fallback
            (see backend-integration-requirements.md §5.1).
          x-implemented: false
        destinationLat:
          type: number
          format: double
          description: >
            [TODO] Frontend-expected destination latitude. Not yet persisted on
            the Shipment model — clients currently geocode `destination` as a
            fallback (see backend-integration-requirements.md §5.1).
          x-implemented: false
        destinationLng:
          type: number
          format: double
          description: >
            [TODO] Frontend-expected destination longitude. Not yet persisted on
            the Shipment model — clients currently geocode `destination` as a
            fallback (see backend-integration-requirements.md §5.1).
          x-implemented: false
        isDelayed:
          type: boolean
          description: >
            [TODO] Frontend-expected flag indicating the shipment is past its
            expected delivery. Not yet computed or persisted on the Shipment
            model (see backend-integration-requirements.md §5.1; related
            analytics work tracked in #357).
          x-implemented: false
        stellarTokenId:
          type: string
          description: >
            Stellar asset/token identifier assigned when the shipment is
            tokenized on-chain. Set by tokenizeShipment during creation.
          x-implemented: true
        stellarTxHash:
          type: string
          description: >
            Stellar transaction hash for the shipment tokenization (or related
            on-chain) operation. Used for explorer links and ledger events.
          x-implemented: true
        deliveryProof:
          type: object
          nullable: true
          description: >
            Proof-of-delivery metadata uploaded via POST /api/shipments/:id/proof.
            Null/omitted until proof has been submitted.
          x-implemented: true
          properties:
            url:
              type: string
              description: URL of the uploaded proof image or document.
            recipientSignatureName:
              type: string
              description: Name of the recipient who signed for delivery.
            notes:
              type: string
              description: Optional notes attached to the proof upload.
            uploadedAt:
              type: string
              format: date-time
              description: When the proof was uploaded.
        milestones:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              timestamp:
                type: string
                format: date-time
              description:
                type: string
        documents:
          type: array
          items:
            $ref: '#/components/schemas/ShipmentDocument'
        photos:
          type: array
          items:
            $ref: '#/components/schemas/ShipmentPhoto'
        offChainMetadata:
          type: object
          description: Optional key-value store for unstructured off-chain data.
        createdAt:
          type: string
          format: date-time
          description: Shipment creation timestamp (ISO 8601).
        updatedAt:
          type: string
          format: date-time
          description: Shipment last-update timestamp (ISO 8601).
    Organization:
      type: object
      properties:
        _id:
          type: string
        name:
          type: string
        type:
          type: string
          enum: [ENTERPRISE, LOGISTICS]
        settings:
          type: object
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    Anomaly:
      type: object
      properties:
        _id:
          type: string
        shipmentId:
          type: string
        type:
          type: string
          enum:
            [
              TEMPERATURE_EXCEEDED,
              TEMPERATURE_BELOW_MIN,
              HUMIDITY_EXCEEDED,
              HUMIDITY_BELOW_MIN,
              BATTERY_LOW,
            ]
        severity:
          type: string
          enum: [LOW, MEDIUM, HIGH]
        message:
          type: string
        timestamp:
          type: string
          format: date-time
        resolved:
          type: boolean
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ErrorCode:
      type: string
      enum:
        - VALIDATION_ERROR
        - ERR_AUTH_INVALID
        - ERR_PERMISSION_DENIED
        - ERR_NOT_FOUND
        - ERR_BAD_REQUEST
        - ERR_VALIDATION_FAILED
        - ERR_INTERNAL_SERVER_ERROR
        - ERR_SHIPMENT_NOT_FOUND
        - ERR_SHIPMENT_INVALID_TRANSITION
        - ERR_PAYMENT_NOT_FOUND
        - ERR_SETTLEMENT_NOT_FOUND
        - ERR_SETTLEMENT_ALREADY_DISPUTED
        - ERR_ORGANIZATION_NOT_FOUND
        - ERR_TEMPLATE_NOT_FOUND
        - ERR_DUPLICATE_KEY
        - ERR_AUTH_INVALID_RESET_TOKEN
        - ERR_STELLAR_CONFIG
        - ERR_STELLAR_INVALID_HASH
        - ERR_CHAIN_UNAUTHORIZED
        - ERR_CHAIN_INVALID_HASH
        - ERR_CHAIN_ALREADY_ANCHORED
        - ERR_CHAIN_ESCROW_EXISTS
        - ERR_CHAIN_ESCROW_NOT_FOUND
        - ERR_CHAIN_ESCROW_ALREADY_RELEASED
        - ERR_CHAIN_INVALID_AMOUNT
        - ERR_CHAIN_INVALID_PROOF
        - ERR_CHAIN_UNKNOWN
        - ERR_CHAIN_INVALID_EVENT
        - ERR_RATE_LIMIT_EXCEEDED
        - ERR_LEDGER_BLOCK_NOT_FOUND
        - ERR_FILE_TOO_LARGE
        - ERR_INVALID_MIME_TYPE
        - ERR_INVALID_DOCUMENT_TYPE
        - ERR_PHOTO_LIMIT_EXCEEDED
        - ERR_EVENTS_POLL_FAILED
        - ERR_AUTH_TOKEN_REVOKED
        - ERR_NOTIFICATION_NOT_FOUND
        - ERR_AUTH_2FA_INVALID_CODE
        - ERR_AUTH_2FA_NOT_SETUP
        - ERR_AUTH_2FA_ALREADY_ENABLED
        - ERR_AUTH_2FA_NOT_ENABLED
        - ERR_AUTH_2FA_INVALID_BACKUP_CODE
        - ERR_AUTH_2FA_INVALID_SECRET_FORMAT
        - ERR_AUTH_INVALID_TOKEN_IDENTIFIER
        - ERR_FILE_UPLOAD_FAILED
        - ERR_FILE_DELETE_FAILED
      description: |
        Exhaustive machine-readable error code registry. Every value of
        `ErrorCodes` in src/shared/http/errors.ts is listed below, plus the
        `VALIDATION_ERROR` literal emitted by validateRequest for 400 schema
        failures. Referenced from ErrorResponse. See docs/ERROR_CODES.md for details.
        - VALIDATION_ERROR: Schema validation failed (400)
        - ERR_AUTH_INVALID: Invalid or missing authentication token (401)
        - ERR_PERMISSION_DENIED: Insufficient role permissions (403)
        - ERR_NOT_FOUND: Generic resource not found (404)
        - ERR_BAD_REQUEST: Malformed request (400)
        - ERR_VALIDATION_FAILED: Schema validation failed (400, legacy alias of VALIDATION_ERROR)
        - ERR_INTERNAL_SERVER_ERROR: Unhandled server error (500)
        - ERR_SHIPMENT_NOT_FOUND: Specific shipment not found (404)
        - ERR_SHIPMENT_INVALID_TRANSITION: Shipment status transition not allowed (400)
        - ERR_PAYMENT_NOT_FOUND: Specific payment not found (404)
        - ERR_SETTLEMENT_NOT_FOUND: Settlement not found (404)
        - ERR_SETTLEMENT_ALREADY_DISPUTED: Settlement already disputed (409)
        - ERR_ORGANIZATION_NOT_FOUND: Organization not found (404)
        - ERR_TEMPLATE_NOT_FOUND: Shipment template not found (404)
        - ERR_DUPLICATE_KEY: Unique constraint violation (409)
        - ERR_AUTH_INVALID_RESET_TOKEN: Invalid or expired reset token (400)
        - ERR_STELLAR_CONFIG: Stellar server configuration missing (500)
        - ERR_STELLAR_INVALID_HASH: Invalid Stellar data hash (400)
        - ERR_CHAIN_UNAUTHORIZED: Contract NotAuthorized (403)
        - ERR_CHAIN_INVALID_HASH: Contract InvalidHash (422)
        - ERR_CHAIN_ALREADY_ANCHORED: Contract AlreadyAnchored (409)
        - ERR_CHAIN_ESCROW_EXISTS: Contract EscrowExists (409)
        - ERR_CHAIN_ESCROW_NOT_FOUND: Contract EscrowNotFound (404)
        - ERR_CHAIN_ESCROW_ALREADY_RELEASED: Contract EscrowAlreadyReleased (409)
        - ERR_CHAIN_INVALID_AMOUNT: Contract InvalidAmount (422)
        - ERR_CHAIN_INVALID_PROOF: Contract InvalidProof (422)
        - ERR_CHAIN_UNKNOWN: Unmapped contract error (502)
        - ERR_CHAIN_INVALID_EVENT: Indexed event failed spec validation (502)
        - ERR_RATE_LIMIT_EXCEEDED: Too many requests (429)
        - ERR_LEDGER_BLOCK_NOT_FOUND: Ledger block not found (404)
        - ERR_FILE_TOO_LARGE: Upload exceeds size cap (413)
        - ERR_INVALID_MIME_TYPE: Upload MIME type not accepted (415)
        - ERR_INVALID_DOCUMENT_TYPE: Uploaded document type not accepted (415)
        - ERR_PHOTO_LIMIT_EXCEEDED: Photo count limit reached (400)
        - ERR_EVENTS_POLL_FAILED: Redis event store unavailable (502)
        - ERR_AUTH_TOKEN_REVOKED: JWT revoked (401)
        - ERR_NOTIFICATION_NOT_FOUND: Notification not found (404)
        - ERR_AUTH_2FA_INVALID_CODE: TOTP code did not match (401)
        - ERR_AUTH_2FA_NOT_SETUP: TOTP not configured (400)
        - ERR_AUTH_2FA_ALREADY_ENABLED: TOTP already enabled (409)
        - ERR_AUTH_2FA_NOT_ENABLED: Operation requires TOTP (400)
        - ERR_AUTH_2FA_INVALID_BACKUP_CODE: Backup code did not match (401)
        - ERR_AUTH_2FA_INVALID_SECRET_FORMAT: Stored TOTP secret unreadable (500)
        - ERR_AUTH_INVALID_TOKEN_IDENTIFIER: Token jti is not a UUID v4 (400)
        - ERR_FILE_UPLOAD_FAILED: Provider rejected the upload (502)
        - ERR_FILE_DELETE_FAILED: Provider rejected the delete (502)

    ShipmentTimelineEventType:
      type: string
      description: Event kinds emitted by GET /api/shipments/{id}/timeline
      enum:
        - STATUS_CHANGE
        - TELEMETRY_ANCHORED
        - ANOMALY_DETECTED
        - PROOF_UPLOADED
    ShipmentTimelineEvent:
      type: object
      required: [type, timestamp, description, metadata]
      description: |
        Unified timeline event after aggregation. Internal cursor keys are stripped
        before the response; pagination uses `meta.nextCursor` / `meta.hasMore`.
      properties:
        type:
          $ref: '#/components/schemas/ShipmentTimelineEventType'
        timestamp:
          type: string
          format: date-time
          description: Event time in ISO-8601 UTC
        description:
          type: string
        metadata:
          type: object
          additionalProperties: true
          description: Source-specific fields (status, telemetryId, stellarTxHash, proof URL, etc.)
    PublicTrackingMilestone:
      type: object
      required: [id, label, status, timestamp, isCompleted]
      description: A single milestone in the public tracking timeline.
      properties:
        id:
          type: string
          description: Unique milestone identifier.
        label:
          type: string
          description: Human-readable milestone label (e.g., CREATED, IN_TRANSIT, DELIVERED).
        status:
          type: string
          description: Current status of this milestone.
        timestamp:
          type: string
          format: date-time
          description: When this milestone occurred (ISO 8601 UTC).
        location:
          type: string
          nullable: true
          description: Optional location associated with the milestone.
        isCompleted:
          type: boolean
          description: Whether this milestone is completed.
        isCurrent:
          type: boolean
          description: Whether this is the current active milestone.
    PublicTrackingResponse:
      type: object
      required: [trackingNumber, status, originCity, destinationCity, milestones]
      description: Public shipment tracking response for unauthenticated tracking page.
      properties:
        trackingNumber:
          type: string
          description: Unique tracking number for the shipment.
        status:
          type: string
          description: Current lifecycle status of the shipment.
        originCity:
          type: string
          description: Human-readable origin city/location name.
        destinationCity:
          type: string
          description: Human-readable destination city/location name.
        expectedDelivery:
          type: string
          format: date-time
          nullable: true
          description: Expected delivery timestamp (ISO 8601 UTC), if available.
        milestones:
          type: array
          items:
            $ref: '#/components/schemas/PublicTrackingMilestone'
          description: Chronological list of tracking milestones.
    MilestoneEvent:
      type: string
      enum:
        - CREATED
        - PICKUP_CONFIRMED
        - IN_TRANSIT
        - CUSTOMS_CLEARED
        - OUT_FOR_DELIVERY
        - DELIVERED
        - SETTLEMENT_INITIATED
        - SETTLEMENT_COMPLETED
        - PROOF_SUBMITTED
        - CANCELLED
      description: All lifecycle events that can appear on a shipment timeline.
    LedgerBlock:
      type: object
      properties:
        _id:
          type: string
          description: Ledger block ObjectId
        shipmentId:
          type: string
          description: Associated shipment ObjectId
        milestoneEvent:
          $ref: '#/components/schemas/MilestoneEvent'
          description: Canonical lifecycle event for this block.
        dataHash:
          type: string
          nullable: true
          description: >
            SHA-256 hex digest of the payload committed by the on-chain transaction.
            Allows independent verification that `transactionHash` covers the expected data.
            Present only when the block was created with an associated on-chain anchor.
        canonicalPayload:
          type: object
          additionalProperties: true
          nullable: true
          description: >
            Canonical JSON payload that was hashed into dataHash and anchored on-chain.
            Stored alongside the block for independent verification.
        transactionHash:
          type: string
          nullable: true
          description: Stellar transaction hash, if applicable
        actor:
          type: string
          description: User ObjectId who triggered the event, if applicable
        metadata:
          type: object
          description: Additional event-specific metadata
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    LedgerVerificationBundle:
      type: object
      description: >
        Off-chain / on-chain verification bundle for a ledger block, returned by
        GET /api/ledger/blocks/{id}/verification. A verifier recomputes
        sha256(canonicalPayload) and compares it with dataHash, then confirms the
        digest is committed on-chain via txHash.
      properties:
        canonicalPayload:
          type: object
          additionalProperties: true
          nullable: true
          description: >
            Exact object that was hashed into `dataHash`. Null for blocks written
            before the payload began being persisted; such blocks are unverifiable,
            not invalid.
        dataHash:
          type: string
          nullable: true
          description: >
            Lowercase hex SHA-256 digest (64 chars) of the canonical payload,
            committed on-chain by `txHash`.
        txHash:
          type: string
          nullable: true
          description: On-chain transaction hash to look up on Horizon / Soroban RPC.
        transactionHash:
          type: string
          nullable: true
          description: Alias of `txHash`.
        ledger:
          type: integer
          description: Stellar ledger sequence the transaction landed in.
    Notification:
      type: object
      description: A notification entry for a user.
      properties:
        _id:
          type: string
          description: Notification MongoDB ObjectId.
        userId:
          type: string
          description: Owner user ObjectId.
        type:
          type: string
          enum: [shipments, settlements, system]
          description: Notification category.
        icon:
          type: string
          nullable: true
        title:
          type: string
        badge:
          type: string
          nullable: true
        badgeColor:
          type: string
          nullable: true
        description:
          type: string
        timestamp:
          type: string
          format: date-time
        shipmentId:
          type: string
          nullable: true
          description: Associated shipment ObjectId, if any.
        trackingNumber:
          type: string
          nullable: true
        actionLabel:
          type: string
          nullable: true
        isRead:
          type: boolean
          description: Whether the notification has been read.
        link:
          type: string
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    NotificationPreference:
      type: object
      description: Channel preference for a notification event.
      properties:
        _id:
          type: string
          description: Preference MongoDB ObjectId.
        userId:
          type: string
          description: Owner user ObjectId.
        event:
          type: string
          enum:
            [
              shipment_created,
              status_changed,
              delivery_confirmed,
              payment_received,
              dispute_opened,
              dispute_resolved,
            ]
        channel:
          type: string
          enum: [email, sms]
        enabled:
          type: boolean
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
  securitySchemes:
    stellarSignature:
      type: apiKey
      in: header
      name: x-stellar-signature
      description: >
        Required HMAC-SHA256 hex digest of the raw request body, signed with
        STELLAR_WEBHOOK_SECRET. Requests without a valid signature receive 401.
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        JWT access token issued by `/api/auth/login`, `/api/auth/signup`, `/api/auth/register/company`, or `/api/auth/refresh`.
        Send as `Authorization: Bearer <token>`.

        **Claims (payload):**
        - `userId` (string, required) — authenticated user ObjectId
        - `role` (string, required) — one of `SUPER_ADMIN`, `ADMIN`, `MANAGER`, `VIEWER`, `CUSTOMER`
        - `organizationId` (string, optional) — user's organization ObjectId
        - `organizationType` (string, optional) — `ENTERPRISE` or `LOGISTICS`
        - `jti` (string, required) — unique token id for revocation / logout
        - `exp` / `iat` — standard JWT expiry and issued-at (7-day TTL)

        Role permissions, frontend persona mapping, and the pending Driver alignment gap are
        documented in `docs/auth-model.md`.
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key for IoT device authentication
  headers:
    X-Request-ID:
      description: All API responses include an X-Request-ID header containing a unique identifier for request tracking and debugging. Clients can provide their own X-Request-ID in the request header, which will be echoed back in the response.
      schema:
        type: string
        example: '550e8400-e29b-41d4-a716-446655440000'
  responses:
    Unauthorized:
      description: Missing or invalid authorization token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Insufficient role permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'