@hablala/api-contract 0.7.0 → 0.8.0

package/dist/index.d.ts

@@ -1335,6 +1335,26 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/objects/{object_slug}/uploads": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Pedir una URL de subida para un attribute file (staged upload)
+         * @description Fase 1 del flujo de archivos de un record: valida el archivo declarado contra el config del attribute `file` (`accepted_content_types` con comodines `image/*`, `max_size_bytes`) y devuelve el destino de subida prefirmado. Luego: (2) `PUT` del blob crudo a `uploadUrl` con `headers`; (3) confirmar escribiendo el record con `fileUrl` en el envelope del attribute (`{"url": fileUrl, …}`) — el servidor verifica el blob contra el storage (tamaño/tipo REALES) y lo promueve a su ubicación definitiva. Un blob nunca confirmado expira solo. Gate `records:create`.
+         */
+        post: operations["HablalaApiWeb.Machine.UploadController.create"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/organizations": {
         parameters: {
             query?: never;
@@ -3617,6 +3637,26 @@ interface paths {
         patch: operations["HablalaApiWeb.PublicApi.RecordController.update (2)"];
         trace?: never;
     };
+    "/v1/public/me/objects/{object_slug}/uploads": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Pedir una URL de subida para un attribute file (canal público)
+         * @description Como el staged upload del canal de máquina (`POST /v1/objects/{object_slug}/uploads`), pero gobernado por el ABAC default-deny del canal público: exige una policy `allow` de `create` o `update` para el principal (`public` con la API key; `end_user` con el session token en la variante `/me`) sobre el object — sin policy, 403. Flujo: presign → `PUT` del blob a `uploadUrl` → confirmar escribiendo el record con `fileUrl` en el envelope del attribute `file`.
+         */
+        post: operations["HablalaApiWeb.PublicApi.UploadController.create"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/public/me/query": {
         parameters: {
             query?: never;
@@ -3673,6 +3713,26 @@ interface paths {
         patch: operations["HablalaApiWeb.PublicApi.RecordController.update (4)"];
         trace?: never;
     };
+    "/v1/public/objects/{object_slug}/uploads": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Pedir una URL de subida para un attribute file (canal público)
+         * @description Como el staged upload del canal de máquina (`POST /v1/objects/{object_slug}/uploads`), pero gobernado por el ABAC default-deny del canal público: exige una policy `allow` de `create` o `update` para el principal (`public` con la API key; `end_user` con el session token en la variante `/me`) sobre el object — sin policy, 403. Flujo: presign → `PUT` del blob a `uploadUrl` → confirmar escribiendo el record con `fileUrl` en el envelope del attribute `file`.
+         */
+        post: operations["HablalaApiWeb.PublicApi.UploadController.create (2)"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/public/query": {
         parameters: {
             query?: never;
@@ -7185,6 +7245,7 @@ interface components {
         Policy: {
             /** @enum {string} */
             action: "read" | "create" | "update" | "delete";
+            /** @description Predicado por fila: hoja `{attr, op, value|value_from}` o árbol `and`/`or`. `attr` admite un attribute path de UN nivel por un attribute `reference` (`pet.owner`: condiciona sobre el record destino; fail-closed si la referencia es nula). */
             condition?: Record<string, never>;
             /** @enum {string} */
             effect: "allow" | "deny";
@@ -7206,6 +7267,7 @@ interface components {
         PolicyInput: {
             /** @enum {string} */
             action: "read" | "create" | "update" | "delete";
+            /** @description Predicado por fila: hoja `{attr, op, value|value_from}` o árbol `and`/`or`. `attr` admite un attribute path de UN nivel por un attribute `reference` (`pet.owner`: condiciona sobre el record destino; fail-closed si la referencia es nula). */
             condition?: Record<string, never>;
             /** @enum {string} */
             effect: "allow" | "deny";
@@ -7503,6 +7565,38 @@ interface components {
         RecordResponse: {
             data: components["schemas"]["Record"];
         };
+        /**
+         * RecordUploadRequest
+         * @description Archivo a adjuntar a un attribute `file` de un record: para qué attribute es y qué se va a subir. El servidor lo valida contra el config del attribute (`accepted_content_types` con comodines `image/*`, `max_size_bytes`) antes de emitir la URL de subida.
+         */
+        RecordUploadRequest: {
+            /** @description Slug del attribute `data_type: file` del object al que se adjuntará. */
+            attribute: string;
+            /** @description MIME type del archivo (p. ej. `image/jpeg`). Se valida contra `accepted_content_types` del attribute. */
+            contentType: string;
+            /** @description Nombre del archivo (p. ej. `firulais.jpg`). */
+            filename: string;
+            /** @description Tamaño declarado en bytes (opcional). Si excede `max_size_bytes` el presign se rechaza aquí (fail-fast); la verdad final la impone el storage al confirmar el record (el tamaño REAL se relee del blob). */
+            size?: number | null;
+        };
+        /** RecordUploadResponse */
+        RecordUploadResponse: {
+            data: components["schemas"]["RecordUploadTarget"];
+        };
+        /**
+         * RecordUploadTarget
+         * @description Destino de subida prefirmado (*staged upload target*, patrón Shopify `stagedUploadsCreate` / S3 presigned upload): el cliente hace `PUT` del blob crudo a `uploadUrl` con `headers`, y luego CONFIRMA escribiendo el record con `fileUrl` en el envelope del attribute `file` (`{"url": fileUrl, "filename": …, "content_type": …}`). Un blob nunca confirmado expira solo en el staging.
+         */
+        RecordUploadTarget: {
+            /** @description URL del blob (en staging `pending/…`): va como `url` en el envelope del attribute `file` al crear/actualizar el record. Al confirmarse, el servidor la reescribe a la definitiva. */
+            fileUrl: string;
+            /** @description Cabeceras que el cliente debe enviar en el `PUT` (p. ej. `content-type`). */
+            headers?: {
+                [key: string]: string;
+            };
+            /** @description Destino del `PUT` del blob (URL prefirmada, expira). */
+            uploadUrl: string;
+        };
         /** RegisterCredentials */
         RegisterCredentials: {
             /** Format: email */
@@ -11008,6 +11102,51 @@ interface operations {
             };
         };
     };
+    "HablalaApiWeb.Machine.UploadController.create": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                object_slug: string;
+            };
+            cookie?: never;
+        };
+        /** @description Archivo a subir */
+        requestBody?: {
+            content: {
+                "application/json": components["schemas"]["RecordUploadRequest"];
+            };
+        };
+        responses: {
+            /** @description Destino de subida prefirmado */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["RecordUploadResponse"];
+                };
+            };
+            /** @description Objeto desconocido */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description Attribute inexistente/no-file, MIME no admitido o tamaño excedido */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
     "HablalaApiWeb.Orgs.OrganizationController.index": {
         parameters: {
             query?: never;
@@ -17763,6 +17902,60 @@ interface operations {
             };
         };
     };
+    "HablalaApiWeb.PublicApi.UploadController.create": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                object_slug: string;
+            };
+            cookie?: never;
+        };
+        /** @description Archivo a subir */
+        requestBody?: {
+            content: {
+                "application/json": components["schemas"]["RecordUploadRequest"];
+            };
+        };
+        responses: {
+            /** @description Destino de subida prefirmado */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["RecordUploadResponse"];
+                };
+            };
+            /** @description Sin policy allow de create/update para este principal */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description Objeto desconocido */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description Attribute inexistente/no-file, MIME no admitido o tamaño excedido */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
     "HablalaApiWeb.PublicApi.QueryController.create (2)": {
         parameters: {
             query?: never;
@@ -18018,6 +18211,60 @@ interface operations {
             };
         };
     };
+    "HablalaApiWeb.PublicApi.UploadController.create (2)": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                object_slug: string;
+            };
+            cookie?: never;
+        };
+        /** @description Archivo a subir */
+        requestBody?: {
+            content: {
+                "application/json": components["schemas"]["RecordUploadRequest"];
+            };
+        };
+        responses: {
+            /** @description Destino de subida prefirmado */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["RecordUploadResponse"];
+                };
+            };
+            /** @description Sin policy allow de create/update para este principal */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description Objeto desconocido */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description Attribute inexistente/no-file, MIME no admitido o tamaño excedido */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
     "HablalaApiWeb.PublicApi.QueryController.create": {
         parameters: {
             query?: never;

package/openapi.json

@@ -9356,6 +9356,7 @@
             "x-validate": null
           },
           "condition": {
+            "description": "Predicado por fila: hoja `{attr, op, value|value_from}` o árbol `and`/`or`. `attr` admite un attribute path de UN nivel por un attribute `reference` (`pet.owner`: condiciona sobre el record destino; fail-closed si la referencia es nula).",
             "type": "object",
             "x-struct": null,
             "x-validate": null
@@ -9457,6 +9458,7 @@
             "x-validate": null
           },
           "condition": {
+            "description": "Predicado por fila: hoja `{attr, op, value|value_from}` o árbol `and`/`or`. `attr` admite un attribute path de UN nivel por un attribute `reference` (`pet.owner`: condiciona sobre el record destino; fail-closed si la referencia es nula).",
             "type": "object",
             "x-struct": null,
             "x-validate": null
@@ -10476,6 +10478,96 @@
         "x-struct": "Elixir.HablalaApiWeb.Schemas.RecordResponse",
         "x-validate": null
       },
+      "RecordUploadRequest": {
+        "description": "Archivo a adjuntar a un attribute `file` de un record: para qué attribute es y qué se va a subir. El servidor lo valida contra el config del attribute (`accepted_content_types` con comodines `image/*`, `max_size_bytes`) antes de emitir la URL de subida.",
+        "properties": {
+          "attribute": {
+            "description": "Slug del attribute `data_type: file` del object al que se adjuntará.",
+            "type": "string",
+            "x-struct": null,
+            "x-validate": null
+          },
+          "contentType": {
+            "description": "MIME type del archivo (p. ej. `image/jpeg`). Se valida contra `accepted_content_types` del attribute.",
+            "type": "string",
+            "x-struct": null,
+            "x-validate": null
+          },
+          "filename": {
+            "description": "Nombre del archivo (p. ej. `firulais.jpg`).",
+            "type": "string",
+            "x-struct": null,
+            "x-validate": null
+          },
+          "size": {
+            "description": "Tamaño declarado en bytes (opcional). Si excede `max_size_bytes` el presign se rechaza aquí (fail-fast); la verdad final la impone el storage al confirmar el record (el tamaño REAL se relee del blob).",
+            "minimum": 1,
+            "nullable": true,
+            "type": "integer",
+            "x-struct": null,
+            "x-validate": null
+          }
+        },
+        "required": [
+          "attribute",
+          "filename",
+          "contentType"
+        ],
+        "title": "RecordUploadRequest",
+        "type": "object",
+        "x-struct": "Elixir.HablalaApiWeb.Schemas.RecordUploadRequest",
+        "x-validate": null
+      },
+      "RecordUploadResponse": {
+        "properties": {
+          "data": {
+            "$ref": "#/components/schemas/RecordUploadTarget"
+          }
+        },
+        "required": [
+          "data"
+        ],
+        "title": "RecordUploadResponse",
+        "type": "object",
+        "x-struct": "Elixir.HablalaApiWeb.Schemas.RecordUploadResponse",
+        "x-validate": null
+      },
+      "RecordUploadTarget": {
+        "description": "Destino de subida prefirmado (*staged upload target*, patrón Shopify `stagedUploadsCreate` / S3 presigned upload): el cliente hace `PUT` del blob crudo a `uploadUrl` con `headers`, y luego CONFIRMA escribiendo el record con `fileUrl` en el envelope del attribute `file` (`{\"url\": fileUrl, \"filename\": …, \"content_type\": …}`). Un blob nunca confirmado expira solo en el staging.",
+        "properties": {
+          "fileUrl": {
+            "description": "URL del blob (en staging `pending/…`): va como `url` en el envelope del attribute `file` al crear/actualizar el record. Al confirmarse, el servidor la reescribe a la definitiva.",
+            "type": "string",
+            "x-struct": null,
+            "x-validate": null
+          },
+          "headers": {
+            "additionalProperties": {
+              "type": "string",
+              "x-struct": null,
+              "x-validate": null
+            },
+            "description": "Cabeceras que el cliente debe enviar en el `PUT` (p. ej. `content-type`).",
+            "type": "object",
+            "x-struct": null,
+            "x-validate": null
+          },
+          "uploadUrl": {
+            "description": "Destino del `PUT` del blob (URL prefirmada, expira).",
+            "type": "string",
+            "x-struct": null,
+            "x-validate": null
+          }
+        },
+        "required": [
+          "uploadUrl",
+          "fileUrl"
+        ],
+        "title": "RecordUploadTarget",
+        "type": "object",
+        "x-struct": "Elixir.HablalaApiWeb.Schemas.RecordUploadTarget",
+        "x-validate": null
+      },
       "RegisterCredentials": {
         "properties": {
           "email": {
@@ -16775,6 +16867,73 @@
         ]
       }
     },
+    "/v1/objects/{object_slug}/uploads": {
+      "post": {
+        "callbacks": {},
+        "description": "Fase 1 del flujo de archivos de un record: valida el archivo declarado contra el config del attribute `file` (`accepted_content_types` con comodines `image/*`, `max_size_bytes`) y devuelve el destino de subida prefirmado. Luego: (2) `PUT` del blob crudo a `uploadUrl` con `headers`; (3) confirmar escribiendo el record con `fileUrl` en el envelope del attribute (`{\"url\": fileUrl, …}`) — el servidor verifica el blob contra el storage (tamaño/tipo REALES) y lo promueve a su ubicación definitiva. Un blob nunca confirmado expira solo. Gate `records:create`.",
+        "operationId": "HablalaApiWeb.Machine.UploadController.create",
+        "parameters": [
+          {
+            "description": "",
+            "in": "path",
+            "name": "object_slug",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "x-struct": null,
+              "x-validate": null
+            }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RecordUploadRequest"
+              }
+            }
+          },
+          "description": "Archivo a subir",
+          "required": false
+        },
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/RecordUploadResponse"
+                }
+              }
+            },
+            "description": "Destino de subida prefirmado"
+          },
+          "404": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Objeto desconocido"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Attribute inexistente/no-file, MIME no admitido o tamaño excedido"
+          }
+        },
+        "summary": "Pedir una URL de subida para un attribute file (staged upload)",
+        "tags": [
+          "records"
+        ]
+      }
+    },
     "/v1/organizations": {
       "get": {
         "callbacks": {},
@@ -28164,6 +28323,83 @@
         ]
       }
     },
+    "/v1/public/me/objects/{object_slug}/uploads": {
+      "post": {
+        "callbacks": {},
+        "description": "Como el staged upload del canal de máquina (`POST /v1/objects/{object_slug}/uploads`), pero gobernado por el ABAC default-deny del canal público: exige una policy `allow` de `create` o `update` para el principal (`public` con la API key; `end_user` con el session token en la variante `/me`) sobre el object — sin policy, 403. Flujo: presign → `PUT` del blob a `uploadUrl` → confirmar escribiendo el record con `fileUrl` en el envelope del attribute `file`.",
+        "operationId": "HablalaApiWeb.PublicApi.UploadController.create",
+        "parameters": [
+          {
+            "description": "",
+            "in": "path",
+            "name": "object_slug",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "x-struct": null,
+              "x-validate": null
+            }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RecordUploadRequest"
+              }
+            }
+          },
+          "description": "Archivo a subir",
+          "required": false
+        },
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/RecordUploadResponse"
+                }
+              }
+            },
+            "description": "Destino de subida prefirmado"
+          },
+          "403": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Sin policy allow de create/update para este principal"
+          },
+          "404": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Objeto desconocido"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Attribute inexistente/no-file, MIME no admitido o tamaño excedido"
+          }
+        },
+        "summary": "Pedir una URL de subida para un attribute file (canal público)",
+        "tags": [
+          "public"
+        ]
+      }
+    },
     "/v1/public/me/query": {
       "post": {
         "callbacks": {},
@@ -28539,6 +28775,83 @@
         ]
       }
     },
+    "/v1/public/objects/{object_slug}/uploads": {
+      "post": {
+        "callbacks": {},
+        "description": "Como el staged upload del canal de máquina (`POST /v1/objects/{object_slug}/uploads`), pero gobernado por el ABAC default-deny del canal público: exige una policy `allow` de `create` o `update` para el principal (`public` con la API key; `end_user` con el session token en la variante `/me`) sobre el object — sin policy, 403. Flujo: presign → `PUT` del blob a `uploadUrl` → confirmar escribiendo el record con `fileUrl` en el envelope del attribute `file`.",
+        "operationId": "HablalaApiWeb.PublicApi.UploadController.create (2)",
+        "parameters": [
+          {
+            "description": "",
+            "in": "path",
+            "name": "object_slug",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "x-struct": null,
+              "x-validate": null
+            }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RecordUploadRequest"
+              }
+            }
+          },
+          "description": "Archivo a subir",
+          "required": false
+        },
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/RecordUploadResponse"
+                }
+              }
+            },
+            "description": "Destino de subida prefirmado"
+          },
+          "403": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Sin policy allow de create/update para este principal"
+          },
+          "404": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Objeto desconocido"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Attribute inexistente/no-file, MIME no admitido o tamaño excedido"
+          }
+        },
+        "summary": "Pedir una URL de subida para un attribute file (canal público)",
+        "tags": [
+          "public"
+        ]
+      }
+    },
     "/v1/public/query": {
       "post": {
         "callbacks": {},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hablala/api-contract",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "type": "module",
   "description": "Contrato tipado (OpenAPI → TypeScript) de la API de Hablalá — single source of truth generada desde el backend Elixir.",
   "license": "MIT",