> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Objetos

> Lista, inspecciona, enlaza, actualiza, elimina, copia y mueve objetos de Blob Storage con @squarecloud/blob.

<Note>
  Los ids de objeto son opacos (`pub/...`, `prv/...`). Guárdalos tal como se devuelven, nunca los construyas ni los analices, y reemplaza el id que tengas guardado siempre que [`update()`](#actualizar-objetos) devuelva uno nuevo. Consulta [IDs de objeto](/es/sdks/blob/client#ids-de-objeto).
</Note>

## Listar

`list()` es un **async generator** que sigue el cursor a través de todas las páginas. El orden no está garantizado.

```typescript theme={"system"}
for await (const object of blob.list({ prefix: "avatars/" })) {
    console.log(object.id, object.size, object.url);
}
```

`listPage()` obtiene **una sola página**. Úsalo para la paginación manual o para obtener `folders`:

```typescript theme={"system"}
const { objects, folders, continuationToken } = await blob.listPage({
    prefix: "avatars/",
    delimiter: "/",
});

// next page
if (continuationToken) {
    const next = await blob.listPage({ prefix: "avatars/", delimiter: "/", cursor: continuationToken });
}
```

| Opción      | Tipo      | Descripción                                                         |
| ----------- | --------- | ------------------------------------------------------------------- |
| `prefix`    | `string`  | Solo los objetos bajo este prefijo.                                 |
| `delimiter` | `"/"`     | Agrupa por carpeta: la página también devuelve `folders`.           |
| `private`   | `boolean` | Solo objetos privados (`true`) o públicos (`false`).                |
| `limit`     | `number`  | Objetos por página, de 1 a 1000 (por defecto 1000).                 |
| `cursor`    | `string`  | Solo en `listPage()`: el `continuationToken` de la página anterior. |

Una página tiene `objects`, `folders` (solo con `delimiter`) y `continuationToken` (**ausente en la última página**). Cada objeto listado tiene `id`, `size`, `created_at`, `expires_at`, `private`, `url` y `etag`. Consulta [Object List](/es/blob-reference/endpoint/list).

## Detalles de un objeto

```typescript theme={"system"}
const info = await blob.info(id);
```

Devuelve `id`, `size`, `content_type`, `etag`, `created_at`, `expires_at`, `private`, `url`, `cache_control`, `content_disposition`, `original_name`, `metadata` y `legacy`. Consulta [Object Info](/es/blob-reference/endpoint/info).

<Note>
  `created_at` es la fecha de última modificación en el almacenamiento: una actualización que copia el objeto (visibilidad, expiración, encabezados) la reinicia.
</Note>

## Enlaces de descarga

```typescript theme={"system"}
const { url, expires_at } = await blob.downloadUrl(id, { expires: 3600 });
```

* Un objeto **público** recibe su **URL permanente del CDN**, con `expires_at: null`.
* Un objeto **privado**, o cualquier llamada con `disposition` o `filename`, recibe un **enlace temporal** que dura `expires` segundos (hasta 24 horas).

<Warning>
  Un enlace temporal **no se puede revocar**. Para enlaces revocables, protegidos con contraseña o con un límite de descargas, usa un [enlace compartido](/es/sdks/blob/sharing).
</Warning>

| Opción        | Tipo                         | Descripción                                                        |
| ------------- | ---------------------------- | ------------------------------------------------------------------ |
| `expires`     | `number`                     | Duración del enlace en segundos, de 60 a 86400 (por defecto 3600). |
| `disposition` | `"inline"` \| `"attachment"` | Sobrescribe `Content-Disposition` para este enlace.                |
| `filename`    | `string`                     | Nombre de archivo con el que el navegador guarda la descarga.      |

El resultado tiene `url`, `expires_at`, `private`, `size` y `content_type`. Consulta [Object Download](/es/blob-reference/endpoint/download).

## Actualizar objetos

`update()` cambia la visibilidad, la expiración, la caché, la disposición o los metadatos de **un objeto o de hasta 50**. **Siempre devuelve un array**, un resultado por objeto, y cada resultado indica su propio éxito en `ok`.

```typescript theme={"system"}
const [result] = await blob.update(id, { private: true, expire: null });

if (result.ok) {
    id = result.id; // the id changed: store the new one
} else {
    console.error(result.code);
}
```

| Cambio          | Tipo                                     | Descripción                                                  |
| --------------- | ---------------------------------------- | ------------------------------------------------------------ |
| `private`       | `boolean`                                | Hace el objeto privado o público. **Cambia el id.**          |
| `expire`        | `string \| null`                         | Nueva expiración; `null` la elimina. **Cambia el id.**       |
| `cache_control` | `string \| null`                         | `null` lo elimina.                                           |
| `disposition`   | `"inline"` \| `"attachment"` \| `null`   | `null` la elimina.                                           |
| `metadata`      | `Record<string, string \| null> \| null` | `{ key: null }` elimina una clave; `null` las elimina todas. |

Un resultado correcto (`ok: true`) tiene `object` (el id que enviaste), `changed`, `id` (**el id después del cambio**), `private`, `url`, `expires_at` y `size`. Un resultado fallido (`ok: false`) tiene `object` y `code`. Un lote no lanza errores por los fallos de objetos individuales. Consulta [Object Update](/es/blob-reference/endpoint/update).

## Eliminar

La eliminación es **inmediata y permanente**: no hay papelera.

```typescript theme={"system"}
// Single id: resolves to nothing, throws OBJECT_NOT_FOUND when missing
await blob.delete(id);

// Batch, up to 100 ids
const { deleted, not_found, failed } = await blob.delete([id1, id2]);
```

| Llamada         | Devuelve                         | Con un objeto inexistente                                |
| --------------- | -------------------------------- | -------------------------------------------------------- |
| `delete(id)`    | `void`                           | Lanza `SquareCloudBlobError` (`OBJECT_NOT_FOUND`).       |
| `delete([ids])` | `{ deleted, not_found, failed }` | Se indica en `not_found`. `failed` lista `{ id, code }`. |

Con **un único id dentro de un array**, el SDK sigue devolviendo `{ deleted, not_found, failed }`: un objeto inexistente va a `not_found`, y `DELETE_FAILED` o `PREFIX_NOT_ALLOWED` van a `failed` en lugar de lanzar un error. Cualquier otro error (autenticación, límite de tasa, red) sigue lanzándose. Consulta [Delete Objects](/es/blob-reference/endpoint/delete).

## Copiar, mover y renombrar

Ambas operaciones se ejecutan en el servidor, sin descargar el archivo.

```typescript theme={"system"}
// Copy: counts toward your storage quota
await blob.copy(id, { name: "photo_copy", prefix: "backup" });

// Move or rename: does not count toward the quota
const moved = await blob.move(id, { name: "renamed" });
id = moved.id;
```

`move(source, destination, options)` es `copy()` con `move: true`.

| Campo de destino | Tipo             | Descripción                                                                         |
| ---------------- | ---------------- | ----------------------------------------------------------------------------------- |
| `name`           | `string`         | Obligatorio. Nombre **sin extensión**: el destino conserva la extensión del origen. |
| `prefix`         | `string`         | Prefijo de destino.                                                                 |
| `private`        | `boolean`        | Visibilidad del destino.                                                            |
| `security_hash`  | `boolean`        | Añade `_<hash>` al nombre.                                                          |
| `expire`         | `string \| null` | Si se omite, se conserva la expiración del origen; `null` la elimina.               |

| Opción      | Aceptada por       | Descripción                                                                              |
| ----------- | ------------------ | ---------------------------------------------------------------------------------------- |
| `overwrite` | `copy()`, `move()` | `true` reemplaza un objeto existente en el destino.                                      |
| `move`      | `copy()`           | `true` elimina el origen una vez que la copia se completa (igual que llamar a `move()`). |

El resultado tiene `id`, `private`, `url`, `expires_at`, `size`, `source`, `moved` y `replaced`. Consulta [Object Copy](/es/blob-reference/endpoint/copy).

<Note>
  `update()`, `delete()`, `copy()` y `move()` son escrituras: tienen un **único intento** y nunca se reintentan. Consulta [Política de reintentos](/es/sdks/blob/errors#política-de-reintentos).
</Note>