{
  "openapi": "3.1.0",
  "info": {
    "title": "Eco-Theory Store API",
    "description": "Public and customer REST API for the Eco-Theory artisanal soap and sustainable cosmetics storefront.",
    "version": "1.0.0",
    "contact": {
      "name": "Eco-Theory Support",
      "email": "andrewlawler@eco-theory.com",
      "url": "https://eco-theory.com/contact"
    }
  },
  "x-service-info": {
    "categories": [
      "e-commerce",
      "skincare",
      "retail",
      "personal-care"
    ],
    "description": "Eco-Theory Store handcrafted artisanal soaps and organic skincare products."
  },
  "servers": [
    {
      "url": "https://eco-theory.com/api",
      "description": "Production Server"
    }
  ],
  "paths": {
    "/maintenance": {
      "get": {
        "summary": "Check Maintenance Mode Status",
        "description": "Returns current site maintenance state and availability status.",
        "responses": {
          "200": {
            "description": "Status retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "maintenance": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/shop/products": {
      "get": {
        "summary": "List All Products",
        "description": "Retrieves the full catalog of artisanal soaps and cosmetics.",
        "responses": {
          "200": {
            "description": "Array of products",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Product"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/shop/featured": {
      "get": {
        "summary": "List Featured Products",
        "description": "Retrieves curated featured products for storefront display.",
        "responses": {
          "200": {
            "description": "Array of featured products",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Product"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/shop/new-arrivals": {
      "get": {
        "summary": "List New Arrivals",
        "description": "Retrieves the newest batch arrivals and freshly formulated soaps.",
        "responses": {
          "200": {
            "description": "Array of new arrival products",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Product"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/shop/product/{id}": {
      "get": {
        "summary": "Get Product Details",
        "description": "Retrieves detailed product specifications, ingredients, pricing, and imagery.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "description": "Product ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Product details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Product"
                }
              }
            }
          },
          "404": {
            "description": "Product not found"
          }
        }
      }
    },
    "/shop/product/{id}/reviews": {
      "get": {
        "summary": "Get Product Reviews",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of reviews",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Review"
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Submit Product Review",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReviewSubmission"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Review submitted successfully"
          }
        }
      }
    },
    "/shop/checkout": {
      "post": {
        "summary": "Process Store Checkout Order",
        "description": "Submits cart items for purchase and processes order payment via Stripe.",
        "x-payment-info": {
          "intent": "charge",
          "method": "stripe",
          "amount": "10.00",
          "currency": "USD",
          "description": "Eco-Theory Store checkout order payment"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CheckoutRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Checkout successful",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CheckoutResponse"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required"
          }
        }
      }
    },
    "/checkout": {
      "post": {
        "summary": "Direct Card Checkout",
        "description": "Initiate automated payment card charge for customer order.",
        "x-payment-info": {
          "intent": "charge",
          "method": "card",
          "amount": "10.00",
          "currency": "USD",
          "description": "Credit card payment for store checkout"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CheckoutRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Order paid successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CheckoutResponse"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required"
          }
        }
      }
    },
    "/shop/order": {
      "post": {
        "summary": "Create Checkout Payment Session",
        "description": "Creates an order session for deferred or hosted checkout settlement.",
        "x-payment-info": {
          "intent": "session",
          "method": "stripe",
          "amount": "10.00",
          "currency": "USD",
          "description": "Hosted checkout payment session"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CheckoutRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Session created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "session_id": { "type": "string" },
                    "session_url": { "type": "string" }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Payment Required"
          }
        }
      }
    },
    "/api/pay": {
      "post": {
        "summary": "Machine Micropayment Charge",
        "description": "Pay-per-call machine payment charge via Tempo protocol.",
        "x-payment-info": {
          "intent": "charge",
          "method": "tempo",
          "amount": "0.01",
          "currency": "USD",
          "description": "Machine agent micropayment settlement"
        },
        "responses": {
          "200": {
            "description": "Micropayment accepted"
          },
          "402": {
            "description": "Payment Required"
          }
        }
      }
    },
    "/api/tip": {
      "post": {
        "summary": "Artisan Tip / Support Donation",
        "description": "Send an artisan tip or support contribution via Stripe.",
        "x-payment-info": {
          "intent": "charge",
          "method": "stripe",
          "amount": "5.00",
          "currency": "USD",
          "description": "Artisan tip contribution via Stripe"
        },
        "responses": {
          "200": {
            "description": "Tip accepted successfully"
          },
          "402": {
            "description": "Payment Required"
          }
        }
      }
    },
    "/contact": {
      "post": {
        "summary": "Submit Contact Form",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name", "email", "message"],
                "properties": {
                  "name": { "type": "string" },
                  "email": { "type": "string", "format": "email" },
                  "subject": { "type": "string" },
                  "message": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Message received"
          }
        }
      }
    },
    "/config": {
      "get": {
        "summary": "Public Configuration",
        "responses": {
          "200": {
            "description": "Public client parameters"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Product": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string" },
          "description": { "type": "string" },
          "price": { "type": "number" },
          "stock_quantity": { "type": "integer" },
          "image_url": { "type": "string" },
          "on_sale": { "type": "boolean" },
          "sale_price": { "type": "number" },
          "category": { "type": "string" },
          "ingredients": { "type": "string" }
        }
      },
      "Review": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "author_name": { "type": "string" },
          "rating": { "type": "integer", "minimum": 1, "maximum": 5 },
          "title": { "type": "string" },
          "comment": { "type": "string" },
          "verified_purchase": { "type": "boolean" },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "ReviewSubmission": {
        "type": "object",
        "required": ["rating", "comment"],
        "properties": {
          "author_name": { "type": "string" },
          "rating": { "type": "integer", "minimum": 1, "maximum": 5 },
          "title": { "type": "string" },
          "comment": { "type": "string" }
        }
      },
      "CheckoutRequest": {
        "type": "object",
        "required": ["items", "customer_email"],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["product_id", "quantity"],
              "properties": {
                "product_id": { "type": "integer" },
                "quantity": { "type": "integer", "minimum": 1 }
              }
            }
          },
          "customer_email": { "type": "string", "format": "email" },
          "shipping_address": {
            "type": "object",
            "properties": {
              "line1": { "type": "string" },
              "city": { "type": "string" },
              "state": { "type": "string" },
              "postal_code": { "type": "string" },
              "country": { "type": "string" }
            }
          }
        }
      },
      "CheckoutResponse": {
        "type": "object",
        "properties": {
          "order_id": { "type": "string" },
          "status": { "type": "string" },
          "total_amount": { "type": "number" },
          "currency": { "type": "string" },
          "receipt_url": { "type": "string" }
        }
      }
    }
  }
}