{
  "openapi": "3.1.0",
  "info": {
    "title": "Althemax Agent API",
    "version": "0.1.0",
    "description": "Public, unauthenticated API for AI agents to search, inspect, and check availability of products on the Althemax marketplace at https://althemax.com. Prices in GBP. Each product's response includes a `url` field pointing at the seller's storefront where checkout completes (e.g. https://shop.althemax.com/products/{handle} for Althemax)."
  },
  "servers": [
    { "url": "https://althemax.com", "description": "Marketplace (production)" }
  ],
  "paths": {
    "/api/agent/health": {
      "get": {
        "operationId": "health",
        "summary": "Health probe",
        "description": "Returns service status and a live Shopify connectivity check.",
        "responses": {
          "200": {
            "description": "Healthy",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } }
          },
          "503": {
            "description": "Unhealthy (Shopify unreachable or token mint failed)",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } }
          }
        }
      }
    },
    "/api/agent/search": {
      "get": {
        "operationId": "searchProducts",
        "summary": "Search active products",
        "parameters": [
          { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Free-text query. Empty returns most relevant active products." },
          { "name": "first", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } },
          { "name": "after", "in": "query", "schema": { "type": "string" }, "description": "GraphQL cursor returned by previous page." }
        ],
        "responses": {
          "200": {
            "description": "Search results",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResult" } } }
          },
          "502": { "description": "Upstream Shopify error" }
        }
      }
    },
    "/api/agent/product/{handle}": {
      "get": {
        "operationId": "getProduct",
        "summary": "Get a product by handle",
        "parameters": [
          { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Product",
            "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "$ref": "#/components/schemas/Product" } }, "required": ["product"] } } }
          },
          "404": { "description": "Not found" },
          "502": { "description": "Upstream Shopify error" }
        }
      }
    },
    "/api/agent/availability": {
      "get": {
        "operationId": "checkAvailability",
        "summary": "Check stock and per-variant availability for a product",
        "parameters": [
          { "name": "handle", "in": "query", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Availability snapshot",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Availability" } } }
          },
          "400": { "description": "Missing handle" },
          "404": { "description": "Not found" },
          "502": { "description": "Upstream Shopify error" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Health": {
        "type": "object",
        "properties": {
          "service": { "type": "string" },
          "shopify": {
            "type": "object",
            "properties": {
              "ok": { "type": "boolean" },
              "shopName": { "type": "string" },
              "primaryDomain": { "type": "string" },
              "currency": { "type": "string" },
              "error": { "type": "string" }
            },
            "required": ["ok"]
          },
          "timestamp": { "type": "string", "format": "date-time" }
        },
        "required": ["service", "shopify", "timestamp"]
      },
      "Money": {
        "type": "object",
        "properties": {
          "amount": { "type": "string", "description": "Decimal string, e.g. \"19.99\"" },
          "currencyCode": { "type": "string", "example": "GBP" }
        },
        "required": ["amount", "currencyCode"]
      },
      "Variant": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "title": { "type": "string" },
          "sku": { "type": "string", "nullable": true },
          "price": { "$ref": "#/components/schemas/Money" },
          "available": { "type": "boolean" },
          "inventoryQuantity": { "type": "integer", "nullable": true }
        },
        "required": ["id", "title", "price", "available"]
      },
      "Product": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "handle": { "type": "string" },
          "title": { "type": "string" },
          "description": { "type": "string" },
          "vendor": { "type": "string", "nullable": true },
          "productType": { "type": "string", "nullable": true },
          "tags": { "type": "array", "items": { "type": "string" } },
          "status": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "image": {
            "type": "object",
            "nullable": true,
            "properties": {
              "url": { "type": "string", "format": "uri" },
              "alt": { "type": "string", "nullable": true }
            }
          },
          "priceRange": {
            "type": "object",
            "properties": {
              "min": { "$ref": "#/components/schemas/Money" },
              "max": { "$ref": "#/components/schemas/Money" }
            },
            "required": ["min", "max"]
          },
          "totalInventory": { "type": "integer", "nullable": true },
          "available": { "type": "boolean" },
          "variants": { "type": "array", "items": { "$ref": "#/components/schemas/Variant" } }
        },
        "required": ["id", "handle", "title", "url", "priceRange", "available", "variants"]
      },
      "SearchResult": {
        "type": "object",
        "properties": {
          "query": { "type": "string", "nullable": true },
          "count": { "type": "integer" },
          "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } },
          "pageInfo": {
            "type": "object",
            "properties": {
              "hasNextPage": { "type": "boolean" },
              "endCursor": { "type": "string", "nullable": true }
            },
            "required": ["hasNextPage"]
          }
        },
        "required": ["count", "products", "pageInfo"]
      },
      "Availability": {
        "type": "object",
        "properties": {
          "handle": { "type": "string" },
          "available": { "type": "boolean" },
          "totalInventory": { "type": "integer", "nullable": true },
          "variants": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": { "type": "string" },
                "sku": { "type": "string", "nullable": true },
                "available": { "type": "boolean" },
                "inventoryQuantity": { "type": "integer", "nullable": true }
              },
              "required": ["id", "available"]
            }
          }
        },
        "required": ["handle", "available", "variants"]
      }
    }
  }
}