LumiBase JavaScript SDK

npm install @lumibase/sdk
# or
pnpm add @lumibase/sdk

import { createClient } from '@lumibase/sdk'

const lumibase = createClient({
  url: 'https://api.mysite.lumibase.dev',
  siteId: 'site_abc123',
})

// Authenticate
await lumibase.auth.login({ email: 'admin@example.com', password: 'password' })

// Read items
const articles = await lumibase.items('articles').readMany({
  filter: { status: { _eq: 'published' } },
  sort: ['-created_at'],
  limit: 10,
})

// Create an item
const newArticle = await lumibase.items('articles').createOne({
  title: 'Hello World',
  status: 'draft',
})

const lumibase = createClient({
  url: string              // Required: CMS API base URL
  siteId: string           // Required: site identifier
  token?: string           // Optional: static access token (skip auth flow)
  timeout?: number         // Optional: request timeout in ms (default: 30000)
  onTokenRefresh?: (token: string) => void  // Optional: callback on token refresh
})

const { access_token, refresh_token, user } = await lumibase.auth.login({
  email: 'admin@example.com',
  password: 'your-password',
})

const { access_token } = await lumibase.auth.refresh(refresh_token)

await lumibase.auth.logout()

const me = await lumibase.auth.me()
// { id, email, firstName, lastName, role, capabilities }

const lumibase = createClient({
  url: '...',
  siteId: '...',
  token: process.env.LUMIBASE_API_TOKEN,  // Long-lived token from Settings → API Tokens
})

const { data, meta } = await lumibase.items('articles').readMany({
  fields: ['id', 'title', 'status', 'author.name'],
  filter: {
    status: { _eq: 'published' },
    _and: [
      { published_at: { _gte: '$NOW(-30 days)' } }
    ]
  },
  sort: ['-published_at'],
  page: 1,
  limit: 20,
  search: 'lumibase',
})
// data: Article[]
// meta: { total, page, pageSize }

const article = await lumibase.items('articles').readOne('art_abc123', {
  fields: ['id', 'title', 'content', 'author.name', 'tags'],
})

const settings = await lumibase.singleton('site_settings').read({
  fields: ['*'],
})

const article = await lumibase.items('articles').createOne({
  title: 'New Article',
  status: 'draft',
  author: 'usr_abc123',
})

const articles = await lumibase.items('articles').createMany([
  { title: 'Article 1', status: 'published' },
  { title: 'Article 2', status: 'draft' },
])

const updated = await lumibase.items('articles').updateOne('art_abc123', {
  status: 'published',
  published_at: new Date().toISOString(),
})

await lumibase.items('articles').deleteOne('art_abc123')

await lumibase.items('articles').deleteMany(['art_abc123', 'art_def456'])

const stats = await lumibase.items('articles').readMany({
  aggregate: { count: '*', sum: ['views'] },
  groupBy: ['status'],
})
// [{ status: 'published', count: 42, sum_views: 10000 }, ...]

// Browser: File object
const file = await lumibase.files.upload(fileInput.files[0], {
  title: 'My Image',
  folder: 'fld_images',
})

// Node.js: Buffer or stream
const file = await lumibase.files.upload(buffer, {
  filename: 'image.png',
  type: 'image/png',
  title: 'My Image',
})

const url = lumibase.files.getAssetUrl('fil_abc123', {
  width: 800,
  height: 600,
  format: 'webp',
  quality: 80,
  fit: 'cover',
})
// Returns: https://api.../assets/fil_abc123?width=800&height=600&format=webp&...

import {
  generateAgentApp,
  listAgentRuns,
  publishAgentArtifact,
  rollbackAgentArtifact,
} from '@lumibase/sdk/rest'

const result = await generateAgentApp({
  collections: ['products', 'orders', 'customers'],
  targetApp: 'storefront',
  approvalPolicy: 'before_commit',
  budget: { maxToolCalls: 20 },
})(lumibase)

// result.artifacts contains page_spec, component_spec, seed_data, api_spec
const runs = await listAgentRuns()(lumibase)
const published = await publishAgentArtifact(result.artifacts[0].id)(lumibase)
await rollbackAgentArtifact(published.id, 'revert generated storefront')(lumibase)

const ws = lumibase.realtime()

// Subscribe to a collection
const subscription = ws.subscribe('articles', {
  event: '*',  // 'create' | 'update' | 'delete' | '*'
  query: {
    fields: ['id', 'title', 'status'],
    filter: { status: { _eq: 'published' } },
  },
  callback: (event) => {
    console.log(event.event, event.data)  // 'update', { id: '...', title: '...' }
  },
})

// Unsubscribe
subscription.unsubscribe()

// Presence (who's online)
ws.joinRoom('articles/art_abc123')
ws.onPresence((users) => {
  console.log('Active users:', users)
})

// Disconnect
ws.disconnect()

import type { Collections } from './lumibase-types'

type Article = Collections['articles']
// { id: string; title: string; status: 'draft' | 'published'; ... }

const article: Article = await lumibase.items('articles').readOne('art_abc123')

import { LumibaseError } from '@lumibase/sdk'

try {
  await lumibase.items('articles').createOne({ title: '' })
} catch (error) {
  if (error instanceof LumibaseError) {
    console.error(error.code)    // 'VALIDATION_FAILED'
    console.error(error.message) // 'title is required'
    console.error(error.errors)  // [{ code, message, path }]
  }
}

// Trigger a flow
const run = await lumibase.flows.run('flw_abc123', {
  userId: 'usr_xyz',
  action: 'welcome',
})

// Get run status
const runDetail = await lumibase.flows.getRun('flw_abc123', run.runId)

// Send a chat message
const response = await lumibase.ai.chat('Create a collection called "events"')

if (response.status === 'executed') {
  console.log('Done:', response.data)
} else if (response.status === 'pending_approval') {
  console.log('Waiting for approval:', response.approvalId)
}

// List pending approvals
const approvals = await lumibase.ai.listApprovals()

// Approve
await lumibase.ai.decide(approvals[0].id, 'approved')