Log In

TypeScript SDK

Add semantic search to your applications with the Lightfast TypeScript SDK for Node.js and browser environments.

TypeScript SDK

The lightfast package provides a type-safe client for the Lightfast API, letting you search your engineering org's memory from any Node.js application.

Installation

bash
npm install lightfast

Quick Start

typescript
import { Lightfast } from "lightfast";

const lightfast = new Lightfast({
  apiKey: process.env.LIGHTFAST_API_KEY,
});

// Search your organization's memory
const results = await lightfast.search({
  query: "how does authentication work",
});

console.log(results.data[0].title);
// → "Add JWT authentication to API endpoints"

Configuration

typescript
const lightfast = new Lightfast({
  // Required: Your API key (starts with sk-lf-)
  apiKey: "sk-lf-...",

  // Optional: Override base URL (default: https://lightfast.ai)
  baseUrl: "https://lightfast.ai",

  // Optional: Request timeout in ms (default: 30000)
  timeout: 30000,
});

You can also set the LIGHTFAST_API_KEY environment variable and pass it directly:

typescript
const lightfast = new Lightfast({
  apiKey: process.env.LIGHTFAST_API_KEY,
});

Methods

search()

Search through your organization's knowledge for relevant documents and observations.

typescript
const results = await lightfast.search({
  // Required: Natural language query
  query: "database migration patterns",

  // Optional: Number of results (default: 10)
  limit: 10,

  // Optional: Pagination offset (default: 0)
  offset: 0,

  // Optional: Search mode - "fast" | "balanced" | "thorough" (default: "balanced")
  mode: "balanced",

  // Optional: Filter results
  filters: {
    sourceTypes: ["github"],
    observationTypes: ["pull_request", "issue"],
    dateRange: {
      start: "2024-01-01T00:00:00Z",
    },
  },
});

Response:

typescript
{
  data: [
    {
      id: "doc_abc123",
      type: "pull_request",
      title: "Add database migration framework",
      snippet: "Implemented Drizzle ORM migrations with...",
      score: 0.92,
      source: "github",
      url: "https://github.com/org/repo/pull/456"
    }
  ],
  meta: {
    total: 24,
    limit: 10,
    offset: 0,
    took: 145,
    mode: "balanced",
    paths: { vector: true, entity: true, cluster: true }
  },
  requestId: "req_abc123"
}

Error Handling

The SDK provides typed errors for common scenarios:

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

try {
  const results = await lightfast.search({ query: "test" });
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Invalid or expired API key
  } else if (error instanceof ValidationError) {
    // Invalid request parameters
    console.log(error.details); // Field-specific errors
  } else if (error instanceof RateLimitError) {
    // Too many requests
    console.log(error.retryAfter); // Seconds until retry
  } else if (error instanceof NotFoundError) {
    // Resource not found
  } else if (error instanceof NetworkError) {
    // Connection or timeout error
  }
}

TypeScript Types

All request and response types are exported:

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

Examples

Build a CLI Search Tool

typescript
import { Lightfast } from "lightfast";

const lightfast = new Lightfast({
  apiKey: process.env.LIGHTFAST_API_KEY,
});

async function search(query: string) {
  const { data } = await lightfast.search({ query, limit: 5 });

  for (const result of data) {
    console.log(`[${result.score.toFixed(2)}] ${result.title}`);
    console.log(`  ${result.url}\n`);
  }
}

search(process.argv[2]);

Add Context to AI Prompts

typescript
import { Lightfast } from "lightfast";
import { generateText } from "ai";

const lightfast = new Lightfast({
  apiKey: process.env.LIGHTFAST_API_KEY,
});

async function answerWithContext(question: string) {
  // Get relevant context from your codebase
  const { data } = await lightfast.search({
    query: question,
    limit: 5,
  });

  const context = data
    .map((r) => `[${r.title}]\n${r.snippet}`)
    .join("\n\n");

  // Use context in AI prompt
  const { text } = await generateText({
    model: "gpt-4",
    prompt: `Based on this context from our codebase:\n\n${context}\n\nAnswer: ${question}`,
  });

  return text;
}

Next Steps

On this page

TypeScript SDKInstallationQuick StartConfigurationMethodssearch()Error HandlingTypeScript TypesExamplesBuild a CLI Search ToolAdd Context to AI PromptsNext Steps