Skip to main content
Esta página documenta o @squarecloud/blob v4. Atualizando da v3? Leia o guia de migração v3 → v4.
@squarecloud/blob é o SDK oficial em JavaScript para o Blob Storage da Square Cloud. Ele cobre todos os endpoints da API de Blob, além do gateway S3.

​
Requisitos

  • Node.js 20 ou superior, ou qualquer navegador moderno. O SDK usa apenas fetch, FormData e Blob.
  • Distribuído como ESM e CommonJS, com zero dependências em tempo de execução.
  • @aws-sdk/client-s3 é uma peer dependency opcional, necessária apenas se você chamar s3().

​
Instalação

​
Criando o cliente

Os exemplos leem a chave da variável de ambiente SQUARECLOUD_API_KEY. Defina-a no terminal em que você vai executá-los:
Confira o cliente com uma primeira chamada. stats() lê o seu uso:
Ele imprime o número de objetos e os bytes que eles ocupam, por exemplo:

​
Construtor

​
Credenciais

A credencial é enviada como está no header Authorization, sem o prefixo Bearer.
Nunca envie uma chave de API para um navegador. Gere um token de upload no seu servidor e entregue apenas o token ao cliente.

​
O que você não pode configurar

maxRetries é a única opção. O cliente não aceita:
  • Uma URL base. Ela é fixa em https://blob.squarecloud.app/v1/.
  • Um fetch personalizado. As requisições usam o fetch global.
  • Um timeout ou um AbortSignal. Uma chamada dura o tempo que o fetch esperar, e não há como cancelá-la.
  • Headers personalizados.

​
Métodos

Todo método retorna dados simples (sem classes), exceto s3(), que retorna um S3Client. Opções e resultados usam os próprios nomes de campos da API, em sua maioria em snake_case (security_hash, expires_at), então a referência da API de Blob se aplica diretamente. O pacote também exporta SquareCloudBlobError, o tipo BlobErrorCode e todos os tipos de opções e resultados (PutOptions, PutResult, ListedObject, ObjectInfo, Share, Rule, …). Veja Erros.

​
Ids de objetos

Todo objeto é identificado por um id opaco, como pub/... para um objeto público ou prv/... para um privado.
  • Armazene o id exatamente como retornado. Nunca monte um manualmente e nunca o interprete.
  • Alterar private ou expire altera o id. Sempre substitua o id armazenado pelo que update() retorna.
  • Use a url da resposta em vez de montar URLs. Objetos privados têm url: null: obtenha um link com downloadUrl() ou um compartilhamento.

​
Próximos passos

Uploads

Envie arquivos e gere tokens de upload.

Guia rápido da API do Blob

URL base e um primeiro upload com curl.

Planos do Blob Storage

O que cada plano inclui.