npm package: @runpiper/sdk
Description: JavaScript/TypeScript SDK for the runpiper runtime
Author: runpiper
Latest version: 0.1.34

# @runpiper/sdk

JavaScript/TypeScript SDK for the runpiper runtime.

## Installation

```bash
npm install @runpiper/sdk
```

Or with bun:

```bash
bun add @runpiper/sdk
```

## Quick Start

```typescript
import { RunpiperClient } from '@runpiper/sdk';

const client = new RunpiperClient({
  apiKey: process.env.RUNPIPER_API_KEY,
  baseUrl: 'https://api.runpiper.com',
});
```

## Chat Completions

OpenAI-compatible chat completions for conversational AI.

### Basic Usage

```typescript
const response = await client.chat.execute({
  model: 'openai/gpt-5-nano-2025-08-07',
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'Hello, how are you doing today?' },
  ],
});

console.log(response.choices[0]?.message.content);
```

### Streaming

```typescript
for await (const chunk of client.chat.stream({
  model: 'openai/gpt-5-nano-2025-08-07',
  messages: [{ role: 'user', content: 'Tell me a story.' }],
})) {
  process.stdout.write(chunk.choices[0]?.delta?.content || '');
}
```

## Task Execution

Execute pre-defined AI tasks across chat, tool, and execution modes.

### Execute a Task

```typescript
const response = await client.task.execute('summarize-text', {
  text: 'Long text to summarize...',
  max_sentences: 3,
});

console.log(response.output);
console.log(response.usage.cost_usd);
```

### Execute with Preview

Test preview deployments before production:

```typescript
const response = await client.task.executeWithPreview(
  'summarize-text',
  { text: '...' },
  'preview-slug'
);
```

### Execute with Types

Type-safe task execution using generics:

```typescript
interface SummarizeTextInput {
  text: string;
  max_sentences?: number;
}

interface SummarizeTextOutput {
  summary: string;
  key_points?: string[];
}

const response = await client.task.execute<SummarizeTextInput, SummarizeTextOutput>(
  'summarize-text',
  { text: '...', max_sentences: 3 }
);

if (response.output) {
  console.log(response.output.summary);
}
```

### Check Run Status

```typescript
const status = await client.runs.get('run-id');
console.log(status.status);
console.log(status.latency_ms);
```

## Task Discovery

Discover available tasks and their input/output schemas.

### List Available Tasks

```typescript
const tasks = await client.task.list();
console.log(tasks.map((t) => t.name));
```

### Get Task Details

```typescript
const task = await client.task.get('summarize-text');
console.log(task.definition.task.description);
```

### Fetch Task Types

Generate TypeScript type definitions for a task:

```typescript
const types = await client.task.fetchTypes('summarize-text');
console.log(types.input);
console.log(types.output);
```

## Configuration

```typescript
const client = new RunpiperClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.runpiper.com',
  timeout: 30000,
  maxRetries: 3,
  debug: false,
});
```

### Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `apiKey` | string | Required | Your runpiper API key |
| `baseUrl` | string | `https://api.runpiper.com` | Base URL for API requests |
| `timeout` | number | `30000` | Request timeout in milliseconds |
| `maxRetries` | number | `3` | Maximum number of retries |
| `debug` | boolean | `false` | Enable debug logging |

## Examples

See the `examples/` directory for more usage examples:

- `basic-usage.ts` - Basic chat completion example
- `streaming.ts` - Streaming chat completion example
- `tasks.ts` - Task management example
- `runs.ts` - Run execution example
- `typed-tasks.ts` - Typed task execution example

## License

MIT