{
  "openapi": "3.1.0",
  "info": {
    "title": "Hermes Plant API",
    "description": "Public agent-facing endpoints for the Hermes Plant digital storefront.",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://hermesplant.com"
    }
  ],
  "paths": {
    "/api/health": {
      "get": {
        "summary": "Health check",
        "operationId": "getHealth",
        "responses": {
          "200": {
            "description": "Service is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "example": "ok" },
                    "site": { "type": "string", "format": "uri" },
                    "name": { "type": "string" }
                  },
                  "required": ["status", "site", "name"]
                }
              }
            }
          }
        }
      }
    },
    "/api/catalog": {
      "get": {
        "summary": "List products",
        "operationId": "listProducts",
        "responses": {
          "200": {
            "description": "Product catalog",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "products": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/ProductSummary" }
                    }
                  },
                  "required": ["products"]
                }
              }
            }
          }
        }
      }
    },
    "/api/checkout": {
      "get": {
        "summary": "Checkout policy URLs",
        "operationId": "getCheckoutInfo",
        "responses": {
          "200": {
            "description": "Legal policy URLs and usage hint",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "policies": { "$ref": "#/components/schemas/LegalUrls" },
                    "message": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Start Stripe checkout",
        "operationId": "createCheckoutSession",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "slug": {
                    "type": "string",
                    "description": "Product slug from the catalog"
                  }
                },
                "required": ["slug"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Stripe Checkout session URL",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": { "type": "string", "format": "uri" }
                  },
                  "required": ["url"]
                }
              }
            }
          },
          "400": { "description": "Missing or invalid product slug" },
          "404": { "description": "Product not found" },
          "503": { "description": "Stripe not configured" }
        }
      }
    },
    "/api/billing-portal": {
      "post": {
        "summary": "Open Stripe billing portal",
        "operationId": "createBillingPortalSession",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "description": "Email with an active subscription"
                  }
                },
                "required": ["email"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Stripe billing portal URL",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": { "type": "string", "format": "uri" }
                  },
                  "required": ["url"]
                }
              }
            }
          },
          "400": { "description": "Email required" },
          "404": { "description": "No active subscription" },
          "503": { "description": "Stripe not configured" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ProductSummary": {
        "type": "object",
        "properties": {
          "slug": { "type": "string" },
          "name": { "type": "string" },
          "description": { "type": "string" },
          "priceCents": { "type": "integer" },
          "currency": { "type": "string" },
          "mode": { "type": "string", "enum": ["payment", "subscription"] },
          "interval": { "type": ["string", "null"] },
          "deliveryType": { "type": "string" },
          "url": { "type": "string" }
        },
        "required": ["slug", "name", "description", "priceCents", "currency", "mode", "deliveryType", "url"]
      },
      "LegalUrls": {
        "type": "object",
        "properties": {
          "terms": { "type": "string", "format": "uri" },
          "privacy": { "type": "string", "format": "uri" },
          "refunds": { "type": "string", "format": "uri" },
          "cancellation": { "type": "string", "format": "uri" },
          "contact": { "type": "string", "format": "uri" }
        }
      }
    }
  }
}