{
  "openapi": "3.1.0",
  "info": {
    "title": "Soma BPMN Studio API",
    "version": "1.0.0",
    "description": "API para generar y gestionar diagramas BPMN. Autenticación vía Authorization: Bearer <token>. El token puede ser Firebase idToken (JWT) o una API key con prefijo soma_."
  },
  "servers": [
    { "url": "https://bpm.soma.consulting", "description": "Production" }
  ],
  "tags": [
    { "name": "Health", "description": "Comprobación del servicio" },
    { "name": "Settings", "description": "API key del usuario" },
    { "name": "Diagrams", "description": "CRUD de diagramas BPMN" },
    { "name": "Projects", "description": "Proyectos (biblioteca)" },
    { "name": "AI", "description": "Generación, análisis y transcripción" }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Authorization: Bearer <token>. Acepta Firebase idToken (JWT) o API key (soma_...)."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": { "type": "string" },
          "suggestion": { "type": "string" }
        }
      },
      "Diagram": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "bpmnXml": { "type": "string" },
          "transcript": { "type": "string" },
          "processDescription": { "type": "string" },
          "recommendations": { "type": "array", "items": { "type": "string" } },
          "projectId": { "type": ["string", "null"] },
          "tags": { "type": "array", "items": { "type": "string" } },
          "createdAt": { "type": "string", "format": "date-time" },
          "updatedAt": { "type": "string", "format": "date-time" }
        }
      },
      "Project": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "createdAt": { "type": "string", "format": "date-time" },
          "updatedAt": { "type": "string", "format": "date-time" }
        }
      },
      "Version": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "label": { "type": "string" },
          "bpmnXml": { "type": "string" },
          "createdAt": { "type": "string", "format": "date-time" }
        }
      }
    }
  },
  "security": [{ "bearerAuth": [] }],
  "paths": {
    "/api/health": {
      "get": {
        "tags": ["Health"],
        "summary": "Health check",
        "operationId": "healthCheck",
        "security": [],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } }
              }
            }
          }
        }
      }
    },

    "/api/settings/api-key": {
      "get": {
        "tags": ["Settings"],
        "summary": "Estado de la API key",
        "operationId": "getApiKeyStatus",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": { "type": "object", "properties": { "hasKey": { "type": "boolean" } } }
              }
            }
          }
        }
      }
    },

    "/api/settings/api-key/generate": {
      "post": {
        "tags": ["Settings"],
        "summary": "Generar API key",
        "operationId": "generateApiKey",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": { "type": "object", "properties": { "apiKey": { "type": "string" } } }
              }
            }
          }
        }
      }
    },

    "/api/settings/api-key/revoke": {
      "post": {
        "tags": ["Settings"],
        "summary": "Revocar API key",
        "operationId": "revokeApiKey",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } }
              }
            }
          }
        }
      }
    },

    "/api/diagrams": {
      "get": {
        "tags": ["Diagrams"],
        "summary": "Listar diagramas",
        "operationId": "listDiagrams",
        "parameters": [
          { "name": "projectId", "in": "query", "schema": { "type": "string" }, "description": "Filtrar por proyecto" },
          { "name": "tag", "in": "query", "schema": { "type": "string" }, "description": "Filtrar por etiqueta" }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "diagrams": { "type": "array", "items": { "$ref": "#/components/schemas/Diagram" } }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": ["Diagrams"],
        "summary": "Crear diagrama",
        "operationId": "createDiagram",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["bpmnXml"],
                "properties": {
                  "name": { "type": "string" },
                  "bpmnXml": { "type": "string" },
                  "transcript": { "type": "string" },
                  "processDescription": { "type": "string" },
                  "recommendations": { "type": "array", "items": { "type": "string" } },
                  "projectId": { "type": ["string", "null"] },
                  "tags": { "type": "array", "items": { "type": "string" } }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": { "type": "object", "properties": { "diagram": { "$ref": "#/components/schemas/Diagram" } } }
              }
            }
          },
          "400": {
            "description": "bpmnXml requerido",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          },
          "403": {
            "description": "Límite free alcanzado",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      }
    },

    "/api/diagrams/{id}": {
      "get": {
        "tags": ["Diagrams"],
        "summary": "Obtener diagrama",
        "operationId": "getDiagram",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": { "type": "object", "properties": { "diagram": { "$ref": "#/components/schemas/Diagram" } } }
              }
            }
          },
          "404": {
            "description": "Diagrama no encontrado",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      },
      "put": {
        "tags": ["Diagrams"],
        "summary": "Actualizar diagrama",
        "operationId": "updateDiagram",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": { "type": "string" },
                  "bpmnXml": { "type": "string" },
                  "transcript": { "type": "string" },
                  "processDescription": { "type": "string" },
                  "recommendations": { "type": "array", "items": { "type": "string" } },
                  "projectId": { "type": ["string", "null"] },
                  "tags": { "type": "array", "items": { "type": "string" } }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": { "application/json": { "schema": { "type": "object", "properties": { "diagram": { "$ref": "#/components/schemas/Diagram" } } } } }
          },
          "404": {
            "description": "Diagrama no encontrado",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      },
      "delete": {
        "tags": ["Diagrams"],
        "summary": "Eliminar diagrama",
        "operationId": "deleteDiagram",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": {
            "description": "OK",
            "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } }
          },
          "404": {
            "description": "Diagrama no encontrado",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      }
    },

    "/api/projects": {
      "get": {
        "tags": ["Projects"],
        "summary": "Listar proyectos",
        "operationId": "listProjects",
        "responses": {
          "200": {
            "description": "OK",
            "content": { "application/json": { "schema": { "type": "object", "properties": { "projects": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } } } } } }
          }
        }
      },
      "post": {
        "tags": ["Projects"],
        "summary": "Crear proyecto",
        "operationId": "createProject",
        "requestBody": {
          "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } } } } }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": { "application/json": { "schema": { "type": "object", "properties": { "project": { "$ref": "#/components/schemas/Project" } } } } }
          }
        }
      }
    },

    "/api/projects/{id}": {
      "get": {
        "tags": ["Projects"],
        "summary": "Obtener proyecto por ID",
        "operationId": "getProject",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "project": { "$ref": "#/components/schemas/Project" },
                    "diagramCount": { "type": "integer", "description": "Número de diagramas asignados al proyecto" }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Proyecto no encontrado",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      },
      "put": {
        "tags": ["Projects"],
        "summary": "Actualizar proyecto",
        "operationId": "updateProject",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "requestBody": {
          "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } } } } }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": { "application/json": { "schema": { "type": "object", "properties": { "project": { "$ref": "#/components/schemas/Project" } } } } }
          },
          "404": {
            "description": "Proyecto no encontrado",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      },
      "delete": {
        "tags": ["Projects"],
        "summary": "Eliminar proyecto",
        "operationId": "deleteProject",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": {
            "description": "OK. Los diagramas asignados se mueven a Sin proyecto.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "unassignedCount": { "type": "integer", "description": "Diagramas desasignados del proyecto" }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Proyecto no encontrado",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      }
    },

    "/api/generate": {
      "post": {
        "tags": ["AI"],
        "summary": "Generar BPMN desde texto",
        "operationId": "generateBpmn",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["transcript"],
                "properties": {
                  "transcript": { "type": "string" },
                  "redesign": { "type": "boolean" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "OK" },
          "400": {
            "description": "transcript vacío o archivo inválido",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          },
          "429": {
            "description": "Límite de uso",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      }
    },

    "/api/analyze-bpmn": {
      "post": {
        "tags": ["AI"],
        "summary": "Analizar proceso BPMN",
        "operationId": "analyzeBpmn",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "type": "object", "required": ["bpmnXml"], "properties": { "bpmnXml": { "type": "string" } } }
            }
          }
        },
        "responses": {
          "200": { "description": "OK" },
          "400": {
            "description": "bpmnXml requerido",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          },
          "429": {
            "description": "Límite de uso",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      }
    },

    "/api/redesign-bpmn": {
      "post": {
        "tags": ["AI"],
        "summary": "Rediseñar BPMN",
        "operationId": "redesignBpmn",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "type": "object", "required": ["bpmnXml"], "properties": { "bpmnXml": { "type": "string" }, "instructions": { "type": "string" } } }
            }
          }
        },
        "responses": {
          "200": { "description": "OK" },
          "400": {
            "description": "bpmnXml requerido",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          },
          "429": {
            "description": "Límite de uso",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      }
    },

    "/api/transcribe": {
      "post": {
        "tags": ["AI"],
        "summary": "Transcribir audio",
        "operationId": "transcribeAudio",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "type": "object", "required": ["audio"], "properties": { "audio": { "type": "string", "format": "byte" }, "mimeType": { "type": "string" } } }
            }
          }
        },
        "responses": {
          "200": { "description": "OK" },
          "400": {
            "description": "Audio faltante o demasiado corto",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      }
    },

    "/api/extract-text": {
      "post": {
        "tags": ["AI"],
        "summary": "Extraer texto de archivo",
        "operationId": "extractText",
        "security": [],
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } } }
            }
          }
        },
        "responses": {
          "200": { "description": "OK" },
          "400": {
            "description": "No se envió archivo o formato no soportado",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      }
    }
  }
}