@hostwebhook/node-types 1.71.0 → 1.72.0

package/dist/esm/bucket-operations.js

@@ -1,6 +1,6 @@
 /**
- * El nodo de bucket: guardar, firmar y borrar objetos en un almacenamiento
- * compatible con S3.
+ * El nodo de bucket: mirar, leer, guardar, firmar y borrar objetos en un
+ * almacenamiento compatible con S3.
  *
  * ## Por qué se llama `bucket` y no `r2`
  *
@@ -19,33 +19,70 @@
  * un enlace que se manda por correo. Sin esto no había forma de entregarle a un
  * comprador una descarga temporal desde un flujo.
  *
- * ## Por qué sólo cuatro operaciones
+ * ## Por qué siete, y qué sigue fuera
  *
- * Listar y subida multiparte son las dos que piden el SDK de AWS de verdad
- * —paginación y reanudación— y el ejecutor hoy no tiene ni un `@aws-sdk/*`.
- * Entrar sin esa dependencia y traerla cuando aparezca la operación que la
- * justifique es más barato que al revés. Y un nodo con veinte operaciones es un
- * nodo que nadie entiende.
+ * Las cuatro primeras —`presignDownload`, `putObject`, `headObject`,
+ * `deleteObject`— actúan todas sobre un objeto que ya sabes nombrar. Faltaba lo
+ * contrario: **no había forma de mirar dentro del bucket**, ni de traerse el
+ * contenido de un objeto al flujo, ni de dejar que un tercero SUBA sin darle la
+ * credencial. Eso son las tres nuevas:
+ *
+ *  - `listObjects` — qué ficheros y qué CARPETAS hay bajo un prefijo. S3 no
+ *    tiene carpetas de verdad; con `delimiter` te las sintetiza como prefijos
+ *    comunes, que es exactamente lo que una persona quiere ver.
+ *  - `getObject` — el contenido, no un enlace al contenido. `presignDownload`
+ *    da una URL para que la abra OTRO; cuando el paso de abajo necesita los
+ *    bytes, una URL no sirve.
+ *  - `presignUpload` — el simétrico de `presignDownload`.
+ *
+ * Aquí se decía que listar «pedía el SDK de AWS de verdad». No lo pide:
+ * `ListObjectsV2` contesta XML plano y un raspador corto lo lee. Lo que sí
+ * sigue pidiendo el SDK es la **subida multiparte** —reanudación, partes,
+ * reintentos por parte— y por eso ésa no está. Traer `@aws-sdk/*` el día que
+ * aparezca la operación que lo justifique sigue siendo más barato que al revés.
+ * Y un nodo con veinte operaciones es un nodo que nadie entiende.
  */
 export const BUCKET_OPERATIONS = [
     "presignDownload",
     "putObject",
     "headObject",
     "deleteObject",
+    /* Las tres nuevas van AL FINAL y no intercaladas por tema: el orden de este
+       array es el orden del desplegable, y reordenar las cuatro de arriba le
+       mueve las filas de sitio a quien ya tiene el nodo en pantalla por un
+       cambio que no le aporta nada. El agrupado por tema vive en el dashboard,
+       que es donde se puede hacer sin tocar el contrato. */
+    "listObjects",
+    "getObject",
+    "presignUpload",
 ];
 export function isBucketOperation(value) {
     return (typeof value === "string" &&
         BUCKET_OPERATIONS.includes(value));
 }
 /**
- * Ninguna es iterable.
+ * Sólo `listObjects`.
  *
  * Una operación iterable es la que devuelve una COLECCIÓN sobre la que el nodo
- * de abajo repite. Las cuatro de aquí actúan sobre UN objeto, así que el que
- * viene detrás recibe un resultado, no una lista. El día que entre `listObjects`
- * ésa sí entra en esta lista.
+ * de abajo repite. Las otras seis actúan sobre UN objeto —o devuelven UN
+ * enlace—, así que el que viene detrás recibe un resultado, no una lista.
+ *
+ * ⚠️ Dos cosas que hay que saber antes de implementarla, porque descubrirlas
+ * por las malas cuesta una tarde:
+ *
+ *  1. **Se itera `objects`, y sólo `objects`.** `folders` viaja en el
+ *     contenedor junto a `truncated`, `nextToken`, `prefix` y `count`. Una
+ *     operación tiene un campo iterable, y aquí es el de los ficheros; si las
+ *     carpetas se iteraran también, el aviso de «hay más» se perdería justo en
+ *     la operación que existe para darlo.
+ *  2. **Un prefijo sin nada da `count: 0`, y el nodo de abajo corre CERO
+ *     veces**, sin error. Es la semántica correcta de una lista vacía, y es
+ *     también la trampa clásica: parece que el flujo «no hizo nada» cuando en
+ *     realidad hizo lo que debía.
  */
-export const BUCKET_ITERABLE_OPERATIONS = [];
+export const BUCKET_ITERABLE_OPERATIONS = [
+    "listObjects",
+];
 /* Ayudantes — repetir el mismo objeto cuatro veces es cómo se desincronizan las
    descripciones. */
 const objectKey = (placeholder) => ({
@@ -54,40 +91,55 @@ const objectKey = (placeholder) => ({
     type: "template",
     required: true,
     placeholder,
-    description: "La ruta dentro del bucket. Sin barra inicial. Admite {{payload.x}}.",
+    description: "The path inside the bucket. No leading slash. Supports {{payload.x}}.",
+});
+/* El TTL de las dos operaciones que firman. El tope de siete días es de SigV4 y
+   no se puede pasar: firmar por más tiempo produce una URL que el proveedor
+   rechaza, y el error llega tarde y sin explicación. Va en un ayudante porque
+   con dos operaciones firmando, dos copias del número es una copia de más. */
+const signatureTtl = () => ({
+    name: "expiresIn",
+    label: "Link valid for (seconds)",
+    type: "number",
+    required: true,
+    default: 3600,
+    min: 60,
+    max: 604800,
+    description: "From 60 s up to 7 days, the maximum the signature allows. Past that, the link stops working.",
+});
+/* El mismo interruptor en `headObject` y en `getObject`: las dos preguntan por
+   un objeto que puede no estar, y las dos lo resuelven con el `status` 404/200
+   y no con una excepción. Mismas etiquetas a propósito — son el mismo botón. */
+const failIfMissing = () => ({
+    name: "failIfMissing",
+    label: "Fail when the object is missing",
+    type: "booleanSelect",
+    options: [
+        { value: "true", label: "Yes — stop the flow" },
+        { value: "false", label: "No — carry on with exists: false" },
+    ],
+    description: 'With "No", the step succeeds and the node below decides. With "Yes", a missing object stops the flow.',
 });
 export const BUCKET_OPERATION_SPECS = {
     presignDownload: {
         label: "Sign download link",
-        description: "Devuelve una URL temporal para descargar un objeto privado. No mueve el fichero.",
+        description: "Returns a temporary URL to download a private object. Does not move the file.",
         apiRoute: "GET (presigned)",
         params: [
             objectKey("cuadernillos/{{payload.orderId}}.pdf"),
-            {
-                name: "expiresIn",
-                label: "Link valid for (seconds)",
-                type: "number",
-                required: true,
-                default: 3600,
-                min: 60,
-                /* El tope de SigV4 es de siete días y no se puede pasar: firmar por
-                   más tiempo produce una URL que el proveedor rechaza, y el error
-                   llega tarde y sin explicación. */
-                max: 604800,
-                description: "Desde 60 s hasta 7 días, que es el máximo que admite la firma. Pasado ese plazo el enlace deja de servir.",
-            },
+            signatureTtl(),
             {
                 name: "downloadAs",
                 label: "Download as (filename)",
                 type: "template",
                 placeholder: "Cuadernillo 1.pdf",
-                description: "Si se rellena, el navegador DESCARGA el fichero con ese nombre en vez de abrirlo. Déjalo vacío para que lo abra.",
+                description: "When set, the browser DOWNLOADS the file under that name instead of opening it. Leave it empty to have it opened.",
             },
         ],
     },
     putObject: {
         label: "Upload object",
-        description: "Guarda un objeto en el bucket. Sobreescribe si la clave ya existe.",
+        description: "Stores an object in the bucket. Overwrites when the key already exists.",
         apiRoute: "PUT /{bucket}/{key}",
         params: [
             objectKey("recibos/{{payload.orderId}}.json"),
@@ -97,7 +149,7 @@ export const BUCKET_OPERATION_SPECS = {
                 type: "textarea",
                 required: true,
                 placeholder: "{{payload}}",
-                description: "Lo que se guarda. Admite {{payload.x}}; un objeto se guarda como JSON.",
+                description: "What gets stored. Supports {{payload.x}}; an object is stored as JSON.",
             },
             {
                 name: "contentType",
@@ -105,32 +157,118 @@ export const BUCKET_OPERATION_SPECS = {
                 type: "template",
                 default: "application/json",
                 placeholder: "application/pdf",
-                description: "Lo que el navegador usará para decidir qué hacer con el fichero.",
+                description: "What the browser uses to decide what to do with the file.",
             },
         ],
     },
     headObject: {
         label: "Check object exists",
-        description: "Comprueba si un objeto existe, y su tamaño, sin descargarlo.",
+        description: "Checks whether an object exists, and its size, without downloading it.",
         apiRoute: "HEAD /{bucket}/{key}",
+        params: [objectKey("cuadernillos/{{payload.orderId}}.pdf"), failIfMissing()],
+    },
+    deleteObject: {
+        label: "Delete object",
+        description: "Deletes an object from the bucket. It cannot be undone.",
+        apiRoute: "DELETE /{bucket}/{key}",
+        params: [objectKey("temporales/{{payload.id}}.tmp")],
+    },
+    listObjects: {
+        label: "List objects",
+        description: "Lists the files and folders under a prefix. The node below runs once per file; folders travel alongside the list, they are not iterated. An empty prefix means zero runs, not an error.",
+        apiRoute: "GET /{bucket}?list-type=2",
         params: [
-            objectKey("cuadernillos/{{payload.orderId}}.pdf"),
+            /* NO usa `objectKey()`, y no es un descuido: ese ayudante marca
+               `required: true` y la validación de clave rechaza la cadena vacía. Un
+               prefijo puede ser vacío —el bucket entero— y puede acabar en barra,
+               que es justo lo que lo hace un prefijo y no una clave. */
             {
-                name: "failIfMissing",
-                label: "Fail when the object is missing",
+                name: "prefix",
+                label: "Prefix",
+                type: "template",
+                placeholder: "cuadernillos/2026/",
+                description: "Only keys starting with this. No leading slash. Leave it empty to list the whole bucket. Supports {{payload.x}}.",
+            },
+            {
+                name: "groupIntoFolders",
+                label: "Group into folders",
                 type: "booleanSelect",
                 options: [
-                    { value: "true", label: "Sí — cortar el flujo" },
-                    { value: "false", label: "No — seguir con exists: false" },
+                    { value: "true", label: "Yes — one level, with folders" },
+                    { value: "false", label: "No — every key under the prefix" },
                 ],
-                description: 'Con "No", el paso sale bien y el de abajo decide. Con "Sí", un objeto que falta corta el flujo.',
+                description: 'With "Yes" you get the files at this level plus the folder names below it. With "No" you get every key under the prefix, however deep. Defaults to Yes.',
+            },
+            {
+                name: "maxKeys",
+                label: "Maximum objects",
+                type: "number",
+                default: 1000,
+                min: 1,
+                max: 5000,
+                /* El proveedor devuelve 1.000 por llamada como mucho, así que de 1.000
+                   en adelante el ejecutor pagina por dentro. El techo de 5.000 no es
+                   timidez: el contenedor viaja como JSON al nodo de abajo y se guarda
+                   en el historial, y ahí ya hay un recorte a 256 KB por payload. */
+                description: "Up to 5000, paginated for you. When there are more, the step still succeeds: truncated says so and nextToken lets the next run carry on from there.",
+            },
+            {
+                name: "startAfter",
+                label: "Continue after",
+                type: "template",
+                advanced: true,
+                placeholder: "{{payload.nextToken}}",
+                description: "Resumes a listing: feed it the nextToken of the previous run. Leave it empty to start from the top.",
             },
         ],
     },
-    deleteObject: {
-        label: "Delete object",
-        description: "Borra un objeto del bucket. No se puede deshacer.",
-        apiRoute: "DELETE /{bucket}/{key}",
-        params: [objectKey("temporales/{{payload.id}}.tmp")],
+    /* El tope de lectura NO es un parámetro: es del ejecutor, no una preferencia
+       por nodo. Y se dice en la descripción, no se descubre — al superarlo el
+       paso FALLA con el tamaño real y un puntero a `presignDownload`; nunca
+       devuelve un `content` a medias. Un contenido truncado se parsea, se manda
+       por correo y nadie se entera. */
+    getObject: {
+        label: "Read object",
+        description: "Downloads an object and puts its contents in the payload. Up to 5 MB; past that the step fails and points you at Sign download link.",
+        apiRoute: "GET /{bucket}/{key}",
+        params: [
+            objectKey("recibos/{{payload.orderId}}.json"),
+            {
+                name: "as",
+                label: "Read as",
+                type: "select",
+                required: true,
+                default: "text",
+                options: [
+                    { value: "text", label: "Text — UTF-8 into content" },
+                    { value: "json", label: "JSON — parsed into content" },
+                    { value: "base64", label: "Base64 — bytes into contentBase64" },
+                ],
+                /* Lo binario se PIDE, no se adivina: un PDF leído como texto llega
+                   como UTF-8 roto y el fallo aparece tres nodos más abajo. */
+                description: "Binary files need Base64 — read as text they arrive corrupted, and Base64 weighs a third more than the file. With JSON, a body that does not parse fails the step. Over 256 KB the contents still flow on whole, but the run history stores them trimmed.",
+            },
+            failIfMissing(),
+        ],
+    },
+    presignUpload: {
+        label: "Sign upload link",
+        description: "Returns a temporary URL for someone else to PUT a file into the bucket, without giving them the credential.",
+        apiRoute: "PUT (presigned)",
+        params: [
+            objectKey("subidas/{{payload.orderId}}.pdf"),
+            signatureTtl(),
+            {
+                name: "contentType",
+                label: "Content type",
+                type: "template",
+                default: "application/octet-stream",
+                placeholder: "application/pdf",
+                /* NO se firma. Meterlo en `signedHeaders` obliga al que sube a mandar
+                   esa cabecera exacta o comerse un 403 que no puede depurar, y quien
+                   recibe el enlace no suele controlar su cliente HTTP. */
+                description: "What the object will be stored as. It is not enforced — the bucket stores whatever arrives.",
+            },
+        ],
     },
 };