paths:
  /packets:
    post:
      summary: Generate packet
      description: Generate a non-scheme integration packet (PDF + sidecars)
      operationId: generatePacket
      tags:
        - Packets
      security:
        - oauth2:
            - packets:write
      x-idempotency: true
      parameters:
        - $ref: '../components/parameters.yaml#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/components/schemas/GeneratePacketRequest'
      responses:
        '201':
          description: Packet generated
          content:
            application/json:
              schema:
                $ref: '../components/schemas.yaml#/components/schemas/Packet'
    
    get:
      summary: List packets
      description: List packets with optional filtering
      operationId: listPackets
      tags:
        - Packets
      security:
        - oauth2:
            - packets:read
      parameters:
        - name: triggerId
          in: query
          schema:
            type: string
            pattern: '^[a-fA-F0-9]{64}$'
          description: Filter by trigger ID
        - name: instructionId
          in: query
          schema:
            type: string
            pattern: '^[a-fA-F0-9]{64}$'
          description: Filter by instruction ID
        - name: status
          in: query
          schema:
            type: string
            enum: ["GENERATED", "DISPATCHED", "DELIVERED", "ACKNOWLEDGED", "FAILED"]
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: offset
          in: query
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        '200':
          description: List of packets
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '../components/schemas.yaml#/components/schemas/Packet'
                  total:
                    type: integer
                  limit:
                    type: integer
                  offset:
                    type: integer

  /packets/{packetId}:
    get:
      summary: Get packet
      description: Get packet metadata and hashes
      operationId: getPacket
      tags:
        - Packets
      security:
        - oauth2:
            - packets:read
      parameters:
        - $ref: '../components/parameters.yaml#/components/parameters/PacketId'
      responses:
        '200':
          description: Packet metadata
          content:
            application/json:
              schema:
                $ref: '../components/schemas.yaml#/components/schemas/Packet'
        '404':
          $ref: '../openapi.yaml#/components/responses/NotFound'

  /packets/{packetId}/download:
    get:
      summary: Download packet
      description: Download packet file (PDF, etc.) - auth controlled
      operationId: downloadPacket
      tags:
        - Packets
      security:
        - oauth2:
            - packets:read
      parameters:
        - $ref: '../components/parameters.yaml#/components/parameters/PacketId'
      responses:
        '200':
          description: Packet file
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '404':
          $ref: '../openapi.yaml#/components/responses/NotFound'

  /packets/{packetId}/dispatch:
    post:
      summary: Dispatch packet
      description: Dispatch packet via email/AS4/portal
      operationId: dispatchPacket
      tags:
        - Packets
      security:
        - oauth2:
            - packets:write
      x-idempotency: true
      parameters:
        - $ref: '../components/parameters.yaml#/components/parameters/PacketId'
        - $ref: '../components/parameters.yaml#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - channel
              properties:
                channel:
                  type: string
                  enum: ["EMAIL", "AS4", "PORTAL"]
                recipient:
                  type: string
                  description: Recipient address/identifier
      responses:
        '200':
          description: Packet dispatched
          content:
            application/json:
              schema:
                $ref: '../components/schemas.yaml#/components/schemas/Packet'

  /packets/{packetId}/ack:
    post:
      summary: Record packet acknowledgement
      description: Record an acknowledgement/receipt for a packet
      operationId: acknowledgePacket
      tags:
        - Packets
      security:
        - oauth2:
            - packets:write
      x-idempotency: true
      parameters:
        - $ref: '../components/parameters.yaml#/components/parameters/PacketId'
        - $ref: '../components/parameters.yaml#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - status
              properties:
                status:
                  type: string
                  enum: ["RECEIVED", "ACCEPTED", "REJECTED"]
                ackId:
                  type: string
                  description: Acknowledgement identifier
      responses:
        '200':
          description: Acknowledgement recorded
          content:
            application/json:
              schema:
                $ref: '../components/schemas.yaml#/components/schemas/Packet'