@lightning-logs/sdk

TypeScript SDK for Lightning Logs platform.

Installation

npm install @lightning-logs/sdk

Or if using as a local package in a monorepo:

{
  "dependencies": {
    "@lightning-logs/sdk": "workspace:*"
  }
}

Usage

import { LightningLogsClient } from '@lightning-logs/sdk'
import { supabase } from '@supabase/supabase-js'

const client = new LightningLogsClient({
  baseURL: 'https://your-project.supabase.co',
  apiKey: 'your-anon-key',
  getAuthToken: async () => {
    const { data: { session } } = await supabase.auth.getSession()
    return session?.access_token || null
  }
})

// Search logs with DSL
const results = await client.logs.search({
  tsFrom: '2025-01-15T00:00:00Z',
  tsTo: '2025-01-15T23:59:59Z',
  query: "level = 'error' AND service = 'api'"
})

// Save a search
const savedSearch = await client.searches.create({
  name: 'API Errors',
  queryDsl: "level = 'error' AND service = 'api'",
  category: 'errors'
})

DSL Query Language

Examples

// Simple equality
"level = 'error'"

// Multiple conditions
"level = 'error' AND service = 'api'"

// OR logic
"level IN ('error', 'warn') OR service = 'worker'"

// Grouping
"(level = 'error' OR level = 'warn') AND service = 'api'"

// JSONB fields
"attrs.status = 500"

// Pattern matching
"msg LIKE '%payment%'"

// Full-text search
"msg CONTAINS 'payment failed'"

Building Queries Programmatically

import { buildQuery } from '@lightning-logs/sdk'

const query = buildQuery({
  level: ['error', 'warn'],
  service: ['api'],
  text: 'payment',
  operator: 'AND'
})
// Returns: "level IN ('error', 'warn') AND service = 'api' AND msg CONTAINS 'payment'"

API Reference

LogsAPI

• search(params: SearchParams): Promise<SearchResponse> - Search logs with DSL or legacy filters
• ingest(events: LogEvent[]): Promise<IngestResponse> - Send log events

SearchesAPI

• list(includeShared?: boolean): Promise<SavedSearch[]> - List saved searches
• get(id: string): Promise<SavedSearch> - Get saved search by ID
• create(search: CreateSavedSearch): Promise<SavedSearch> - Create saved search
• update(id: string, search: Partial<CreateSavedSearch>): Promise<SavedSearch> - Update saved search
• delete(id: string): Promise<void> - Delete saved search
• run(params: RunSavedSearchParams): Promise<SearchResponse> - Execute saved search
• checkFeatureAccess(): Promise<FeatureAccess> - Check if plan supports saved searches
• getCount(): Promise<number> - Get current saved search count
• getCategories(): Promise<string[]> - Get all categories

Error Handling

import {
  SDKError,
  AuthenticationError,
  ValidationError,
  FeatureNotAvailableError,
  PlanLimitError
} from '@lightning-logs/sdk'

try {
  await client.searches.create({ ... })
} catch (error) {
  if (error instanceof FeatureNotAvailableError) {
    // Show upgrade prompt
  } else if (error instanceof PlanLimitError) {
    // Show limit reached message
  }
}

Development

cd packages/sdk
npm install
npm run build
npm test

License

MIT