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

> Installez @squarecloud/blob et créez un client SquareCloudBlob avec une clé API ou un jeton d'envoi. La seule option est maxRetries.

<Info>
  Cette page documente **`@squarecloud/blob` v4**. Vous effectuez une mise à niveau depuis la v3 ? Lisez le [guide de migration v3 → v4](/fr/sdks/blob/migrating_to_v4).
</Info>

`@squarecloud/blob` est le SDK JavaScript officiel de [Square Cloud Blob Storage](/fr/services/blob). Il couvre chaque endpoint de l'[API Blob](/fr/blob-reference/authentication), ainsi que la [passerelle S3](/fr/blob-reference/s3-compatibility).

## Prérequis

* **Node.js 20** ou plus récent, ou n'importe quel navigateur moderne. Le SDK n'utilise que `fetch`, `FormData` et `Blob`.
* Distribué en **ESM et CommonJS**, avec **aucune dépendance d'exécution**.
* `@aws-sdk/client-s3` est une **dépendance pair optionnelle**, nécessaire uniquement si vous appelez [`s3()`](/fr/sdks/blob/s3).

## Installation

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

## Créer le 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>

### Constructeur

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

| Paramètre            | Type     | Par défaut | Description                                                                                                                                                                                                                                                                          |
| -------------------- | -------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `credential`         | `string` | requis     | Une **clé API**, ou un **jeton d'envoi** (`squp_...`) qui ne peut appeler que `put()`.                                                                                                                                                                                               |
| `options.maxRetries` | `number` | `2`        | Nombre de nouvelles tentatives d'une requête répétable sans risque (un `GET` ou une partie multipart) après une erreur réseau ou un `5xx`. `0` désactive les nouvelles tentatives. Voir [Politique de nouvelles tentatives](/fr/sdks/blob/errors#politique-de-nouvelles-tentatives). |

## Identifiants

L'identifiant est envoyé **tel quel** dans l'en-tête `Authorization`, sans préfixe `Bearer`.

| Identifiant                | D'où il provient                                                                                      | Ce qu'il permet                                                                                               |
| -------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| Clé API                    | [Tableau de bord Square Cloud](https://squarecloud.app/account/security)                              | Toutes les méthodes, selon ses [scopes](/fr/blob-reference/authentication#scopes) `blob:read` / `blob:write`. |
| Jeton d'envoi (`squp_...`) | [`blob.uploadTokens.create()`](/fr/sdks/blob/uploads#envoyer-depuis-le-navigateur), sur votre serveur | Uniquement `put()`. Toute autre méthode échoue avec `403 UPLOAD_TOKEN_NOT_ALLOWED`.                           |

<Warning>
  N'envoyez jamais une clé API à un navigateur. Générez un jeton d'envoi sur votre serveur et ne transmettez que le jeton au client.
</Warning>

## Ce que vous ne pouvez pas configurer

`maxRetries` est la **seule** option. Le client n'accepte pas :

* **Une URL de base.** Elle est fixée à `https://blob.squarecloud.app/v1/`.
* **Un `fetch` personnalisé.** Les requêtes utilisent le `fetch` global.
* **Un timeout ou un `AbortSignal`.** Un appel dure aussi longtemps que `fetch` attend, et il n'y a aucun moyen de l'annuler.
* **Des en-têtes personnalisés.**

## Méthodes

Chaque méthode renvoie des données brutes (pas de classes), sauf `s3()`, qui renvoie un `S3Client`. Les options et les résultats utilisent les noms de champs propres à l'API, le plus souvent en snake\_case (`security_hash`, `expires_at`), la [référence de l'API Blob](/fr/blob-reference/authentication) s'applique donc telle quelle.

| Groupe                | Méthodes                                                                                                                                                                                        | Page                                                         |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `blob`                | `put(file, options)`                                                                                                                                                                            | [Envois](/fr/sdks/blob/uploads)                              |
| `blob.uploadTokens`   | `create(options)`                                                                                                                                                                               | [Envois](/fr/sdks/blob/uploads#envoyer-depuis-le-navigateur) |
| `blob`                | `list(options)`, `listPage(options)`, `info(id)`, `downloadUrl(id, options)`, `update(ids, changes)`, `delete(ids)`, `copy(source, destination, options)`, `move(source, destination, options)` | [Objets](/fr/sdks/blob/objects)                              |
| `blob.shares`         | `create(object, options)`, `list()`, `revoke(id)`                                                                                                                                               | [Partage](/fr/sdks/blob/sharing)                             |
| `blob.rules` / `blob` | `get()`, `set(rules)` / `stats()`                                                                                                                                                               | [Règles et statistiques](/fr/sdks/blob/rules_and_stats)      |
| `blob`                | `s3Credentials()`, `s3()`                                                                                                                                                                       | [S3](/fr/sdks/blob/s3)                                       |

Le paquet exporte aussi `SquareCloudBlobError`, le type `BlobErrorCode` et chaque type d'option et de résultat (`PutOptions`, `PutResult`, `ListedObject`, `ObjectInfo`, `Share`, `Rule`, ...). Voir [Erreurs](/fr/sdks/blob/errors).

## IDs des objets

Chaque objet est identifié par un **identifiant opaque**, comme `pub/...` pour un objet public ou `prv/...` pour un objet privé.

* **Stockez l'identifiant exactement tel qu'il est renvoyé.** Ne le construisez jamais à la main et ne l'analysez jamais.
* **Modifier `private` ou `expire` change l'identifiant.** Remplacez toujours l'identifiant stocké par celui que renvoie [`update()`](/fr/sdks/blob/objects#mettre-à-jour-des-objets).
* **Utilisez l'`url` de la réponse** au lieu de construire des URL. Les objets privés ont `url: null` : obtenez un lien avec [`downloadUrl()`](/fr/sdks/blob/objects#liens-de-téléchargement) ou un [partage](/fr/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
```