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

Property	Type	Required	Default	Description
`apiKey`	`string`	Yes	-	API key (starts with `lf_`)
`baseUrl`	`string`	No	`https://lightfast.ai`	API base URL
`timeout`	`number`	No	`30000`	Request timeout in milliseconds

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

SearchInput accepts a natural-language query, optional pagination, optional search mode, and optional filters. SearchResponse returns ranked results, metadata, and a request id for support.

SearchFilters

Property	Type	Description
`observationTypes`	`string[]`	Observation types to include (e.g., `["decision", "incident"]`)
`entityTypes`	`string[]`	Entity types to filter by (e.g., `["service", "repository"]`)
`dateRange`	`{ start?: string; end?: string }`	Date range filter with ISO datetime strings

Example

typescript
const results = await client.search({
  query: "authentication implementation",
  limit: 10,
  mode: "balanced",
  filters: {
    entityTypes: ["service", "repository"],
    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: {
    entityTypes: ["service", "repository"],
    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

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";

Error Class	HTTP Status	Description
`AuthenticationError`	401	Invalid or expired API key
`ValidationError`	400	Invalid request parameters. Access `error.details` for field-specific errors
`NotFoundError`	404	Resource not found
`RateLimitError`	429	Too many requests. Access `error.retryAfter` for retry delay in seconds
`ServerError`	500, 502, 503, 504	Internal server error or service unavailable
`NetworkError`	-	Connection or timeout error

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";

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