Bridge SDK

import type { Bridge, BridgeRow, ReadOptions, ReadResult, QueryOptions, QueryResult } from '@semilayer/bridge-sdk'

export class MyBridge implements Bridge {
  constructor(config: Record<string, unknown>) {}

  /** Open the connection. Called once before ingest begins. */
  async connect(): Promise<void> { ... }

  /**
   * Read one page of records from a target (table, collection, endpoint, etc.).
   *
   * options.cursor     — opaque string from the previous page's result.nextCursor.
   *                      Absent on the first call.
   * options.limit      — max records per page. Defaults to 1000 if omitted.
   * options.fields     — source column/field names to return. Return all if omitted.
   * options.changedSince — only return records updated after this Date.
   *                       Requires options.changeTrackingColumn to be set.
   *
   * Returns:
   *   rows:       array of { [field]: value } records
   *   nextCursor: opaque string for the next page. undefined when exhausted.
   *   total:      optional total record count for progress reporting.
   */
  async read(target: string, options?: ReadOptions): Promise<ReadResult> { ... }

  /** Return the total number of records in target. Used for progress reporting. */
  async count(target: string): Promise<number> { ... }

  /** Close the connection. Called after ingest completes or errors. */
  async disconnect(): Promise<void> { ... }

  /**
   * Optional: execute a WHERE-filtered query directly on the source.
   * Required to enable lens.rules.query. Not needed for search or similar.
   */
  async query?(
    target: string,
    options: QueryOptions,
  ): Promise<QueryResult<BridgeRow>> { ... }

  /**
   * Optional: list available targets (tables, collections, endpoints, ...).
   * Used by `semilayer sources connect` introspection.
   */
  async listTargets?(): Promise<string[]>

  /**
   * Optional: return schema info for a target (column names, types, PK).
   * Used by `semilayer sources connect` introspection.
   */
  async introspectTarget?(target: string): Promise<TargetSchema>
}

type BridgeRow = Record<string, unknown>

interface ReadOptions {
  fields?: string[]            // column names to select; all if omitted
  cursor?: string              // opaque pagination cursor from previous page
  limit?: number               // page size; defaults to 1000
  changedSince?: Date          // incremental: only rows updated after this
  changeTrackingColumn?: string // column to compare against changedSince
}

interface ReadResult {
  rows: BridgeRow[]
  nextCursor?: string          // undefined = last page
  total?: number               // optional — for progress display
}

interface QueryOptions {
  where?: Record<string, unknown>                          // field equality or operators
  orderBy?: { field: string; dir?: 'asc' | 'desc' }       // single or array
        | Array<{ field: string; dir?: 'asc' | 'desc' }>
  select?: string[]            // fields to return; all if omitted
  limit?: number
  offset?: number
}

interface QueryResult<T = BridgeRow> {
  rows: T[]
  total?: number
}

import { createBridgeTestSuite } from '@semilayer/bridge-sdk'
import { describe } from 'vitest'
import { MyBridge } from '../src/bridge.js'

describe('MyBridge compliance', () => {
  createBridgeTestSuite({
    factory: () => new MyBridge({ url: process.env.MY_SOURCE_URL }),
    seed: {
      target: 'test_records',
      primaryKey: 'id',
      rows: [
        { id: 1, name: 'Alpha' },
        { id: 2, name: 'Beta' },
        { id: 3, name: 'Gamma' },
      ],
    },
    // Optional lifecycle hooks for test setup/teardown:
    beforeSeed: async (bridge) => {
      // e.g. create the test table before seeding
    },
    afterCleanup: async (bridge) => {
      // e.g. drop the test table after tests finish
    },
  })
})

import { MockBridge } from '@semilayer/bridge-sdk'

const bridge = new MockBridge()

// Seed data before connecting
bridge.seed('products', [
  { id: 1, name: 'Sneakers', category: 'footwear', price: 89 },
  { id: 2, name: 'Boots',    category: 'footwear', price: 149 },
  { id: 3, name: 'T-Shirt',  category: 'apparel',  price: 29 },
])

await bridge.connect()

const { rows } = await bridge.read('products', { limit: 2 })
// rows → [{ id: 1, name: 'Sneakers', ... }, { id: 2, name: 'Boots', ... }]

const count = await bridge.count('products')
// count → 3

const result = await bridge.query('products', {
  where: { category: 'footwear' },
  orderBy: { field: 'price', dir: 'asc' },
})
// result.rows → [{ id: 1, ... }, { id: 2, ... }]

await bridge.disconnect()

git clone https://github.com/semilayer/bridge-sdk
cd bridge-sdk
pnpm install

# Creates packages/bridge-<name>/ from the template
pnpm new-bridge <name>

# From the monorepo root:
pnpm --filter @semilayer/bridge-<name> test

export const BUILT_IN_BRIDGES: Record<string, () => Promise<BridgeCtor>> = {
  '@semilayer/bridge-postgres': () =>
    import('@semilayer/bridge-postgres').then((m) => m.PostgresBridge),

  // Add your bridge:
  '@semilayer/bridge-<name>': () =>
    import('@semilayer/bridge-<name>').then((m) => m.MyBridge),
}

{
  "dependencies": {
    "@semilayer/bridge-<name>": "workspace:*"
  }
}

// apps/worker/src/bridges.ts (enterprise custom)
import { registerBridge } from '@semilayer/bridge-resolver'
import { MyInternalBridge } from '@my-company/bridge-internal'

registerBridge('@my-company/bridge-internal', MyInternalBridge)