{
  "openapi": "3.1.0",
  "info": {
    "title": "Revent Store API",
    "version": "1.0.0",
    "description": "Public machine-readable API for Revent Store UAE & KSA certified refurbished electronics.",
    "contact": {
      "name": "Revent Support",
      "email": "care@revent.store",
      "url": "https://uae.revent.store/pages/contact-us"
    }
  },
  "servers": [
    {
      "url": "https://uae.revent.store",
      "description": "Revent UAE Storefront Production"
    },
    {
      "url": "https://ksa.revent.store",
      "description": "Revent KSA Storefront Production"
    }
  ],
  "paths": {
    "/products.json": {
      "get": {
        "operationId": "listProducts",
        "summary": "List all products in catalog",
        "description": "Returns active certified refurbished products with pricing, image assets, and variant stock.",
        "parameters": [
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } },
          { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }
        ],
        "responses": {
          "200": {
            "description": "Product list response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/products/{handle}.json": {
      "get": {
        "operationId": "getProductByHandle",
        "summary": "Get product details by URL handle",
        "parameters": [
          { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Product details object" },
          "404": { "$ref": "#/components/responses/NotFoundError" }
        }
      }
    },
    "/collections/{handle}/products.json": {
      "get": {
        "operationId": "getCollectionProducts",
        "summary": "Get products in a collection",
        "parameters": [
          { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 30 } }
        ],
        "responses": {
          "200": { "description": "Collection product list" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "OAuth2": {
        "type": "oauth2",
        "description": "RFC 9728 OAuth 2.0 Scoped Authentication",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://uae.revent.store/oauth/token",
            "scopes": {
              "read_products": "Read catalog and product specs",
              "read_inventory": "Read real-time UAE stock availability",
              "create_cart": "Create buyer cart and line items",
              "create_checkout": "Generate buyer-approved checkout URL"
            }
          }
        }
      }
    },
    "schemas": {
      "Product": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "title": { "type": "string" },
          "handle": { "type": "string" },
          "vendor": { "type": "string" },
          "product_type": { "type": "string" },
          "variants": { "type": "array", "items": { "type": "object" } }
        }
      },
      "ErrorEnvelope": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": { "type": "string", "example": "RESOURCE_NOT_FOUND" },
              "message": { "type": "string", "example": "Product handle not found" },
              "resolution": { "type": "string", "example": "Check /sitemap.xml or search via /search" }
            }
          }
        }
      }
    },
    "responses": {
      "NotFoundError": {
        "description": "Entity not found",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }
          }
        }
      }
    }
  }
}