npm package: @lightning-logs/sdk
Description: TypeScript/JavaScript SDK for Lightning Logs — structured logging, distributed tracing, and real-time log streaming.
Author: Lightning Logs
Latest version: 0.2.0

# @lightning-logs/sdk

TypeScript SDK for Lightning Logs platform.

## Installation

```bash
npm install @lightning-logs/sdk
```

Or if using as a local package in a monorepo:

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

## Usage

```typescript
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

```typescript
// 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

```typescript
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

```typescript
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

```bash
cd packages/sdk
npm install
npm run build
npm test
```

## License

MIT