Skip to main content
Cette page documente @squarecloud/blob v4. Vous effectuez une mise à niveau depuis la v3 ? Lisez le guide de migration v3 → v4.
@squarecloud/blob est le SDK JavaScript officiel de Square Cloud Blob Storage. Il couvre chaque endpoint de l’API Blob, ainsi que la passerelle S3.

​
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().

​
Installation

​
Créer le client

​
Constructeur

​
Identifiants

L’identifiant est envoyé tel quel dans l’en-tête Authorization, sans préfixe Bearer.
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.

​
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 s’applique donc telle quelle. 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.

​
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().
  • 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() ou un partage.