npm package: @hyperscale-sdk/sdk
Description: Hyperscale SDK — client library wrapping OpenRouter inference API
Author: Hyperscale
Latest version: 1.1.4

# Hyperscale SDK

Client library for the Hyperscale API — chat inference, model discovery, usage tracking, and billing through a single integration with Hyperscale authentication and routing.

## Install

```bash
npm install @hyperscale-sdk/sdk
```

## Quick start

```ts
import { HyperscaleClient } from "@hyperscale-sdk/sdk";

const client = new HyperscaleClient({
  apiKey: process.env.HYPERSCALE_API_KEY!,
  baseURL: "https://compute.hyperscale.fund",
});

// Non-streaming
const response = await client.chat.completions.create({
  model: "openai/gpt-5.2",
  messages: [{ role: "user", content: "Hello!" }],
  max_tokens: 1024,
});
console.log(response.choices[0].message.content);

// Streaming
const stream = await client.chat.completions.create({
  model: "openai/gpt-5.2",
  messages: [{ role: "user", content: "Tell me a story." }],
  stream: true,
  max_tokens: 1024,
});
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}
```

## Features

- **Chat completions** — streaming and non-streaming, OpenAI-compatible request/response
- **Model discovery** — `models.list()` with optional category filter and ~5 min cache
- **Usage & cost** — `usage` on completion responses; `generations.get(id)` for post-hoc stats; `keys.getCredits()` for balance
- **Errors** — typed exceptions (`ValidationError`, `AuthError`, `InsufficientCreditsError`, `RateLimitError`, `UpstreamError`) with retry for 429/5xx
- **Model routing** — optional model ID suffixes where supported (`:free`, `:nitro`, `:floor`, `:online`, `:thinking`); see Hyperscale docs for availability

## API overview

| Method | Description |
|--------|-------------|
| `client.chat.completions.create(params)` | Chat completion (use `stream: true` for streaming) |
| `client.models.list({ category? })` | List models (cached) |
| `client.models.endpoints(author, slug)` | Providers for a model |
| `client.generations.get(id)` | Token/cost stats for a generation |
| `client.keys.getKeyInfo()` | Key rate limit and usage |
| `client.keys.getCredits()` | Account credit balance |

## Testing

### 1. Unit tests (no API key needed)

From the repo root:

```bash
npm install
npm test
```

This runs Vitest on `tests/` (SSE parsing, error mapping). Use `npm run test:watch` for watch mode.

### 2. Live API test

After building, you can hit the Hyperscale API to verify the SDK end-to-end.

1. **Build the SDK**
   ```bash
   npm run build
   ```

2. **Set your API key** (and optional base URL)

   - `HYPERSCALE_API_KEY` — your Hyperscale API key  
   - `HYPERSCALE_BASE_URL` — optional (default: `https://compute.hyperscale.fund`)

   **Windows (PowerShell):**
   ```powershell
   $env:HYPERSCALE_API_KEY="your-key"
   $env:HYPERSCALE_BASE_URL="https://compute.hyperscale.fund"   # optional
   ```
   **Windows (CMD):**
   ```cmd
   set HYPERSCALE_API_KEY=your-key
   ```
   **Linux / macOS:**
   ```bash
   export HYPERSCALE_API_KEY=your-key
   export HYPERSCALE_BASE_URL=https://compute.hyperscale.fund   # optional
   ```

## Error handling

```ts
import {
  HyperscaleClient,
  AuthError,
  InsufficientCreditsError,
  RateLimitError,
} from "@hyperscale-sdk/sdk";

try {
  const r = await client.chat.completions.create({ ... });
} catch (e) {
  if (e instanceof AuthError) { /* invalid key */ }
  if (e instanceof InsufficientCreditsError) { /* add credits */ }
  if (e instanceof RateLimitError) { /* back off; SDK retries by default */ }
}
```

## License

MIT