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

npm install @skimly/sdk

Quick Start

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

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

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

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

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

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

Error Handling

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

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

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

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

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

TypeScript Support

Full TypeScript definitions are included:

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

Examples

See the examples directory for complete usage examples:

Basic Usage - Simple chat and streaming
Blob Management - Large content handling

License

MIT