openapi: 3.0.3
info:
  title: Demo Commerce API for AgentCore Gateway
  version: 0.1.0
  description: |
    Sample OpenAPI target for Amazon Bedrock AgentCore Gateway.
    8 tools for the eCommerce multi-agent blog artifacts.
    Demo paths and schemas only — replace host with your OMS / catalog API.
servers:
  - url: https://commerce-api.example.internal/v1
    description: Replace with private API Gateway / ALB URL
paths:
  /products:
    get:
      operationId: searchProducts
      summary: Search catalog products
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Product search hits
  /products/{sku}:
    get:
      operationId: getProduct
      summary: Get product by SKU
      parameters:
        - name: sku
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Product detail
  /carts/{cartId}:
    get:
      operationId: getCart
      summary: Get cart contents
      parameters:
        - name: cartId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Cart
  /orders/{orderId}:
    get:
      operationId: getOrder
      summary: Get order by ID
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Order
  /orders/{orderId}/shipment:
    get:
      operationId: getShipment
      summary: Get shipment tracking for an order
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Shipment
  /orders/{orderId}/cancel:
    post:
      operationId: cancelOrder
      summary: Cancel an order (Policy-gated write)
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [reason]
              properties:
                reason:
                  type: string
      responses:
        '200':
          description: Cancel accepted
        '403':
          description: Policy denied
  /returns:
    post:
      operationId: createReturn
      summary: Create a return / refund request (Policy-gated)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [orderId, reason, refundUsd]
              properties:
                orderId:
                  type: string
                reason:
                  type: string
                refundUsd:
                  type: number
                  format: float
      responses:
        '200':
          description: Return created
        '403':
          description: Policy denied
  /inventory/{sku}:
    get:
      operationId: getInventory
      summary: Read inventory for SKU
      parameters:
        - name: sku
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Inventory row
    put:
      operationId: updateInventory
      summary: Update on-hand inventory (associate-only, Policy-gated)
      parameters:
        - name: sku
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [onHand, reason]
              properties:
                onHand:
                  type: integer
                  minimum: 0
                reason:
                  type: string
      responses:
        '200':
          description: Updated
        '403':
          description: Policy denied