n8n-nodes-orbital-actions 2.2.2 → 3.0.0

package/README.md

@@ -0,0 +1,287 @@
+# n8n-nodes-orbital-actions
+
+Nodo de n8n para reportar progreso, steps y callbacks a Orbital desde workflows ejecutados como **Actions**.
+
+> **v3.0.0** — Modelo plano (Pipeline + Fases + Steps) con plantillas de industria. Breaking change respecto a v2.x — ver sección [Migración](#migración).
+
+## Instalación
+
+```bash
+npm install n8n-nodes-orbital-actions
+```
+
+O desde la UI de n8n: **Settings → Community Nodes → Install** → `n8n-nodes-orbital-actions`.
+
+## Concepto
+
+Cuando Orbital lanza un flujo n8n como **Action**, envía un payload con JWT del job (trae `jobId`, `userId`, `projectId`, `agentId` embebidos). Este nodo se usa **dentro del flujo** para reportar:
+
+- **Pipeline** de fases al inicio (esqueleto del job)
+- **Progreso** y **steps** durante la ejecución (hidratación)
+- **Callback** de éxito/error al final
+- **Documentos**, **notificaciones**, **aprobaciones HITL** según convenga
+
+El dashboard de Orbital muestra todo en tiempo real (polling cada 8s).
+
+## Modelo de datos
+
+```
+Job                                   ← workflow_jobs (1 por ejecución)
+ └── Fase                             ← pipelineUi (declarada al inicio)
+      └── Step (flat, sin jerarquía)  ← job_steps filtrado por phase_ref
+           └── ai.tools[] (inline)    ← metadata del step AI, no substeps
+```
+
+**3 niveles fijos, no árbol recursivo**. Alineado con NIST, GitHub Actions, Airflow, Temporal.
+
+## Uso típico
+
+### 1. Declarar Pipeline (PRIMER nodo del flujo)
+
+```
+[Webhook Trigger]
+    ↓
+[Orbital Actions]
+  Operación: Declarar Pipeline
+  Plantilla: [CyberSOC NIST ▾]
+    → Envía POST /public/wh/pipeline
+    → Dashboard muestra 5 fases vacías:
+       - Identificación/Protección
+       - Detección
+       - Correlación
+       - Respuesta
+       - Análisis
+```
+
+### 2. Reportar progreso y steps
+
+```
+[Orbital Actions]
+  Operación: Reportar Progreso
+  Fase: detection           ← marca como activa
+  Progreso: 20
+
+[HTTP Request: recolectar logs]
+
+[Orbital Actions]
+  Operación: Reportar Step
+  Fase: detection           ← dropdown autocompletado tras 1ª ejecución
+  Título: "Logs firewall recolectados"
+  Tipo: io
+  Estado: success
+```
+
+### 3. Saltar fase (opcional, early-exit)
+
+```
+[IF es falso positivo?]
+  -> SI: [Orbital Actions] Saltar Fase: correlation, Motivo: "Falso positivo L1"
+  -> SI: [Orbital Actions] Saltar Fase: response,   Motivo: "No aplica"
+  -> SI: [Orbital Actions] Saltar Fase: analysis,   Motivo: "Cadena cerrada"
+```
+
+### 4. Finalizar
+
+```
+[Orbital Actions]
+  Operación: Finalizar - Éxito
+  Título del Resultado: "Informe generado"
+  Contenido: markdown del informe
+```
+
+## Operaciones disponibles
+
+### Pipeline
+
+| Operación | Uso |
+|---|---|
+| **Declarar Pipeline** | PRIMER nodo. Envía fases al backend desde una plantilla de industria o custom. |
+| **Saltar Fase** | Marca una fase como saltada con motivo (early-exit, fases ya hechas, N/A). |
+
+### Progreso y Steps
+
+| Operación | Uso |
+|---|---|
+| **Reportar Progreso** | Actualiza `status`/`progress`/`phase` del job. |
+| **Reportar Step** | Crea un step en la fase actual — 90% de casos. |
+| **Construir Step (sin enviar)** | Devuelve JSON del step para manipular con Code/Merge. |
+| **Batch > Añadir Step al Buffer** | Acumula step localmente (sin HTTP). |
+| **Batch > Enviar Buffer** | Envía todos los steps acumulados en un POST atómico. |
+| **Actualizar Step Abierto (async)** | **Solo** para async/loops largos — cierra un step con `status=started`. |
+
+### Callbacks
+
+| Operación | Uso |
+|---|---|
+| **Finalizar - Éxito** | Marca job como `complete`. Puede crear documento. |
+| **Finalizar - Error** | Marca job como `errored` con categoría. |
+| **Crear Documento** | Añade un documento al centro de documentos del usuario. |
+| **Notificar Usuario** | Envía notificación visible al usuario. |
+| **Solicitar Aprobación (HITL)** | Pausa el job esperando acción del usuario. |
+
+## Plantillas built-in (22)
+
+### Cybersecurity / SOC (5)
+- **CyberSOC NIST** (Operativo L1/L2/L3) — Identificación/Protección -> Detección -> Correlación -> Respuesta -> Análisis (default)
+- **NIST CSF 2.0** (Estratégico) — Govern -> Identify -> Protect -> Detect -> Respond -> Recover
+- **SOC Incident Response** — Triage -> Investigate -> Contain -> Eradicate -> Recover -> Post-mortem
+- **ISO 27001 Audit** — Scope -> Evidence -> Gap -> Remediation -> Verification
+- **MITRE ATT&CK Response** — Detection -> Analysis -> Containment -> Eradication -> Recovery -> Lessons Learned
+
+### Offensive Security (2)
+- **Penetration Test** — Recon -> Scanning -> Enum -> Exploitation -> Post-Exploit -> Reporting
+- **Red Team Operation** — Planning -> Recon -> Initial Access -> Lateral Movement -> Objectives -> Exfil -> Cleanup
+
+### Research / Análisis (4)
+- **Deep Research** — Scope -> Gather -> Analyze -> Synthesize -> Validate -> Report
+- **Threat Intelligence** — Collect -> Process -> Analyze -> Disseminate -> Feedback
+- **Market Research** — Define -> Design -> Collect -> Analyze -> Report -> Recommend
+- **User Research (UX)** — Discover -> Define -> Design -> Test -> Iterate
+
+### IT Service Management (2)
+- **ITIL Change Management** — Request -> Assess -> Approve -> Plan -> Implement -> Review -> Close
+- **ITIL Incident Management** — Detect -> Log -> Categorize -> Prioritize -> Diagnose -> Resolve -> Close
+
+### DevOps (2)
+- **CI/CD Deploy** — Build -> Test -> Stage -> Deploy -> Validate -> Monitor
+- **Bug Triage & Fix** — Report -> Reproduce -> Diagnose -> Fix -> Verify -> Release
+
+### Data (2)
+- **ETL Pipeline** — Extract -> Transform -> Validate -> Load -> Verify
+- **ML Model Lifecycle** — Prepare -> Train -> Validate -> Deploy -> Monitor -> Retrain
+
+### Business (2)
+- **Customer Onboarding** — Welcome -> Setup -> Training -> Verification -> Go-Live -> Follow-up
+- **Sales Pipeline** — Lead -> Qualify -> Demo -> Propose -> Negotiate -> Close -> Handoff
+
+### Compliance (2)
+- **GDPR DPIA** — Identify -> Assess -> Mitigate -> Document -> Review
+- **Contract Review** — Draft -> Review -> Negotiate -> Approve -> Sign -> Archive
+
+### Content (1)
+- **Content Production** — Brief -> Research -> Draft -> Review -> Publish -> Promote
+
+### Custom
+- **Custom** — Define tus propias fases manualmente.
+
+## Dropdown dinámico de fases (loadOptions)
+
+Tras ejecutar `Declarar Pipeline` al menos una vez, los siguientes nodos con campo **Fase** (Reportar Step, Saltar Fase, etc.) muestran un **dropdown** con las fases declaradas.
+
+**Limitación n8n**: `loadOptions` solo lee de `workflowStaticData` (persistido de ejecuciones anteriores), no del output del mismo run. En la 1ª ejecución, escribe el `ref` directamente (ej: `detection`) o déjalo vacío — el backend auto-asigna a la fase activa (`currentPhaseRef`).
+
+## Auto-asignación de fase
+
+Si un step no trae `phaseRef`, el backend lo auto-asigna a `currentPhaseRef` (última fase marcada con `reportProgress`). Por tanto:
+
+```
+[Reportar Progreso] fase=detection
+[Reportar Step]     (sin phaseRef) -> auto-asigna a "detection"
+[Reportar Step]     (sin phaseRef) -> auto-asigna a "detection"
+[Reportar Progreso] fase=response
+[Reportar Step]     (sin phaseRef) -> auto-asigna a "response"
+```
+
+## Combinación con OrbitalProcess
+
+Si el flujo invoca agentes IA via `n8n-nodes-orbital` (OrbitalProcess), activar **Emitir Step** en ese nodo genera automáticamente un step `kind=ai` con `ai.tools[]` inline en la fase actual:
+
+```
+[Orbital Actions: Reportar Progreso] fase=detection
+    ↓
+[Orbital Process: Ejecutar Agente "clasificador"]
+   [X] Emitir Step
+   Fase: detection
+    -> Emite 1 step AI con tools inline (modelo plano, sin substeps)
+```
+
+Dashboard:
+```
+Detection (2 steps, 3.1s)
+  [ok] Logs recolectados                io, 1.2s
+  [ok] Clasificador IA                  ai, 1.9s
+     gpt-4o, 1250 tokens, 3 tools
+     (expandir: get_logs, classify, score con input/output)
+```
+
+## Auth
+
+Header `Authorization: Bearer eyJ...` — JWT del job, extraído del payload del Webhook:
+
+```
+Token JWT: {{ $("Webhook").item.json.body.auth.token }}
+```
+
+El JWT trae embebidos: `jobId`, `userId`, `projectId`, `agentId`, `conversationId`. El backend no necesita nada más.
+
+## Endpoints internos
+
+El nodo llama a:
+
+- `POST /public/wh/pipeline` — declarePipeline (endpoint dedicado REST)
+- `POST /public/wh/events` — reportProgress / reportStep / batchFlush / updateStep / skipPhase / requestApproval
+- `POST /public/wh/callback` — Finalizar Éxito / Error
+- `POST /public/wh/documents` — Crear Documento
+- `POST /public/wh/notify` — Notificar
+
+El middleware `apiKeyValidation` detecta automáticamente el token como JWT (empieza por `eyJ`) o API Key (`oapi_`).
+
+## Output
+
+Cada operación devuelve en `json`:
+
+```json
+{
+  "operation": "reportStep",
+  "url": "https://api.orbital.../public/wh/events",
+  "stepId": "step_abc123",
+  "step": { "id": "...", "kind": "...", "status": "...", "title": "...", "phaseRef": "..." },
+  "success": true
+}
+```
+
+El `stepId` se puede usar en operaciones posteriores:
+```
+={{ $("Reportar Step").item.json.stepId }}
+```
+
+## Migración desde v2.x
+
+**Breaking changes en v3.0.0**:
+
+| Cambio | v2.x | v3.0.0 |
+|---|---|---|
+| Modelo | Árbol recursivo con `parentStepId` | **Plano por fase** (sin parent) |
+| Tools del agente (emitStep) | N+1 steps (1 AI + N tools) | **1 step con `ai.tools[]` inline** |
+| Campo "Es Substep De" | Sí | **Eliminado** |
+| Stack automático `status=started` | Sí | **Eliminado** — usar explícitamente `updateStep` solo para async |
+| Declaración de pipeline | No | **Nueva operación `declarePipeline`** con 22 plantillas |
+| Skip de fase | No | **Nueva operación `skipPhase`** con motivo |
+| Campo `phaseRef` en steps | String libre | **Dropdown dinámico** (loadOptions) con autocomplete |
+
+**Cómo adaptar flujos v2.x**:
+
+1. Añadir un nodo `Declarar Pipeline` al inicio del flujo.
+2. Rellenar el campo **Fase** en cada step (o dejarlo vacío — se auto-asigna a la fase activa).
+3. Eliminar el campo `parentStepId` de los steps (ya no existe).
+4. Si usabas steps con `status=started` + substeps automáticos, ahora crea steps planos individuales en la misma fase.
+
+## Build local
+
+```bash
+pnpm install
+pnpm run build
+```
+
+El output queda en `dist/`. Para testing local:
+
+```bash
+npm link                           # en este paquete
+cd ~/.n8n/custom                   # o donde tengas custom nodes
+npm link n8n-nodes-orbital-actions
+# reiniciar n8n
+```
+
+## Licencia
+
+MIT

package/dist/nodes/Orbital/OrbitalActions.node.d.ts

@@ -1,4 +1,4 @@
-import type { IExecuteFunctions, INodeExecutionData, INodeType, INodeTypeDescription } from 'n8n-workflow';
+import type { IExecuteFunctions, ILoadOptionsFunctions, INodeExecutionData, INodePropertyOptions, INodeType, INodeTypeDescription } from 'n8n-workflow';
 /**
  * ORBITAL ACTIONS — Nodo para integración webhook/actions con Orbital.
  *
@@ -9,5 +9,24 @@ import type { IExecuteFunctions, INodeExecutionData, INodeType, INodeTypeDescrip
  */
 export declare class OrbitalActions implements INodeType {
     description: INodeTypeDescription;
+    /**
+     * loadOptions — populan dropdowns dinámicos en design-time.
+     *
+     * LIMITACIÓN n8n: loadOptions solo puede leer de workflowStaticData (persistido
+     * de ejecuciones anteriores) o hacer HTTP. NO puede resolver expresiones n8n
+     * como {{ $("X").json... }} porque corre ANTES de runtime.
+     *
+     * Flujo:
+     * 1. Usuario ejecuta el workflow al menos 1 vez con declarePipeline
+     * 2. Tras la ejecución, orbitalPipelinePhases queda guardado en staticData
+     * 3. En la siguiente vez que abre el nodo, el dropdown se llena con esas fases
+     * 4. En la 1ª ejecución, el dropdown está vacío — el usuario escribe el ref
+     *    manualmente (ej: "detection") o deja vacío para auto-asignar a currentPhaseRef
+     */
+    methods: {
+        loadOptions: {
+            getPipelinePhases(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
+        };
+    };
     execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]>;
 }