{
  "openapi": "3.1.0",
  "info": {
    "title": "Mehak Home Agent-Native API",
    "version": "1.0.0",
    "description": "Read-only catalog API for AI agents to browse Mehak Home products, categories, brands, and run searches. Write operations (cart, checkout) require an authenticated session and are intentionally excluded from the public agent surface."
  },
  "servers": [
    {
      "url": "https://mehakhome.com",
      "description": "Production"
    }
  ],
  "paths": {
    "/api/products": {
      "get": {
        "summary": "List products",
        "operationId": "listProducts",
        "parameters": [
          { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } },
          { "name": "brand", "in": "query", "schema": { "type": "string" }, "description": "Brand slug" },
          { "name": "category", "in": "query", "schema": { "type": "string" }, "description": "Category slug; includes subcategories" },
          { "name": "min_price", "in": "query", "schema": { "type": "integer" } },
          { "name": "max_price", "in": "query", "schema": { "type": "integer" } },
          { "name": "condition", "in": "query", "schema": { "type": "string", "enum": ["new", "refurbished", "open_box", "used"] } }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of products",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ProductListResponse" }
              }
            }
          }
        }
      }
    },
    "/api/products/{slug}": {
      "get": {
        "summary": "Get a product by slug",
        "operationId": "getProduct",
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Product detail with images, reviews, related items",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ProductDetailResponse" }
              }
            }
          },
          "404": { "description": "Product not found" }
        }
      }
    },
    "/api/categories": {
      "get": {
        "summary": "List all active categories",
        "operationId": "listCategories",
        "responses": {
          "200": {
            "description": "Flat list of categories",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CategoryListResponse" }
              }
            }
          }
        }
      }
    },
    "/api/brands": {
      "get": {
        "summary": "List all brands",
        "operationId": "listBrands",
        "responses": {
          "200": {
            "description": "Flat list of brands",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/BrandListResponse" }
              }
            }
          }
        }
      }
    },
    "/api/search": {
      "get": {
        "summary": "Full-text product search",
        "operationId": "searchProducts",
        "parameters": [
          { "name": "q", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }
        ],
        "responses": {
          "200": {
            "description": "Paginated search results",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ProductListResponse" }
              }
            }
          },
          "400": { "description": "Missing query parameter" }
        }
      }
    },
    "/api/mcp": {
      "get": {
        "summary": "MCP server discovery",
        "operationId": "mcpDiscovery",
        "responses": {
          "200": {
            "description": "Server capabilities",
            "content": { "application/json": {} }
          }
        }
      },
      "post": {
        "summary": "MCP JSON-RPC-style tool invocation",
        "operationId": "mcpInvoke",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["method"],
                "properties": {
                  "method": { "type": "string", "enum": ["tools/list", "tools/call"] },
                  "params": {
                    "type": "object",
                    "properties": {
                      "name": { "type": "string" },
                      "arguments": { "type": "object" }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": { "200": { "description": "MCP response" } }
      }
    },
    "/api/acp": {
      "get": {
        "summary": "ACP capability discovery",
        "operationId": "acpDiscovery",
        "responses": { "200": { "description": "ACP capability list" } }
      }
    },
    "/api/x402": {
      "get": {
        "summary": "x402 v2 probe (HTTP transport)",
        "operationId": "x402Probe",
        "description": "Returns 402 with PAYMENT-REQUIRED header (base64 PaymentRequired) when X402_WALLET_ADDRESS and X402_FACILITATOR_URL are set. Clients retry with PAYMENT-SIGNATURE (base64 PaymentPayload).",
        "responses": {
          "200": { "description": "Payment signal accepted (verify via facilitator in production)" },
          "402": {
            "description": "Payment required",
            "headers": {
              "PAYMENT-REQUIRED": {
                "description": "Base64-encoded x402 v2 PaymentRequired JSON",
                "schema": { "type": "string" }
              }
            }
          },
          "503": { "description": "x402 env not configured" }
        }
      }
    },
    "/api/protected/{path}": {
      "get": {
        "summary": "Example x402-gated API (middleware)",
        "operationId": "x402ProtectedExample",
        "description": "Same PAYMENT-REQUIRED / PAYMENT-SIGNATURE flow as /api/x402 when env is configured.",
        "parameters": [
          {
            "name": "path",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": { "description": "OK after payment signal" },
          "402": { "description": "Payment required" },
          "503": { "description": "Not configured" }
        }
      }
    },
    "/api/checkout": {
      "post": {
        "summary": "Create checkout session",
        "operationId": "createCheckoutSession",
        "x-payment-info": {
          "intent": "session",
          "method": "stripe",
          "amount": "0.00",
          "currency": "RON"
        },
        "responses": {
          "200": { "description": "Checkout created" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Money": {
        "type": "integer",
        "description": "Price in RON (integer, no fractional unit)."
      },
      "Product": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string" },
          "slug": { "type": "string" },
          "sku": { "type": "string" },
          "description": { "type": "string", "nullable": true },
          "price_pkr": { "$ref": "#/components/schemas/Money" },
          "compare_at_price_pkr": { "type": "integer", "nullable": true },
          "stock_qty": { "type": "integer" },
          "condition": { "type": "string", "enum": ["new", "refurbished", "open_box", "used"] },
          "warranty_months": { "type": "integer" },
          "is_active": { "type": "integer" },
          "is_featured": { "type": "integer" },
          "brand_id": { "type": "integer", "nullable": true },
          "category_id": { "type": "integer" },
          "created_at": { "type": "string", "format": "date-time" },
          "primary_image_url": { "type": "string", "nullable": true },
          "brand_name": { "type": "string", "nullable": true }
        },
        "required": ["id", "name", "slug", "sku", "price_pkr", "stock_qty", "condition", "category_id"]
      },
      "ProductImage": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "product_id": { "type": "integer" },
          "url": { "type": "string" },
          "alt_text": { "type": "string", "nullable": true },
          "sort_order": { "type": "integer" },
          "is_primary": { "type": "integer" }
        }
      },
      "Category": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string" },
          "slug": { "type": "string" },
          "parent_id": { "type": "integer", "nullable": true },
          "hero_image_url": { "type": "string", "nullable": true },
          "is_active": { "type": "integer" }
        }
      },
      "Brand": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string" },
          "slug": { "type": "string" },
          "logo_url": { "type": "string", "nullable": true }
        }
      },
      "PaginationMeta": {
        "type": "object",
        "properties": {
          "page": { "type": "integer" },
          "limit": { "type": "integer" },
          "total": { "type": "integer" },
          "total_pages": { "type": "integer" }
        }
      },
      "ProductListResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Product" }
          },
          "meta": { "$ref": "#/components/schemas/PaginationMeta" }
        }
      },
      "ProductDetailResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "product": { "$ref": "#/components/schemas/Product" },
              "images": {
                "type": "array",
                "items": { "$ref": "#/components/schemas/ProductImage" }
              },
              "reviews": { "type": "array", "items": { "type": "object" } },
              "avg_rating": { "type": "number", "nullable": true },
              "review_count": { "type": "integer" },
              "related": {
                "type": "array",
                "items": { "$ref": "#/components/schemas/Product" }
              }
            }
          }
        }
      },
      "CategoryListResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Category" }
          }
        }
      },
      "BrandListResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Brand" }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": { "type": "string" },
              "message": { "type": "string" }
            }
          }
        }
      }
    }
  }
}