npm package: @slim-protocol/client
Description: TypeScript SDK for fetching web content in SLIM format - optimized for AI consumption
Author: SLIM Protocol Team
Latest version: 1.0.0-beta.1

# @slim-protocol/client

TypeScript SDK for fetching web content in **SLIM format** - optimized for AI consumption with ~90% token reduction.

## Features

- **One-line usage** - `const slim = await fetchSlim(url)`
- **Zero dependencies** - Uses native `fetch`
- **Full TypeScript** - Complete type definitions
- **Tiny bundle** - < 4KB (gzipped)
- **Universal** - Node.js, Browser, Deno, Bun, Edge Runtime

## Installation

```bash
npm install @slim-protocol/client
```

## Quick Start

```typescript
import { fetchSlim } from '@slim-protocol/client';

const slim = await fetchSlim('https://example.com');

// Access structured content
console.log(slim.payload.l1.title);     // Page title
console.log(slim.payload.l1.type);      // Content type (article, video, etc.)
console.log(slim.payload.l5?.keyPoints); // Key points extracted

// Check compression metrics
console.log(slim.meta?.tokensEstimate);     // Estimated tokens
console.log(slim.meta?.compressionRatio);   // Compression achieved
```

## API

### `fetchSlim(url, options?)`

Fetch web content in SLIM format.

```typescript
const slim = await fetchSlim('https://example.com', {
  timeout: 60000,        // Request timeout (default: 30000)
  includeImages: true,   // Include image analysis (default: true)
  includeVideos: true,   // Include video metadata (default: true)
  level: 'L5',           // Specific SLIM level to request
  signal: controller.signal, // AbortController for cancellation
});
```

### `configureSlim(config)`

Configure the SDK globally.

```typescript
import { configureSlim } from '@slim-protocol/client';

configureSlim({
  proxyUrl: 'https://my-proxy.example.com',
  timeout: 60000,
  debug: true,
});
```

### `isValidSlimUrl(url)`

Check if a URL is valid for fetching.

```typescript
import { isValidSlimUrl } from '@slim-protocol/client';

if (isValidSlimUrl(userInput)) {
  const slim = await fetchSlim(userInput);
}
```

## SLIM Pyramid Levels

The response contains hierarchical content levels:

| Level | Name | Contains |
|-------|------|----------|
| L1 | Identity | Title, type, author, description |
| L3 | Structure | Headings, sections, navigation |
| L5 | Insights | Key points, topics, entities |
| L7 | Full Content | Complete text content |

```typescript
// L1: Always present - basic identification
slim.payload.l1.title
slim.payload.l1.type
slim.payload.l1.author

// L3: Document structure
slim.payload.l3?.sections
slim.payload.l3?.structure

// L5: Extracted insights
slim.payload.l5?.keyPoints
slim.payload.l5?.topics
slim.payload.l5?.summary

// L7: Full content
slim.payload.l7?.fullContent
```

## Error Handling

```typescript
import { fetchSlim, SlimError, SlimErrorCode } from '@slim-protocol/client';

try {
  const slim = await fetchSlim(url);
} catch (error) {
  if (error instanceof SlimError) {
    switch (error.code) {
      case SlimErrorCode.INVALID_URL:
        console.log('Please provide a valid URL');
        break;
      case SlimErrorCode.TIMEOUT:
        console.log('Request timed out');
        break;
      case SlimErrorCode.NETWORK_ERROR:
        console.log('Network error:', error.message);
        break;
      case SlimErrorCode.PROXY_ERROR:
        console.log('Proxy error:', error.statusCode);
        break;
    }

    // Helpful suggestions
    if (error.suggestion) {
      console.log('Suggestion:', error.suggestion);
    }
  }
}
```

## Use with AI/LLMs

SLIM content is optimized for AI consumption:

```typescript
import { fetchSlim } from '@slim-protocol/client';
import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic();

// Fetch content in SLIM format
const slim = await fetchSlim('https://example.com/article');

// Pass to Claude with dramatically reduced tokens
const response = await anthropic.messages.create({
  model: 'claude-sonnet-4-20250514',
  messages: [{
    role: 'user',
    content: `Summarize this article:\n\n${slim.rawSlim?.full || JSON.stringify(slim.payload)}`
  }]
});

console.log(`Tokens used: ~${slim.meta?.tokensEstimate}`);
```

## Cancellation

```typescript
const controller = new AbortController();

// Cancel after 5 seconds
setTimeout(() => controller.abort(), 5000);

try {
  const slim = await fetchSlim('https://example.com', {
    signal: controller.signal,
  });
} catch (error) {
  if (error instanceof SlimError && error.code === SlimErrorCode.ABORTED) {
    console.log('Request was cancelled');
  }
}
```

## TypeScript Types

All types are exported:

```typescript
import type {
  SlimResponse,
  SlimPayload,
  SlimL1, SlimL3, SlimL5, SlimL7,
  SlimSource,
  SlimMeta,
  FetchSlimOptions,
  SlimConfig,
} from '@slim-protocol/client';
```

## Environment Support

| Environment | Support |
|-------------|---------|
| Node.js 18+ | ✅ Full |
| Browser (ES2020+) | ✅ Full |
| Deno | ✅ Full |
| Bun | ✅ Full |
| Vercel Edge | ✅ Full |
| Cloudflare Workers | ✅ Full |

## License

MIT