# SDKs A Vibedasher entrega SDKs oficiais e totalmente tipados para **TypeScript** e **Python**, gerados a partir da especificação OpenAPI da API para que permaneçam sincronizados com a plataforma. É assim que seu próprio código alcança a plataforma mantida: execute SQL contra seus conjuntos de dados, dispare atualizações, gerencie conexões e direitos de acesso, conecte um painel a dados ao vivo, ou automatize a partir de um script qualquer coisa que as [ferramentas MCP](/pt-BR/guides/build-with-your-agent.md) fazem a partir de um agente. | Linguagem | Pacote | Documentado aqui | | ---------- | ------------------------------------------------------------------------ | ---------------- | | TypeScript | [`@vibedasher/client`](https://www.npmjs.com/package/@vibedasher/client) | 4.1.5 | | Python | [`vibedasher`](https://pypi.org/project/vibedasher/) | 4.3.19 | Ambos os SDKs se autenticam com uma **chave de API** no cabeçalho `X-Api-Key`. Gere uma no app em **Configurações → Chaves de API** em [cloud.vibedasher.com](https://cloud.vibedasher.com) — veja [Autenticação](/pt-BR/api/authentication.md). (Os SDKs são o caminho de *código*; se seu agente está conduzindo a Vibedasher via MCP, ele faz login com `vibedasher login` em vez disso e não precisa de chave nenhuma — veja [Construa com seu agente](/pt-BR/guides/build-with-your-agent.md).) Nenhum dos dois clientes precisa que você diga em qual região sua conta vive. Sem URL base e sem `region`, ambos resolvem para `https://api.vibedasher.com/api`, que roteia cada requisição pela credencial que ela carrega — veja [Um único host, roteado pela sua credencial](/pt-BR/api/authentication.md#one-host-routed-by-your-credential). Passar `region` continua suportado e fixa o cliente no hostname próprio daquela região, `https://api.{region}.vibedasher.com/api`; um `baseUrl` / `base_url` explícito prevalece sobre os dois. (`region` passou a ser opcional em `@vibedasher/client` 4.1.5 e `vibedasher` 4.3.19.) Procurando um endpoint específico? Navegue pela **[Referência da API](/pt-BR/reference/vibedasher-sdk-api.md)** completa — cada operação agrupada por recurso, com exemplos de requisição em curl / Python / TypeScript gerados a partir das mesmas assinaturas com as quais os SDKs são construídos. ## O formato de cada chamada[​](#o-formato-de-cada-chamada "Link direto para O formato de cada chamada") Ambos os SDKs expõem o mesmo **cliente fluente agrupado por recurso**. Construa-o uma vez, depois chame métodos agrupados por recurso. As assinaturas são **simples**: primeiro os parâmetros de caminho (na ordem do caminho), depois o corpo da requisição, depois um objeto de opções opcional no final contendo os parâmetros de consulta. Não há objetos wrapper `path` / `query` / `body`. Os recursos são os mesmos 23 em ambas as linguagens, camelCase em TypeScript e snake\_case em Python: `accounts`, `aiProviders`, `apiKeys`, `chats`, `connections`, `dashboardSubscriptions`, `datasets`, `dbt`, `embedTokens`, `folders`, `groups`, `images`, `questions`, `refreshes`, `skills`, `sql`, `subscriptions`, `tasks`, `templates`, `tools`, `upload`, `users`, `viz`. Uma resposta não-2xx **lança uma exceção** — `VibedasherApiError` em ambas as linguagens. Métodos nunca resolvem para uma união de erro, então você não verifica um resultado antes de usá-lo. ## TypeScript[​](#typescript "Link direto para TypeScript") ``` npm install @vibedasher/client ``` ``` import { Vibedasher, VibedasherApiError } from '@vibedasher/client'; const client = new Vibedasher({ apiKey: process.env.VIBEDASHER_API_KEY!, }); // List datasets — query params go in the trailing options object const page = await client.datasets.list({ limit: 50 }); // Create — the body is positional const created = await client.datasets.create({ name: 'Sales', type: 'csv' }); // Fetch one by id — path params are positional const one = await client.datasets.get(created.dataset.id); // Update — path param, then body const updated = await client.datasets.update(one.dataset.id, { name: 'Sales 2026' }); ``` Todo método é tipado de ponta a ponta: os tipos de argumento e o tipo de resposta resolvido vêm da especificação, e as interfaces por recurso (`DatasetsResource`, `DatasetsListOptions`, …) e os tipos de modelo (`DatasetResponse`, `DatasetUpdate`, …) são exportados a partir da raiz do pacote, caso você queira anotar uma variável. ### Executando SQL[​](#executando-sql "Link direto para Executando SQL") `client.query` é o método escrito à mão que a superfície gerada não tem: uma chamada de entrada, resultados colunares tipados de saída. ``` const result = await client.query({ sql: 'SELECT country, SUM(revenue) AS revenue FROM sales GROUP BY 1', }); console.log(result.columns, result.rows); ``` `datasetIds` é opcional — omita-o e o servidor resolve o conjunto de conjuntos de dados a partir dos aliases que seu SQL referencia, aplicando exatamente a mesma autorização. ### Enviando um CSV[​](#enviando-um-csv "Link direto para Enviando um CSV") ``` const uploaded = await client.datasets.upload({ name: 'Sales', content: 'country,revenue\nFR,10\nDE,12\n', }); console.log(uploaded.cleanSQLName); // the alias to use in client.query SQL ``` ### Válvula de escape[​](#válvula-de-escape "Link direto para Válvula de escape") O cliente `fetch` subjacente está na instância como `client.http`, caso você precise de interceptadores, um `fetch` personalizado, ou sobreposições por chamada. Não há um singleton em nível de módulo para configurar: cada instância de `Vibedasher` é dona do seu próprio cliente, então dois clientes em um mesmo processo nunca sobrescrevem a URL base ou a chave um do outro. ## Python[​](#python "Link direto para Python") ``` pip install vibedasher ``` ``` from vibedasher import Vibedasher, VibedasherApiError from vibedasher.models import DatasetCreate, DatasetUpdate client = Vibedasher(api_key="") # List datasets — query params are keyword-only page = client.datasets.list(limit=50) # Create — the body is the first positional argument created = client.datasets.create(DatasetCreate(name="Sales", type_="csv")) # Fetch one by id — path params are positional one = client.datasets.get(created.dataset.id) # Update — path param, then body updated = client.datasets.update(one.dataset.id, DatasetUpdate(name="Sales 2026")) ``` Modelos de requisição e resposta vivem em `vibedasher.models`. Os atributos de recurso são snake\_case (`client.datasets`, `client.api_keys`, `client.ai_providers`, `client.embed_tokens`, `client.viz`, …), e os métodos também são. ### Executando SQL[​](#executando-sql-1 "Link direto para Executando SQL") ``` result = client.query(sql="SELECT country, SUM(revenue) AS revenue FROM sales GROUP BY 1") print(result.columns, result.rows) ``` ### Enviando um CSV[​](#enviando-um-csv-1 "Link direto para Enviando um CSV") ``` uploaded = client.datasets.upload(name="Sales", content="country,revenue\nFR,10\nDE,12\n") print(uploaded["cleanSQLName"]) # the alias to use in client.query SQL ``` ### Válvula de escape[​](#válvula-de-escape-1 "Link direto para Válvula de escape") Os módulos de operação simples sob `vibedasher.api.` ainda são entregues para qualquer coisa que a fachada não cobre. Construa um cliente bruto com `create_client` e chame `.sync()`, `.sync_detailed()`, `.asyncio()`, ou `.asyncio_detailed()`: ``` from vibedasher import create_client from vibedasher.api.datasets import read_datasets raw = create_client(api_key="") datasets = read_datasets.sync(client=raw) ``` ## Tratamento de erros[​](#tratamento-de-erros "Link direto para Tratamento de erros") Ambos os SDKs lançam uma exceção em uma resposta não-2xx, então o caminho feliz é lido direto e os erros são capturados onde você quer tratá-los. **TypeScript:** ``` import { Vibedasher, VibedasherApiError } from '@vibedasher/client'; try { const page = await client.datasets.list({ limit: 50 }); console.log(page.datasets); } catch (err) { if (err instanceof VibedasherApiError) { console.error(`Request failed (${err.status})`, err.detail, err.requestId); } else { throw err; } } ``` **Python:** ``` from vibedasher import VibedasherApiError try: page = client.datasets.list(limit=50) except VibedasherApiError as err: print(f"Request failed ({err.status_code})", err.detail, err.request_id) ``` Códigos de status comuns: **401/403** (chave de API ausente ou inválida, ou uma chave usada em uma rota somente por sessão), **404** (não encontrado, ou uma viz que não está publicada), **422** (erro de validação de requisição). A página de referência de cada endpoint lista as respostas exatas que ele pode retornar. ## Paginação[​](#paginação "Link direto para Paginação") Endpoints de listagem retornam uma página de resultados mais um cursor `nextKey`. Você raramente precisa conduzir esse cursor você mesmo: todo recurso listável carrega `iterAll()` (TypeScript) / `iter_all()` (Python), que percorre as páginas e produz as linhas. **TypeScript:** ``` for await (const ds of client.datasets.iterAll()) { handle(ds); } ``` **Python:** ``` for ds in client.datasets.iter_all(): handle(ds) ``` Ambos também expõem a forma em nível de página (`iterPages()` / `iter_pages()`) quando você quer o envelope em vez das linhas. Conduzir o cursor manualmente ainda funciona — passe `nextKey` de volta como `exclusiveStartKey` (`exclusive_start_key` em Python) e pare quando ele voltar `null`/`None` — mas os iteradores também detectam um cursor que para de avançar e lançam uma exceção em vez de entrar em loop para sempre. O nome no fio — o que a aba cURL e a tabela de parâmetros de cada página de referência mostram — é sempre `exclusiveStartKey`; o SDK TypeScript mantém essa grafia camelCase como chave da opção, e o SDK Python expõe o mesmo parâmetro como o argumento nomeado `exclusive_start_key`. É um único cursor, escrito conforme a linguagem — nunca os dois em uma mesma requisição. ## Ressalva sobre tipagem de resposta[​](#ressalva-sobre-tipagem-de-resposta "Link direto para Ressalva sobre tipagem de resposta") Algumas rotas da API atualmente retornam respostas fracamente tipadas (`object` / `Any`) porque declaram um formato de resposta genérico no backend. Corpos de requisição, parâmetros de consulta/caminho, e um conjunto crescente de respostas são totalmente tipados. Os tipos de resposta estão sendo reforçados módulo por módulo — atualize o SDK para obter as melhorias. observação Os SDKs são gerados, nunca editados à mão. Se você notar uma lacuna, ela quase sempre está a montante, na especificação OpenAPI da API — entre em contato pela [página de contato](https://vibedasher.com/contact).