TypeScript SDK

The official TypeScript SDK for Butterbase. Works in browser, Node.js, and Deno environments.

Installation

npm install @butterbase/sdk

Quick start

import { createClient } from '@butterbase/sdk';

const butterbase = createClient({
  appId: 'app_abc123',
  apiUrl: 'https://api.butterbase.ai',
  anonKey: 'your-anon-key' // Optional, for public access
});

Data operations

Query

const { data, error } = await butterbase
  .from('posts')
  .select('*')
  .eq('status', 'published')
  .order('created_at', { ascending: false })
  .limit(10);

Insert

const { data, error } = await butterbase
  .from('posts')
  .insert({ title: 'Hello World', content: 'My first post' });

Update

const { data, error } = await butterbase
  .from('posts')
  .update({ status: 'archived' })
  .eq('id', '123');

Delete

const { data, error } = await butterbase
  .from('posts')
  .delete()
  .eq('id', '123');

Query operators

Method	SQL Equivalent
eq(column, value)	=
neq(column, value)	!=
gt(column, value)	>
gte(column, value)	>=
lt(column, value)	<
lte(column, value)	<=
like(column, pattern)	LIKE (case-sensitive)
ilike(column, pattern)	ILIKE (case-insensitive)
in(column, values)	IN (...)
is(column, value)	IS NULL / TRUE / FALSE

Query modifiers

Method	Description
select(columns)	Select specific columns
order(column, options)	Order results
limit(count)	Limit results
offset(count)	Skip results

Authentication

Sessions are automatically persisted to localStorage and restored on page refresh. Access tokens are automatically refreshed before they expire.

// Sign up
const { data, error } = await butterbase.auth.signUp({
  email: 'user@example.com',
  password: 'secure123'
});

// Sign in
const { data, error } = await butterbase.auth.signIn({
  email: 'user@example.com',
  password: 'secure123'
});

// Get current user
const { data: user } = await butterbase.auth.getUser();

// Sign out
await butterbase.auth.signOut();

// Refresh session manually
const { data } = await butterbase.auth.refreshSession();

// OAuth
const { url } = butterbase.auth.signInWithOAuth({
  provider: 'google',
  redirectTo: 'http://localhost:3000/callback'
});
window.location.href = url;

Auth state changes

const { unsubscribe } = butterbase.onAuthStateChange((event, session) => {
  // event: 'SIGNED_IN' | 'SIGNED_OUT' | 'TOKEN_REFRESHED' | 'SESSION_RESTORED'
  console.log(event, session?.user);
});

Custom session storage

// Disable persistence
const butterbase = createClient({
  appId: 'app_abc123',
  apiUrl: 'https://api.butterbase.ai',
  persistSession: false,
});

// Custom adapter (e.g. React Native)
const butterbase = createClient({
  appId: 'app_abc123',
  apiUrl: 'https://api.butterbase.ai',
  sessionStorage: myCustomStorage, // implements { getItem, setItem, removeItem }
});

Storage

const { data, error } = await butterbase.storage.upload(file);
const { data } = await butterbase.storage.getDownloadUrl(objectId);
const { data: objects } = await butterbase.storage.list();
await butterbase.storage.delete(objectId);

Functions

const { data, error } = await butterbase.functions.invoke('my-function', {
  body: { key: 'value' },
  method: 'POST'
});

TypeScript support

All methods return ButterbaseResponse<T> with proper type inference:

interface Post {
  id: string;
  title: string;
  content: string;
  status: 'draft' | 'published';
}

const { data, error } = await butterbase
  .from<Post>('posts')
  .select('*')
  .eq('status', 'published');
// data is typed as Post[] | null

Deno usage

import { createClient } from 'npm:@butterbase/sdk';

const butterbase = createClient({
  appId: Deno.env.get('BUTTERBASE_APP_ID')!,
  apiUrl: Deno.env.get('BUTTERBASE_API_URL')!,
});

Migration from 0.x to 1.0

The authUrl parameter has been removed. All auth endpoints now run on the same URL as the API — just use apiUrl.