JavaScript / TypeScript SDK

The Kolaybase SDK provides a type-safe client for interacting with your project's database, authentication, and storage from any JavaScript or TypeScript environment.

Installation

npm install kolaybase-js

Initialization

import { createClient } from 'kolaybase-js'

const kb = createClient({
  apiUrl: 'https://api.kolaybase.com',
  projectId: 'your-project-id',
  apiKey: 'your-anon-key',
})

Option	Type	Description
`apiUrl`	string	Base URL of the Kolaybase API
`projectId`	string	Your project ID
`apiKey`	string	Anon key (client-safe) or service key (server only)
`autoRefreshToken`	boolean	Auto-refresh auth tokens (default: true)
`headers`	object	Custom headers for every request

Database

Query Builder

kb.from(table) returns a chainable query builder.

// Select all posts
const { data, error } = await kb.from('posts').select()

// Select specific columns with filters
const { data } = await kb.from('posts')
  .select('id, title, created_at')
  .eq('status', 'published')
  .order('created_at', { ascending: false })
  .limit(10)

// Insert
const { data } = await kb.from('posts')
  .insert({ title: 'Hello', body: 'World' })

// Update
const { data } = await kb.from('posts')
  .update({ title: 'Updated' })
  .eq('id', 1)

// Delete
const { error } = await kb.from('posts')
  .delete()
  .eq('id', 1)

// Upsert
const { data } = await kb.from('posts')
  .upsert({ id: 1, title: 'Upserted' }, { onConflict: 'id' })

Filters

Method	SQL Equivalent	Example
`.eq(col, val)`	`= val`	`.eq('status', 'active')`
`.neq(col, val)`	`!= val`	`.neq('role', 'admin')`
`.gt(col, val)`	`> val`	`.gt('age', 18)`
`.gte(col, val)`	`>= val`	`.gte('score', 90)`
`.lt(col, val)`	`< val`	`.lt('price', 100)`
`.lte(col, val)`	`<= val`	`.lte('qty', 0)`
`.like(col, pattern)`	`LIKE`	`.like('name', '%john%')`
`.ilike(col, pattern)`	`ILIKE`	`.ilike('name', '%john%')`
`.is(col, val)`	`IS`	`.is('deleted_at', null)`
`.in(col, vals)`	`IN (...)`	`.in('id', [1,2,3])`
`.not(col, op, val)`	`NOT`	`.not('status', 'eq', 'draft')`
`.or(filters)`	`OR`	`.or('status.eq.active,role.eq.admin')`

Modifiers

Method	Description
`.order(col, opts?)`	Sort results. `{ ascending: false }`
`.limit(n)`	Limit number of rows
`.offset(n)`	Skip rows
`.range(from, to)`	Pagination range
`.single()`	Return single object (error if not exactly one)
`.maybeSingle()`	Return single object or null

Raw SQL

const { data, error } = await kb.sql('SELECT COUNT(*) FROM users')

const { data } = await kb.listTables()
const { data } = await kb.getColumns('posts')

Authentication

All auth methods are under kb.auth.

Sign Up & Sign In

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

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

// Sign out
await kb.auth.signOut()

Email Verification

// User receives OTP via email after sign up
const { data, error } = await kb.auth.verifyEmail('123456')

Password Reset

// Request reset
await kb.auth.forgotPassword('user@example.com')

// Reset with OTP
await kb.auth.resetPassword('123456', 'newpassword')

Magic Link

// Send magic link
await kb.auth.sendMagicLink('user@example.com')

// Verify (from email link)
const { data } = await kb.auth.verifyMagicLink('otp-from-url')

OAuth

// Redirect to Google
const { data } = await kb.auth.signInWithProvider('google', {
  redirectTo: 'https://myapp.com/auth/callback',
})
// data.url → redirect user to this URL

// On callback page
const { data, error } = await kb.auth.handleProviderCallback()

Session Management

const user = await kb.auth.getUser()
const session = await kb.auth.getSession()
const token = kb.auth.getAccessToken()

// Listen to auth changes
kb.auth.onAuthStateChange((event, session) => {
  // event: 'SIGNED_IN' | 'SIGNED_OUT' | 'TOKEN_REFRESHED'
})

Other Auth Methods

Method	Description
`changeEmail(newEmail)`	Request email change
`confirmChangeEmail(otp)`	Confirm with OTP
`requestReauth()`	Request re-authentication OTP
`verifyReauth(otp)`	Verify re-auth
`inviteUser(email)`	Invite user (service key only)
`refreshSession()`	Manually refresh tokens
`setAccessToken(token)`	Set token manually

Storage

S3-compatible file storage via kb.storage.

Bucket Management

// List buckets
const { data } = await kb.storage.listBuckets()

// Create bucket
await kb.storage.createBucket('avatars', { public: true })

// Delete bucket
await kb.storage.deleteBucket('avatars')

// Update bucket
await kb.storage.updateBucket('avatars', { public: false })

File Operations

const bucket = kb.storage.from('avatars')

// Upload
const { data, error } = await bucket.upload(
  'user-123/photo.jpg',
  file,
  { contentType: 'image/jpeg' }
)

// Download
const { data } = await bucket.download('user-123/photo.jpg')

// List files
const { data } = await bucket.list('user-123/')

// Signed URL (temporary access)
const { data } = await bucket.createSignedUrl('user-123/photo.jpg', {
  expiresIn: 3600 // seconds
})

// Public URL (for public buckets)
const { data } = bucket.getPublicUrl('user-123/photo.jpg')

// Delete
await bucket.remove(['user-123/photo.jpg', 'user-123/old.jpg'])