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

# Upload

> Carica file con put(): percorsi di file, Blob/File o byte, upload multipart automatici oltre i 90 MiB e token di upload per caricare direttamente dal browser.

## `put(file, options)`

`put()` carica un file e restituisce il nuovo oggetto.

```typescript theme={"system"}
const { id, url } = await blob.put("./photo.png", {
    name: "photo",
    prefix: "avatars",
});
```

### Input

| Input                           | Ambiente          | Note                                                                                                                                                   |
| ------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `string` (percorso di file)     | **Solo Node.js**  | Aperto con `fs.openAsBlob` e **trasmesso in streaming dal disco**, mai caricato interamente in memoria. L'estensione deriva dal basename del percorso. |
| `Blob` / `File`                 | Node.js e browser | Un `File` fornisce il suo `name` (e la sua estensione).                                                                                                |
| `Uint8Array` (incluso `Buffer`) | Node.js e browser | Passa `filename` per impostare l'estensione.                                                                                                           |
| `ArrayBuffer`                   | Node.js e browser | Passa `filename` per impostare l'estensione.                                                                                                           |

L'estensione dell'oggetto deriva da `filename`, poi dal basename del percorso o dal nome del `File`. I byte e un semplice `Blob` non hanno nome, quindi **passa `filename`** (ad esempio `"data.json"`) quando li carichi.

<Note>
  In Node.js, un percorso che non può essere aperto lancia un semplice `Error` (`Cannot open file: <path>`, con l'errore originale in `cause`). In un browser, passare un percorso fallisce prima, con l'errore dell'importazione di `node:fs`. Usa invece un `File` proveniente da un `<input type="file">`.
</Note>

### Opzioni

| Opzione           | Tipo                         | Descrizione                                                                                                                                                                                        |
| ----------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`            | `string`                     | Nome dell'oggetto **senza estensione**, conforme a `^[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}$`, senza `..`, che non termini con `-ex<digits>`. Obbligatorio, a meno che un token di upload non lo fissi. |
| `prefix`          | `string`                     | Percorso simile a una cartella: fino a 8 segmenti conformi a `^[A-Za-z0-9_][A-Za-z0-9_.-]{0,63}$`, 256 caratteri.                                                                                  |
| `private`         | `boolean`                    | Predefinito `false`. Gli oggetti privati ricevono sempre un hash di sicurezza e hanno `url: null`.                                                                                                 |
| `security_hash`   | `boolean`                    | Aggiunge `_<hash>` al nome.                                                                                                                                                                        |
| `expire`          | `string`                     | `"30"` (giorni), `"30d"` o `"168h"`; da 7 a 1825 giorni (Enterprise fino a 1 ora). La scadenza diventa parte dell'id.                                                                              |
| `overwrite`       | `boolean`                    | `false` fallisce con `OBJECT_ALREADY_EXISTS` quando il nome è già in uso. **Solo upload semplici.**                                                                                                |
| `disposition`     | `"inline"` \| `"attachment"` | `Content-Disposition` dell'oggetto.                                                                                                                                                                |
| `auto_download`   | `boolean`                    | Forza un download (`application/octet-stream`).                                                                                                                                                    |
| `cache_control`   | `string`                     | `immutable`, `max-age=60..31536000` o `no-cache` (Enterprise).                                                                                                                                     |
| `metadata`        | `Record<string, string>`     | Pro ed Enterprise. Chiavi `^[a-z0-9-]{1,64}$` (mai `sq-*`), fino a 5 chiavi e 512 byte.                                                                                                            |
| `checksum_sha256` | `string`                     | 64 caratteri esadecimali minuscoli. Una mancata corrispondenza fallisce con `CHECKSUM_MISMATCH` e non viene memorizzato nulla. **Solo upload semplici.**                                           |
| `filename`        | `string`                     | Nome di file la cui estensione diventa l'estensione dell'oggetto. Per impostazione predefinita è il nome del `File` o il basename del percorso.                                                    |
| `mime_type`       | `string`                     | Usato solo per scegliere l'estensione quando `filename` non ne ha una. Il server ricava il `Content-Type`.                                                                                         |

Vedi [Object Post](/it/blob-reference/endpoint/post) per tutte le regole lato server.

### Risultato

| Campo                                  | Tipo             | Descrizione                                                                                                    |
| -------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------- |
| `id`                                   | `string`         | Id opaco dell'oggetto. [Memorizzalo così com'è](/it/sdks/blob/client#id-degli-oggetti).                        |
| `private`                              | `boolean`        | Se l'oggetto è privato.                                                                                        |
| `url`                                  | `string \| null` | URL pubblico, o `null` per un oggetto privato (usa [`downloadUrl()`](/it/sdks/blob/objects#link-di-download)). |
| `expires_at`                           | `string`         | Quando scade l'oggetto, se ha una scadenza.                                                                    |
| `size`                                 | `number`         | Dimensione in byte.                                                                                            |
| `name`, `prefix`, `sha256`, `replaced` |                  | Solo upload semplici.                                                                                          |
| `parts`                                | `number`         | Solo upload multipart: numero di parti inviate.                                                                |

## Upload semplici e multipart

`put()` sceglie il flusso di upload in base alla dimensione del file:

| Dimensione del file                         | Flusso                         | Endpoint                                                 |
| ------------------------------------------- | ------------------------------ | -------------------------------------------------------- |
| Fino a **90 MiB** (94.371.840 byte) inclusi | Upload semplice, una richiesta | [Object Post](/it/blob-reference/endpoint/post)          |
| Oltre 90 MiB, fino a **10 GiB**             | Upload multipart (a blocchi)   | [Chunked Init](/it/blob-reference/endpoint/chunked-init) |

Ogni file deve avere **almeno 512 byte**; i file più piccoli falliscono con `FILE_TOO_SMALL`. Un `max_size` di una regola o di un token di upload, o la tua quota di storage, possono abbassare il limite di 10 GiB.

### Come funziona un upload multipart

1. L'SDK avvia l'upload e il server risponde con i limiti delle parti (`max_size`, `max_parts`).
2. Il file viene diviso in parti di `min(max_size, max(16 MiB, ceil(size / max_parts)))` byte. Una parte è di solito di 16 MiB o più, ma è più piccola quando il `max_size` del server è più piccolo.
3. Le parti vengono inviate **6 alla volta**, il limite del server per le parti in transito. Una parte fallita viene [ritentata](/it/sdks/blob/errors#politica-di-retry) entro `maxRetries`.
4. Quando tutte le parti sono arrivate, l'SDK completa l'upload.

Se una parte fallisce definitivamente, o il completamento fallisce, l'SDK **attende le parti ancora in transito** e poi **annulla** l'upload, così nessuna parte arriva dopo l'annullamento. Viene lanciato l'errore originale. **Non c'è ripresa**: chiama di nuovo `put()`.

<Warning>
  Un upload multipart **non verifica `overwrite: false` né `checksum_sha256`**. Sostituisce sempre un oggetto esistente con lo stesso nome.
</Warning>

<Note>
  Un account può avere al massimo **32 upload multipart aperti** (condivisi con il gateway S3); uno in più fallisce con `TOO_MANY_OPEN_UPLOADS`. Poiché le parti vengono inviate 6 alla volta per account, esegui **un solo upload di grandi dimensioni alla volta**.
</Note>

## Upload dal browser

Non inviare mai la chiave API a un browser. Invece, il tuo server genera un **token di upload** a breve durata e il browser carica con quello.

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

    const blob = new SquareCloudBlob(process.env.SQUARECLOUD_API_KEY);

    // e.g. inside your API route
    const { token } = await blob.uploadTokens.create({
        prefix: "avatars/",
        security_hash: true,
        max_size: 5 * 1024 * 1024,
        allowed_extensions: ["png", "jpg"],
    });
    // send only `token` to the browser
    ```
  </Tab>

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

    const upload = new SquareCloudBlob(token);
    const { url } = await upload.put(input.files[0], { name: "avatar" });
    ```
  </Tab>
</Tabs>

Un client creato con un token può **solo chiamare `put()`**, inclusi gli upload multipart. Qualsiasi altro metodo fallisce con `403 UPLOAD_TOKEN_NOT_ALLOWED`.

### `uploadTokens.create(options)`

Il token vincola ogni opzione con cui è stato generato.

| Opzione              | Tipo                     | Descrizione                                                                                         |
| -------------------- | ------------------------ | --------------------------------------------------------------------------------------------------- |
| `name`               | `string`                 | Fissa il nome dell'oggetto. Senza di esso, l'hash di sicurezza viene sempre applicato.              |
| `prefix`             | `string`                 | Fissa il prefisso.                                                                                  |
| `private`            | `boolean`                | Fissa la visibilità.                                                                                |
| `security_hash`      | `boolean`                | Aggiunge `_<hash>` al nome.                                                                         |
| `expire`             | `string`                 | Scadenza dell'oggetto, come in `put()`.                                                             |
| `max_size`           | `number`                 | Dimensione massima del file in byte.                                                                |
| `allowed_extensions` | `string[]`               | Da 1 a 20 estensioni.                                                                               |
| `metadata`           | `Record<string, string>` | Metadati applicati all'oggetto caricato.                                                            |
| `expires_in`         | `number`                 | Durata del token in secondi, da 60 a 3600 (predefinito 900).                                        |
| `max_uses`           | `number`                 | Upload consentiti, da 1 a 100 (predefinito 1). Dopodiché il token fallisce con `UPLOAD_TOKEN_USED`. |

Restituisce `{ token, expires_at, max_uses }`. Vedi [Upload Tokens](/it/blob-reference/endpoint/upload-tokens) per le regole lato server.

<Note>
  `uploadTokens.create()` è una scrittura e ha un **solo tentativo**: non viene mai ripetuto.
</Note>