npm package: @skimly/sdk
Description: Production-grade TypeScript SDK for Skimly - AI token optimization with streaming, tools, and full API coverage
Latest version: 2.0.7

# Skimly Node.js SDK

A production-grade TypeScript/JavaScript SDK for Skimly - the drop-in gateway for AI-powered coding tools that reduces output token usage through smart compression.

## Features

- 🚀 **Full TypeScript Support** - Comprehensive type definitions matching Anthropic/OpenAI APIs
- 🌊 **Streaming Support** - Real-time streaming with Server-Sent Events
- 🛠️ **Tool Calling** - Complete tool calling interface with helpers
- 📦 **Blob Management** - Large content handling with deduplication
- ⚡ **Performance** - Built-in retry logic, timeouts, and error handling
- 🔄 **Provider Agnostic** - Works with OpenAI, Anthropic, and other providers
- 💾 **Smart Caching** - Automatic blob deduplication to reduce costs

## Installation

```bash
npm install @skimly/sdk
```

## Quick Start

```typescript
import { SkimlyClient } from '@skimly/sdk'

const client = new SkimlyClient({
  apiKey: 'sk-your-api-key',
  baseURL: 'https://api.skimly.dev'
})

// Basic chat
const response = await client.messages.create({
  provider: 'anthropic',
  model: 'claude-3-5-sonnet-20241022',
  max_tokens: 1024,
  messages: [{
    role: 'user',
    content: 'Hello, world!'
  }]
})

console.log(response.content[0].text)
console.log('Tokens saved:', response.skimly_meta.tokens_saved)
```

## Streaming

```typescript
const stream = client.messages.stream({
  provider: 'openai',
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Write a story' }],
  stream: true
})

for await (const chunk of stream) {
  if (chunk.type === 'content_block_delta' && chunk.delta?.text) {
    process.stdout.write(chunk.delta.text)
  }
}
```

## Tool Calling

```typescript
import { Tools } from '@skimly/sdk'

const response = await client.messages.create({
  provider: 'anthropic',
  model: 'claude-3-5-sonnet-20241022',
  messages: [{ role: 'user', content: 'What is the weather in SF?' }],
  tools: [
    Tools.function('get_weather', 'Get weather for a location', {
      type: 'object',
      properties: {
        location: { type: 'string' }
      },
      required: ['location']
    })
  ]
})

// Check for tool uses
const toolUses = response.content.filter(block => block.type === 'tool_use')
```

## Blob Management

```typescript
// Upload large content
const { blob_id } = await client.createBlob(largeDocument)

// Use in chat with pointer
const response = await client.messages.create({
  provider: 'anthropic', 
  model: 'claude-3-5-sonnet-20241022',
  messages: [{
    role: 'user',
    content: [
      { type: 'text', text: 'Summarize this:' },
      { type: 'pointer', blob_id }
    ]
  }]
})

// Automatic deduplication
const { blob_id: dedupedId } = await client.createBlobIfNew(sameDocument)
```

## Environment Setup

```bash
export SKIMLY_KEY=sk-your-api-key
export SKIMLY_BASE=https://api.skimly.dev
```

```typescript
import { fromEnv } from '@skimly/sdk'
const client = fromEnv()
```

## Error Handling

```typescript
import { 
  SkimlyError, 
  SkimlyAPIError, 
  SkimlyAuthenticationError 
} from '@skimly/sdk'

try {
  const response = await client.messages.create(params)
} catch (error) {
  if (error instanceof SkimlyAuthenticationError) {
    console.log('Invalid API key')
  } else if (error instanceof SkimlyAPIError) {
    console.log(`API error ${error.status}: ${error.message}`)
  }
}
```

## Configuration

```typescript
const client = new SkimlyClient({
  apiKey: 'sk-your-key',
  baseURL: 'https://api.skimly.dev',
  timeout: 60000,        // 60 seconds
  maxRetries: 3,         // Retry failed requests
  defaultHeaders: {
    'User-Agent': 'MyApp/1.0'
  }
})
```

## Advanced Usage

### Streaming with Collection

```typescript
import { collectStream } from '@skimly/sdk'

const stream = client.messages.stream(params)
const message = await collectStream(stream)
console.log(message.content[0].text)
```

### Transform Tool Results

```typescript
const compressed = await client.transform({
  result: JSON.stringify(toolOutput),
  tool_name: 'code_analysis',
  command: 'analyze_files',
  model: 'claude-3-5-sonnet-20241022'
})
```

### Fetch with Range

```typescript
const content = await client.fetchBlob(blobId, { 
  start: 0, 
  end: 1000 
})
```

## TypeScript Support

Full TypeScript definitions are included:

```typescript
import type { 
  MessageParams,
  MessageResponse, 
  StreamingChunk,
  ContentBlock,
  Tool,
  SkimlyClientOptions
} from '@skimly/sdk-node'
```

## Examples

See the [examples](./examples/) directory for complete usage examples:

- [Basic Usage](./examples/basic-usage.ts) - Simple chat and streaming
- [Blob Management](./examples/blob-management.ts) - Large content handling

## License

MIT