Skip to content

Proyectos, entornos y releases ​

Esta API interna permite preparar aplicaciones desplegables sin alterar el catálogo DSL ni publicar infraestructura. Sus rutas operativas requieren sesión de usuario de plataforma y membresía OWNER/ADMIN vigente en la empresa activa. La promoción directa requiere el principal OAuth confidencial de Nimo y el scope nimo:application-projects:promote; un JWT USER recibe 403. La SPA promociona mediante el BFF cookie-only. La asignación permanece shareable=false y publicSafe=false; no se expone a claves API, clientes app, SDK público, MCP externo ni chat embebible.

MétodoRutaEntradaResultado
GET/app-projects?page=1&limit=20page ≥ 1; limit 1–100 (defecto 20)200: { data, total, page, limit }, proyectos de la empresa activa
POST/app-projects{ name, sourceType: "dsl", applicationRef } o { name, sourceType: "git-static" }201: proyecto; crea preview y production con configuración revisión 1 y namespaces diferentes
POST/app-projects/:id/releasesDSL: { sourceVersion: 1 }; Git: { commitSha: "<SHA completo de 40/64 hex>" }201: release con snapshot, hash y versión del formato
POST/app-projects/:projectId/releases/:releaseId/artifactSin bodyCompila bundle DSL inmutable; exige OWNER/ADMIN vigente. sourceHash permanece separado de artifactHash
GET/app-projects/:projectId/releases/:releaseId/artifactUUIDs de proyecto y releaseManifiesto y URL de artefacto; exige OWNER/ADMIN vigente
GET/app-projects/:id/environmentsUUID de proyecto200: entornos con configRevision, releaseGeneration, dataNamespace, currentRelease
GET/app-projects/:projectId/environments/:environmentId/connectionsUUIDs de proyecto y entornoCuatro políticas y diagnóstico; nunca devuelve credenciales
PUT/app-projects/:projectId/environments/:environmentId/connectionsexpectedRevision y política para payment/email/push/webhookNueva revisión con referencias a providers tenant activos. Preview rechaza conexiones productivas; sandbox sin adapter y push/webhook fallan 422 sin escribir; revisión obsoleta: 409
GET/app-projects/:projectId/environments/:environmentId/runtime-originsUUIDs de proyecto y entornoLista de orígenes exactos activos y retirados
POST/app-projects/:projectId/environments/:environmentId/runtime-origins{ origin }Registra HTTPS exacto (localhost/loopback HTTP solo en desarrollo); sin wildcard, credenciales, ruta, query o fragmento
DELETE/app-projects/:projectId/environments/:environmentId/runtime-origins/:originIdUUIDs de proyecto, entorno y origenRetira el origen y deniega inmediatamente sesiones enlazadas
POST/app-projects/:projectId/environments/:environmentId/runtime-sessions{ originId, expiresInSeconds?: 60..3600 }Emite una sola vez una credencial opaca nrs_… con 15 min por defecto, ligada a usuario/app/empresa/proyecto/entorno/release/origen
DELETE/app-projects/runtime-sessions/:idUUID de sesión del usuario actualRevocación inmediata; el siguiente request devuelve 401
POST/app-operationsIdempotency-Key + { projectId, environmentId, releaseId, operationType: deployment|hosting-migration|hosting-rollback, expectedGeneration }201: operationId persistido antes de dispatch; migración/rollback solo sobre el release vigente; clave repetida con misma entrada devuelve la operación, entrada diferente: 409
POST/app-environments/:id/promotionsOAuth interno Nimo con scope nimo:application-projects:promote; payload de promoción201: activa el release probado en Preview; JWT USER normal: 403; revisión obsoleta u operación activa: 409
GET/app-operations/:idUUID de operación200: estado y evidencia saneada de la empresa activa; otra empresa/inexistente: 404
POST/app-operations/:id/cancelUUID de operación200: cancelada; operación terminada: 409

Las operaciones requieren usuario de plataforma con membresía OWNER/ADMIN vigente y no están expuestas a SDK público, MCP externo ni chat embebido. La tabla durable conserva la operación si el proceso se reinicia; una clave de idempotencia no puede reutilizarse con otra entrada. Migración y rollback guardan una instantánea de release, ruta, revisión de configuración y namespace de datos. Si alguno cambia antes del corte, la operación falla sin cambiar la ruta activa. WfP nunca ejecuta código de cliente y los JWT temporales de assets no se guardan en la operación.

Estas rutas no forman parte del OpenAPI ni de los SDK públicos. Requieren el Origin exacto de NIMO_INTERNAL_BFF_ORIGIN y cookie host-only __Secure-nimo_bff_session con Secure, HttpOnly, SameSite=Lax, Path=/ai/internal/bff y TTL de 15 minutos. El login valida contraseña y membresía OWNER/ADMIN activa. No emite JWT ni OAuth bearer. Cada mutación usa X-Nimo-CSRF-Token; la membresía se revalida en cada request y logout o rotación revoca la sesión anterior.

MétodoRutaEntrada / headersResultado
POST/ai/internal/bff/sessionOrigin; { username, password, companyId }Cookie BFF y { csrfToken, expiresAt, user }; error credenciales: 401
POST/ai/internal/bff/session/bootstrapCookie + OriginRenueva CSRF para la sesión; sesión inválida/expirada/replay: 401
POST/ai/internal/bff/session/rotateCookie + Origin + X-Nimo-CSRF-TokenRota la sesión opaca; la anterior se revoca
POST/ai/internal/bff/session/logoutCookie + Origin + X-Nimo-CSRF-TokenRevoca sesión y limpia cookie; 204
POST/ai/internal/bff/promotions/environments/:environmentIdCookie + Origin + X-Nimo-CSRF-Token; payload de promoción201: mismo servicio de promoción con revalidación OWNER/ADMIN live

El BFF es una frontera first-party de navegador. Un cliente que ya posea las credenciales de un OWNER/ADMIN aún puede autenticarse a las rutas API ordinarias; el endpoint de promoción con JWT USER directo continúa denegado.

Los proyectos DSL requieren una definición propia o una definición de plataforma seguida por la empresa. Para plataforma solo puede fijarse la versión exacta actualmente seguida. Sin sesión: 401; permiso revocado o token externo: 403; proyecto/definición/versión ajena, inexistente o no autorizada: 404; entrada inválida: 400. Las operaciones denegadas no dejan escrituras parciales.

Las operaciones anteriores requieren JWT de plataforma y rol OWNER/ADMIN vigente. Las sesiones runtime se limitan a una allowlist explícita de rutas y métodos de ejecución DSL; el guard las deniega en endpoints administrativos, incluidas rutas @Public(). Cada request vuelve a validar membresía, rol de aplicación, release, expiración/revocación y origen registrado exacto. El contexto se deriva de la sesión y los selectors de headers no pueden cambiarlo. CORS refleja orígenes activos para transporte de navegador, pero no concede autoridad. Esta capacidad permanece interna y no se añade a SDK público, MCP externo ni chat embebible.

Publicar otra versión DSL no cambia los releases ni despliega nada. Un release no se edita; crear otro conserva el anterior. currentRelease comienza en null. Las conexiones se guardan como referencias opacas a providers existentes en revisiones inmutables; las credenciales permanecen en el vault. Solo payment/Stripe y email/SMTP de producción pueden referenciar providers tenant activos. Preview no usa credenciales productivas ni recurre a un provider built-in de plataforma; si no hay adapter sandbox, devuelve un diagnóstico 422 y no ejecuta el efecto. Push y webhook siguen bloqueados hasta que existan adapters aprobados. El runtime DSL usa el entorno autorizado como namespace de instancias y relaciones: preview y production no comparten datos. Los IDs recibidos se aceptan solo tras verificar membresía, propiedad del proyecto y release asignado. El namespace de archivos permanece pendiente.

En Git, el SHA es una referencia declarativa: aún no se consulta ni se verifica el repositorio, no se construye y no se despliega. repositoryBindingId se rechaza hasta integrar y autorizar repositorios. toolchain.snapshotSchemaVersion describe el formato de captura, no una compilación ejecutada.

La promoción requiere una sesión OWNER/ADMIN vigente y el release activo de Preview con deployment exitoso confirmado. Verifica la revisión de configuración y las referencias a providers tenant, crea una asignación inmutable en Production y cambia el release activo en una transacción con control de generación. Conserva las asignaciones anteriores. La confirmación indica activación del runtime del backend; no despliega a Pages ni comprueba salud remota de Production. sourceHash, artifactHash y configurationHash describen el snapshot fuente, los bytes compilados y la revisión privada de configuración, respectivamente.