{ "openapi": "3.1.0", "info": { "title": "FireFeed Worker Internal API", "version": "0.0.1", "description": "API interne del Worker FireFeed (Fastify). NON pubblica: usata solo per orchestrare job pipeline. Documentata per riferimento dev." }, "servers": [ { "url": "http://firefeed-worker:4000" } ], "components": { "securitySchemes": { "cookieSession": { "type": "apiKey", "in": "cookie", "name": "authjs.session-token", "description": "Sessione NextAuth v5 (cookie HttpOnly). L'endpoint richiede di essere già autenticati via Keycloak SSO. Il playground non può autenticarsi: testa da browser loggato." } }, "schemas": { "SessionUser": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string", "format": "email" }, "name": { "type": [ "string", "null" ] }, "activeCompanyId": { "type": [ "string", "null" ] } }, "required": [ "id", "email", "name", "activeCompanyId" ] }, "QueueAckResult": { "type": "object", "properties": { "jobId": { "type": "string" }, "status": { "type": "string", "enum": [ "queued" ] } }, "required": [ "jobId", "status" ] }, "WorkerPipelineRunSummary": { "type": "object", "properties": { "runId": { "type": "string" }, "queuedJobs": { "type": "array", "items": { "type": "string" } } }, "required": [ "runId" ] } }, "parameters": {} }, "paths": { "/internal/jobs/import": { "post": { "tags": [ "Internal", "Imports" ], "summary": "Enqueue di un job IMPORT su BullMQ", "description": "Chiamato dal web (`/api/projects/{id}/imports/{importId}/run`) o dallo scheduler. Richiede header `x-internal-secret`. Non destinato all'uso pubblico.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "pipelineRunId": { "type": "string" }, "importId": { "type": "string" }, "projectId": { "type": "string" }, "companyId": { "type": "string" } }, "required": [ "pipelineRunId", "importId", "projectId", "companyId" ] } } } }, "responses": { "202": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/QueueAckResult" } }, "required": [ "data" ], "description": "Envelope di successo. Il payload è in `data`." } } } }, "400": { "description": "Input non valido (validazione Zod fallita).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "description": "Envelope di errore. Il messaggio human-readable è in `error`; lo status code HTTP racconta il tipo (400, 401, 403, 404, 409, 500)." } } } }, "401": { "description": "Non autenticato.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "description": "Envelope di errore. Il messaggio human-readable è in `error`; lo status code HTTP racconta il tipo (400, 401, 403, 404, 409, 500)." } } } }, "403": { "description": "Autenticato ma non autorizzato sulla risorsa.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "description": "Envelope di errore. Il messaggio human-readable è in `error`; lo status code HTTP racconta il tipo (400, 401, 403, 404, 409, 500)." } } } }, "404": { "description": "Risorsa non trovata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "description": "Envelope di errore. Il messaggio human-readable è in `error`; lo status code HTTP racconta il tipo (400, 401, 403, 404, 409, 500)." } } } }, "500": { "description": "Errore interno.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "description": "Envelope di errore. Il messaggio human-readable è in `error`; lo status code HTTP racconta il tipo (400, 401, 403, 404, 409, 500)." } } } } } } }, "/internal/jobs/export": { "post": { "tags": [ "Internal", "Exports" ], "summary": "Enqueue di un job EXPORT su BullMQ", "description": "Chiamato dal web (`/api/projects/{id}/exports/{exportId}/run`). Richiede header `x-internal-secret`.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "pipelineRunId": { "type": "string" }, "exportId": { "type": "string" }, "projectId": { "type": "string" }, "companyId": { "type": "string" } }, "required": [ "pipelineRunId", "exportId", "projectId", "companyId" ] } } } }, "responses": { "202": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/QueueAckResult" } }, "required": [ "data" ], "description": "Envelope di successo. Il payload è in `data`." } } } }, "400": { "description": "Input non valido (validazione Zod fallita).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "description": "Envelope di errore. Il messaggio human-readable è in `error`; lo status code HTTP racconta il tipo (400, 401, 403, 404, 409, 500)." } } } }, "401": { "description": "Non autenticato.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "description": "Envelope di errore. Il messaggio human-readable è in `error`; lo status code HTTP racconta il tipo (400, 401, 403, 404, 409, 500)." } } } }, "403": { "description": "Autenticato ma non autorizzato sulla risorsa.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "description": "Envelope di errore. Il messaggio human-readable è in `error`; lo status code HTTP racconta il tipo (400, 401, 403, 404, 409, 500)." } } } }, "404": { "description": "Risorsa non trovata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "description": "Envelope di errore. Il messaggio human-readable è in `error`; lo status code HTTP racconta il tipo (400, 401, 403, 404, 409, 500)." } } } }, "500": { "description": "Errore interno.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "description": "Envelope di errore. Il messaggio human-readable è in `error`; lo status code HTTP racconta il tipo (400, 401, 403, 404, 409, 500)." } } } } } } }, "/internal/pipeline/run": { "post": { "tags": [ "Internal", "Pipeline" ], "summary": "Lancia una pipeline run completa (orchestrazione)", "description": "Crea un PipelineRun, sequenzia FETCH→PARSE→MERGE→RULES→EXPORT come job BullMQ con dipendenze. Richiede `x-internal-secret`.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "projectId": { "type": "string" }, "companyId": { "type": "string" }, "runType": { "type": "string", "enum": [ "IMPORT", "EXPORT", "BOTH" ] } }, "required": [ "projectId", "companyId", "runType" ] } } } }, "responses": { "202": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WorkerPipelineRunSummary" } }, "required": [ "data" ], "description": "Envelope di successo. Il payload è in `data`." } } } }, "400": { "description": "Input non valido (validazione Zod fallita).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "description": "Envelope di errore. Il messaggio human-readable è in `error`; lo status code HTTP racconta il tipo (400, 401, 403, 404, 409, 500)." } } } }, "401": { "description": "Non autenticato.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "description": "Envelope di errore. Il messaggio human-readable è in `error`; lo status code HTTP racconta il tipo (400, 401, 403, 404, 409, 500)." } } } }, "403": { "description": "Autenticato ma non autorizzato sulla risorsa.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "description": "Envelope di errore. Il messaggio human-readable è in `error`; lo status code HTTP racconta il tipo (400, 401, 403, 404, 409, 500)." } } } }, "404": { "description": "Risorsa non trovata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "description": "Envelope di errore. Il messaggio human-readable è in `error`; lo status code HTTP racconta il tipo (400, 401, 403, 404, 409, 500)." } } } }, "500": { "description": "Errore interno.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "description": "Envelope di errore. Il messaggio human-readable è in `error`; lo status code HTTP racconta il tipo (400, 401, 403, 404, 409, 500)." } } } } } } }, "/internal/scheduler/sync": { "post": { "tags": [ "Internal", "Scheduler" ], "summary": "Sincronizza la schedule di un progetto con il cron worker", "description": "Legge la `Schedule` dal DB e (re)registra il job cron sul scheduler interno. Chiamato dopo ogni PUT di /api/projects/{id}/schedule. Richiede `x-internal-secret`.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "projectId": { "type": "string" } }, "required": [ "projectId" ] } } } }, "responses": { "202": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ] } }, "required": [ "data" ], "description": "Envelope di successo. Il payload è in `data`." } } } }, "400": { "description": "Input non valido (validazione Zod fallita).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "description": "Envelope di errore. Il messaggio human-readable è in `error`; lo status code HTTP racconta il tipo (400, 401, 403, 404, 409, 500)." } } } }, "401": { "description": "Non autenticato.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "description": "Envelope di errore. Il messaggio human-readable è in `error`; lo status code HTTP racconta il tipo (400, 401, 403, 404, 409, 500)." } } } }, "403": { "description": "Autenticato ma non autorizzato sulla risorsa.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "description": "Envelope di errore. Il messaggio human-readable è in `error`; lo status code HTTP racconta il tipo (400, 401, 403, 404, 409, 500)." } } } }, "404": { "description": "Risorsa non trovata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "description": "Envelope di errore. Il messaggio human-readable è in `error`; lo status code HTTP racconta il tipo (400, 401, 403, 404, 409, 500)." } } } }, "500": { "description": "Errore interno.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "description": "Envelope di errore. Il messaggio human-readable è in `error`; lo status code HTTP racconta il tipo (400, 401, 403, 404, 409, 500)." } } } } } } }, "/internal/amazon/test": { "post": { "tags": [ "Internal", "Amazon" ], "summary": "Smoke test connessione Amazon SP-API", "description": "Decifra le credenziali della ApiKey indicata, prova una chiamata `getMarketplaceParticipations` minimale. Restituisce 400 con dettagli se fallisce.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "apiKeyId": { "type": "string" } }, "required": [ "apiKeyId" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success" ] } } } }, "400": { "description": "Input non valido (validazione Zod fallita).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "description": "Envelope di errore. Il messaggio human-readable è in `error`; lo status code HTTP racconta il tipo (400, 401, 403, 404, 409, 500)." } } } }, "401": { "description": "Non autenticato.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "description": "Envelope di errore. Il messaggio human-readable è in `error`; lo status code HTTP racconta il tipo (400, 401, 403, 404, 409, 500)." } } } }, "403": { "description": "Autenticato ma non autorizzato sulla risorsa.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "description": "Envelope di errore. Il messaggio human-readable è in `error`; lo status code HTTP racconta il tipo (400, 401, 403, 404, 409, 500)." } } } }, "404": { "description": "Risorsa non trovata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "description": "Envelope di errore. Il messaggio human-readable è in `error`; lo status code HTTP racconta il tipo (400, 401, 403, 404, 409, 500)." } } } }, "500": { "description": "Errore interno.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "description": "Envelope di errore. Il messaggio human-readable è in `error`; lo status code HTTP racconta il tipo (400, 401, 403, 404, 409, 500)." } } } } } } }, "/events/pipeline/{projectId}": { "get": { "tags": [ "Internal", "SSE" ], "summary": "Stream SSE diretto dal worker (auth via Keycloak JWT)", "description": "Endpoint SSE alternativo al web `/api/projects/{id}/pipeline/events`: autentica via token Keycloak in query param, verifica membership della company, subscribe al canale Redis pubsub. Usato per dev/debug; produzione passa dal web.", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "projectId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "token", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "description": "Stream SSE (text/event-stream)" } } } }, "400": { "description": "Input non valido (validazione Zod fallita).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "description": "Envelope di errore. Il messaggio human-readable è in `error`; lo status code HTTP racconta il tipo (400, 401, 403, 404, 409, 500)." } } } }, "401": { "description": "Non autenticato.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "description": "Envelope di errore. Il messaggio human-readable è in `error`; lo status code HTTP racconta il tipo (400, 401, 403, 404, 409, 500)." } } } }, "403": { "description": "Autenticato ma non autorizzato sulla risorsa.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "description": "Envelope di errore. Il messaggio human-readable è in `error`; lo status code HTTP racconta il tipo (400, 401, 403, 404, 409, 500)." } } } }, "404": { "description": "Risorsa non trovata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "description": "Envelope di errore. Il messaggio human-readable è in `error`; lo status code HTTP racconta il tipo (400, 401, 403, 404, 409, 500)." } } } }, "500": { "description": "Errore interno.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "description": "Envelope di errore. Il messaggio human-readable è in `error`; lo status code HTTP racconta il tipo (400, 401, 403, 404, 409, 500)." } } } } } } }, "/health": { "get": { "tags": [ "Internal", "System" ], "summary": "Liveness + readiness check del worker (DB + Redis)", "description": "Restituisce 200 se DB e Redis rispondono entro 2s, 503 altrimenti. Usato da Dokploy/Traefik per il routing healthy. Vedi packages/worker/src/services/health.service.ts.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "service": { "type": "string" }, "checks": { "type": "object", "properties": { "db": { "type": "object", "properties": { "ok": { "type": "boolean" }, "latencyMs": { "type": "integer", "minimum": 0 }, "error": { "type": "string" } }, "required": [ "ok", "latencyMs" ] }, "redis": { "type": "object", "properties": { "ok": { "type": "boolean" }, "latencyMs": { "type": "integer", "minimum": 0 }, "error": { "type": "string" } }, "required": [ "ok", "latencyMs" ] } }, "required": [ "db", "redis" ] } }, "required": [ "status", "service", "checks" ] } } } }, "400": { "description": "Input non valido (validazione Zod fallita).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "description": "Envelope di errore. Il messaggio human-readable è in `error`; lo status code HTTP racconta il tipo (400, 401, 403, 404, 409, 500)." } } } }, "401": { "description": "Non autenticato.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "description": "Envelope di errore. Il messaggio human-readable è in `error`; lo status code HTTP racconta il tipo (400, 401, 403, 404, 409, 500)." } } } }, "403": { "description": "Autenticato ma non autorizzato sulla risorsa.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "description": "Envelope di errore. Il messaggio human-readable è in `error`; lo status code HTTP racconta il tipo (400, 401, 403, 404, 409, 500)." } } } }, "404": { "description": "Risorsa non trovata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "description": "Envelope di errore. Il messaggio human-readable è in `error`; lo status code HTTP racconta il tipo (400, 401, 403, 404, 409, 500)." } } } }, "500": { "description": "Errore interno.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "description": "Envelope di errore. Il messaggio human-readable è in `error`; lo status code HTTP racconta il tipo (400, 401, 403, 404, 409, 500)." } } } }, "503": { "description": "HTTP 503", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "degraded" ] }, "service": { "type": "string" }, "checks": { "type": "object", "properties": { "db": { "type": "object", "properties": { "ok": { "type": "boolean" }, "latencyMs": { "type": "integer", "minimum": 0 }, "error": { "type": "string" } }, "required": [ "ok", "latencyMs" ] }, "redis": { "type": "object", "properties": { "ok": { "type": "boolean" }, "latencyMs": { "type": "integer", "minimum": 0 }, "error": { "type": "string" } }, "required": [ "ok", "latencyMs" ] } }, "required": [ "db", "redis" ] } }, "required": [ "status", "service", "checks" ] } } } } } } }, "/metrics": { "get": { "tags": [ "Internal", "System" ], "summary": "Esposizione metriche Prometheus", "description": "Text format Prometheus (firefeed_pipeline_runs_total, firefeed_pipeline_run_duration_seconds, firefeed_bullmq_jobs_active, firefeed_export_artifacts_size_bytes + default Node metrics). Endpoint interno, non auth — protetto a livello network.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "description": "text/plain — Prometheus exposition format" } } } }, "400": { "description": "Input non valido (validazione Zod fallita).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "description": "Envelope di errore. Il messaggio human-readable è in `error`; lo status code HTTP racconta il tipo (400, 401, 403, 404, 409, 500)." } } } }, "401": { "description": "Non autenticato.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "description": "Envelope di errore. Il messaggio human-readable è in `error`; lo status code HTTP racconta il tipo (400, 401, 403, 404, 409, 500)." } } } }, "403": { "description": "Autenticato ma non autorizzato sulla risorsa.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "description": "Envelope di errore. Il messaggio human-readable è in `error`; lo status code HTTP racconta il tipo (400, 401, 403, 404, 409, 500)." } } } }, "404": { "description": "Risorsa non trovata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "description": "Envelope di errore. Il messaggio human-readable è in `error`; lo status code HTTP racconta il tipo (400, 401, 403, 404, 409, 500)." } } } }, "500": { "description": "Errore interno.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "description": "Envelope di errore. Il messaggio human-readable è in `error`; lo status code HTTP racconta il tipo (400, 401, 403, 404, 409, 500)." } } } } } } } }, "webhooks": {} }