Magioc Portion Brewery API

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Magical Potion Brewery API
  description: An API for conjuring magical potions, managing orders, and discovering daily specials.

x-sfdc:
  agent:
    topic:
      name: Magical Potion Brewery
      classificationDescription: This topic is designed for managing the mystical art of potion brewing, from ordering ingredients to delivering enchanting concoctions.
      scope: Your role is to facilitate the magical production and delivery of potions. You can brew new potions, check their brewing status, and discover daily specials.
      instructions:
        - To conjure a new potion, use the `brewPotion` action with the potion name, desired quantity, and a list of magical ingredients.
        - To check on a potion order, use the `checkDeliveryStatus` action with the unique order ID.
        - To discover today's special enchanting brew, use the `getDailySpecial` action.

components:
  securitySchemes:
    MagicKeyAuth:
      type: apiKey
      in: header
      name: X-Magic-Key
      description: API Key for authenticating magical requests.
    EnchantmentAuth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://magic-auth.example.com/oauth/authorize
          scopes:
            brew: Allows brewing potions
            view_specials: Allows viewing daily specials

security:
  - MagicKeyAuth: []
  - EnchantmentAuth:
      - brew
      - view_specials

paths:
  /potions/brew:
    post:
      summary: Conjure a New Potion
      description: Initiate the magical brewing process for a new potion.
      operationId: brewPotion
      x-sfdc:
        agent:
          action:
            publishAsAgentAction: true # Enable as an AI asset action
      requestBody:
        required: true
        description: Details for brewing a new magical potion, including its name, quantity, and mystical ingredients.
        content:
          application/json:
            schema:
              additionalProperties: false # Strict validation for AI
              type: object
              x-sfdc:
                agent:
                  action:
                    isUserInput: true # Inputs are from the user via AI
              properties:
                potionName:
                  type: string
                  description: The enchanting name of the potion to brew (e.g., 'Elixir of Euphoria').
                quantity:
                  type: integer
                  description: The number of potion vials to conjure.
                  minimum: 1
                ingredients:
                  type: array
                  items:
                    type: string
                  description: A list of mystical ingredients required (e.g., ['Dragon\'s Breath', 'Fairy Dust']).
                  minItems: 1
              required:
                - potionName
                - quantity
                - ingredients
      responses:
        '200':
          description: Potion brewing initiated successfully.
          content:
            application/json:
              schema:
                additionalProperties: false
                type: object
                x-sfdc:
                  agent:
                    action:
                      isDisplayable: true # Display this response to the user
                properties:
                  orderId:
                    type: string
                    description: Unique identifier for the potion brewing order.
                  status:
                    type: string
                    description: Current status of the brewing process (e.g., 'Initiated', 'In Progress').

  /potions/daily-special:
    get:
      summary: Get Today's Special Potion
      operationId: getDailySpecial
      description: Fetches the details of the magical potion special for the current day.
      x-sfdc:
        agent:
          action:
            publishAsAgentAction: true # Enable as an AI asset action
      responses:
        '200':
          description: Details of today's special potion.
          content:
            application/json:
              schema:
                additionalProperties: false
                x-sfdc:
                  agent:
                    action:
                      isDisplayable: true # Display this response to the user
                type: object
                properties:
                  specialName:
                    type: string
                    description: The name of today's special potion.
                  effect:
                    type: string
                    description: The magical effect of the potion.
                  price:
                    type: number
                    format: float
                    description: The cost in enchanted coins.
                  availability:
                    type: string
                    enum:
                      - In Stock
                      - Limited Supply
                      - Sold Out
                    description: Current stock status.
                  imageUrl:
                    type: string
                    format: url
                    description: URL to an image of the special potion.

  /potions/orders/{orderId}/status:
    get:
      summary: Check Potion Delivery Status
      operationId: checkDeliveryStatus
      description: Checks the current delivery status of a specific potion order.
      x-sfdc:
        agent:
          action:
            publishAsAgentAction: true # Enable as an AI asset action
      parameters:
        - name: orderId
          in: path
          required: true
          x-sfdc:
            agent:
              action:
                isUserInput: true # This parameter comes from user input via AI
          schema:
            type: string
          description: The unique identifier of the potion order.
      responses:
        '200':
          description: Current delivery status of the potion order.
          content:
            application/json:
              schema:
                additionalProperties: false
                x-sfdc:
                  agent:
                    action:
                      isDisplayable: true # Display this response to the user
                type: object
                properties:
                  orderId:
                    type: string
                    description: The ID of the order being checked.
                  deliveryStatus:
                    type: string
                    enum:
                      - Preparing
                      - In Transit
                      - Delivered
                      - Delayed
                    description: The current status of the potion delivery.
                  estimatedDelivery:
                    type: string
                    format: date-time
                    description: Estimated time of magical delivery.