{
  "openapi": "3.0.3",
  "info": {
    "title": "PureScan AI API",
    "description": "API services for PureScan AI - food & cosmetic safety analysis, ingredient hazard scanning, app downloads, and Dodo Payments customer billing portal management.",
    "version": "1.0.0",
    "contact": {
      "name": "PureScan AI Support",
      "url": "https://scaningredients.com/support"
    }
  },
  "servers": [
    {
      "url": "https://scaningredients.com",
      "description": "Production server"
    }
  ],
  "paths": {
    "/api/health": {
      "get": {
        "summary": "Service health check",
        "description": "Returns operational status of PureScan AI API endpoints.",
        "responses": {
          "200": {
            "description": "API is operational",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "example": "ok" },
                    "timestamp": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/checkout": {
      "post": {
        "summary": "Create Dodo Payments checkout session",
        "description": "Generates a single-use hosted checkout session URL for purchasing PureScan AI Pro subscriptions.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["productId"],
                "properties": {
                  "productId": { "type": "string", "description": "Dodo Payments product ID (Monthly or Annual)" },
                  "email": { "type": "string", "format": "email", "description": "Customer email" },
                  "userId": { "type": "string", "description": "Supabase authenticated user ID" },
                  "returnUrl": { "type": "string", "format": "uri", "description": "Post-payment redirect URL" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Checkout session created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "checkout_url": { "type": "string", "format": "uri" },
                    "session_id": { "type": "string" }
                  }
                }
              }
            }
          },
          "400": { "description": "Missing productId" },
          "500": { "description": "Server error" }
        }
      }
    },
    "/api/portal": {
      "post": {
        "summary": "Create customer portal session",
        "description": "Generates a self-service Dodo Payments customer billing portal session URL for an authenticated customer.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["email"],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "description": "Customer email address"
                  },
                  "customerId": {
                    "type": "string",
                    "description": "Optional direct Dodo Payments customer ID"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Portal session URL created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": { "type": "string", "format": "uri" }
                  }
                }
              }
            }
          },
          "400": { "description": "Invalid input or missing email" },
          "404": { "description": "Customer not found" },
          "500": { "description": "Server error" }
        }
      }
    },
    "/api/webhook": {
      "post": {
        "summary": "Dodo Payments webhook handler",
        "description": "Receives and verifies cryptographically signed webhook events from Dodo Payments.",
        "responses": {
          "200": { "description": "Event processed successfully" },
          "401": { "description": "Invalid webhook signature" },
          "500": { "description": "Server error processing event" }
        }
      }
    },
    "/api/download": {
      "get": {
        "summary": "Platform-aware mobile app download redirect",
        "description": "Detects visitor user-agent and redirects iOS users to App Store and Android users to Google Play.",
        "responses": {
          "302": { "description": "Redirect to Apple App Store or Google Play Store" }
        }
      }
    }
  }
}
