TypeScript SDK Reference

The lightfast npm package provides a type-safe client for the Lightfast API.

Installation

bash
npm install lightfast
npm install lightfast

Client Configuration

typescript
import { Lightfast } from "lightfast";

const client = new Lightfast(config: LightfastConfig);
import { Lightfast } from "lightfast";

const client = new Lightfast(config: LightfastConfig);

LightfastConfig

Methods

search()

Search through your organization's knowledge — decisions, observations, and documents.

typescript
const response = await client.search(input: SearchInput): Promise<SearchResponse>
const response = await client.search(input: SearchInput): Promise<SearchResponse>

SearchInput & Response

SearchFilters

Example

typescript
const results = await client.search({
  query: "authentication implementation",
  limit: 10,
  mode: "balanced",
  filters: {
    sourceTypes: ["github"],
    dateRange: {
      start: "2024-01-01T00:00:00Z",
      end: "2024-12-31T23:59:59Z",
    },
  },
});

console.log(results.data); // Array of search results
console.log(results.meta.total); // Total matching documents
const results = await client.search({
  query: "authentication implementation",
  limit: 10,
  mode: "balanced",
  filters: {
    sourceTypes: ["github"],
    dateRange: {
      start: "2024-01-01T00:00:00Z",
      end: "2024-12-31T23:59:59Z",
    },
  },
});

console.log(results.data); // Array of search results
console.log(results.meta.total); // Total matching documents

proxySearch()

Discover connected providers, their resources, and available actions. Returns connection IDs, resource names with pre-computed action params, and the full action catalog.

typescript
const response = await client.proxySearch(): Promise<ProxySearchResponse>
const response = await client.proxySearch(): Promise<ProxySearchResponse>

Example

typescript
const { connections } = await client.proxySearch();

for (const conn of connections) {
  console.log(conn.provider);    // e.g., "github"
  console.log(conn.resources);   // Connected repos/projects with params
  console.log(conn.actions);     // Available actions
}
const { connections } = await client.proxySearch();

for (const conn of connections) {
  console.log(conn.provider);    // e.g., "github"
  console.log(conn.resources);   // Connected repos/projects with params
  console.log(conn.actions);     // Available actions
}

proxyCall()

Execute a provider API action. Use action strings from proxySearch() and pass a flat params object — resource params from the search response can be spread directly into the call. Auth is handled automatically.

typescript
const response = await client.proxyCall(input: ProxyCall): Promise<ProxyCallResponse>
const response = await client.proxyCall(input: ProxyCall): Promise<ProxyCallResponse>

ProxyCall

Example

typescript
const result = await client.proxyCall({
  action: "github.list-pull-requests",
  params: { owner: "acme", repo: "web", state: "open" },
});

console.log(result.data);    // Raw provider API response
console.log(result.status);  // HTTP status code
const result = await client.proxyCall({
  action: "github.list-pull-requests",
  params: { owner: "acme", repo: "web", state: "open" },
});

console.log(result.data);    // Raw provider API response
console.log(result.status);  // HTTP status code

Error Classes

The SDK exports typed error classes for handling specific error conditions.

typescript
import {
  AuthenticationError,
  ValidationError,
  NotFoundError,
  RateLimitError,
  NetworkError,
  ServerError,
} from "lightfast";
import {
  AuthenticationError,
  ValidationError,
  NotFoundError,
  RateLimitError,
  NetworkError,
  ServerError,
} from "lightfast";

Type Exports

All request and response types are exported:

typescript
import type {
  LightfastConfig,
  SearchInput,
  SearchFilters,
  SearchRequest,
  SearchResponse,
  SearchResult,
  RerankMode,
  SearchContext,
  SearchLatency,
  ProxySearchResponse,
  ProxyConnection,
  ProxyAction,
  ProxyResource,
  ProxyCall,
  ProxyCallResponse,
} from "lightfast";
import type {
  LightfastConfig,
  SearchInput,
  SearchFilters,
  SearchRequest,
  SearchResponse,
  SearchResult,
  RerankMode,
  SearchContext,
  SearchLatency,
  ProxySearchResponse,
  ProxyConnection,
  ProxyAction,
  ProxyResource,
  ProxyCall,
  ProxyCallResponse,
} from "lightfast";

Related

• TypeScript SDK Tutorial - Getting started guide with examples
• POST /v1/search - REST API endpoint reference
• GitHub Repository - SDK source code