@onveloz/blob

SDK oficial do Veloz Blob — envie, sirva e remova arquivos por uma CDN global.

Cada blob store recebe um domínio dedicado (ex.: meu-app.cdn.runveloz.com) e você envia objetos a partir do seu app com este SDK ou direto pela API REST.

Instalação

npm install @onveloz/blob

Requer Node 18+ (ou qualquer runtime com fetch global). Em ambientes sem fetch, passe { fetch } em cada chamada.

Autenticação

Toda chamada usa uma chave vbk_* vinculada a um blob store, gerada na aba Chaves de API do store no dashboard. Defina no ambiente:

VELOZ_BLOB_TOKEN=vbk_sua_chave

Trate a chave como senha: nunca commite no Git. Para apontar para outro ambiente, defina VELOZ_BLOB_API ou passe apiUrl em cada chamada.

Uso

import { put, del } from "@onveloz/blob";

// Lê VELOZ_BLOB_TOKEN do ambiente (ou passe { token }).
const blob = await put("uploads/foto.png", arquivo, {
  access: "public",
  contentType: "image/png",
});

console.log(blob.url); // https://meu-app.cdn.runveloz.com/uploads/foto.png

await del("uploads/foto.png");

put aceita string, Blob, ArrayBuffer, ArrayBufferView, Uint8Array ou ReadableStream como corpo.

Cliente com configuração fixa

import { BlobClient } from "@onveloz/blob";

const blob = new BlobClient({ token: process.env.VELOZ_BLOB_TOKEN });
await blob.put("uploads/foto.png", arquivo);
await blob.del("uploads/foto.png");

Erros

O SDK lança erros tipados:

| Erro | Quando | | ----------------- | ------------------------------------------ | | BlobAccessError | token ausente ou inválido (401/403) | | BlobUploadError | falha no envio do arquivo à CDN | | BlobError | genérico, com code e status (ex.: 429) |

Como funciona

O envio é em dois passos, transparente para quem usa o SDK:

1. POST /api/blob/v1/upload-url troca a sua chave por uma URL de upload assinada e temporária.
2. PUT direto nessa URL — o payload é encaminhado ao armazenamento via CDN.

A chave vbk_* só trafega no cabeçalho Authorization, nunca na URL.

Documentação

Guia completo e referência da API REST: https://onveloz.com/docs/blob

Licença

MIT