@hablala/api-contract 0.6.0 → 0.7.0

package/openapi.json

@@ -3,7 +3,7 @@
     "responses": {},
     "schemas": {
       "AccessToken": {
-        "description": "Metadatos de un access token de máquina (`hpat_…`): la credencial con la que un agente (Claude Code) o un script CI escribe el modelo de datos por HTTP. El secreto en claro NO se incluye aquí — solo se devuelve una vez, al crearlo.",
+        "description": "Metadatos de un access token de máquina (`mat_…`): la credencial con la que un agente (Claude Code) o un script CI escribe el modelo de datos por HTTP. El secreto en claro NO se incluye aquí — solo se devuelve una vez, al crearlo.",
         "properties": {
           "active": {
             "description": "¿Ni revocado ni expirado?",
@@ -54,7 +54,7 @@
             "x-validate": null
           },
           "prefix": {
-            "description": "Primeros caracteres del secreto (no secreto), p. ej. `hpat_a1b2`.",
+            "description": "Primeros caracteres del secreto (no secreto), p. ej. `mat_a1b2`.",
             "nullable": true,
             "type": "string",
             "x-struct": null,
@@ -147,7 +147,7 @@
             "x-validate": null
           },
           "token": {
-            "description": "El secreto en claro (`hpat_…`). Solo en esta respuesta.",
+            "description": "El secreto en claro (`mat_…`). Solo en esta respuesta.",
             "type": "string",
             "x-struct": null,
             "x-validate": null
@@ -246,7 +246,7 @@
             "x-validate": null
           },
           "name": {
-            "description": "Etiqueta para identificarlo en el panel.",
+            "description": "Etiqueta opcional para el panel. Por defecto: \"Default\".",
             "type": "string",
             "x-struct": null,
             "x-validate": null
@@ -269,9 +269,6 @@
             "x-validate": null
           }
         },
-        "required": [
-          "name"
-        ],
         "title": "AccessTokenRequest",
         "type": "object",
         "x-struct": "Elixir.HablalaApiWeb.Schemas.AccessTokenRequest",
@@ -953,6 +950,17 @@
             "x-struct": null,
             "x-validate": null
           },
+          "packages": {
+            "description": "Los verticales instalables sobre el core horizontal (p. ej. `commerce`, `crm`). El server materializa sus objects (seeded, con su `package`) desde su definición propia; el manifiesto solo declara los NOMBRES. Instalar es idempotente; declarar no desinstala.",
+            "items": {
+              "type": "string",
+              "x-struct": null,
+              "x-validate": null
+            },
+            "type": "array",
+            "x-struct": null,
+            "x-validate": null
+          },
           "policies": {
             "oneOf": [
               {
@@ -1828,8 +1836,41 @@
         "x-struct": "Elixir.HablalaApiWeb.Schemas.ApiKeyCreatedResponse",
         "x-validate": null
       },
+      "ApiKeyPairCreated": {
+        "description": "El par de API keys recién creado: la publishable (`pk_`) y la secret (`sk_`), cada una con su secreto en claro (`token`) presente UNA sola vez. Guárdalos: no se pueden recuperar.",
+        "properties": {
+          "publishable": {
+            "$ref": "#/components/schemas/ApiKeyCreated"
+          },
+          "secret": {
+            "$ref": "#/components/schemas/ApiKeyCreated"
+          }
+        },
+        "required": [
+          "publishable",
+          "secret"
+        ],
+        "title": "ApiKeyPairCreated",
+        "type": "object",
+        "x-struct": "Elixir.HablalaApiWeb.Schemas.ApiKeyPairCreated",
+        "x-validate": null
+      },
+      "ApiKeyPairCreatedResponse": {
+        "properties": {
+          "data": {
+            "$ref": "#/components/schemas/ApiKeyPairCreated"
+          }
+        },
+        "required": [
+          "data"
+        ],
+        "title": "ApiKeyPairCreatedResponse",
+        "type": "object",
+        "x-struct": "Elixir.HablalaApiWeb.Schemas.ApiKeyPairCreatedResponse",
+        "x-validate": null
+      },
       "ApiKeyRequest": {
-        "description": "Datos para emitir una API key. Todos opcionales (kind por defecto: publishable).",
+        "description": "Datos para emitir el par de API keys. Todos opcionales: `name` por defecto \"Default\" (lo comparten ambas keys del par). `kind` solo aplica a la vía avanzada de una sola key.",
         "properties": {
           "expiresAt": {
             "description": "Caducidad opcional (ISO 8601). Omitir = no caduca.",
@@ -1839,7 +1880,7 @@
             "x-validate": null
           },
           "kind": {
-            "description": "Por defecto: publishable.",
+            "description": "Solo vía avanzada (una key). Por defecto: publishable.",
             "enum": [
               "publishable",
               "secret"
@@ -1849,7 +1890,7 @@
             "x-validate": null
           },
           "name": {
-            "description": "Etiqueta para identificarla en el panel.",
+            "description": "Etiqueta opcional para el panel. Por defecto: \"Default\".",
             "type": "string",
             "x-struct": null,
             "x-validate": null
@@ -2638,6 +2679,29 @@
         "x-struct": "Elixir.HablalaApiWeb.Schemas.AvailabilityRequest",
         "x-validate": null
       },
+      "AvailabilityResponse": {
+        "description": "Disponibilidad de compra por variante (patrón Shopify `availableForSale`): un mapa id-público → booleano. `true` = comprable (activa y con stock). Se expone el booleano derivado, no el conteo de stock (mínima exposición).",
+        "properties": {
+          "availability": {
+            "additionalProperties": {
+              "type": "boolean",
+              "x-struct": null,
+              "x-validate": null
+            },
+            "description": "Mapa `variantId` (`rec_…`) → `true`/`false` (comprable).",
+            "type": "object",
+            "x-struct": null,
+            "x-validate": null
+          }
+        },
+        "required": [
+          "availability"
+        ],
+        "title": "AvailabilityResponse",
+        "type": "object",
+        "x-struct": "Elixir.HablalaApiWeb.Schemas.AvailabilityResponse",
+        "x-validate": null
+      },
       "BanMemberRequest": {
         "description": "Banea a un miembro del grupo (bloqueo, estilo Telegram). Sin `until` = ban permanente; con `until` = ban temporal que expira en esa fecha.",
         "properties": {
@@ -3125,6 +3189,60 @@
         "x-struct": "Elixir.HablalaApiWeb.Schemas.ChannelRequest",
         "x-validate": null
       },
+      "CheckoutItem": {
+        "description": "Un artículo del checkout: qué variante comprar y cuántas unidades.",
+        "properties": {
+          "quantity": {
+            "description": "Unidades a comprar (≥ 1).",
+            "minimum": 1,
+            "type": "integer",
+            "x-struct": null,
+            "x-validate": null
+          },
+          "variantId": {
+            "description": "Id público (`rec_…`) del `product_variant`.",
+            "type": "string",
+            "x-struct": null,
+            "x-validate": null
+          }
+        },
+        "required": [
+          "variantId",
+          "quantity"
+        ],
+        "title": "CheckoutItem",
+        "type": "object",
+        "x-struct": "Elixir.HablalaApiWeb.Schemas.CheckoutItem",
+        "x-validate": null
+      },
+      "CheckoutRequest": {
+        "description": "Checkout nativo: los artículos del carrito + la moneda. El pedido se ata al usuario final identificado por la sesión (`sess_…`), no a un cliente enviado por el cuerpo.",
+        "properties": {
+          "currency": {
+            "description": "Código ISO 4217 (MXN, USD, EUR).",
+            "type": "string",
+            "x-struct": null,
+            "x-validate": null
+          },
+          "items": {
+            "items": {
+              "$ref": "#/components/schemas/CheckoutItem"
+            },
+            "minItems": 1,
+            "type": "array",
+            "x-struct": null,
+            "x-validate": null
+          }
+        },
+        "required": [
+          "items",
+          "currency"
+        ],
+        "title": "CheckoutRequest",
+        "type": "object",
+        "x-struct": "Elixir.HablalaApiWeb.Schemas.CheckoutRequest",
+        "x-validate": null
+      },
       "ContactContent": {
         "description": "Payload de un mensaje `contact` (compartir contacto, estilo WhatsApp). El cliente pinta una tarjeta con acción 'Agregar a contactos'. `vcard` es el vCard crudo opcional (fuente de verdad para importar); `name`/`phones` son la vista renderizable.",
         "properties": {
@@ -4498,6 +4616,75 @@
         "x-struct": "Elixir.HablalaApiWeb.Schemas.EventsResponse",
         "x-validate": null
       },
+      "FileEnvelope": {
+        "description": "Un archivo dentro del valor de un atributo `data_type: file` (siempre un array de estos, aun para un solo archivo). Solo `url` es obligatoria; el resto es metadata para renderizar sin un HEAD por archivo. La `url` DEBE ser del storage de la plataforma (subida por el flujo de upload prefirmado) — una URL externa se rechaza.",
+        "properties": {
+          "blurhash": {
+            "description": "Placeholder BlurHash de la imagen (preview borroso instantáneo). Null si no es imagen.",
+            "nullable": true,
+            "type": "string",
+            "x-struct": null,
+            "x-validate": null
+          },
+          "content_type": {
+            "nullable": true,
+            "type": "string",
+            "x-struct": null,
+            "x-validate": null
+          },
+          "duration_ms": {
+            "description": "Duración del medio en milisegundos (audio/video). Permite pintar el reproductor sin descargar.",
+            "minimum": 0,
+            "nullable": true,
+            "type": "integer",
+            "x-struct": null,
+            "x-validate": null
+          },
+          "filename": {
+            "nullable": true,
+            "type": "string",
+            "x-struct": null,
+            "x-validate": null
+          },
+          "height": {
+            "description": "Alto en px.",
+            "minimum": 0,
+            "nullable": true,
+            "type": "integer",
+            "x-struct": null,
+            "x-validate": null
+          },
+          "size": {
+            "description": "Tamaño en bytes.",
+            "minimum": 0,
+            "nullable": true,
+            "type": "integer",
+            "x-struct": null,
+            "x-validate": null
+          },
+          "url": {
+            "description": "URL permanente del blob en el object storage (la que devuelve el presign).",
+            "type": "string",
+            "x-struct": null,
+            "x-validate": null
+          },
+          "width": {
+            "description": "Ancho en px (para reservar el aspect-ratio y evitar layout shift).",
+            "minimum": 0,
+            "nullable": true,
+            "type": "integer",
+            "x-struct": null,
+            "x-validate": null
+          }
+        },
+        "required": [
+          "url"
+        ],
+        "title": "FileEnvelope",
+        "type": "object",
+        "x-struct": "Elixir.HablalaApiWeb.Schemas.FileEnvelope",
+        "x-validate": null
+      },
       "Friend": {
         "properties": {
           "displayName": {
@@ -4804,7 +4991,7 @@
         "x-validate": null
       },
       "GraphNode": {
-        "description": "Un nodo del grafo de datos: un record, con su object, su título y su grado.",
+        "description": "Un nodo del grafo de datos: un record, con su object, su título, su imagen representativa y su grado.",
         "properties": {
           "degree": {
             "description": "Nº de aristas incidentes al nodo (grado). El cliente lo usa para el tamaño.",
@@ -4818,6 +5005,13 @@
             "x-struct": null,
             "x-validate": null
           },
+          "imageUrl": {
+            "description": "URL de la imagen representativa del record (primer atributo file de tipo imagen, respetando el field_mask), o null. El cliente la pinta como avatar del nodo; sin ella, el nodo es el círculo tintado por object.",
+            "nullable": true,
+            "type": "string",
+            "x-struct": null,
+            "x-validate": null
+          },
           "objectSlug": {
             "description": "Slug del object del record (para color/navegación).",
             "type": "string",
@@ -8084,7 +8278,7 @@
         "x-validate": null
       },
       "OauthGrantApproveRequest": {
-        "description": "Aprobación del consent: qué permisos tendrá el token (mismas reglas que emitir un `hpat_` en el panel: `preset` gana, y todo se intersecta con los permisos del aprobador).",
+        "description": "Aprobación del consent: qué permisos tendrá el token (mismas reglas que emitir un `mat_` en el panel: `preset` gana, y todo se intersecta con los permisos del aprobador).",
         "properties": {
           "permissions": {
             "description": "Permisos crudos `recurso:accion` (vía avanzada).",
@@ -8175,10 +8369,10 @@
         "x-validate": null
       },
       "OauthTokenResponse": {
-        "description": "Éxito del token endpoint (RFC 6749 §5.1): el `access_token` es un `hpat_…` normal (la misma credencial que emite el panel), mostrado UNA sola vez.",
+        "description": "Éxito del token endpoint (RFC 6749 §5.1): el `access_token` es un `mat_…` normal (la misma credencial que emite el panel), mostrado UNA sola vez.",
         "properties": {
           "access_token": {
-            "description": "El secreto `hpat_…` en claro.",
+            "description": "El secreto `mat_…` en claro.",
             "type": "string",
             "x-struct": null,
             "x-validate": null
@@ -8407,6 +8601,63 @@
         "x-struct": "Elixir.HablalaApiWeb.Schemas.ObjectsResponse",
         "x-validate": null
       },
+      "OrderLineItem": {
+        "description": "Un renglón del pedido: la variante comprada con snapshots de título/sku/precio (el catálogo puede cambiar después). `id` + `properties` como cualquier record del diccionario.",
+        "properties": {
+          "id": {
+            "type": "string",
+            "x-struct": null,
+            "x-validate": null
+          },
+          "properties": {
+            "description": "Valores del renglón por slug: `variant_ref`, `product_ref`, `title`, `sku`, `quantity`, `unit_price` (centavos), `line_total` (centavos).",
+            "type": "object",
+            "x-struct": null,
+            "x-validate": null
+          }
+        },
+        "required": [
+          "id",
+          "properties"
+        ],
+        "title": "OrderLineItem",
+        "type": "object",
+        "x-struct": "Elixir.HablalaApiWeb.Schemas.OrderLineItem",
+        "x-validate": null
+      },
+      "OrderResponse": {
+        "description": "El pedido recién creado por el checkout, con sus renglones. `properties` trae el `order_number` (#1001), `financial_status` (nace `pending`), `fulfillment_status` (nace `unfulfilled`), `total_amount` (centavos), `currency` y `customer`.",
+        "properties": {
+          "id": {
+            "type": "string",
+            "x-struct": null,
+            "x-validate": null
+          },
+          "lineItems": {
+            "items": {
+              "$ref": "#/components/schemas/OrderLineItem"
+            },
+            "type": "array",
+            "x-struct": null,
+            "x-validate": null
+          },
+          "properties": {
+            "description": "Valores del pedido por slug (order_number, financial_status, total_amount…).",
+            "type": "object",
+            "x-struct": null,
+            "x-validate": null
+          }
+        },
+        "required": [
+          "id",
+          "properties",
+          "lineItems"
+        ],
+        "title": "OrderResponse",
+        "type": "object",
+        "x-struct": "Elixir.HablalaApiWeb.Schemas.OrderResponse",
+        "x-validate": null
+      },
       "Organization": {
         "properties": {
           "avatarUrl": {
@@ -9321,6 +9572,14 @@
             "x-struct": null,
             "x-validate": null
           },
+          "maxSize": {
+            "description": "Tope de bytes que el servidor FIRMA en el borde (POST policy `content-length-range`): un cuerpo mayor se rechaza con 413, sin confiar en el cliente. Tómalo del `max_size_bytes` del atributo `file`.",
+            "minimum": 1,
+            "nullable": true,
+            "type": "integer",
+            "x-struct": null,
+            "x-validate": null
+          },
           "purpose": {
             "description": "Uso del archivo. `avatar` restringe el `contentType` a imágenes (perfil de usuario / icono de org). Omitir para adjuntos genéricos.",
             "enum": [
@@ -9355,37 +9614,56 @@
         "x-validate": null
       },
       "PresignResult": {
+        "description": "Sobre de subida auto-descriptivo. El cliente OBEDECE `method`: `POST` → arma un form multipart con TODOS los `fields` y añade el archivo como el campo `file` al final, luego hace POST a `url`; `PUT` → hace PUT del blob crudo a `url` con `headers`. En ambos, `fileUrl` es la URL final del blob.",
         "properties": {
+          "fields": {
+            "additionalProperties": {
+              "type": "string",
+              "x-struct": null,
+              "x-validate": null
+            },
+            "description": "Campos del form multipart a enviar ANTES del archivo (POST policy: `key`, `Content-Type`, `Policy`, firma…). Vacío cuando `method` es `PUT`.",
+            "type": "object",
+            "x-struct": null,
+            "x-validate": null
+          },
           "fileUrl": {
-            "description": "URL final del blob; va en el `attachment` del mensaje.",
+            "description": "URL final del blob; va en el `attachment` del mensaje o el atributo `file`.",
             "type": "string",
             "x-struct": null,
             "x-validate": null
           },
           "headers": {
-            "description": "Cabeceras que el cliente debe enviar en el PUT.",
+            "additionalProperties": {
+              "type": "string",
+              "x-struct": null,
+              "x-validate": null
+            },
+            "description": "Cabeceras que el cliente envía en el `PUT`. Vacío cuando `method` es `POST`.",
             "type": "object",
             "x-struct": null,
             "x-validate": null
           },
           "method": {
+            "description": "Cómo subir: `POST` (form multipart, POST policy) o `PUT` (blob directo).",
             "enum": [
+              "POST",
               "PUT"
             ],
             "type": "string",
             "x-struct": null,
             "x-validate": null
           },
-          "uploadUrl": {
-            "description": "Destino del PUT del blob.",
+          "url": {
+            "description": "Destino de la subida.",
             "type": "string",
             "x-struct": null,
             "x-validate": null
           }
         },
         "required": [
-          "uploadUrl",
           "method",
+          "url",
           "fileUrl"
         ],
         "title": "PresignResult",
@@ -9393,6 +9671,49 @@
         "x-struct": "Elixir.HablalaApiWeb.Schemas.PresignResult",
         "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": {
+          "avatarUrl": {
+            "description": "Logo/icono de la marca (el \"server icon\" del tenant), o `null`.",
+            "nullable": true,
+            "type": "string",
+            "x-struct": null,
+            "x-validate": null
+          },
+          "id": {
+            "description": "ID público de la organización.",
+            "type": "string",
+            "x-struct": null,
+            "x-validate": null
+          },
+          "name": {
+            "description": "Nombre visible de la marca.",
+            "type": "string",
+            "x-struct": null,
+            "x-validate": null
+          },
+          "settings": {
+            "$ref": "#/components/schemas/ManifestSettings"
+          },
+          "slug": {
+            "description": "Slug estable de la organización.",
+            "type": "string",
+            "x-struct": null,
+            "x-validate": null
+          }
+        },
+        "required": [
+          "id",
+          "name",
+          "slug",
+          "settings"
+        ],
+        "title": "PublicOrganization",
+        "type": "object",
+        "x-struct": "Elixir.HablalaApiWeb.Schemas.PublicOrganization",
+        "x-validate": null
+      },
       "PublicSchema": {
         "properties": {
           "objects": {
@@ -9403,6 +9724,9 @@
             "x-struct": null,
             "x-validate": null
           },
+          "organization": {
+            "$ref": "#/components/schemas/PublicOrganization"
+          },
           "relationships": {
             "items": {
               "$ref": "#/components/schemas/PublicSchemaRelationship"
@@ -9413,6 +9737,7 @@
           }
         },
         "required": [
+          "organization",
           "objects",
           "relationships"
         ],
@@ -9948,13 +10273,58 @@
             "x-validate": null
           },
           "properties": {
-            "type": "object",
-            "x-struct": null,
-            "x-validate": null
-          },
-          "referenceLabels": {
             "additionalProperties": {
-              "properties": {
+              "oneOf": [
+                {
+                  "items": {
+                    "$ref": "#/components/schemas/FileEnvelope"
+                  },
+                  "type": "array",
+                  "x-struct": null,
+                  "x-validate": null
+                },
+                {
+                  "type": "string",
+                  "x-struct": null,
+                  "x-validate": null
+                },
+                {
+                  "type": "number",
+                  "x-struct": null,
+                  "x-validate": null
+                },
+                {
+                  "type": "boolean",
+                  "x-struct": null,
+                  "x-validate": null
+                },
+                {
+                  "items": {
+                    "type": "string",
+                    "x-struct": null,
+                    "x-validate": null
+                  },
+                  "type": "array",
+                  "x-struct": null,
+                  "x-validate": null
+                },
+                {
+                  "type": "object",
+                  "x-struct": null,
+                  "x-validate": null
+                }
+              ],
+              "x-struct": null,
+              "x-validate": null
+            },
+            "description": "Mapa slug→valor. El valor de un atributo `data_type: file` es un array de `FileEnvelope`; el resto de tipos son escalares/arrays/objetos según el `data_type` del atributo.",
+            "type": "object",
+            "x-struct": null,
+            "x-validate": null
+          },
+          "referenceLabels": {
+            "additionalProperties": {
+              "properties": {
                 "label": {
                   "type": "string",
                   "x-struct": null,
@@ -9995,10 +10365,76 @@
         "x-struct": "Elixir.HablalaApiWeb.Schemas.Record",
         "x-validate": null
       },
+      "RecordDependencies": {
+        "description": "Preview del impacto de borrar un record, SIN borrarlo (confirmación dependent-aware, patrón Salesforce/Notion). `edgeCount` = relaciones del grafo que se desvincularían (el vecino sobrevive). `blockers` = referencias core activas que IMPEDIRÍAN el borrado (restrict-on-delete); `deletable: false` si hay alguna.",
+        "properties": {
+          "data": {
+            "properties": {
+              "blockers": {
+                "description": "Referencias core activas que bloquean; vacía si se puede borrar.",
+                "items": {
+                  "properties": {
+                    "count": {
+                      "minimum": 1,
+                      "type": "integer",
+                      "x-struct": null,
+                      "x-validate": null
+                    },
+                    "label": {
+                      "description": "Etiqueta legible (p. ej. \"facturas sin cerrar\").",
+                      "type": "string",
+                      "x-struct": null,
+                      "x-validate": null
+                    }
+                  },
+                  "required": [
+                    "count",
+                    "label"
+                  ],
+                  "type": "object",
+                  "x-struct": null,
+                  "x-validate": null
+                },
+                "type": "array",
+                "x-struct": null,
+                "x-validate": null
+              },
+              "deletable": {
+                "description": "`false` si algún blocker impediría el borrado.",
+                "type": "boolean",
+                "x-struct": null,
+                "x-validate": null
+              },
+              "edgeCount": {
+                "description": "Aristas del grafo (ambos extremos) que se romperían al borrar.",
+                "minimum": 0,
+                "type": "integer",
+                "x-struct": null,
+                "x-validate": null
+              }
+            },
+            "required": [
+              "edgeCount",
+              "deletable",
+              "blockers"
+            ],
+            "type": "object",
+            "x-struct": null,
+            "x-validate": null
+          }
+        },
+        "required": [
+          "data"
+        ],
+        "title": "RecordDependencies",
+        "type": "object",
+        "x-struct": "Elixir.HablalaApiWeb.Schemas.RecordDependencies",
+        "x-validate": null
+      },
       "RecordInput": {
         "properties": {
           "properties": {
-            "description": "Mapa slug→valor validado contra el diccionario. Un atributo `reference` acepta el id público del record destino (`\"rec_…\"`) o, como azúcar de DX, una **referencia por clave de negocio**: `{\"$ref\": {\"<attr>\": <valor>}}`, donde `<attr>` es un atributo único del objeto destino (p. ej. `{\"$ref\": {\"sku\": \"DRM-VITC-30\"}}`). Se resuelve al `rec_…` en el servidor — útil para sincronizar por external id sin conocer el id de Hablalá (patrón Salesforce/Airtable).",
+            "description": "Mapa slug→valor validado contra el diccionario. Un atributo `reference` acepta el id público del record destino (`\"rec_…\"`) o, como azúcar de DX, una **referencia por clave de negocio**: `{\"$ref\": {\"<attr>\": <valor>}}`, donde `<attr>` es un atributo único del objeto destino (p. ej. `{\"$ref\": {\"sku\": \"DRM-VITC-30\"}}`). Se resuelve al `rec_…` en el servidor — útil para sincronizar por external id sin conocer el id de Hablalá (patrón Salesforce/Airtable). Un atributo `data_type: file` toma un array de `FileEnvelope`: la `url` de cada archivo debe venir del flujo de upload prefirmado (una URL externa se rechaza).",
             "type": "object",
             "x-struct": null,
             "x-validate": null
@@ -11482,6 +11918,29 @@
         "x-struct": "Elixir.HablalaApiWeb.Schemas.UsernameAvailableResponse",
         "x-validate": null
       },
+      "VariantAvailabilityRequest": {
+        "description": "Los ids públicos (`rec_…`) de las variantes cuya disponibilidad de compra se consulta (una llamada resuelve toda una página de catálogo).",
+        "properties": {
+          "variantIds": {
+            "items": {
+              "description": "Id público (`rec_…`) de un `product_variant`.",
+              "type": "string",
+              "x-struct": null,
+              "x-validate": null
+            },
+            "type": "array",
+            "x-struct": null,
+            "x-validate": null
+          }
+        },
+        "required": [
+          "variantIds"
+        ],
+        "title": "VariantAvailabilityRequest",
+        "type": "object",
+        "x-struct": "Elixir.HablalaApiWeb.Schemas.VariantAvailabilityRequest",
+        "x-validate": null
+      },
       "VerificationRejectRequest": {
         "properties": {
           "reason": {
@@ -14935,7 +15394,7 @@
     "/v1/me/uploads/presign": {
       "post": {
         "callbacks": {},
-        "description": "Como el presign de organización, pero el blob se namespacea por usuario. El cliente hace `PUT` a `uploadUrl` y referencia `fileUrl` en los adjuntos del mensaje.",
+        "description": "Como el presign de organización, pero el blob se namespacea por usuario. Devuelve un sobre auto-descriptivo (`method`/`url`/`fields`/`headers`); el cliente sube según `method` y referencia `fileUrl` en los adjuntos del mensaje.",
         "operationId": "HablalaApiWeb.Me.UploadController.presign",
         "parameters": [],
         "requestBody": {
@@ -14958,7 +15417,7 @@
                 }
               }
             },
-            "description": "URL prefirmada"
+            "description": "Sobre de subida prefirmado"
           },
           "415": {
             "content": {
@@ -14971,7 +15430,7 @@
             "description": "Tipo de archivo no soportado"
           }
         },
-        "summary": "Pedir una URL de subida prefirmada (adjunto personal)",
+        "summary": "Pedir un sobre de subida prefirmado (adjunto personal)",
         "tags": [
           "personal uploads"
         ]
@@ -15172,7 +15631,7 @@
     "/v1/oauth/token": {
       "post": {
         "callbacks": {},
-        "description": "`grant_type=authorization_code` (loopback + PKCE) o `grant_type=urn:ietf:params:oauth:grant-type:device_code` (polling del device flow). El `access_token` devuelto es un `hpat_…` normal; guárdalo, no se puede recuperar.",
+        "description": "`grant_type=authorization_code` (loopback + PKCE) o `grant_type=urn:ietf:params:oauth:grant-type:device_code` (polling del device flow). El `access_token` devuelto es un `mat_…` normal; guárdalo, no se puede recuperar.",
         "operationId": "HablalaApiWeb.Oauth.TokenController.create",
         "parameters": [],
         "requestBody": {
@@ -15756,6 +16215,84 @@
         ]
       }
     },
+    "/v1/objects/{object_slug}/records/trash": {
+      "get": {
+        "callbacks": {},
+        "description": "Lista los records SOFT-DELETED del objeto (`deleted_at IS NOT NULL`), para restaurarlos. Misma lectura gobernada que `POST /query` (RBAC + ABAC por fila + field_mask + paginación keyset), sobre el otro lado de `deleted_at`. Gate RBAC: `records:delete`.",
+        "operationId": "HablalaApiWeb.Machine.RecordController.trash",
+        "parameters": [
+          {
+            "description": "",
+            "in": "path",
+            "name": "object_slug",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "x-struct": null,
+              "x-validate": null
+            }
+          },
+          {
+            "description": "",
+            "in": "query",
+            "name": "limit",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "x-struct": null,
+              "x-validate": null
+            }
+          },
+          {
+            "description": "",
+            "in": "query",
+            "name": "cursor",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "x-struct": null,
+              "x-validate": null
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/QueryResultResponse"
+                }
+              }
+            },
+            "description": "Records borrados"
+          },
+          "403": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Sin permiso"
+          },
+          "404": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Objeto desconocido"
+          }
+        },
+        "summary": "Listar los records borrados (soft) del objeto — la Papelera",
+        "tags": [
+          "records"
+        ]
+      }
+    },
     "/v1/objects/{object_slug}/records/{id}": {
       "delete": {
         "callbacks": {},
@@ -16049,6 +16586,73 @@
         ]
       }
     },
+    "/v1/objects/{object_slug}/records/{record_id}/dependencies": {
+      "get": {
+        "callbacks": {},
+        "description": "Devuelve cuántos edges se desvincularían y qué referencias core BLOQUEARÍAN el borrado (restrict-on-delete), sin mutar nada. Alimenta la confirmación dependent-aware de la UI. Misma fuente que el guard del borrado real, así que preview y borrado no divergen. Gate `records:delete` + ABAC de escritura por fila.",
+        "operationId": "HablalaApiWeb.Machine.RecordController.dependencies",
+        "parameters": [
+          {
+            "description": "",
+            "in": "path",
+            "name": "object_slug",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "x-struct": null,
+              "x-validate": null
+            }
+          },
+          {
+            "description": "",
+            "in": "path",
+            "name": "record_id",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "x-struct": null,
+              "x-validate": null
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/RecordDependencies"
+                }
+              }
+            },
+            "description": "Dependencias"
+          },
+          "403": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Sin permiso ABAC sobre este record"
+          },
+          "404": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "No encontrado (o de otro objeto)"
+          }
+        },
+        "summary": "Preview de dependencias de un record (impacto de borrarlo, sin borrar)",
+        "tags": [
+          "records"
+        ]
+      }
+    },
     "/v1/objects/{object_slug}/records/{record_id}/events": {
       "get": {
         "callbacks": {},
@@ -16642,7 +17246,7 @@
       },
       "post": {
         "callbacks": {},
-        "description": "Emite una credencial de máquina (`hpat_…`) con la que un agente (Claude Code) o un script CI escribe el modelo de datos por HTTP. La respuesta incluye el secreto en claro UNA sola vez (`token`); guárdalo, no se puede recuperar. Los permisos se intersectan con los del creador (un token nunca puede más que quien lo emite).",
+        "description": "Emite una credencial de máquina (`mat_…`) con la que un agente (Claude Code) o un script CI escribe el modelo de datos por HTTP. La respuesta incluye el secreto en claro UNA sola vez (`token`); guárdalo, no se puede recuperar. Los permisos se intersectan con los del creador (un token nunca puede más que quien lo emite).",
         "operationId": "HablalaApiWeb.AccessTokens.TokenController.create",
         "parameters": [
           {
@@ -17176,7 +17780,7 @@
       },
       "post": {
         "callbacks": {},
-        "description": "Emite una credencial read-only para la Data API. La respuesta incluye el secreto en claro UNA sola vez (`token`); guárdalo, no se puede recuperar. `kind`: public (client-side) o private (server-side).",
+        "description": "Emite el **par** de API keys del canal público en una operación: una **publishable** (`pk_`, client-side) y una **secret** (`sk_`, server-side). La respuesta incluye el secreto en claro de AMBAS una sola vez (`publishable.token`/`secret.token`); guárdalos, no se pueden recuperar. Es el flujo del panel: se muestran completos para copiar/pegar en el `.env` de la app cliente. `name` por defecto \"Default\".",
         "operationId": "HablalaApiWeb.PublicApi.ApiKeyController.create",
         "parameters": [
           {
@@ -17199,7 +17803,7 @@
               }
             }
           },
-          "description": "Datos del token",
+          "description": "Datos del par",
           "required": false
         },
         "responses": {
@@ -17207,11 +17811,11 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/ApiKeyCreatedResponse"
+                  "$ref": "#/components/schemas/ApiKeyPairCreatedResponse"
                 }
               }
             },
-            "description": "Token creado (con secreto)"
+            "description": "Par creado (con secretos)"
           },
           "403": {
             "content": {
@@ -17234,7 +17838,7 @@
             "description": "Error de validación"
           }
         },
-        "summary": "Crear una API key",
+        "summary": "Crear un par de API keys",
         "tags": [
           "public"
         ]
@@ -17290,10 +17894,11 @@
         ]
       }
     },
-    "/v1/organizations/{organization_id}/appointments": {
-      "get": {
+    "/v1/organizations/{organization_id}/api-keys/{id}/rotate": {
+      "post": {
         "callbacks": {},
-        "operationId": "HablalaApiWeb.Scheduling.AppointmentController.index",
+        "description": "Rota la key (modelo Stripe *roll*): emite un reemplazo del mismo tipo y nombre y revoca la original de inmediato. La respuesta incluye el nuevo secreto en claro UNA sola vez (`token`); guárdalo. Las requests que usaban la key vieja dejan de autenticar.",
+        "operationId": "HablalaApiWeb.PublicApi.ApiKeyController.rotate",
         "parameters": [
           {
             "description": "",
@@ -17308,19 +17913,75 @@
           },
           {
             "description": "",
-            "in": "query",
-            "name": "organizerId",
-            "required": false,
+            "in": "path",
+            "name": "id",
+            "required": true,
             "schema": {
               "type": "string",
               "x-struct": null,
               "x-validate": null
             }
-          },
-          {
-            "description": "ISO-8601; solape con [from, to).",
-            "in": "query",
-            "name": "from",
+          }
+        ],
+        "responses": {
+          "201": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiKeyCreatedResponse"
+                }
+              }
+            },
+            "description": "Key rotada (nuevo secreto)"
+          },
+          "403": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Sin permiso"
+          }
+        },
+        "summary": "Rotar una API key",
+        "tags": [
+          "public"
+        ]
+      }
+    },
+    "/v1/organizations/{organization_id}/appointments": {
+      "get": {
+        "callbacks": {},
+        "operationId": "HablalaApiWeb.Scheduling.AppointmentController.index",
+        "parameters": [
+          {
+            "description": "",
+            "in": "path",
+            "name": "organization_id",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "x-struct": null,
+              "x-validate": null
+            }
+          },
+          {
+            "description": "",
+            "in": "query",
+            "name": "organizerId",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "x-struct": null,
+              "x-validate": null
+            }
+          },
+          {
+            "description": "ISO-8601; solape con [from, to).",
+            "in": "query",
+            "name": "from",
             "required": false,
             "schema": {
               "type": "string",
@@ -22189,7 +22850,7 @@
     "/v1/organizations/{organization_id}/oauth/grants/{user_code}/approve": {
       "post": {
         "callbacks": {},
-        "description": "El consent: fija la organización del path y los permisos elegidos (intersectados con los del aprobador) en el grant. El CLI que sondea recibirá su `hpat_…` en el siguiente poll.",
+        "description": "El consent: fija la organización del path y los permisos elegidos (intersectados con los del aprobador) en el grant. El CLI que sondea recibirá su `mat_…` en el siguiente poll.",
         "operationId": "HablalaApiWeb.Oauth.GrantController.approve",
         "parameters": [
           {
@@ -22929,6 +23590,95 @@
         ]
       }
     },
+    "/v1/organizations/{organization_id}/objects/{object_slug}/records/trash": {
+      "get": {
+        "callbacks": {},
+        "description": "Lista los records SOFT-DELETED del objeto (`deleted_at IS NOT NULL`), para restaurarlos. Misma lectura gobernada que `POST /query` (RBAC + ABAC por fila + field_mask + paginación keyset), sobre el otro lado de `deleted_at`. Gate RBAC: `records:delete`.",
+        "operationId": "HablalaApiWeb.Data.RecordController.trash",
+        "parameters": [
+          {
+            "description": "",
+            "in": "path",
+            "name": "organization_id",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "x-struct": null,
+              "x-validate": null
+            }
+          },
+          {
+            "description": "",
+            "in": "path",
+            "name": "object_slug",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "x-struct": null,
+              "x-validate": null
+            }
+          },
+          {
+            "description": "",
+            "in": "query",
+            "name": "limit",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "x-struct": null,
+              "x-validate": null
+            }
+          },
+          {
+            "description": "",
+            "in": "query",
+            "name": "cursor",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "x-struct": null,
+              "x-validate": null
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/QueryResultResponse"
+                }
+              }
+            },
+            "description": "Records borrados"
+          },
+          "403": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Sin permiso"
+          },
+          "404": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Objeto desconocido"
+          }
+        },
+        "summary": "Listar los records borrados (soft) del objeto — la Papelera",
+        "tags": [
+          "records"
+        ]
+      }
+    },
     "/v1/organizations/{organization_id}/objects/{object_slug}/records/{id}": {
       "delete": {
         "callbacks": {},
@@ -23266,6 +24016,84 @@
         ]
       }
     },
+    "/v1/organizations/{organization_id}/objects/{object_slug}/records/{record_id}/dependencies": {
+      "get": {
+        "callbacks": {},
+        "description": "Devuelve cuántos edges se desvincularían y qué referencias core BLOQUEARÍAN el borrado (restrict-on-delete), sin mutar nada. Alimenta la confirmación dependent-aware de la UI. Misma fuente que el guard del borrado real, así que preview y borrado no divergen. Gate `records:delete` + ABAC de escritura por fila.",
+        "operationId": "HablalaApiWeb.Data.RecordController.dependencies",
+        "parameters": [
+          {
+            "description": "",
+            "in": "path",
+            "name": "organization_id",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "x-struct": null,
+              "x-validate": null
+            }
+          },
+          {
+            "description": "",
+            "in": "path",
+            "name": "object_slug",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "x-struct": null,
+              "x-validate": null
+            }
+          },
+          {
+            "description": "",
+            "in": "path",
+            "name": "record_id",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "x-struct": null,
+              "x-validate": null
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/RecordDependencies"
+                }
+              }
+            },
+            "description": "Dependencias"
+          },
+          "403": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Sin permiso ABAC sobre este record"
+          },
+          "404": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "No encontrado (o de otro objeto)"
+          }
+        },
+        "summary": "Preview de dependencias de un record (impacto de borrarlo, sin borrar)",
+        "tags": [
+          "records"
+        ]
+      }
+    },
     "/v1/organizations/{organization_id}/objects/{object_slug}/records/{record_id}/events": {
       "get": {
         "callbacks": {},
@@ -25915,7 +26743,7 @@
     "/v1/organizations/{organization_id}/uploads/presign": {
       "post": {
         "callbacks": {},
-        "description": "Devuelve una URL prefirmada para subir un archivo directo al object storage. El cliente hace `PUT` del blob a `uploadUrl` y luego referencia `fileUrl` en los adjuntos del mensaje. (El camino personal usa `HablalaApiWeb.Me.UploadController` en `/v1/me/uploads/presign`.)",
+        "description": "Devuelve un sobre auto-descriptivo para subir un archivo directo al object storage. Según `method`: `POST` → form multipart con `fields` + el archivo como campo `file` (S3/R2 POST policy, con tope de tamaño firmado en el borde); `PUT` → PUT del blob a `url` con `headers` (adaptador local de dev). Luego se referencia `fileUrl`. (El camino personal usa `HablalaApiWeb.Me.UploadController` en `/v1/me/uploads/presign`.)",
         "operationId": "HablalaApiWeb.UploadController.presign",
         "parameters": [
           {
@@ -25950,7 +26778,7 @@
                 }
               }
             },
-            "description": "URL prefirmada"
+            "description": "Sobre de subida prefirmado"
           },
           "415": {
             "content": {
@@ -25963,7 +26791,7 @@
             "description": "Tipo de archivo no soportado"
           }
         },
-        "summary": "Pedir una URL de subida prefirmada",
+        "summary": "Pedir un sobre de subida prefirmado",
         "tags": [
           "uploads"
         ]
@@ -26949,6 +27777,98 @@
         ]
       }
     },
+    "/v1/public/me/checkout": {
+      "post": {
+        "callbacks": {},
+        "description": "Crea un pedido atómicamente: valida stock por variante, numera (#1001), crea el `order` (source = web, financial_status = pending) + sus renglones con snapshots de precio, y decrementa el inventario. Autenticado por end-user session token; el comprador sale de la sesión (no del cuerpo). Idempotente vía el header `Idempotency-Key`.",
+        "operationId": "HablalaApiWeb.PublicApi.CheckoutController.create",
+        "parameters": [
+          {
+            "description": "Clave de idempotencia (estándar Stripe): dos envíos con la misma → un pedido.",
+            "in": "header",
+            "name": "Idempotency-Key",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "x-struct": null,
+              "x-validate": null
+            }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CheckoutRequest"
+              }
+            }
+          },
+          "description": "Artículos del carrito + moneda",
+          "required": false
+        },
+        "responses": {
+          "201": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/OrderResponse"
+                }
+              }
+            },
+            "description": "Pedido creado"
+          },
+          "401": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Sesión anónima o token inválido"
+          },
+          "403": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "El ABAC no permite crear pedidos"
+          },
+          "409": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Sin stock suficiente para una variante"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Carrito inválido"
+          }
+        },
+        "security": [
+          {
+            "endUserToken": []
+          }
+        ],
+        "summary": "Checkout nativo (crear un pedido)",
+        "tags": [
+          "public"
+        ]
+      }
+    },
     "/v1/public/me/objects/{object_slug}/records": {
       "post": {
         "callbacks": {},
@@ -27777,6 +28697,66 @@
         ]
       }
     },
+    "/v1/public/variants/availability": {
+      "post": {
+        "callbacks": {},
+        "description": "Dado un lote de ids de `product_variant`, devuelve por variante si es comprable (activa y con stock > 0) — el booleano del badge \"Agotado\". Autenticado por API key. Se expone el booleano derivado, no el conteo de stock.",
+        "operationId": "HablalaApiWeb.PublicApi.AvailabilityController.create",
+        "parameters": [],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/VariantAvailabilityRequest"
+              }
+            }
+          },
+          "description": "Ids de variante",
+          "required": false
+        },
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AvailabilityResponse"
+                }
+              }
+            },
+            "description": "Disponibilidad por variante"
+          },
+          "401": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Token inválido"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Petición inválida"
+          }
+        },
+        "security": [
+          {
+            "apiKey": []
+          }
+        ],
+        "summary": "Disponibilidad de compra de variantes (Public API)",
+        "tags": [
+          "public"
+        ]
+      }
+    },
     "/v1/push-tokens": {
       "post": {
         "callbacks": {},