@motherbase/client is the official TypeScript SDK for Motherbase. Its public shape is intentionally close to supabase-js: createClient(...), client.from(table), client.auth, client.storage.from(bucket), client.channel(name), and client.functions.invoke().

Use Project Studio -> Connect for the exact API URL, WebSocket URL, package name, and project ID for a project.

Install

npm install @motherbase/client
# Optional, only when you use realtime:
npm install socket.io-client

Initialize

import { createClient, localStorageStorage } from '@motherbase/client'
 
export const client = createClient(
  process.env.NEXT_PUBLIC_MOTHERBASE_URL!,
  process.env.NEXT_PUBLIC_MOTHERBASE_ANON_KEY,
  { storage: localStorageStorage() },
)
 
await client.hydrate()

The second argument is the project's publishable key, sent as an apikey header. Find it on Project Studio → Connect. It is optional unless the project has key enforcement turned on.

Passing a secret key instead (mb_secret_...) runs every request as service_role, which bypasses row level security, and unlocks the client.auth.admin namespace below. Server side only — see API Keys. The SDK logs a console warning if a secret key is used where window exists.

Client options — native shape:

createClient(url, key, {
  storage,            // session storage adapter, defaults to memoryStorage()
  autoRefresh: true,  // refresh once on 401, defaults to true
  fetch,              // custom fetch implementation
  headers,            // extra headers for every request
  realtimeIoFactory,  // test/custom socket.io factory
})

The supabase-js option shape is accepted too, so a ported config compiles as-is:

createClient(url, key, {
  auth: { persistSession: true, storage, storageKey, autoRefreshToken: true, detectSessionInUrl: true },
  global: { headers, fetch },
  db: { schema: 'public' },
})

Storage precedence is storage → auth.storage → auth.persistSession (true means localStorage, false means memory). auth.flowType and auth.debug are accepted for signature parity and ignored — Motherbase runs the implicit flow only. db.schema throws for anything but 'public', which is the only schema the REST layer exposes.

Result shape

Expected API failures resolve to { data, error } instead of throwing.

const { data, error } = await client.from('products').select('*').limit(20)
 
if (error) {
  console.error(error.message, error.status, error.code)
}

error is null on success. Programmer errors can still throw, for example calling unsupported realtime channel event types.

Query builder

client.from(table) returns a chainable, awaitable PostgREST-style builder mapped to /rest/v1/:model.

const { data: products, error } = await client
  .from('products')
  .select('id,name,price')
  .eq('status', 'active')
  .in('id', ['p1', 'p2'])
  .lt('price', 50)
  .order('name', { ascending: false })
  .range(0, 9)

Single-row helpers:

const { data: product } = await client
  .from('products')
  .select('*')
  .eq('id', 'p1')
  .single()
 
const { data: maybeProduct } = await client
  .from('products')
  .select('*')
  .eq('id', 'p1')
  .maybeSingle()

Mutations:

await client.from('products').insert({ name: 'Tea', price: 12 })
await client.from('products').update({ price: 9 }).eq('id', 'p1')
await client.from('products').delete().eq('id', 'p1')
 
// INSERT .. ON CONFLICT DO UPDATE. The target defaults to the primary key.
await client.from('products').upsert({ id: 'p1', name: 'Tea' })
await client.from('products').upsert({ sku: 'T1', name: 'Tea' }, { onConflict: 'sku' })
await client.from('products').upsert(rows, { ignoreDuplicates: true })

Writes return no rows by default. Chain .select() when you need the inserted or updated representation; the caller must also have SELECT access to receive it. Raw REST writes default to Prefer: return=minimal, while Prefer: return=representation requests rows explicitly. A bulk insert/upsert sends an explicit column set, so a key missing from one row is still written as NULL (or as the column default under { defaultToNull: false }) rather than being inferred from the first row alone.

Two server-side rules apply to every query and will bite if you assume supabase-js behaviour: an unbounded select() is capped at 1000 rows by default (the operator can lower api.rest.maxRows; paginate with .range() or pass an explicit .limit()), and an unfiltered delete() or update() is refused with a 400 for non-admin callers — deliberately, since supabase-js would have rewritten every visible row.

Filters

await client
  .from('posts')
  .select('*')
  .or('status.eq.live,and(price.gt.10,price.lt.20)')
  .textSearch('body', 'cat & dog', { type: 'websearch', config: 'english' })
  .contains('tags', ['news'])
  .not('archived', 'is', null)

Modifiers

// Row count without fetching rows
const { count } = await client.from('products').select('*', { count: 'exact', head: true })
 
// CSV instead of JSON — data is a string
const { data: csv } = await client.from('products').select('*').csv()
 
// Query plan. Admin session only; anyone else gets 403 PGRST103.
const { data: plan } = await client.from('products').select('*').explain({ analyze: true })
 
// Cancel in flight
const controller = new AbortController()
await client.from('products').select('*').abortSignal(controller.signal)
 
// Validate a write without persisting it
await client.from('products').update({ price: 9 }).eq('id', 'p1').rollback()
 
// Refuse to touch more than one row, in case the filter is wrong
await client.from('products').update({ price: 9 }).eq('id', 'p1').maxAffected(1)

maxAffected sends a Prefer header; a server that does not implement the preference ignores it. It is a safety net, not a guarantee — keep the filter right.

Embedding

Foreign keys are resolved in both directions, so the PostgREST embedding syntax works:

await client.from('posts').select('id,title,author(id,name)')
await client.from('posts').select('*,comments!inner(body)')

An embedded relation passes the same exposure and RLS checks as a top-level one.

Database functions

const { data } = await client.rpc('search_products', { term: 'tea' })
 
// Read-only form: arguments become query parameters
await client.rpc('search_products', { term: 'tea' }, { get: true })
 
// Count only
const { count } = await client.rpc('search_products', { term: 'tea' }, { head: true, count: 'exact' })

Transactions

const { data, error } = await client.transaction(tx => {
  tx.from('orders').insert({ id, total })
  tx.from('stock').update({ count: 4 }).eq('sku', sku)
})

All or nothing: one Postgres transaction for the whole callback. supabase-js has no equivalent — the usual workaround is a sequence of awaited writes inside a try, which is not a rollback, because whatever already committed stays committed.

The callback awaits nothing. It describes the writes; they are sent together and applied together. data is one result array per operation, in declaration order.

• Writes only (insert, upsert, update, delete). A read throws before anything is sent.
• An empty callback throws.
• 100 operations maximum, enforced server side.
• The whole batch runs as one caller, so two operations can never run as different users.

Wire format: POST /rest/v1/batch.

Typed clients

Pass the type generated by motherbase gen types typescript and the whole builder becomes schema-aware — relation names are checked, rows and inserts are typed, and .rpc() reads its argument and return types from Functions:

import type { Database } from './database.types'
 
const client = createClient<Database>(url, anonKey)
const { data } = await client.from('products').select('id,name')  // data: { id: string; name: string }[]

Without a Database type the client behaves exactly as it does untyped. See the CLI reference.

Note

REST queries are enforced by PostgreSQL RLS. A signed-out request runs as anon; a signed-in request runs as authenticated with auth.uid() and auth.jwt() claims.

Auth

const { data: signedUp } = await client.auth.signUp({
  email: 'user@example.com',
  password: 'secret123',
  username: 'alice',
})
 
const { data: signedIn } = await client.auth.signInWithPassword({
  email: 'user@example.com',
  password: 'secret123',
})
 
const { data: userResult } = await client.auth.getUser()
const { data: sessionResult } = await client.auth.getSession()
 
await client.auth.refreshSession()
await client.auth.signOut()

Email OTP and password reset:

await client.auth.signInWithOtp({ email: 'user@example.com' })
await client.auth.verifyOtp({ email: 'user@example.com', token: '123456', type: 'email' })
 
await client.auth.resetPasswordForEmail('user@example.com')
await client.auth.resetPassword({ email: 'user@example.com', otp: '123456', password: 'new-secret' })

OAuth:

const { data } = await client.auth.signInWithOAuth({
  provider: 'google',
  options: {
    redirectTo: 'https://app.example.com/callback',
    scopes: 'email profile',
    skipBrowserRedirect: true,   // otherwise the browser is sent to data.url immediately
  },
})

In a browser, signInWithOAuth navigates to the provider straight away unless skipBrowserRedirect is set. On the server it just resolves with data.url.

Account management:

// Profile fields
await client.auth.updateUser({ data: { name: 'Ada' } })
 
// Password change needs the current one — Better Auth has no blind overwrite
await client.auth.updateUser({ password: 'new-secret', currentPassword: 'old-secret' })
 
// Adopt a token captured elsewhere (an OAuth redirect, an SSR handoff).
// Validated against the server before it is persisted.
await client.auth.setSession({ access_token })
 
// Self-service account deletion
await client.auth.deleteUser()

Auth state listener:

const { data: { subscription } } = client.auth.onAuthStateChange((event, session) => {
  // event: 'INITIAL_SESSION' | 'SIGNED_IN' | 'SIGNED_OUT' | 'TOKEN_REFRESHED'
  //      | 'USER_UPDATED' | 'MFA_CHALLENGE_VERIFIED'
})
 
subscription.unsubscribe()

INITIAL_SESSION fires once, as soon as the stored session has been read and before any other event — asynchronously, so unsubscribing synchronously suppresses it, exactly as in supabase-js. It is what the standard bootstrap (if (event === 'INITIAL_SESSION') setLoading(false)) depends on: a signed-out visitor produces no other event, so without it the app renders its loading state forever.

The SDK attaches the Better Auth session token automatically. On a 401 it revalidates the session once against /api/auth/get-session; concurrent requests share a single revalidation. If the session is gone it clears local state and emits SIGNED_OUT. refreshSession() re-checks the current session (Better Auth bearer sessions have no refresh token).

Two-factor

The server has shipped TOTP with backup codes and trusted devices from the start; this is the namespace that reaches it.

// Enrolment returns the otpauth URI (render it as a QR code), the raw secret for
// users who type it by hand, and the backup codes. Shown once.
const { data } = await client.auth.mfa.enroll({ password })
 
await client.auth.mfa.verify({ code: '123456', trustDevice: true })
await client.auth.mfa.listFactors()
await client.auth.mfa.regenerateBackupCodes({ password })
await client.auth.mfa.unenroll({ password })
 
// Second factor over email or SMS instead of TOTP
await client.auth.mfa.challenge({ channel: 'email' })
await client.auth.mfa.verify({ code, type: 'otp' })
 
// Spend a recovery code
await client.auth.mfa.verify({ code, type: 'backup' })

Three differences from supabase.auth.mfa, stated rather than papered over:

• Enrolment requires the user's password. Better Auth treats enabling two-factor as a credential change.
• There is one TOTP factor, not a factor list: Better Auth models two-factor as a property of the user.
• challenge() is a local no-op for TOTP and sends nothing, because the code is already on the user's device. It exists so the challenge/verify sequence compiles unchanged.

Enterprise SSO

await client.auth.signInWithSSO({ domain: 'acme.com' })
await client.auth.signInWithSSO({ providerId: 'acme-okta' })
await client.auth.signInWithSSO({ email, options: { redirectTo } })

Resolves the identity provider and, in a browser, redirects to it unless options.skipBrowserRedirect is set. The project needs the SSO plugin enabled and at least one provider registered (Studio → Authentication → Organizations, with the project-wide Auth · SSO switch enabled).

Organizations, invitations and teams

Organizations are an additional Motherbase namespace, not part of the Supabase-shaped API:

const { data: organization, error } = await client.auth.organization.create({
  name: 'Acme',
  slug: 'acme',
})
 
await client.auth.organization.inviteMember({
  organizationId: organization!.id,
  email: 'person@acme.example',
  role: 'member',
})
 
const { data: full } = await client.auth.organization.getFullOrganization({
  organizationId: organization!.id,
})

The namespace exposes:

organizationId is optional on methods that target an organization and defaults to the active organization in the session. create activates the new organization unless keepCurrentActiveOrganization is true. Teams require auth.organization.teamsEnabled; the available roles are owner, admin and member. auth.organization.maxMembers is 0 for unlimited seats and applies to direct member adds, invitation acceptance and SSO auto-provisioning.

Invitations are email-based. The invitation email contains the invitation id; the recipient can inspect it with getInvitation({ id }), then call acceptInvitation({ invitationId }) or rejectInvitation({ invitationId }). An organization admin can withdraw an outgoing invitation with cancelInvitation({ invitationId }).

For authorization checks, use hasPermission({ permissions }) or handle the structured error returned by a refused operation. Do not infer permissions from the fact that a caller is an organization member.

Runtime SSO provider management

Organization SSO providers are tenant data. The project must have Auth · SSO enabled, and an organization provider must include that organization's organizationId:

const { data, error } = await client.auth.sso.register({
  providerId: 'acme-okta',
  issuer: 'https://acme.okta.com',
  domain: 'acme.example',
  organizationId: organization.id,
  oidcConfig: {
    clientId: '…',
    clientSecret: '…',
    discoveryEndpoint: 'https://acme.okta.com/.well-known/openid-configuration',
    scopes: ['openid', 'email', 'profile'],
  },
})

Use samlConfig instead of oidcConfig for SAML. The returned redirectURI is the callback URL to register at the IdP. listProviders() and getProvider() mask or omit secrets; updateProvider() merges the supplied config fields. Only an organization owner or admin may manage a provider scoped to that organization. A provider without organizationId is project-wide.

User administration

Requires a secret key, so this belongs on a server. A publishable key gets a 401 from these routes.

const admin = createClient(API_URL, process.env.MOTHERBASE_SECRET_KEY!)
 
await admin.auth.admin.listUsers({ page: 1, perPage: 50 })
await admin.auth.admin.getUserById(id)
await admin.auth.admin.createUser({ email, password, role: 'USER' })
await admin.auth.admin.updateUserById(id, { role: 'ADMIN', password })
await admin.auth.admin.signOut(id)              // ends every session they hold
await admin.auth.admin.deleteUser(id)
await admin.auth.admin.inviteUserByEmail(email)

generateLink is available through client.auth.admin.generateLink(...) with a secret project key. It returns a one-time code flow; recovery is code-based and does not return an action_link. Email-change link types are refused.

Linked identities

const { data } = await client.auth.getUserIdentities()   // data.identities
await client.auth.linkIdentity({ provider: 'github', options: { redirectTo } })
await client.auth.unlinkIdentity({ provider: 'github', id })

Backed by Better Auth's account list, which is why a password account shows email as an identity: it is a real linked credential, exactly as in Supabase. linkIdentity only starts the flow — in a browser it redirects to the provider unless options.skipBrowserRedirect is set.

Native id-token sign-in and claims

// Sign in with Apple / Google One Tap: hand over the provider's id token
await client.auth.signInWithIdToken({ provider: 'apple', token, nonce })
 
// Session claims as a JWT payload, plus the token itself
const { data } = await client.auth.getClaims()   // { claims, token }
 
// Revalidate on a timer (opt-in; the SDK already refreshes on a 401)
client.auth.startAutoRefresh(60_000)
client.auth.stopAutoRefresh()

getClaims() asks the server's JWT plugin to mint a token and decodes it. The decode is not a verification — verify server side against /api/auth/jwks.

Not exposed

PKCE code exchange (exchangeCodeForSession) and admin generateLink are supported. The compatibility matrix lists every remaining gap.

Session storage

For a ready-made wiring per framework — Next.js, React, Vue, Nuxt, SvelteKit, Expo, Node — see Framework Quickstarts.

Exports:

import {
  memoryStorage,
  localStorageStorage,
  cookieStorage,
  serverCookieStorage,
} from '@motherbase/client'

Browser local storage:

const client = createClient(API_URL, ANON_KEY, {
  storage: localStorageStorage(),
})

Browser cookies:

const client = createClient(API_URL, ANON_KEY, {
  storage: cookieStorage({ secure: true, sameSite: 'lax' }),
})

Next.js server cookie storage. serverCookieStorage(cookies, key?, { secure? }) takes the batch getAll / setAll shape that next/headers, NextRequest.cookies and NextResponse.cookies already expose, so the store can be passed through:

import { cookies } from 'next/headers'
import { createClient, serverCookieStorage } from '@motherbase/client'
 
export async function createServerClient() {
  const store = await cookies()
 
  return createClient(API_URL, ANON_KEY, {
    storage: serverCookieStorage({
      getAll: () => store.getAll(),
      setAll: (list) => list.forEach(({ name, value, options }) => store.set(name, value, options)),
    }),
  })
}

In a Next.js app, prefer createBrowserClient / createServerClient from @motherbase/ssr, which wire this up for you.

Expo / React Native:

import AsyncStorage from '@react-native-async-storage/async-storage'
import { createClient } from '@motherbase/client'
 
const client = createClient(API_URL, ANON_KEY, {
  storage: {
    async get() {
      const raw = await AsyncStorage.getItem('session')
      return raw ? JSON.parse(raw) : null
    },
    async set(session) {
      if (session) await AsyncStorage.setItem('session', JSON.stringify(session))
      else await AsyncStorage.removeItem('session')
    },
  },
})

Storage

const bucket = client.storage.from('avatars')
 
const { data: uploaded, error } = await bucket.upload('me.png', file, {
  visibility: 'public',
})
 
if (!error && uploaded) {
  const { data: blob } = await bucket.download(uploaded.path)
  const { data: signed } = await bucket.createSignedUrl(uploaded.path, 3600)
  const { data: pub } = bucket.getPublicUrl(uploaded.path)
 
  await bucket.remove([uploaded.path])
}

Objects are addressed by path within the bucket, the same way supabase-js does. upload resolves to { path, id, fullPath }; download, remove, createSignedUrl and getPublicUrl all take that path. A bare UUID is also accepted anywhere a path is, and routes to the object by its server-issued file id instead — useful when you stored the id rather than the key.

Listing:

const { data: objects } = await bucket.list('avatars/', {
  limit: 50,
  offset: 0,
  search: 'me',
  sortBy: { column: 'name', order: 'asc' },
})

Many files at once:

const { data: results } = await bucket.uploadMany(
  files.map(file => ({ path: `avatars/${file.name}`, file })),
  {
    concurrency: 4,
    onProgress: ({ completed, total, path, error }) => setProgress(completed / total),
  },
)

uploadMany never rejects: each entry comes back as { path, data, error }, in input order, so one bad file does not lose the other nineteen results. concurrency defaults to 4, and the workers share one cursor rather than fixed slices, so a slow file does not stall the rest.

storage.from(bucket).upload(...) sends the bucket slug to Motherbase. Quota, CORS, access tokens, and webhooks are still managed from Project Studio, the admin API, or the CLI; buckets themselves can also be administered from the SDK (below).

Bucket administration

const { data: buckets } = await client.storage.listBuckets()
const { data: bucket }  = await client.storage.getBucket('avatars')
 
await client.storage.createBucket('avatars', { public: true, name: 'Avatars' })
await client.storage.updateBucket('avatars', { public: false })
 
await client.storage.emptyBucket('avatars')             // objects go, bucket stays
await client.storage.deleteBucket('avatars', { force: true })

Every one of these needs a secret project API key — the same rule Supabase applies, where bucket administration is a service-role operation. With a publishable key they resolve with a 401 error, so keep them in server code and setup scripts, never in a browser bundle. deleteBucket refuses a bucket that still holds objects unless force is passed, so one unqualified call cannot destroy the files in it.

getPublicUrl(path) is synchronous and returns <url>/api/storage/<bucket>/files/<path>. Use it only for public bucket objects — it signs nothing and checks nothing. Private objects should be read with download() or createSignedUrl() from an authenticated session.

Copy, move, replace, and metadata:

await bucket.update('me.png', file)          // upload with upsert forced on
await bucket.copy('me.png', 'archive/me.png', { upsert: true })
await bucket.move('me.png', 'archive/me.png')
 
const { data: meta } = await bucket.info('me.png')   // no download
const { data: there } = await bucket.exists('me.png')

exists() reads a 404 as false. Anything else — a 403, a network failure — comes back as an error rather than as "no", because treating an authorization failure as absence is how a UI offers to create something that already exists.

Signed URLs:

const { data } = await bucket.createSignedUrl('me.png', 900)   // 15 minutes
// data.signedUrl, data.expiresAt
 
// Several at once. Each entry reports on its own; one missing object does not
// fail the batch.
const { data: many } = await bucket.createSignedUrls(['a.png', 'b.png'], 900)
// [{ path, signedUrl, error }, …]

expiresIn is in seconds, defaults to 3600, and must be between 1 and 604800 (7 days, the AWS SigV4 ceiling). Anything outside that is a 400 rather than a silent clamp — a caller asking for 30 days wants a 30-day URL, and quietly returning a 7-day one is the same bug as ignoring the argument.

Direct-to-storage uploads (S3 driver only):

const { data: slot } = await bucket.createSignedUploadUrl('me.png', {
  size: file.size,
  contentType: file.type,
})
 
await bucket.uploadToSignedUrl('me.png', slot.token, file)

Unlike supabase-js this needs the byte size up front: the upload is reserved against the bucket quota and the signature is bound to that exact length, which is what stops a signed URL from becoming an unbounded write. uploadToSignedUrl PUTs the bytes and then finalises server-side; the object only becomes readable after the finalise, so a PUT that lands with a failed finalise leaves a reservation to expire rather than a half-visible object. The local driver has no presigned uploads.

Note

expiresAt is null when nothing actually expires: a public object's URL is permanent, and a private object under the local storage driver resolves to the authenticated streaming endpoint, which is bound to the session rather than to a clock and so cannot be handed to a third party at all. Check expiresAt rather than assuming expiresIn applied.

Realtime

const channel = client
  .channel('room-products')
  .on('postgres_changes', { event: '*', schema: 'public', table: 'products' }, (payload) => {
    console.log(payload.eventType, payload.new, payload.old)
  })
  .subscribe((status, error) => {
    console.log(status, error)
  })
 
client.getChannels()                 // every channel this client holds
await client.removeChannel(channel)
await client.removeAllChannels()

Realtime uses Socket.IO at /ws. socket.io-client is imported lazily when connect() runs, so apps that never use realtime do not need the optional dependency.

Supported channel event types: postgres_changes, broadcast, presence. Any other type throws immediately rather than silently never firing.

postgres_changes event filters: INSERT, UPDATE, DELETE, *.

Broadcast:

const room = client.channel('room-1', { config: { broadcast: { self: true, ack: true } } })
 
room.on('broadcast', { event: 'cursor' }, ({ payload }) => console.log(payload))
room.subscribe()
 
await room.send({ type: 'broadcast', event: 'cursor', payload: { x: 12, y: 40 } })

The sender receives its own message only with config.broadcast.self. With config.broadcast.ack, send() resolves on the server ack ('ok' | 'timed out' | 'error') instead of resolving immediately.

Presence:

const room = client.channel('room-1', { config: { presence: { key: userId } } })
 
room.on('presence', { event: 'sync' }, () => console.log(room.presenceState()))
room.on('presence', { event: 'join' }, ({ key, newPresences }) => {})
room.on('presence', { event: 'leave' }, ({ key, leftPresences }) => {})
 
room.subscribe(status => {
  if (status === 'SUBSCRIBED') void room.track({ name: 'Ada', typing: false })
})
 
await room.untrack()

The server sends the full presence state; the client diffs it into sync / join / leave.

subscribe() returns the channel, not a promise — track() and send() before the join ack are rejected server-side, so issue the first one from the SUBSCRIBED callback. See Realtime for presence keys, typing indicators, and reconnection.

Channel status, reported to the subscribe() callback: SUBSCRIBED, TIMED_OUT, CHANNEL_ERROR, CLOSED.

Payload shape:

interface PostgresChangePayload<T> {
  schema: string
  table: string
  eventType: 'INSERT' | 'UPDATE' | 'DELETE'
  new: T | Record<string, never>
  old: T | Record<string, never>
  commit_timestamp: string
}

Realtime table events respect the same RLS visibility model as REST for rows that still exist. Delete events carry the deleted row in old.

The low-level client.realtime module is exported for direct table watchers and status listeners, but app code should prefer client.channel().

Edge functions

const { data, error } = await client.functions.invoke('hello', {
  body: { name: 'Ada' },
  method: 'POST',        // GET and DELETE send no body
  headers: { 'x-trace': '1' },
})

invoke always resolves { data, error } — it never throws — but error is an instance of the supabase-js error classes, so ported code that branches on them keeps working:

import { FunctionsHttpError, FunctionsFetchError } from '@motherbase/client'
 
if (error instanceof FunctionsHttpError) console.error(error.status)

FunctionsHttpError means the function ran and answered non-2xx; FunctionsFetchError means the request never reached it. FunctionsRelayError and the FunctionsError base are exported for parity.

Public invocation is disabled by default. Enable EDGE_PUBLIC_INVOKE_ENABLED=true, or call protected routes from a trusted server with an edge token:

await client.functions.invoke('hello', {
  body: {},
  auth: { type: 'edge-token', token: process.env.EDGE_INVOKE_TOKEN! },
})

Subpath exports

Two extra entry points ship in the same package. Neither is loaded by @motherbase/client itself.

@motherbase/client/query

Cache keys and fetchers for React Query or SWR. No dependency on either: the returned object is a plain { queryKey, queryFn }, which is what useQuery takes, and SWR uses the same two fields as key and fetcher.

import { keys, listQuery, rowQuery, allRowsQuery } from '@motherbase/client/query'
 
useQuery(listQuery(client, 'posts', {
  filters: { author },
  build: q => q.select('*').eq('author', author).order('created_at'),
}))
 
useQuery(rowQuery(client, 'posts', id))            // resolves null when absent, does not throw
useQuery(allRowsQuery(client, 'tags'))             // walks stream(), ignores api.rest.maxRows

The fetchers throw on { error } instead of returning it. That is the whole point: a fetcher that resolves with { data: null, error } looks successful to React Query, so the error gets cached, isError stays false, and the UI renders an empty list forever.

Keys are hierarchical — keys.table('posts') is a prefix of every list and row key below it, so one invalidateQueries after a write reaches all of them. Pass filters for any filtered list, or two different filters on the same table share one cache entry.

@motherbase/client/testing

Run a query as a specific user, or as nobody, so an RLS policy can actually be asserted.

import { createTestClient } from '@motherbase/client/testing'
 
const asAlice = createTestClient(url, secretKey, { as: alice.id })
const asBob   = createTestClient(url, secretKey, { as: bob.id })
const asAnon  = createTestClient(url, secretKey, { as: 'anon' })
 
expect((await asAlice.from('notes').select('*')).data).toHaveLength(1)
expect((await asBob.from('notes').select('*')).data).toHaveLength(0)

as takes a user id, 'anon' for a signed-out visitor, or 'service_role' to keep the secret key's own bypass-everything identity. Each client gets its own in-memory session, so two of them in one file cannot clobber each other.

Warning

Server side only. It needs the project secret key, which bypasses RLS and must never reach a browser. createTestClient throws if the key is not an mb_secret_… one, and the server refuses the x-motherbase-impersonate header with a 403 for any other key — so the worst case is a failed request, not a privilege escalation. Impersonation can only ever lower the privilege of a caller who already had everything.

Compatibility matrix

Every row below is produced by a contract test that runs the real @motherbase/client against a real Motherbase server backed by a real Postgres, in the backend repository (apps/server/tests/sdk-contract.integration.test.ts). The test writes packages/client/COMPATIBILITY.md; npm run docs:sync splices that file in here. The table cannot claim more or less than the code does, and a row marked Not supported asserts the current failure behaviour — implementing the feature breaks the test and forces the table to be regenerated.

• Supported: behaves as supabase-js does.
• Partial: works, with the difference stated in the note.
• Not supported: not implemented today. The note says what happens if you call it.

Client

Data · verbs

Data · filters

Data · modifiers

Data · response

Auth

Storage

Realtime

Edge functions

Beyond the contract test

These surfaces exist on the client but are not rows in the generated matrix above, either because they have no supabase-js equivalent to be compatible with or because they are covered by their own tests rather than the compat suite. Stated here rather than left out, so the two tables together are the whole client.