npm package: @perf_technology/sdk
Description: Official Perf SDK for JavaScript/TypeScript
Author: Perf Technology, Inc.
Latest version: 2.1.0

# @perf_technology/sdk

Official JavaScript/TypeScript SDK for [Perf](https://withperf.pro) - the AI Runtime Orchestrator.

Perf automatically picks the best AI model for your prompt based on:
- Task type and complexity
- Cost constraints
- Output reliability
- Fallback logic

## Installation

```bash
npm install @perf_technology/sdk
# or
yarn add @perf_technology/sdk
# or
pnpm add @perf_technology/sdk
```

## Quick Start

```typescript
import { PerfClient } from '@perf_technology/sdk';

const client = new PerfClient({
  apiKey: 'pk_live_your_api_key',
});

// Simple chat completion
const response = await client.chat({
  messages: [
    { role: 'user', content: 'What is the capital of France?' }
  ],
});

console.log(response.choices[0].message.content);
// Output: "The capital of France is Paris."

// Access Perf metadata
console.log(response.perf);
// { model_used: 'gpt-4o-mini', cost_usd: 0.0001, latency_ms: 234, ... }
```

## Streaming

```typescript
// Stream responses
for await (const chunk of client.chatStream({
  messages: [{ role: 'user', content: 'Write a haiku about coding' }],
})) {
  process.stdout.write(chunk.choices[0]?.delta?.content || '');
}

// Or collect into a string
const content = await client.chatStreamToString({
  messages: [{ role: 'user', content: 'Explain quantum computing' }],
});
```

## Error Handling

```typescript
import {
  PerfClient,
  PerfError,
  RateLimitError,
  AuthenticationError
} from '@perf_technology/sdk';

try {
  const response = await client.chat({
    messages: [{ role: 'user', content: 'Hello!' }],
  });
} catch (error) {
  if (error instanceof RateLimitError) {
    // Wait and retry
    const retryAfter = error.retryAfter || 60;
    console.log(`Rate limited. Retry after ${retryAfter} seconds`);
  } else if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof PerfError) {
    console.error(`API Error: ${error.code} - ${error.message}`);
  } else {
    console.error('Unexpected error:', error);
  }
}
```

## Configuration Options

```typescript
const client = new PerfClient({
  apiKey: 'pk_live_your_api_key',     // Required
  baseUrl: 'https://api.withperf.pro', // Optional, default shown
  timeout: 120000,                      // Request timeout in ms (default: 2 min)
  maxRetries: 3,                        // Retry attempts (default: 3)
  retryDelay: 1000,                     // Base retry delay in ms (default: 1s)
});
```

## Request Options

```typescript
const response = await client.chat({
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'Hello!' },
  ],
  model: 'gpt-4o',           // Optional: override model selection
  max_tokens: 1000,          // Optional: limit response length
  temperature: 0.7,          // Optional: sampling temperature
  max_cost_per_call: 0.01,   // Optional: cost budget in USD
  metadata: {                // Optional: custom metadata
    user_id: '123',
    session_id: 'abc',
  },
});
```

## TypeScript Types

All types are exported for your convenience:

```typescript
import type {
  Message,
  ChatRequest,
  ChatResponse,
  ChatStreamChunk,
  PerfMetadata,
  PerfClientConfig,
} from '@perf_technology/sdk';
```

## Features

- **Full TypeScript support** with comprehensive type definitions
- **Streaming support** with AsyncGenerator API
- **Automatic retries** with exponential backoff
- **Error classes** for different error types
- **Timeout handling** with configurable limits
- **Dual ESM/CommonJS** builds

## Requirements

- Node.js 18 or higher
- Browser environments with Fetch API support

## Links

- [Documentation](https://docs.withperf.pro)
- [Dashboard](https://dashboard.withperf.pro)
- [Status](https://status.withperf.pro)
- [Support](mailto:support@withperf.pro)

## License

MIT