Skip to content

client-sdk.md

Latest commit

 

History

History
308 lines (238 loc) · 5.22 KB

client-sdk.md

File metadata and controls

308 lines (238 loc) · 5.22 KB

Client SDK

The @betterbase/client package provides a TypeScript SDK for interacting with BetterBase backends.

Installation

bun add @betterbase/client

Quick Setup

import { createClient } from '@betterbase/client'

const client = createClient({
  url: 'http://localhost:3000',
  auth: {
    persistSession: true,
    autoRefreshToken: true
  }
})

Configuration

interface ClientOptions {
  url: string
  auth?: {
    persistSession?: boolean
    autoRefreshToken?: boolean
  }
  storage?: {
    type?: 'local' | 'session'
  }
}

Authentication

signUp

const { data, error } = await client.auth.signUp({
  email: string,
  password: string,
  name?: string
})

signInWithPassword

const { data, error } = await client.auth.signInWithPassword({
  email: string,
  password: string
})

signInWithOAuth

const { data, error } = await client.auth.signInWithOAuth({
  provider: 'github' | 'google' | 'discord'
})

signOut

await client.auth.signOut()

getUser

const { data, error } = await client.auth.getUser()

getSession

const { data, error } = await client.auth.getSession()

Database Operations

select

// Get all records
const { data, error } = await client
  .from('users')
  .select()

// Select specific columns
const { data, error } = await client
  .from('users')
  .select('id, name, email')

// With filters
const { data, error } = await client
  .from('posts')
  .select()
  .eq('published', true)
  .order('createdAt', { ascending: false })
  .limit(10)

insert

const { data, error } = await client
  .from('users')
  .insert({
    name: 'John Doe',
    email: 'john@example.com'
  })

update

const { data, error } = await client
  .from('users')
  .update({ name: 'Jane Doe' })
  .eq('id', 'user-123')

delete

const { data, error } = await client
  .from('users')
  .delete()
  .eq('id', 'user-123')

Query Builder Methods

Method Description
.select(columns?) Select columns to return
.eq(column, value) Filter by equality
.neq(column, value) Filter by inequality
.gt(column, value) Greater than
.gte(column, value) Greater or equal
.lt(column, value) Less than
.lte(column, value) Less or equal
.like(column, pattern) Pattern match
.in(column, array) In array
.order(column, options) Sort results
.limit(count) Limit results
.offset(count) Offset results
.single() Return single record

Realtime

Subscribe

const channel = client.channel('public:posts')

channel
  .on('postgres_changes', 
    { event: 'INSERT', table: 'posts' },
    (payload) => console.log('New post:', payload.new)
  )
  .subscribe()

Channel Events

channel.on('status', (status) => {
  console.log('Connection status:', status)
})

Unsubscribe

channel.unsubscribe()

Storage

upload

const { data, error } = await client.storage.upload(
  bucket: string,
  path: string,
  file: File | Blob
)

download

const { data, error } = await client.storage.download(
  bucket: string,
  path: string
)

remove

const { data, error } = await client.storage.remove(
  bucket: string,
  path: string
)

getPublicUrl

const { data: { url } } = client.storage.getPublicUrl(
  bucket: string,
  path: string
)

list

const { data, error } = await client.storage.list(bucket: string)

GraphQL

query

const { data, error } = await client.graphql.query(`
  query GetUsers {
    users {
      id
      name
      email
    }
  }
`)

mutation

const { data, error } = await client.graphql.mutation(`
  mutation CreateUser($name: String!, $email: String!) {
    insert_users_one(object: { name: $name, email: $email }) {
      id
      name
    }
  }
`, { name: 'John', email: 'john@example.com' })

Error Handling

const { data, error } = await client.from('users').select()

if (error) {
  console.error('Error:', error.message)
  console.error('Code:', error.code)
  return
}

console.log('Data:', data)

Error Types

Error Code Description
PGRST116 Record not found
23505 Unique constraint violation
42501 Permission denied
AUTH_REQUIRED Authentication required

TypeScript Types

import type {
  User,
  Session,
  Post,
  StorageResult,
  RealtimeChannel
} from '@betterbase/client'

Best Practices

  1. Use persistSession - Keep user logged in across page reloads
  2. Handle errors - Always check error before processing data
  3. Type your data - Use TypeScript types for better DX
  4. Clean up subscriptions - Unsubscribe when done

Related