Beam Client

npm install @semilayer/client

import { BeamClient, type BeamConfig } from '@semilayer/client'

const client = new BeamClient({
  baseUrl: 'https://api.semilayer.com',  // required
  apiKey: 'sk_live_...',                 // required
  userToken?: string,                    // optional — user JWT for RBAC
  wsUrl?: string,                        // optional — override WebSocket URL
  fetch?: typeof fetch,                  // optional — custom fetch implementation
  WebSocket?: WebSocketConstructor,      // optional — custom WebSocket class (Node.js)
})

const sharedClient = new BeamClient({ baseUrl, apiKey: 'pk_live_...' })

// Per request — bind the user's JWT:
const userClient = sharedClient.withUser(req.headers['x-user-token'])
const { results } = await userClient.search('products', { query: 'shoes' })

async search<M = Record<string, unknown>>(
  lens: string,
  params: SearchParams,
): Promise<SearchResponse<M>>

interface SearchParams {
  query: string
  limit?: number      // default: 10
  minScore?: number   // default: 0
  mode?: 'semantic' | 'keyword' | 'hybrid'
}

interface SearchResponse<M> {
  results: SearchResult<M>[]
  meta: { lens: string; query: string; mode: string; count: number; durationMs: number }
}

interface SearchResult<M> {
  id: string           // internal embedding ID
  sourceRowId: string  // your source DB primary key
  content: string | null
  metadata: M          // your declared fields
  score: number        // 0-1 cosine similarity
}

interface Product { id: number; name: string; category: string; price: number }

const { results } = await client.search<Product>('products', {
  query: 'eco-friendly water bottle',
  limit: 10,
  mode: 'hybrid',
})

// results[0].metadata.name   ← string ✓
// results[0].score           ← number ✓

async similar<M = Record<string, unknown>>(
  lens: string,
  params: SimilarParams,
): Promise<SimilarResponse<M>>

interface SimilarParams {
  id: string          // source record primary key
  limit?: number
  minScore?: number
}

interface SimilarResponse<M> {
  results: SearchResult<M>[]  // same shape as SearchResponse
  meta: { lens: string; sourceId: string; count: number; durationMs: number }
}

const { results } = await client.similar<Product>('products', { id: '42', limit: 5 })
// results[0].metadata.name  ← name of similar product

async query<M = Record<string, unknown>>(
  lens: string,
  params?: QueryParams,
): Promise<QueryResponse<M>>

interface QueryParams {
  where?: Record<string, unknown>
  orderBy?: { field: string; dir?: 'asc' | 'desc' }
          | Array<{ field: string; dir?: 'asc' | 'desc' }>
  limit?: number
  offset?: number
  cursor?: string
  select?: string[]
}

interface QueryResponse<M> {
  rows: M[]  // direct M access — no .metadata wrapper
  meta: { lens: string; total?: number; nextCursor?: string; count: number; durationMs: number }
}

const { rows, meta } = await client.query<Product>('products', {
  where: { category: 'footwear' },
  orderBy: { field: 'price', dir: 'asc' },
  limit: 20,
})

// rows[0].name  ← string (direct M access, no .metadata wrapper)

// Paginate:
if (meta.nextCursor) {
  const page2 = await client.query<Product>('products', {
    where: { category: 'footwear' },
    cursor: meta.nextCursor,
    limit: 20,
  })
}

stream.search<M = Record<string, unknown>>(
  lens: string,
  params: StreamSearchParams,  // extends SearchParams + { batchSize?: number }
): AsyncIterable<SearchResult<M>>

for await (const result of client.stream.search<Product>('products', {
  query: 'eco-friendly water bottle',
  limit: 50,
})) {
  render(result) // SearchResult<Product> — arrives per batch before all results are ready
}

stream.query<M = Record<string, unknown>>(
  lens: string,
  params: StreamQueryParams,  // extends QueryParams + { batchSize?: number }
): AsyncIterable<M>

for await (const row of client.stream.query<Product>('products', {
  where: { category: 'footwear' },
})) {
  process(row)  // M — direct field access
}

stream.subscribe<M = Record<string, unknown>>(
  lens: string,
  params?: SubscribeParams,
): AsyncIterable<StreamEvent<M>>

interface SubscribeParams {
  filter?: Record<string, unknown>  // simple equality filter (v0.1)
}

interface StreamEvent<M> {
  kind: 'insert' | 'update' | 'delete'
  record: M
}

for await (const event of client.stream.subscribe<Product>('products')) {
  if (event.kind === 'insert') addToList(event.record)
  if (event.kind === 'update') updateInList(event.record)
  if (event.kind === 'delete') removeFromList(event.record)
}

observe<M = Record<string, unknown>>(
  lens: string,
  recordId: string,
): AsyncIterable<M>

for await (const snapshot of client.observe<Product>('products', '42')) {
  setProduct(snapshot)  // M — fires on every change to this record
}

import {
  BeamError,
  BeamAuthError,
  BeamNotFoundError,
  BeamStreamError,
  BeamStreamRateLimitError,
  BeamStreamClosedError,
} from '@semilayer/client'

import { BeamAuthError, BeamStreamClosedError } from '@semilayer/client'

try {
  const { results } = await client.search('products', { query: 'shoes' })
} catch (err) {
  if (err instanceof BeamAuthError) {
    // API key invalid or expired
  }
  throw err
}

// Streaming — reconnect on close
async function watchFeed() {
  while (true) {
    try {
      for await (const event of client.stream.subscribe('products')) {
        handleEvent(event)
      }
    } catch (err) {
      if (err instanceof BeamStreamClosedError) {
        await sleep(1000)  // wait before reconnecting
        continue
      }
      throw err
    }
  }
}

import { createBeam, type Beam } from './semilayer'

const beam = createBeam({
  baseUrl: 'https://api.semilayer.com',
  apiKey: process.env.SEMILAYER_API_KEY!,
})

beam.products.search(params: SearchParams): Promise<SearchResponse<ProductsMetadata>>
beam.products.similar(params: SimilarParams): Promise<SimilarResponse<ProductsMetadata>>
beam.products.query(params?: QueryParams): Promise<QueryResponse<ProductsMetadata>>
beam.products.stream.search(params): AsyncIterable<SearchResult<ProductsMetadata>>
beam.products.stream.query(params): AsyncIterable<ProductsMetadata>
beam.products.stream.subscribe(params?): AsyncIterable<StreamEvent<ProductsMetadata>>
beam.products.observe(recordId: string): AsyncIterable<ProductsMetadata>

// Generated: semilayer/metadata.ts
export interface ProductsMetadata {
  id: number
  name: string
  category: string
  price: number
}

import { BeamClient } from '@semilayer/client'
import WebSocket from 'ws'  // npm install ws

const client = new BeamClient({
  baseUrl: 'https://api.semilayer.com',
  apiKey: 'sk_live_...',
  WebSocket,  // pass the ws constructor
})