@hablala/api-contract 0.9.1 → 0.11.0

package/openapi.json

@@ -730,6 +730,48 @@
       "AccountManifestSections": {
         "description": "Las secciones declarables de una cuenta (ADR-027). El `kind` fija la SUPERFICIE: una `organization` declara el diccionario (objects…), la mensajería (spaces/channels) y el acceso (roles, sso, domains, invitations); un `individual` declara su `profile` y su `privacy` (singletons). Cada sección es opcional (ausente = no gestionada). Gobernanza: la mayoría es AUTORITATIVA (lo no declarado se archiva — policies/roles/sso se BORRAN); son ADITIVAS (siembra, no expulsa) los `initialMembers` de un canal, los `domains` y las `invitations` — lifecycle, no estado deseado. Los datos (records/mensajes) no son configuración.",
         "properties": {
+          "actions": {
+            "oneOf": [
+              {
+                "items": {
+                  "$ref": "#/components/schemas/ManifestAction"
+                },
+                "type": "array",
+                "x-struct": null,
+                "x-validate": null
+              },
+              {
+                "properties": {
+                  "items": {
+                    "items": {
+                      "$ref": "#/components/schemas/ManifestAction"
+                    },
+                    "type": "array",
+                    "x-struct": null,
+                    "x-validate": null
+                  },
+                  "mode": {
+                    "description": "`authoritative` (default): lo no declarado se archiva/borra. `additive`: solo crea/actualiza lo declarado, sin expulsar lo demás (least astonishment).",
+                    "enum": [
+                      "authoritative",
+                      "additive"
+                    ],
+                    "type": "string",
+                    "x-struct": null,
+                    "x-validate": null
+                  }
+                },
+                "required": [
+                  "items"
+                ],
+                "type": "object",
+                "x-struct": null,
+                "x-validate": null
+              }
+            ],
+            "x-struct": null,
+            "x-validate": null
+          },
           "agents": {
             "oneOf": [
               {
@@ -1277,6 +1319,54 @@
         "x-struct": "Elixir.HablalaApiWeb.Schemas.AccountManifestSections",
         "x-validate": null
       },
+      "ActionRunRequest": {
+        "description": "Input de una action transaccional. `input` es el mapa que interpolan los steps (`{{input.…}}`, y `{{item.…}}` en los steps con for_each).",
+        "properties": {
+          "idempotency_key": {
+            "description": "Clave natural para reintentos seguros (se propaga a cada step creado).",
+            "type": "string",
+            "x-struct": null,
+            "x-validate": null
+          },
+          "input": {
+            "description": "Los valores de entrada de la action (forma libre, definida por sus steps).",
+            "type": "object",
+            "x-struct": null,
+            "x-validate": null
+          }
+        },
+        "title": "ActionRunRequest",
+        "type": "object",
+        "x-struct": "Elixir.HablalaApiWeb.Schemas.ActionRunRequest",
+        "x-validate": null
+      },
+      "ActionRunResponse": {
+        "properties": {
+          "data": {
+            "properties": {
+              "results": {
+                "description": "Por step_id, el/los records creados (`{id, properties}`). Un step con for_each devuelve una lista; uno simple, un objeto.",
+                "type": "object",
+                "x-struct": null,
+                "x-validate": null
+              }
+            },
+            "required": [
+              "results"
+            ],
+            "type": "object",
+            "x-struct": null,
+            "x-validate": null
+          }
+        },
+        "required": [
+          "data"
+        ],
+        "title": "ActionRunResponse",
+        "type": "object",
+        "x-struct": "Elixir.HablalaApiWeb.Schemas.ActionRunResponse",
+        "x-validate": null
+      },
       "AddMemberRequest": {
         "description": "Añade un usuario del tenant a una conversación (invitar a un canal).",
         "properties": {
@@ -1698,6 +1788,134 @@
         "x-struct": "Elixir.HablalaApiWeb.Schemas.AgentsResponse",
         "x-validate": null
       },
+      "AggregateQueryRequest": {
+        "description": "Aggregation query: agrupa records por `dimensions` y calcula `measures` (count/sum/avg/min/max), bajo la misma gobernanza (RBAC + ABAC default-deny) que la lectura puntual. El par canónico measures + dimensions del semantic layer (Cube.dev).",
+        "properties": {
+          "dimensions": {
+            "description": "Los attributes por los que agrupar (GROUP BY).",
+            "items": {
+              "properties": {
+                "attr": {
+                  "description": "Slug del attribute a agrupar.",
+                  "type": "string",
+                  "x-struct": null,
+                  "x-validate": null
+                },
+                "granularity": {
+                  "description": "Solo para date/timestamp (time dimension): trunca el valor a ese bucket.",
+                  "enum": [
+                    "day",
+                    "week",
+                    "month",
+                    "quarter",
+                    "year"
+                  ],
+                  "type": "string",
+                  "x-struct": null,
+                  "x-validate": null
+                }
+              },
+              "required": [
+                "attr"
+              ],
+              "type": "object",
+              "x-struct": null,
+              "x-validate": null
+            },
+            "type": "array",
+            "x-struct": null,
+            "x-validate": null
+          },
+          "measures": {
+            "description": "Las agregaciones a calcular (al menos una).",
+            "items": {
+              "properties": {
+                "as": {
+                  "description": "Alias de salida (default: `count` o `<fn>_<attr>`).",
+                  "type": "string",
+                  "x-struct": null,
+                  "x-validate": null
+                },
+                "attr": {
+                  "description": "Slug del attribute a agregar (number para sum/avg; number/date/timestamp para min/max). Omitido solo en `count`.",
+                  "type": "string",
+                  "x-struct": null,
+                  "x-validate": null
+                },
+                "fn": {
+                  "description": "La función de agregación. `count` no lleva `attr`.",
+                  "enum": [
+                    "count",
+                    "sum",
+                    "avg",
+                    "min",
+                    "max"
+                  ],
+                  "type": "string",
+                  "x-struct": null,
+                  "x-validate": null
+                }
+              },
+              "required": [
+                "fn"
+              ],
+              "type": "object",
+              "x-struct": null,
+              "x-validate": null
+            },
+            "type": "array",
+            "x-struct": null,
+            "x-validate": null
+          },
+          "object": {
+            "description": "Slug del objeto raíz (requerido).",
+            "type": "string",
+            "x-struct": null,
+            "x-validate": null
+          },
+          "where": {
+            "description": "Mismo formato que en la consulta puntual: filtra ANTES de agregar.",
+            "items": {
+              "type": "object",
+              "x-struct": null,
+              "x-validate": null
+            },
+            "type": "array",
+            "x-struct": null,
+            "x-validate": null
+          }
+        },
+        "required": [
+          "object",
+          "measures"
+        ],
+        "title": "AggregateQueryRequest",
+        "type": "object",
+        "x-struct": "Elixir.HablalaApiWeb.Schemas.AggregateQueryRequest",
+        "x-validate": null
+      },
+      "AggregateResultResponse": {
+        "properties": {
+          "data": {
+            "description": "Un grupo por combinación de dimensions (o un solo grupo con los totales si no hay dimensions). Cada grupo es un mapa: cada dimension por su slug y cada measure por su alias de salida.",
+            "items": {
+              "type": "object",
+              "x-struct": null,
+              "x-validate": null
+            },
+            "type": "array",
+            "x-struct": null,
+            "x-validate": null
+          }
+        },
+        "required": [
+          "data"
+        ],
+        "title": "AggregateResultResponse",
+        "type": "object",
+        "x-struct": "Elixir.HablalaApiWeb.Schemas.AggregateResultResponse",
+        "x-validate": null
+      },
       "ApiKey": {
         "description": "Metadatos de una API key de la Public API. El secreto en claro NO se incluye aquí — solo se devuelve una vez, al crearla.",
         "properties": {
@@ -2030,6 +2248,13 @@
             "x-struct": null,
             "x-validate": null
           },
+          "seatsPerSlot": {
+            "description": "Capacidad del slot: cuántas citas solapadas del mismo organizador caben a la vez (Cal.com seats per time slot). 1 = no-solape estricto; N = hasta N concurrentes.",
+            "minimum": 1,
+            "type": "integer",
+            "x-struct": null,
+            "x-validate": null
+          },
           "startsAt": {
             "format": "date-time",
             "type": "string",
@@ -2100,6 +2325,13 @@
             "x-struct": null,
             "x-validate": null
           },
+          "seatsPerSlot": {
+            "description": "Capacidad del slot (default 1 = no-solape estricto). N permite hasta N citas solapadas del mismo organizador (aforo, clases, atención en paralelo).",
+            "minimum": 1,
+            "type": "integer",
+            "x-struct": null,
+            "x-validate": null
+          },
           "startsAt": {
             "format": "date-time",
             "type": "string",
@@ -6734,6 +6966,60 @@
         "x-struct": "Elixir.HablalaApiWeb.Schemas.MachineOrganizationResponse",
         "x-validate": null
       },
+      "ManifestAction": {
+        "description": "Una action transaccional del tenant declarada (sección `actions/`), identificada por `slug`. Ejecuta sus `steps` en UNA transacción (todo-o-nada) al invocar `POST /v1/actions/:slug`: crear una cabecera + N líneas de forma atómica (el caso `create_rental` de una app interna). Cada step declara un `object` del diccionario y las `properties` a escribir, con interpolación `{{input.…}}`, `{{steps.<id>.id}}` (ref entre steps) y `{{item.…}}` en un step con `for_each`. Sección AUTORITATIVA: retirarla del manifiesto la archiva. `description`/`synonyms` son el contexto con el que los agentes LLM la descubren vía MCP (obligatoria la descripción, como el resto del diccionario).",
+        "properties": {
+          "description": {
+            "description": "Qué hace la action (contexto para humanos y agentes LLM). Obligatoria al crear.",
+            "type": "string",
+            "x-struct": null,
+            "x-validate": null
+          },
+          "slug": {
+            "description": "Identidad estable snake_case, única por organización (match key).",
+            "type": "string",
+            "x-struct": null,
+            "x-validate": null
+          },
+          "steps": {
+            "description": "Lista NO vacía de pasos. Cada paso: `id` (opcional, para refs `{{steps.<id>.id}}`), `object` (slug del diccionario), `properties` (mapa slug→valor con interpolación) y opcionalmente `for_each` (una ruta del input que expande el step en N records).",
+            "items": {
+              "additionalProperties": true,
+              "type": "object",
+              "x-struct": null,
+              "x-validate": null
+            },
+            "type": "array",
+            "x-struct": null,
+            "x-validate": null
+          },
+          "synonyms": {
+            "description": "Sinónimos para el descubrimiento por búsqueda/LLM.",
+            "items": {
+              "type": "string",
+              "x-struct": null,
+              "x-validate": null
+            },
+            "type": "array",
+            "x-struct": null,
+            "x-validate": null
+          },
+          "title": {
+            "description": "Nombre visible; si se omite, se deriva del slug.",
+            "type": "string",
+            "x-struct": null,
+            "x-validate": null
+          }
+        },
+        "required": [
+          "slug",
+          "steps"
+        ],
+        "title": "ManifestAction",
+        "type": "object",
+        "x-struct": "Elixir.HablalaApiWeb.Schemas.ManifestAction",
+        "x-validate": null
+      },
       "ManifestAgent": {
         "description": "Un agente de IA declarado, identificado por `handle`. Archivar (no declararlo) lo revoca. `ownerUserId` (id público `user_…`) es obligatorio al crear con un access token de máquina; con un usuario, el creador es el dueño por defecto.",
         "properties": {
@@ -7845,49 +8131,178 @@
         "x-struct": "Elixir.HablalaApiWeb.Schemas.MediaResponse",
         "x-validate": null
       },
-      "Membership": {
+      "Member": {
+        "description": "Un miembro de la organización: identidad legible + sus roles (sin secretos).",
         "properties": {
-          "avatarUrl": {
-            "description": "Avatar override para esta org; `null` usa el global del usuario.",
-            "nullable": true,
-            "type": "string",
-            "x-struct": null,
-            "x-validate": null
-          },
           "displayName": {
-            "description": "Nombre visible en esta org (override del `name` global).",
             "nullable": true,
             "type": "string",
             "x-struct": null,
             "x-validate": null
           },
           "email": {
-            "description": "Email corporativo del miembro (dato de org entre colegas, acotado al tenant). `null` si la cuenta no tiene email. No confundir con el perfil público `user`, que no lleva PII.",
-            "format": "email",
             "nullable": true,
             "type": "string",
             "x-struct": null,
             "x-validate": null
           },
           "id": {
+            "description": "Id de la membresía (`mbr_…`).",
             "type": "string",
             "x-struct": null,
             "x-validate": null
           },
-          "insertedAt": {
-            "format": "date-time",
+          "roles": {
+            "description": "Los roles del miembro por nombre (owner/admin/member o custom).",
+            "items": {
+              "type": "string",
+              "x-struct": null,
+              "x-validate": null
+            },
+            "type": "array",
+            "x-struct": null,
+            "x-validate": null
+          }
+        },
+        "required": [
+          "id",
+          "roles"
+        ],
+        "title": "Member",
+        "type": "object",
+        "x-struct": "Elixir.HablalaApiWeb.Schemas.Member",
+        "x-validate": null
+      },
+      "MemberLoginRequest": {
+        "description": "Credenciales de un miembro (empleado que opera la org). La organización sale de la API key.",
+        "properties": {
+          "email": {
+            "format": "email",
             "type": "string",
             "x-struct": null,
             "x-validate": null
           },
-          "organizationId": {
+          "password": {
+            "format": "password",
             "type": "string",
             "x-struct": null,
             "x-validate": null
-          },
-          "roles": {
-            "items": {
-              "$ref": "#/components/schemas/RoleRef"
+          }
+        },
+        "required": [
+          "email",
+          "password"
+        ],
+        "title": "MemberLoginRequest",
+        "type": "object",
+        "x-struct": "Elixir.HablalaApiWeb.Schemas.MemberLoginRequest",
+        "x-validate": null
+      },
+      "MemberResponse": {
+        "properties": {
+          "data": {
+            "$ref": "#/components/schemas/Member"
+          }
+        },
+        "required": [
+          "data"
+        ],
+        "title": "MemberResponse",
+        "type": "object",
+        "x-struct": "Elixir.HablalaApiWeb.Schemas.MemberResponse",
+        "x-validate": null
+      },
+      "MemberSession": {
+        "properties": {
+          "expiresAt": {
+            "format": "date-time",
+            "nullable": true,
+            "type": "string",
+            "x-struct": null,
+            "x-validate": null
+          },
+          "member": {
+            "$ref": "#/components/schemas/Member"
+          },
+          "prefix": {
+            "nullable": true,
+            "type": "string",
+            "x-struct": null,
+            "x-validate": null
+          },
+          "token": {
+            "description": "El member session token en claro (`mem_…`), legible SOLO en esta respuesta.",
+            "type": "string",
+            "x-struct": null,
+            "x-validate": null
+          }
+        },
+        "required": [
+          "token",
+          "member"
+        ],
+        "title": "MemberSession",
+        "type": "object",
+        "x-struct": "Elixir.HablalaApiWeb.Schemas.MemberSession",
+        "x-validate": null
+      },
+      "MemberSessionResponse": {
+        "properties": {
+          "data": {
+            "$ref": "#/components/schemas/MemberSession"
+          }
+        },
+        "required": [
+          "data"
+        ],
+        "title": "MemberSessionResponse",
+        "type": "object",
+        "x-struct": "Elixir.HablalaApiWeb.Schemas.MemberSessionResponse",
+        "x-validate": null
+      },
+      "Membership": {
+        "properties": {
+          "avatarUrl": {
+            "description": "Avatar override para esta org; `null` usa el global del usuario.",
+            "nullable": true,
+            "type": "string",
+            "x-struct": null,
+            "x-validate": null
+          },
+          "displayName": {
+            "description": "Nombre visible en esta org (override del `name` global).",
+            "nullable": true,
+            "type": "string",
+            "x-struct": null,
+            "x-validate": null
+          },
+          "email": {
+            "description": "Email corporativo del miembro (dato de org entre colegas, acotado al tenant). `null` si la cuenta no tiene email. No confundir con el perfil público `user`, que no lleva PII.",
+            "format": "email",
+            "nullable": true,
+            "type": "string",
+            "x-struct": null,
+            "x-validate": null
+          },
+          "id": {
+            "type": "string",
+            "x-struct": null,
+            "x-validate": null
+          },
+          "insertedAt": {
+            "format": "date-time",
+            "type": "string",
+            "x-struct": null,
+            "x-validate": null
+          },
+          "organizationId": {
+            "type": "string",
+            "x-struct": null,
+            "x-validate": null
+          },
+          "roles": {
+            "items": {
+              "$ref": "#/components/schemas/RoleRef"
             },
             "type": "array",
             "x-struct": null,
@@ -10114,6 +10529,111 @@
         "x-struct": "Elixir.HablalaApiWeb.Schemas.PresignResult",
         "x-validate": null
       },
+      "ProvisionMemberInput": {
+        "description": "Datos para dar de alta un operador DIRECTO (sin invitación por email): queda miembro activo al instante y establece su contraseña por el link de set-password de la respuesta.",
+        "properties": {
+          "email": {
+            "description": "Email del operador. Si ya existe un usuario con ese email, se reutiliza.",
+            "format": "email",
+            "type": "string",
+            "x-struct": null,
+            "x-validate": null
+          },
+          "role": {
+            "description": "Nombre del rol a asignar (p. ej. `operator`). Opcional.",
+            "nullable": true,
+            "type": "string",
+            "x-struct": null,
+            "x-validate": null
+          }
+        },
+        "required": [
+          "email"
+        ],
+        "title": "ProvisionMemberInput",
+        "type": "object",
+        "x-struct": "Elixir.HablalaApiWeb.Schemas.ProvisionMemberInput",
+        "x-validate": null
+      },
+      "ProvisionMemberRequest": {
+        "properties": {
+          "member": {
+            "$ref": "#/components/schemas/ProvisionMemberInput"
+          }
+        },
+        "required": [
+          "member"
+        ],
+        "title": "ProvisionMemberRequest",
+        "type": "object",
+        "x-struct": "Elixir.HablalaApiWeb.Schemas.ProvisionMemberRequest",
+        "x-validate": null
+      },
+      "ProvisionMemberResponse": {
+        "description": "El operador dado de alta. `passwordSetupToken` es el token de un solo uso con el que la persona establece SU contraseña (nunca se le comparte una contraseña generada). `userCreated` indica si el usuario nació con esta alta o ya existía (en cuyo caso su contraseña no se toca).",
+        "properties": {
+          "data": {
+            "properties": {
+              "displayName": {
+                "nullable": true,
+                "type": "string",
+                "x-struct": null,
+                "x-validate": null
+              },
+              "email": {
+                "nullable": true,
+                "type": "string",
+                "x-struct": null,
+                "x-validate": null
+              },
+              "id": {
+                "description": "Id de la membresía (`mbr_…`).",
+                "type": "string",
+                "x-struct": null,
+                "x-validate": null
+              },
+              "passwordSetupToken": {
+                "description": "Token de set-password (un solo uso). Entrégaselo a la persona para que fije su contraseña vía el flujo de reset. NO es una contraseña.",
+                "type": "string",
+                "x-struct": null,
+                "x-validate": null
+              },
+              "roles": {
+                "items": {
+                  "type": "string",
+                  "x-struct": null,
+                  "x-validate": null
+                },
+                "type": "array",
+                "x-struct": null,
+                "x-validate": null
+              },
+              "userCreated": {
+                "description": "`true` si el usuario nació con esta alta; `false` si ya existía.",
+                "type": "boolean",
+                "x-struct": null,
+                "x-validate": null
+              }
+            },
+            "required": [
+              "id",
+              "roles",
+              "passwordSetupToken",
+              "userCreated"
+            ],
+            "type": "object",
+            "x-struct": null,
+            "x-validate": null
+          }
+        },
+        "required": [
+          "data"
+        ],
+        "title": "ProvisionMemberResponse",
+        "type": "object",
+        "x-struct": "Elixir.HablalaApiWeb.Schemas.ProvisionMemberResponse",
+        "x-validate": null
+      },
       "PublicOrganization": {
         "description": "Identidad PÚBLICA del tenant (la org del token) — el paralelo horizontal del `shop`/`brand` de Shopify. Deja al cliente pintar su chrome (nombre, logo) y conocer su `endUserObjectSlug` sin hardcodear la marca. NUNCA incluye la PII legal del negocio.",
         "properties": {
@@ -13361,6 +13881,11 @@
         "description": "End-user session token: `Authorization: Bearer <sess_…>`.",
         "scheme": "bearer",
         "type": "http"
+      },
+      "memberToken": {
+        "description": "Member session token: `Authorization: Bearer <mem_…>` (empleado que opera la org).",
+        "scheme": "bearer",
+        "type": "http"
       }
     }
   },
@@ -13582,33 +14107,65 @@
         ]
       }
     },
-    "/v1/device-links": {
+    "/v1/actions/{slug}": {
       "post": {
         "callbacks": {},
-        "description": "Inicia la vinculación de la web: devuelve un `linkCode` para pintar el QR que el teléfono escaneará. Público (es un flujo de login). El teléfono es la raíz de identidad; la web hereda la sesión al aprobarse (modelo WhatsApp *linked devices*).",
-        "operationId": "post /v1/device-links",
-        "parameters": [],
+        "description": "Corre los steps de la action `slug` en UNA transacción (todo-o-nada), interpolando el input, y devuelve los records creados por step. `create_rental`/`register_return` y similares. Gate: records:create.",
+        "operationId": "post /v1/actions/{slug}",
+        "parameters": [
+          {
+            "description": "Slug de la action a ejecutar.",
+            "in": "path",
+            "name": "slug",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "x-struct": null,
+              "x-validate": null
+            }
+          }
+        ],
         "requestBody": {
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/DeviceLinkCreateRequest"
+                "$ref": "#/components/schemas/ActionRunRequest"
               }
             }
           },
-          "description": "Contexto del navegador",
+          "description": "Input de la action",
           "required": false
         },
         "responses": {
-          "201": {
+          "200": {
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/DeviceLinkCreateResponse"
+                  "$ref": "#/components/schemas/ActionRunResponse"
                 }
               }
             },
-            "description": "linkCode para el QR"
+            "description": "Resultado por step"
+          },
+          "403": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Sin permiso"
+          },
+          "404": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Action desconocida"
           },
           "422": {
             "content": {
@@ -13618,46 +14175,44 @@
                 }
               }
             },
-            "description": "Datos inválidos"
+            "description": "Fallo de un step (rollback total)"
           }
         },
-        "security": [],
-        "summary": "Cross-device — la web pide un QR",
+        "summary": "Ejecutar una action transaccional",
         "tags": [
-          "auth"
+          "actions"
         ]
       }
     },
-    "/v1/device-links/{link_code}": {
-      "get": {
+    "/v1/aggregate": {
+      "post": {
         "callbacks": {},
-        "description": "Devuelve `pending` (sigue esperando), `linked` (aprobado: incluye `user` y el `token` de sesión web, SOLO en el primer poll) o `denied`. Público: el `linkCode` es la credencial.",
-        "operationId": "get /v1/device-links/{link_code}",
-        "parameters": [
-          {
-            "description": "El `linkCode` del QR (`dlnk_…`).",
-            "in": "path",
-            "name": "link_code",
-            "required": true,
-            "schema": {
-              "type": "string",
-              "x-struct": null,
-              "x-validate": null
+        "description": "Agrupa records por `dimensions` y calcula `measures` (count/sum/avg/min/max), bajo la misma gobernanza (RBAC + ABAC default-deny) que la lectura puntual. Reemplaza los reportes que serían RPCs de SQL por-tenant.",
+        "operationId": "post /v1/aggregate",
+        "parameters": [],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AggregateQueryRequest"
+              }
             }
-          }
-        ],
+          },
+          "description": "Aggregation query",
+          "required": false
+        },
         "responses": {
           "200": {
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/DeviceLinkStatusResponse"
+                  "$ref": "#/components/schemas/AggregateResultResponse"
                 }
               }
             },
-            "description": "Estado del flujo"
+            "description": "Grupos agregados"
           },
-          "404": {
+          "403": {
             "content": {
               "application/json": {
                 "schema": {
@@ -13665,9 +14220,121 @@
                 }
               }
             },
-            "description": "Código inexistente o expirado"
+            "description": "Sin permiso"
           },
-          "409": {
+          "404": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Objeto desconocido"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Consulta inválida"
+          }
+        },
+        "summary": "Ejecutar una aggregation query",
+        "tags": [
+          "query"
+        ]
+      }
+    },
+    "/v1/device-links": {
+      "post": {
+        "callbacks": {},
+        "description": "Inicia la vinculación de la web: devuelve un `linkCode` para pintar el QR que el teléfono escaneará. Público (es un flujo de login). El teléfono es la raíz de identidad; la web hereda la sesión al aprobarse (modelo WhatsApp *linked devices*).",
+        "operationId": "post /v1/device-links",
+        "parameters": [],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DeviceLinkCreateRequest"
+              }
+            }
+          },
+          "description": "Contexto del navegador",
+          "required": false
+        },
+        "responses": {
+          "201": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/DeviceLinkCreateResponse"
+                }
+              }
+            },
+            "description": "linkCode para el QR"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Datos inválidos"
+          }
+        },
+        "security": [],
+        "summary": "Cross-device — la web pide un QR",
+        "tags": [
+          "auth"
+        ]
+      }
+    },
+    "/v1/device-links/{link_code}": {
+      "get": {
+        "callbacks": {},
+        "description": "Devuelve `pending` (sigue esperando), `linked` (aprobado: incluye `user` y el `token` de sesión web, SOLO en el primer poll) o `denied`. Público: el `linkCode` es la credencial.",
+        "operationId": "get /v1/device-links/{link_code}",
+        "parameters": [
+          {
+            "description": "El `linkCode` del QR (`dlnk_…`).",
+            "in": "path",
+            "name": "link_code",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "x-struct": null,
+              "x-validate": null
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/DeviceLinkStatusResponse"
+                }
+              }
+            },
+            "description": "Estado del flujo"
+          },
+          "404": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Código inexistente o expirado"
+          },
+          "409": {
             "content": {
               "application/json": {
                 "schema": {
@@ -13966,6 +14633,61 @@
         ]
       }
     },
+    "/v1/invitations": {
+      "post": {
+        "callbacks": {},
+        "description": "Crea una invitación por **email** con un rol opcional (`{\"invitation\": {\"email\": \"…\", \"role_id\": \"role_…\"}}`). Al aceptarla, la persona queda como miembro de la organización y podrá iniciar sesión como operador (member session `mem_…`). La org sale del token (org-less), como el resto de la superficie de máquina. Requiere el permiso `invitations:create` (preset `team_admin`).",
+        "operationId": "post /v1/invitations",
+        "parameters": [],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/InvitationRequest"
+              }
+            }
+          },
+          "description": "Datos de la invitación",
+          "required": false
+        },
+        "responses": {
+          "201": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/InvitationResponse"
+                }
+              }
+            },
+            "description": "Invitación creada"
+          },
+          "403": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Sin permiso"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Error de validación"
+          }
+        },
+        "summary": "Invitar a un operador por email (bootstrap del equipo, credencial de máquina)",
+        "tags": [
+          "invitations"
+        ]
+      }
+    },
     "/v1/invitations/accept": {
       "post": {
         "callbacks": {},
@@ -16390,16 +17112,229 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/UsernameAvailableResponse"
+                  "$ref": "#/components/schemas/UsernameAvailableResponse"
+                }
+              }
+            },
+            "description": "Disponibilidad"
+          }
+        },
+        "summary": "¿Está disponible este username? (check en vivo del alta/cambio)",
+        "tags": [
+          "people"
+        ]
+      }
+    },
+    "/v1/members": {
+      "post": {
+        "callbacks": {},
+        "description": "Crea al operador y su membresía ACTIVA al instante. Devuelve un `passwordSetupToken` para que la persona fije su contraseña (no se comparte ninguna contraseña generada). Requiere `organization_memberships:create` (preset `team_admin`).",
+        "operationId": "post /v1/members",
+        "parameters": [],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ProvisionMemberRequest"
+              }
+            }
+          },
+          "description": "Datos del operador",
+          "required": false
+        },
+        "responses": {
+          "201": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProvisionMemberResponse"
+                }
+              }
+            },
+            "description": "Operador dado de alta"
+          },
+          "403": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Sin permiso"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Error de validación"
+          }
+        },
+        "summary": "Dar de alta un operador directo (sin invitación)",
+        "tags": [
+          "members"
+        ]
+      }
+    },
+    "/v1/members/me": {
+      "get": {
+        "callbacks": {},
+        "description": "Devuelve el miembro de la member session actual: id, email, nombre visible y sus roles. El equivalente a `getCurrentUser` de una app interna.",
+        "operationId": "get /v1/members/me",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/MemberResponse"
+                }
+              }
+            },
+            "description": "El miembro actual"
+          },
+          "401": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Sesión inválida"
+          }
+        },
+        "security": [
+          {
+            "memberToken": []
+          }
+        ],
+        "summary": "El miembro autenticado (quién soy)",
+        "tags": [
+          "members"
+        ]
+      }
+    },
+    "/v1/members/session": {
+      "delete": {
+        "callbacks": {},
+        "description": "Revoca el member session token. Idempotente.",
+        "operationId": "delete /v1/members/session",
+        "parameters": [],
+        "responses": {
+          "204": {
+            "description": "Sesión cerrada"
+          }
+        },
+        "security": [
+          {
+            "memberToken": []
+          }
+        ],
+        "summary": "Cerrar la sesión de miembro (logout)",
+        "tags": [
+          "members"
+        ]
+      },
+      "post": {
+        "callbacks": {},
+        "description": "Autentica a un miembro humano (empleado que opera la org) por email+password y devuelve un member session token (`mem_…`) que porta su rol. La organización sale de la API key de la app. Es el login de operador de una app interna (patrón Organizations+Members).",
+        "operationId": "post /v1/members/session",
+        "parameters": [],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MemberLoginRequest"
+              }
+            }
+          },
+          "description": "Credenciales del miembro",
+          "required": false
+        },
+        "responses": {
+          "201": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/MemberSessionResponse"
+                }
+              }
+            },
+            "description": "Sesión de miembro"
+          },
+          "401": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "API key o credenciales inválidas"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Datos inválidos"
+          }
+        },
+        "security": [
+          {
+            "apiKey": []
+          }
+        ],
+        "summary": "Iniciar sesión de un miembro de la organización (login)",
+        "tags": [
+          "members"
+        ]
+      }
+    },
+    "/v1/members/session/refresh": {
+      "post": {
+        "callbacks": {},
+        "description": "Rota el member session token: revoca el actual y emite uno nuevo para la misma membresía (patrón WorkOS refresh). Autenticado por el `mem_` actual.",
+        "operationId": "post /v1/members/session/refresh",
+        "parameters": [],
+        "responses": {
+          "201": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/MemberSessionResponse"
+                }
+              }
+            },
+            "description": "Nueva sesión"
+          },
+          "401": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
                 }
               }
             },
-            "description": "Disponibilidad"
+            "description": "Sesión inválida"
           }
         },
-        "summary": "¿Está disponible este username? (check en vivo del alta/cambio)",
+        "security": [
+          {
+            "memberToken": []
+          }
+        ],
+        "summary": "Renovar la sesión de miembro",
         "tags": [
-          "people"
+          "members"
         ]
       }
     },
@@ -18966,6 +19901,83 @@
         ]
       }
     },
+    "/v1/organizations/{organization_id}/aggregate": {
+      "post": {
+        "callbacks": {},
+        "description": "Agrupa records por `dimensions` y calcula `measures` (count/sum/avg/min/max), bajo la misma gobernanza (RBAC + ABAC default-deny) que la lectura puntual. Reemplaza los reportes que serían RPCs de SQL por-tenant.",
+        "operationId": "post /v1/organizations/{organization_id}/aggregate",
+        "parameters": [
+          {
+            "description": "",
+            "in": "path",
+            "name": "organization_id",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "x-struct": null,
+              "x-validate": null
+            }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AggregateQueryRequest"
+              }
+            }
+          },
+          "description": "Aggregation query",
+          "required": false
+        },
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AggregateResultResponse"
+                }
+              }
+            },
+            "description": "Grupos agregados"
+          },
+          "403": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Sin permiso"
+          },
+          "404": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Objeto desconocido"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Consulta inválida"
+          }
+        },
+        "summary": "Ejecutar una aggregation query",
+        "tags": [
+          "query"
+        ]
+      }
+    },
     "/v1/organizations/{organization_id}/api-keys": {
       "get": {
         "callbacks": {},
@@ -29338,6 +30350,86 @@
         ]
       }
     },
+    "/v1/public/aggregate": {
+      "post": {
+        "callbacks": {},
+        "description": "Agrupa records por `dimensions` y calcula `measures` (count/sum/avg/min/max), autenticado por una API key. Bajo el MISMO default-deny que la lectura: solo agrega lo que las policies exponen al principal `public`/`end_user`.",
+        "operationId": "post /v1/public/aggregate",
+        "parameters": [],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AggregateQueryRequest"
+              }
+            }
+          },
+          "description": "Aggregation query",
+          "required": false
+        },
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AggregateResultResponse"
+                }
+              }
+            },
+            "description": "Grupos agregados"
+          },
+          "401": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Token inválido"
+          },
+          "403": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Sin permiso"
+          },
+          "404": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Objeto o tenant desconocido"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Consulta inválida"
+          }
+        },
+        "security": [
+          {
+            "apiKey": []
+          }
+        ],
+        "summary": "Agregar por la Data API pública (reportes)",
+        "tags": [
+          "public"
+        ]
+      }
+    },
     "/v1/public/end-users": {
       "post": {
         "callbacks": {},
@@ -29478,6 +30570,86 @@
         ]
       }
     },
+    "/v1/public/me/aggregate": {
+      "post": {
+        "callbacks": {},
+        "description": "Agrupa records por `dimensions` y calcula `measures` (count/sum/avg/min/max), autenticado por una API key. Bajo el MISMO default-deny que la lectura: solo agrega lo que las policies exponen al principal `public`/`end_user`.",
+        "operationId": "post /v1/public/me/aggregate",
+        "parameters": [],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AggregateQueryRequest"
+              }
+            }
+          },
+          "description": "Aggregation query",
+          "required": false
+        },
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AggregateResultResponse"
+                }
+              }
+            },
+            "description": "Grupos agregados"
+          },
+          "401": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Token inválido"
+          },
+          "403": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Sin permiso"
+          },
+          "404": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Objeto o tenant desconocido"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Consulta inválida"
+          }
+        },
+        "security": [
+          {
+            "apiKey": []
+          }
+        ],
+        "summary": "Agregar por la Data API pública (reportes)",
+        "tags": [
+          "public"
+        ]
+      }
+    },
     "/v1/public/me/checkout": {
       "post": {
         "callbacks": {},
@@ -30861,6 +32033,39 @@
         ]
       }
     },
+    "/v1/roles": {
+      "get": {
+        "callbacks": {},
+        "operationId": "get /v1/roles",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/RolesResponse"
+                }
+              }
+            },
+            "description": "Roles"
+          },
+          "403": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Sin permiso"
+          }
+        },
+        "summary": "Listar los roles de la organización (para asignar al invitar)",
+        "tags": [
+          "roles"
+        ]
+      }
+    },
     "/v1/sso/callback": {
       "post": {
         "callbacks": {},