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

# Envois

> Envoyez des fichiers avec put() : chemins de fichier, Blob/File ou octets, envois multipart automatiques au-delà de 90 MiB, et jetons d'envoi pour envoyer directement depuis le navigateur.

## `put(file, options)`

`put()` envoie un fichier et renvoie le nouvel objet.

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

### Entrées

| Entrée                            | Environnement          | Remarques                                                                                                                                                 |
| --------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `string` (chemin de fichier)      | **Node.js uniquement** | Ouvert avec `fs.openAsBlob` et **diffusé en flux depuis le disque**, jamais chargé entièrement en mémoire. L'extension provient du nom de base du chemin. |
| `Blob` / `File`                   | Node.js et navigateurs | Un `File` fournit son `name` (et son extension).                                                                                                          |
| `Uint8Array` (y compris `Buffer`) | Node.js et navigateurs | Passez `filename` pour définir l'extension.                                                                                                               |
| `ArrayBuffer`                     | Node.js et navigateurs | Passez `filename` pour définir l'extension.                                                                                                               |

L'extension de l'objet provient de `filename`, puis du nom de base du chemin ou du nom du `File`. Les octets et un `Blob` simple n'ont pas de nom : **passez donc `filename`** (par exemple `"data.json"`) lorsque vous les envoyez.

<Note>
  Dans Node.js, un chemin qui ne peut pas être ouvert lève une `Error` simple (`Cannot open file: <path>`, avec l'erreur d'origine dans `cause`). Dans un navigateur, passer un chemin échoue plus tôt, avec l'erreur de l'import de `node:fs`. Utilisez plutôt un `File` issu d'un `<input type="file">`.
</Note>

### Options

| Option            | Type                         | Description                                                                                                                                                                           |
| ----------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`            | `string`                     | Nom de l'objet **sans extension**, correspondant à `^[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}$`, sans `..`, ne se terminant pas par `-ex<digits>`. Requis, sauf si un jeton d'envoi le fixe. |
| `prefix`          | `string`                     | Chemin de type dossier : jusqu'à 8 segments de `^[A-Za-z0-9_][A-Za-z0-9_.-]{0,63}$`, 256 caractères.                                                                                  |
| `private`         | `boolean`                    | `false` par défaut. Les objets privés reçoivent toujours un hash de sécurité et ont `url: null`.                                                                                      |
| `security_hash`   | `boolean`                    | Ajoute `_<hash>` au nom.                                                                                                                                                              |
| `expire`          | `string`                     | `"30"` (jours), `"30d"` ou `"168h"` ; de 7 à 1825 jours (Enterprise jusqu'à 1 heure). L'expiration fait partie de l'identifiant.                                                      |
| `overwrite`       | `boolean`                    | `false` échoue avec `OBJECT_ALREADY_EXISTS` lorsque le nom est déjà pris. **Envois simples uniquement.**                                                                              |
| `disposition`     | `"inline"` \| `"attachment"` | `Content-Disposition` de l'objet.                                                                                                                                                     |
| `auto_download`   | `boolean`                    | Force un téléchargement (`application/octet-stream`).                                                                                                                                 |
| `cache_control`   | `string`                     | `immutable`, `max-age=60..31536000` ou `no-cache` (Enterprise).                                                                                                                       |
| `metadata`        | `Record<string, string>`     | Pro et Enterprise. Clés `^[a-z0-9-]{1,64}$` (jamais `sq-*`), jusqu'à 5 clés et 512 octets.                                                                                            |
| `checksum_sha256` | `string`                     | 64 caractères hexadécimaux en minuscules. Une non-correspondance échoue avec `CHECKSUM_MISMATCH` et rien n'est stocké. **Envois simples uniquement.**                                 |
| `filename`        | `string`                     | Nom de fichier dont l'extension devient celle de l'objet. Par défaut, le nom du `File` ou le nom de base du chemin.                                                                   |
| `mime_type`       | `string`                     | Utilisé uniquement pour choisir l'extension lorsque `filename` n'en a pas. Le serveur déduit le `Content-Type`.                                                                       |

Voir [Object Post](/fr/blob-reference/endpoint/post) pour l'ensemble des règles côté serveur.

### Résultat

| Champ                                  | Type             | Description                                                                                                              |
| -------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `id`                                   | `string`         | Identifiant opaque de l'objet. [Stockez-le tel quel](/fr/sdks/blob/client#ids-des-objets).                               |
| `private`                              | `boolean`        | Indique si l'objet est privé.                                                                                            |
| `url`                                  | `string \| null` | URL publique, ou `null` pour un objet privé (utilisez [`downloadUrl()`](/fr/sdks/blob/objects#liens-de-téléchargement)). |
| `expires_at`                           | `string`         | Moment où l'objet expire, s'il a une expiration.                                                                         |
| `size`                                 | `number`         | Taille en octets.                                                                                                        |
| `name`, `prefix`, `sha256`, `replaced` |                  | Envois simples uniquement.                                                                                               |
| `parts`                                | `number`         | Envois multipart uniquement : nombre de parties envoyées.                                                                |

## Envois simples et multipart

`put()` choisit le mode d'envoi en fonction de la taille du fichier :

| Taille du fichier                             | Mode                            | Endpoint                                                 |
| --------------------------------------------- | ------------------------------- | -------------------------------------------------------- |
| Jusqu'à **90 MiB** (94 371 840 octets) inclus | Envoi simple, une seule requête | [Object Post](/fr/blob-reference/endpoint/post)          |
| Au-delà de 90 MiB, jusqu'à **10 GiB**         | Envoi multipart (chunked)       | [Chunked Init](/fr/blob-reference/endpoint/chunked-init) |

Chaque fichier doit faire **au moins 512 octets** ; les fichiers plus petits échouent avec `FILE_TOO_SMALL`. Le `max_size` d'une règle ou d'un jeton d'envoi, ou votre quota de stockage, peut abaisser le plafond de 10 GiB.

### Déroulement d'un envoi multipart

1. Le SDK démarre l'envoi, et le serveur répond avec ses limites de parties (`max_size`, `max_parts`).
2. Le fichier est découpé en parties de `min(max_size, max(16 MiB, ceil(size / max_parts)))` octets. Une partie fait généralement 16 MiB ou plus, mais elle est plus petite lorsque le `max_size` du serveur est plus petit.
3. Les parties sont envoyées **6 à la fois**, la limite du serveur pour les parties en cours. Une partie échouée fait l'objet de [nouvelles tentatives](/fr/sdks/blob/errors#politique-de-nouvelles-tentatives) dans la limite de `maxRetries`.
4. Lorsque toutes les parties sont arrivées, le SDK finalise l'envoi.

Si une partie échoue définitivement, ou si la finalisation échoue, le SDK **attend les parties encore en cours** puis **annule** l'envoi, de sorte qu'aucune partie n'arrive après l'annulation. L'erreur d'origine est levée. Il n'y a **pas de reprise** : appelez à nouveau `put()`.

<Warning>
  Un envoi multipart **ne vérifie ni `overwrite: false` ni `checksum_sha256`**. Il remplace toujours un objet existant portant le même nom.
</Warning>

<Note>
  Un compte peut avoir au maximum **32 envois multipart ouverts** (partagés avec la passerelle S3) ; un de plus échoue avec `TOO_MANY_OPEN_UPLOADS`. Comme les parties partent 6 à la fois par compte, effectuez **un seul gros envoi à la fois**.
</Note>

## Envoyer depuis le navigateur

N'envoyez jamais la clé API à un navigateur. À la place, votre serveur génère un **jeton d'envoi** de courte durée et le navigateur envoie avec celui-ci.

<Tabs>
  <Tab title="Serveur">
    ```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="Navigateur">
    ```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 créé avec un jeton ne peut **appeler que `put()`**, envois multipart compris. Toute autre méthode échoue avec `403 UPLOAD_TOKEN_NOT_ALLOWED`.

### `uploadTokens.create(options)`

Le jeton fige toutes les options avec lesquelles il a été généré.

| Option               | Type                     | Description                                                                                     |
| -------------------- | ------------------------ | ----------------------------------------------------------------------------------------------- |
| `name`               | `string`                 | Fixe le nom de l'objet. Sans lui, le hash de sécurité est toujours appliqué.                    |
| `prefix`             | `string`                 | Fixe le préfixe.                                                                                |
| `private`            | `boolean`                | Fixe la visibilité.                                                                             |
| `security_hash`      | `boolean`                | Ajoute `_<hash>` au nom.                                                                        |
| `expire`             | `string`                 | Expiration de l'objet, comme dans `put()`.                                                      |
| `max_size`           | `number`                 | Taille maximale du fichier en octets.                                                           |
| `allowed_extensions` | `string[]`               | De 1 à 20 extensions.                                                                           |
| `metadata`           | `Record<string, string>` | Métadonnées appliquées à l'objet envoyé.                                                        |
| `expires_in`         | `number`                 | Durée de vie du jeton en secondes, de 60 à 3600 (900 par défaut).                               |
| `max_uses`           | `number`                 | Envois autorisés, de 1 à 100 (1 par défaut). Au-delà, le jeton échoue avec `UPLOAD_TOKEN_USED`. |

Elle renvoie `{ token, expires_at, max_uses }`. Voir [Jetons d'envoi](/fr/blob-reference/endpoint/upload-tokens) pour les règles côté serveur.

<Note>
  `uploadTokens.create()` est une écriture et a droit à **une seule tentative** : elle n'est jamais réessayée.
</Note>