Vizion Shipment Visibility Workflow

naftiko: "1.0.0-alpha1"

info:
  label: "Vizion Shipment Visibility Workflow"
  description: >-
    Workflow capability for supply chain and logistics teams needing end-to-end
    container shipment visibility. Combines the Vizion Container Tracking API
    to manage subscriptions, monitor milestone events, and surface estimated
    and actual arrival/departure times. Supports both real-time webhook and
    polling-based integration patterns.
  tags:
    - Vizion
    - Container Tracking
    - Logistics
    - Ocean Freight
    - Shipping
    - Supply Chain
    - Webhooks
  created: "2026-05-03"
  modified: "2026-05-03"

binds:
  - namespace: env
    keys:
      VIZION_API_KEY: VIZION_API_KEY

capability:
  consumes:
    - import: vizion
      location: ./shared/container-tracking.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: vizion-shipment-api
      description: "Unified REST API for container shipment visibility workflows."
      resources:
        - path: /v1/references
          name: references
          description: "Container tracking subscriptions."
          operations:
            - method: GET
              name: list-references
              description: "List all active container tracking references."
              call: "vizion.list-references"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: create-reference
              description: "Subscribe to tracking for a container."
              call: "vizion.create-reference"
              with:
                container_id: "rest.container_id"
                carrier_code: "rest.carrier_code"
                callback_url: "rest.callback_url"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/references/{reference_id}
          name: reference-detail
          description: "Individual container reference details."
          operations:
            - method: GET
              name: get-reference
              description: "Get reference status and metadata."
              call: "vizion.get-reference"
              with:
                reference_id: "rest.reference_id"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: DELETE
              name: delete-reference
              description: "Cancel tracking and remove reference."
              call: "vizion.delete-reference"
              with:
                reference_id: "rest.reference_id"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/references/{reference_id}/updates
          name: tracking-events
          description: "Container tracking milestone events."
          operations:
            - method: GET
              name: list-tracking-events
              description: "Retrieve all tracking events for a container."
              call: "vizion.list-reference-updates"
              with:
                reference_id: "rest.reference_id"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9090
      namespace: vizion-shipment-mcp
      transport: http
      description: "MCP server for AI-assisted container shipment visibility and logistics workflows."
      tools:
        - name: list-container-subscriptions
          description: "List all active container tracking subscriptions in the account."
          hints:
            readOnly: true
            idempotent: true
          call: "vizion.list-references"
          outputParameters:
            - type: object
              mapping: "$."

        - name: track-container
          description: "Subscribe to real-time tracking for a container. Provide the container ID and carrier SCAC code (e.g. MSCU for MSC, MAEU for Maersk). Optionally supply a webhook URL for push updates."
          hints:
            readOnly: false
            idempotent: false
          call: "vizion.create-reference"
          with:
            container_id: "tools.container_id"
            carrier_code: "tools.carrier_code"
            callback_url: "tools.callback_url"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-container-status
          description: "Get the current tracking status for a specific container reference, including whether it is actively receiving updates."
          hints:
            readOnly: true
            idempotent: true
          call: "vizion.get-reference"
          with:
            reference_id: "tools.reference_id"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-shipment-milestones
          description: "Retrieve all tracking milestone events for a container: loading, departure, transshipment, arrival, customs clearance, and delivery events."
          hints:
            readOnly: true
            idempotent: true
          call: "vizion.list-reference-updates"
          with:
            reference_id: "tools.reference_id"
          outputParameters:
            - type: object
              mapping: "$."

        - name: cancel-container-tracking
          description: "Cancel tracking for a container and remove the reference. No further updates will be sent."
          hints:
            readOnly: false
            destructive: true
            idempotent: true
          call: "vizion.delete-reference"
          with:
            reference_id: "tools.reference_id"
          outputParameters:
            - type: object
              mapping: "$."