@superdb/client

Substituto do @supabase/supabase-js para o SuperDB: os mesmos nomes de método, apontando para o seu projeto no SuperDB.

- import { createClient } from '@supabase/supabase-js';
+ import { createClient } from '@superdb/client';

Instalar

npm install @superdb/client

Começar

import { createClient } from '@superdb/client';

const db = createClient('https://auth.superdb.com.br', 'SUA_ANON_KEY', {
  project: 'meu-projeto', // o slug do projeto — obrigatório para usar .from()
});

await db.auth.signInWithPassword({ email: '[email protected]', password: 'senha-forte' });

const { data, error } = await db
  .from('tarefas')
  .select('id, titulo')
  .eq('feita', false)
  .order('criada_em', { ascending: false })
  .limit(20);

Autenticação (db.auth)

| Método | O que faz | | --- | --- | | signUp, signInWithPassword | Cadastro e login por e-mail (ou telefone) e senha | | signInWithOtp, verifyOtp | Código por e-mail, SMS ou WhatsApp (options: { channel: 'whatsapp' }) | | signInWithOAuth, exchangeCodeForSession | Google, GitHub e Apple, com PKCE | | getSession, getUser, refreshSession, setSession | Sessão atual | | onAuthStateChange | Avisa INITIAL_SESSION, SIGNED_IN, SIGNED_OUT, TOKEN_REFRESHED, USER_UPDATED | | updateUser | { data } mescla os metadados; { password, current_password } troca a senha | | resetPasswordForEmail, resetPassword | Manda o link de redefinição; conclui com o token do link | | signOut | Sai ('local' ou 'global') | | mfa.enroll, mfa.verify, mfa.factors | Segundo fator (TOTP) |

A sessão se renova sozinha antes de o token (1 hora) vencer. Para desligar: createClient(url, key, { project, autoRefreshToken: false }).

Diferenças do supabase-js

• updateUser({ password }): se a conta já tem senha, mande também current_password.
• updateUser({ email }) ainda não existe (devolve erro not_implemented).
• Redefinir a senha: o link volta com #token=...; na sua tela de nova senha, chame db.auth.resetPassword({ token, password }).

Dados (db.from() e db.rpc())

• Leitura e escrita: select, insert, upsert (onConflict, ignoreDuplicates), update, delete.
• Filtros: eq, neq, gt, gte, lt, lte, like, ilike, is, in, or, not, match, filter, contains, containedBy, overlaps, range*, textSearch.
• Modificadores: order (com nullsFirst), limit, range, single, maybeSingle, abortSignal, throwOnError, returns.
• Contagem: select('*', { count: 'exact', head: true }).
• Tabela relacionada: order, limit e or aceitam { referencedTable }.
• rpc(fn, args, { get?, head?, count? }).

Como no supabase-js v2, insert, update, upsert e delete só devolvem as linhas quando você encadeia .select().

Arquivos (db.storage)

storage.from(bucket): upload, download, list, remove, createSignedUrl e getPublicUrl.

Realtime

db.channel() ainda não existe no SDK. Gere um token em POST https://auth.superdb.com.br/rt/v1/token (Bearer: await db.auth.getDataPlaneToken()) e use o @supabase/realtime-js no endereço que vem em url na resposta: o socket é do seu projeto, então não fixe o endereço no código. Você recebe só as linhas que a sua RLS deixaria ler.

Da 0.2 para a 0.3

• insert, update e delete sem .select() agora devolvem data: null, como no supabase-js. Se o seu código lia data depois de um insert, acrescente .select().
• A sessão passou a se renovar sozinha.

Notas fiscais (SuperDB Fiscal)

O projeto precisa do SuperDB Fiscal ativo (planos Pro e Escala; a ativação é no painel, em Notas fiscais). Só do seu servidor, com a chave de servidor (service_role). Com a chave anon, o SDK nem faz o pedido e o erro diz o que fazer.

import { createClient } from '@superdb/client'

const sdb = createClient(process.env.SUPERDB_URL!, process.env.SUPERDB_SERVICE_ROLE_KEY!, { project: 'meu_projeto' })

const { data, error } = await sdb.fiscal.nfse.emitir({
  ref: 'pedido-1042', // a chave de idempotência: repetir a mesma ref devolve a mesma nota
  tomador: { cnpj: '11222333000181', nome: 'Cliente Exemplo LTDA' },
  servico: { valor: 150 },
})
// data.situacao === 'pendente'; consulte depois com sdb.fiscal.nfse.consultar(data.id)

Falha de rede em emitir: chame de novo com a mesma ref. O SuperDB devolve a mesma nota, sem duplicar. Guia completo: https://superdb.com.br/docs/notas-fiscais

Licença

MIT — (c) 2026 SuperDB