{
  "openapi": "3.1.0",
  "info": {
    "title": "OpenRoadmap API",
    "version": "0.1.0",
    "description": "Public + admin HTTP API for the OpenRoadmap feedback platform. Widget never talks to the database — only these endpoints."
  },
  "servers": [
    { "url": "http://localhost:8787", "description": "Local wrangler" },
    { "url": "https://api.openroadmap.app", "description": "Production (openroadmap.app zone)" }
  ],
  "tags": [
    { "name": "Public" },
    { "name": "Admin" },
    { "name": "System" }
  ],
  "components": {
    "securitySchemes": {
      "Session": {
        "type": "apiKey",
        "in": "header",
        "name": "X-OpenRoadmap-Session"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": { "error": { "type": "string" } }
      },
      "SubmitFeedbackRequest": {
        "type": "object",
        "required": ["projectKey", "message", "visitorId"],
        "properties": {
          "projectKey": { "type": "string" },
          "message": { "type": "string" },
          "type": { "type": "string", "enum": ["feature", "bug", "general", "question"] },
          "email": { "type": "string" },
          "visitorId": { "type": "string" },
          "honeypot": { "type": "string" },
          "context": { "type": "object", "additionalProperties": { "type": "string" } },
          "identified": {
            "type": "object",
            "required": ["id"],
            "properties": {
              "id": { "type": "string" },
              "email": { "type": "string" },
              "name": { "type": "string" },
              "plan": { "type": "string" },
              "account": { "type": "string" }
            }
          }
        }
      },
      "FeatureStatus": {
        "type": "string",
        "enum": [
          "new",
          "under_review",
          "planned",
          "in_progress",
          "shipped",
          "declined",
          "duplicate",
          "archived"
        ]
      }
    }
  },
  "paths": {
    "/health": {
      "get": {
        "tags": ["System"],
        "summary": "Health check",
        "responses": { "200": { "description": "OK" } }
      }
    },
    "/v1/widget/{pk}/config": {
      "get": {
        "tags": ["Public"],
        "summary": "Widget public config",
        "parameters": [
          { "name": "pk", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Config JSON" },
          "404": { "description": "Project not found" }
        }
      }
    },
    "/v1/feedback": {
      "post": {
        "tags": ["Public"],
        "summary": "Submit feedback",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/SubmitFeedbackRequest" }
            }
          }
        },
        "responses": {
          "201": { "description": "Created" },
          "400": { "description": "Validation error" },
          "403": { "description": "Domain not allowed" },
          "404": { "description": "Invalid project key" }
        }
      }
    },
    "/v1/votes": {
      "post": {
        "tags": ["Public"],
        "summary": "Vote on a feature",
        "responses": { "200": { "description": "OK" } }
      }
    },
    "/v1/subscriptions": {
      "post": {
        "tags": ["Public"],
        "summary": "Follow a feature for status emails",
        "responses": { "200": { "description": "OK" } }
      }
    },
    "/v1/public/{orgSlug}/roadmap": {
      "get": {
        "tags": ["Public"],
        "summary": "Public roadmap buckets",
        "parameters": [
          {
            "name": "orgSlug",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": { "200": { "description": "Roadmap" }, "404": { "description": "Not found" } }
      }
    },
    "/v1/public/{orgSlug}/features": {
      "get": {
        "tags": ["Public"],
        "summary": "List public features",
        "parameters": [
          {
            "name": "orgSlug",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          },
          { "name": "q", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Features" } }
      }
    },
    "/v1/public/{orgSlug}/features/{slug}": {
      "get": {
        "tags": ["Public"],
        "summary": "Feature detail",
        "parameters": [
          {
            "name": "orgSlug",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          },
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Detail" }, "404": { "description": "Not found" } }
      }
    },
    "/v1/auth/login": {
      "post": {
        "tags": ["Admin"],
        "summary": "Demo login — returns session token",
        "responses": { "200": { "description": "Token + user/org/project" } }
      }
    },
    "/v1/me": {
      "get": {
        "tags": ["Admin"],
        "security": [{ "Session": [] }],
        "summary": "Current session",
        "responses": { "200": { "description": "Me" }, "401": { "description": "Unauthorized" } }
      }
    },
    "/v1/stats": {
      "get": {
        "tags": ["Admin"],
        "security": [{ "Session": [] }],
        "summary": "Dashboard stats",
        "responses": { "200": { "description": "Stats" } }
      }
    },
    "/v1/inbox": {
      "get": {
        "tags": ["Admin"],
        "security": [{ "Session": [] }],
        "summary": "Inbox submissions",
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["all", "feature", "bug", "question", "general"]
            }
          }
        ],
        "responses": { "200": { "description": "Items" } }
      }
    },
    "/v1/features": {
      "get": {
        "tags": ["Admin"],
        "security": [{ "Session": [] }],
        "summary": "List features",
        "responses": { "200": { "description": "Features" } }
      },
      "post": {
        "tags": ["Admin"],
        "security": [{ "Session": [] }],
        "summary": "Convert submission to feature",
        "responses": { "201": { "description": "Created" } }
      }
    },
    "/v1/features/{id}/merge": {
      "post": {
        "tags": ["Admin"],
        "security": [{ "Session": [] }],
        "summary": "Merge submission into feature",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Merged" } }
      }
    },
    "/v1/features/{id}/status": {
      "patch": {
        "tags": ["Admin"],
        "security": [{ "Session": [] }],
        "summary": "Update feature status and notify followers",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["status"],
                "properties": {
                  "status": { "$ref": "#/components/schemas/FeatureStatus" },
                  "roadmapColumn": {
                    "type": "string",
                    "enum": ["now", "next", "later"],
                    "nullable": true
                  }
                }
              }
            }
          }
        },
        "responses": { "200": { "description": "Updated" } }
      }
    },
    "/v1/features/{id}": {
      "get": {
        "tags": ["Admin"],
        "security": [{ "Session": [] }],
        "summary": "Feature detail",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Detail" } }
      }
    },
    "/v1/submissions/{id}/archive": {
      "patch": {
        "tags": ["Admin"],
        "security": [{ "Session": [] }],
        "summary": "Archive submission",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "OK" } }
      }
    },
    "/v1/widget-settings": {
      "get": {
        "tags": ["Admin"],
        "security": [{ "Session": [] }],
        "summary": "Widget settings + install snippet meta",
        "responses": { "200": { "description": "Settings" } }
      },
      "patch": {
        "tags": ["Admin"],
        "security": [{ "Session": [] }],
        "summary": "Update widget settings",
        "responses": { "200": { "description": "Updated" } }
      }
    },
    "/v1/emails/outbox": {
      "get": {
        "tags": ["Admin"],
        "security": [{ "Session": [] }],
        "summary": "Email outbox",
        "responses": { "200": { "description": "Items" } }
      }
    },
    "/v1/demo/meta": {
      "get": {
        "tags": ["Public"],
        "summary": "Demo metadata",
        "responses": { "200": { "description": "Meta" } }
      }
    }
  }
}