> ## 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.

# Client

> Installa @squarecloud/blob e crea un client SquareCloudBlob con una chiave API o un token di upload. L'unica opzione è maxRetries.

<Info>
  Questa pagina documenta **`@squarecloud/blob` v4**. Stai effettuando l'upgrade dalla v3? Leggi la [guida alla migrazione v3 → v4](/it/sdks/blob/migrating_to_v4).
</Info>

`@squarecloud/blob` è l'SDK JavaScript ufficiale per [Square Cloud Blob Storage](/it/services/blob). Copre ogni endpoint dell'[API Blob](/it/blob-reference/authentication) più il [gateway S3](/it/blob-reference/s3-compatibility).

## Requisiti

* **Node.js 20** o più recente, oppure qualsiasi browser moderno. L'SDK usa solo `fetch`, `FormData` e `Blob`.
* Distribuito come **ESM e CommonJS**, con **zero dipendenze a runtime**.
* `@aws-sdk/client-s3` è una **peer dependency opzionale**, necessaria solo se chiami [`s3()`](/it/sdks/blob/s3).

## Installazione

<Tabs>
  <Tab title="npm">
    ```bash theme={"system"}
    npm install @squarecloud/blob
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={"system"}
    yarn add @squarecloud/blob
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash theme={"system"}
    pnpm add @squarecloud/blob
    ```
  </Tab>

  <Tab title="bun">
    ```bash theme={"system"}
    bun add @squarecloud/blob
    ```
  </Tab>
</Tabs>

## Creare il client

<Tabs>
  <Tab title="ESM / TypeScript">
    ```typescript theme={"system"}
    import { SquareCloudBlob } from "@squarecloud/blob";

    const blob = new SquareCloudBlob(process.env.SQUARECLOUD_API_KEY);
    ```
  </Tab>

  <Tab title="CommonJS">
    ```javascript theme={"system"}
    const { SquareCloudBlob } = require("@squarecloud/blob");

    const blob = new SquareCloudBlob(process.env.SQUARECLOUD_API_KEY);
    ```
  </Tab>
</Tabs>

### Costruttore

```typescript theme={"system"}
new SquareCloudBlob(credential, { maxRetries: 2 });
```

| Parametro            | Tipo     | Predefinito  | Descrizione                                                                                                                                                                                                                |
| -------------------- | -------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `credential`         | `string` | obbligatorio | Una **chiave API**, oppure un **token di upload** (`squp_...`) che può chiamare solo `put()`.                                                                                                                              |
| `options.maxRetries` | `number` | `2`          | Quante volte una richiesta sicura da ripetere (un `GET` o una parte multipart) viene ritentata dopo un errore di rete o un `5xx`. `0` disattiva i retry. Vedi [Politica di retry](/it/sdks/blob/errors#politica-di-retry). |

## Credenziali

La credenziale viene inviata **così com'è** nell'header `Authorization`, senza prefisso `Bearer`.

| Credenziale                  | Da dove proviene                                                                         | Cosa può fare                                                                                             |
| ---------------------------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| Chiave API                   | [Dashboard di Square Cloud](https://squarecloud.app/account/security)                    | Ogni metodo, in base ai suoi [scope](/it/blob-reference/authentication#scope) `blob:read` / `blob:write`. |
| Token di upload (`squp_...`) | [`blob.uploadTokens.create()`](/it/sdks/blob/uploads#upload-dal-browser), sul tuo server | Solo `put()`. Qualsiasi altro metodo fallisce con `403 UPLOAD_TOKEN_NOT_ALLOWED`.                         |

<Warning>
  Non inviare mai una chiave API a un browser. Genera un token di upload sul tuo server e passa al client solo il token.
</Warning>

## Cosa non puoi configurare

`maxRetries` è l'**unica** opzione. Il client non accetta:

* **Un URL base.** È fisso su `https://blob.squarecloud.app/v1/`.
* **Un `fetch` personalizzato.** Le richieste usano il `fetch` globale.
* **Un timeout o un `AbortSignal`.** Una chiamata dura quanto `fetch` attende, e non c'è modo di annullarla.
* **Header personalizzati.**

## Metodi

Ogni metodo restituisce dati semplici (niente classi), tranne `s3()`, che restituisce un `S3Client`. Opzioni e risultati usano i nomi dei campi dell'API, per lo più in snake\_case (`security_hash`, `expires_at`), quindi il [riferimento dell'API Blob](/it/blob-reference/authentication) si applica così com'è.

| Gruppo                | Metodi                                                                                                                                                                                          | Pagina                                                |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| `blob`                | `put(file, options)`                                                                                                                                                                            | [Upload](/it/sdks/blob/uploads)                       |
| `blob.uploadTokens`   | `create(options)`                                                                                                                                                                               | [Upload](/it/sdks/blob/uploads#upload-dal-browser)    |
| `blob`                | `list(options)`, `listPage(options)`, `info(id)`, `downloadUrl(id, options)`, `update(ids, changes)`, `delete(ids)`, `copy(source, destination, options)`, `move(source, destination, options)` | [Oggetti](/it/sdks/blob/objects)                      |
| `blob.shares`         | `create(object, options)`, `list()`, `revoke(id)`                                                                                                                                               | [Condivisione](/it/sdks/blob/sharing)                 |
| `blob.rules` / `blob` | `get()`, `set(rules)` / `stats()`                                                                                                                                                               | [Regole e statistiche](/it/sdks/blob/rules_and_stats) |
| `blob`                | `s3Credentials()`, `s3()`                                                                                                                                                                       | [S3](/it/sdks/blob/s3)                                |

Il pacchetto esporta anche `SquareCloudBlobError`, il tipo `BlobErrorCode` e ogni tipo di opzione e di risultato (`PutOptions`, `PutResult`, `ListedObject`, `ObjectInfo`, `Share`, `Rule`, ...). Vedi [Errori](/it/sdks/blob/errors).

## Id degli oggetti

Ogni oggetto è identificato da un **id opaco**, come `pub/...` per un oggetto pubblico o `prv/...` per uno privato.

* **Memorizza l'id esattamente come viene restituito.** Non costruirne mai uno a mano e non analizzarlo mai.
* **Modificare `private` o `expire` cambia l'id.** Sostituisci sempre l'id memorizzato con quello restituito da [`update()`](/it/sdks/blob/objects#aggiornare-gli-oggetti).
* **Usa l'`url` della risposta** invece di costruire gli URL. Gli oggetti privati hanno `url: null`: ottieni un link con [`downloadUrl()`](/it/sdks/blob/objects#link-di-download) o con una [condivisione](/it/sdks/blob/sharing).

```typescript theme={"system"}
const { id, url } = await blob.put("./photo.png", { name: "photo", prefix: "avatars" });
// save `id` as-is; use `url` to serve the file
```