@puku-ai/sdk 1.0.0 → 2.0.0

package/README.md

@@ -1,28 +1,29 @@
 # @puku-ai/sdk
 
-Drop-in replacement for [`@anthropic-ai/sdk`](https://www.npmjs.com/package/@anthropic-ai/sdk)
-that routes every request through the **Puku AI gateway**.
+Official TypeScript SDK for the **Puku AI** gateway. One small client class,
+one streaming primitive, and a familiar typed namespace.
 
 ```ts
 import PukuAI from "@puku-ai/sdk";
 
-const client = new PukuAI();
+const client = new PukuAI({
+  apiKey: process.env.PUKU_API_KEY!,
+  baseURL: process.env.PUKU_BASE_URL!,
+});
+
 const msg = await client.messages.create({
-  model: "claude-sonnet-4-5",
+  model: "puku-ai-2.8",
   max_tokens: 1024,
   messages: [{ role: "user", content: "Hello!" }],
 });
 console.log(msg.content[0].text);
 ```
 
-The client class is renamed to **`PukuAI`** (was `Anthropic`) — every method,
-type, stream primitive, and error class is otherwise identical to
-`@anthropic-ai/sdk` 0.81.x. Source code written against the official SDK works
-after a two-line change: import path + class name.
+The client class is `PukuAI`. Method names, request shapes, stream events,
+and error classes follow the Anthropic Messages API conventions.
 
 ## Contents
 
-- [Why](#why)
 - [Install](#install)
 - [Configuration](#configuration)
 - [Usage](#usage)
@@ -30,18 +31,8 @@ after a two-line change: import path + class name.
 - [Examples](#examples)
 - [Documentation](#documentation)
 - [Namespace](#namespace)
-- [How it differs from `@anthropic-ai/sdk`](#how-it-differs-from-anthropic-ai-sdk)
 - [License](#license)
 
-## Why
-
-Puku CLI is a coding assistant built on top of the Anthropic SDK. We want to:
-
-1. Route all requests through the Puku AI router so we can pick the best
-   upstream model per request (Opus / Sonnet / GLM / Kimi / OpenAI-compatible…).
-2. Keep puku-cli's source untouched.
-3. Maintain a single, minimal surface.
-
 ## Install
 
 ```bash
@@ -50,39 +41,23 @@ npm install @puku-ai/sdk
 pnpm add @puku-ai/sdk
 ```
 
+> The package is published under the **`puku-ai`** npm org with restricted
+> (private) access. You must be a member of the org on npm to install it.
+
 ## Configuration
 
-> The SDK only reads two environment variables: `PUKU_API_KEY` and
-> `PUKU_BASE_URL`. There is no bearer-token path and no fallback to
-> `ANTHROPIC_*` env vars. To talk to staging, set
-> `PUKU_BASE_URL=https://api-dev.puku.sh`; for prod, set
-> `PUKU_BASE_URL=https://api-cli.puku.sh`. See `.env.staging.example` and
-> `docs/API-KEY-PLAN.md` § "End-to-end migration order".
+Two environment variables, both required:
+
+| Env var         | Purpose                                |
+| --------------- | -------------------------------------- |
+| `PUKU_API_KEY`  | Puku API key (sent as `X-Api-Key`)     |
+| `PUKU_BASE_URL` | Gateway URL
 
-| Env var         | Purpose                  | Default       |
-| --------------- | ------------------------ | ------------- |
-| `PUKU_API_KEY`  | Puku API key             | _(required)_  |
-| `PUKU_BASE_URL` | Puku AI routing endpoint | _(required)_  |
-| `ANTHROPIC_LOG` | Log level (`debug`, `info`, `warn`, `error`) | `warn` |
 
-### Using an API key
 
-In staging, mint a key via the admin UI (`/account/agents` or
-`/account/user-keys`). Keys minted in staging are prefixed `pk_staging_…`.
-Copy the plaintext once — it is not recoverable later.
 
-```bash
-# .env.staging
-PUKU_BASE_URL=https://api-dev.puku.sh
-PUKU_API_KEY=pk_staging_…
-```
 
-```bash
-node --env-file=.env.staging examples/17-agent-key.mjs
-```
 
-The SDK sends `X-Api-Key: pk_staging_…` on every request. No
-`Authorization` header — there is no bearer-token path.
 
 ## Usage
 
@@ -94,7 +69,7 @@ import PukuAI from "@puku-ai/sdk";
 const client = new PukuAI();
 
 const msg = await client.messages.create({
-  model: "claude-sonnet-4-5",
+  model: "puku-ai-2.8",
   max_tokens: 1024,
   messages: [{ role: "user", content: "Hello!" }],
 });
@@ -105,7 +80,7 @@ console.log(msg.content[0].text);
 
 ```ts
 const stream = client.messages.stream({
-  model: "claude-sonnet-4-5",
+  model: "puku-ai-2.8",
   max_tokens: 1024,
   messages: [{ role: "user", content: "Hello!" }],
 });
@@ -137,68 +112,11 @@ try {
 }
 ```
 
-See [docs/ERROR-HANDLING.md](./docs/ERROR-HANDLING.md) for the full hierarchy.
-
-## Feature matrix
-
-Every API surface in `@anthropic-ai/sdk` 0.81.x is reachable through
-`@puku-ai/sdk`. The matrix below shows where each lives.
-
-| Feature                                | Call site                          | Example |
-|----------------------------------------|------------------------------------|---------|
-| Blocking chat                          | `client.messages.create(...)`      | [01](./examples/01-basic-chat.mjs) |
-| Streaming chat                         | `client.messages.stream(...)`      | [02](./examples/02-streaming.mjs) |
-| System prompt + prefilling             | `system`, last message = assistant | [03](./examples/03-system-prompt.mjs) |
-| Multi-turn history                     | append to `messages`               | [04](./examples/04-multi-turn.mjs) |
-| Prompt caching                         | `cache_control: { type: "ephemeral" }` | [05](./examples/05-prompt-caching.mjs) |
-| Tool use                               | `tools: [...]` + manual loop       | [06](./examples/06-tool-use.mjs) |
-| Vision (base64 / URL / file)           | `image` content blocks             | [07](./examples/07-vision.mjs) |
-| Error handling + aborts                | `instanceof PukuAI.*Error`         | [08](./examples/08-error-handling.mjs) |
-| Async message batches                  | `client.messages.batches.*`        | [09](./examples/09-batches.mjs) |
-| MCP servers (beta)                     | `mcp_servers: [...]`               | [10](./examples/10-mcp.mjs) |
-| Skills & versions (beta)               | `client.beta.skills.*`             | [11](./examples/11-skills.mjs) |
-| Structured (JSON-schema) output        | `output_format: { type: "json_schema", schema }` | [12](./examples/12-structured-output.mjs) |
-| Custom client options                  | `new PukuAI({ ... })`              | [14](./examples/14-custom-client-options.mjs) |
-| Mocking / local server                 | `baseURL` + custom `fetch`         | [15](./examples/15-testing.mjs) |
-
-## Examples
-
-15 runnable scripts under [`examples/`](./examples/README.md) cover every
-common use case. Quick start:
-
-```bash
-PUKU_API_KEY=sk-... node examples/01-basic-chat.mjs
-```
-
-## Test scripts
-
-```bash
-# Offline smoke test (24 cases, no API key, mock server on localhost)
-bun run smoke
-
-# Live integration test (14 cases, hits real Puku AI gateway)
-# Requires PUKU_API_KEY and PUKU_BASE_URL.
-bun run integration
-
-# Type-level parity check (verifies the full PukuAI.* namespace compiles)
-bun run type-check
-```
 
-## Documentation
 
-Guides under [`docs/`](./docs/README.md):
-
-- [MIGRATION.md](./docs/MIGRATION.md) — switch from `@anthropic-ai/sdk` in three lines.
-- [ERROR-HANDLING.md](./docs/ERROR-HANDLING.md) — error hierarchy & retries.
-- [ROUTING.md](./docs/ROUTING.md) — how the Puku AI gateway picks models.
-- [TYPES.md](./docs/TYPES.md) — namespace & type reference.
 
 ## Namespace
 
-The upstream SDK exposes its types under an `Anthropic` namespace
-(`Anthropic.Messages.Message`, etc.); `@puku-ai/sdk` re-exposes the same
-namespace under the `PukuAI` name:
-
 ```ts
 import PukuAI from "@puku-ai/sdk";
 
@@ -208,7 +126,7 @@ type Beta  = PukuAI.Beta.Messages.BetaMessage;
 type Skill = PukuAI.Beta.Skills.SkillRetrieveResponse;
 ```
 
-Static helpers that were on `Anthropic.X` are on `PukuAI.X`:
+Static helpers live on the `PukuAI` class:
 
 ```ts
 PukuAI.HUMAN_PROMPT;     // "\n\nHuman:"
@@ -222,30 +140,6 @@ PukuAI.APIError;         // error class (static)
 PukuAI.RateLimitError;   // error class (static)
 ```
 
-The original `Anthropic` symbol is also exported as a name alias — both
-`new PukuAI()` and `new Anthropic()` return the same class.
-
-## How it differs from `@anthropic-ai/sdk`
-
-The public API is intentionally close to `@anthropic-ai/sdk` — same method
-names, same TypeScript types (under `PukuAI.*`). The behavioral differences are:
-
-1. The client class is named `PukuAI` (was `Anthropic`).
-2. Every request is forwarded to the Puku AI gateway (`PUKU_BASE_URL`)
-   instead of directly to `api.anthropic.com`.
-3. **API-key only.** The SDK no longer supports the upstream `authToken` /
-   `Authorization: Bearer` flow or the `ANTHROPIC_API_KEY` / `ANTHROPIC_BASE_URL`
-   fallback env vars. Authentication is `PUKU_API_KEY` (sent as `X-Api-Key`).
-4. **Explicit `baseURL` is required.** There is no hardcoded default; the SDK
-   throws at construction if `baseURL` isn't passed or `PUKU_BASE_URL` isn't set.
-
-Puku's router picks which upstream model to use per request, then returns a
-response in the standard Anthropic format. To bypass Puku (e.g. for A/B
-testing), point `PUKU_BASE_URL` at `https://api.anthropic.com`.
-
-If a feature of `@anthropic-ai/sdk` is missing from `@puku-ai/sdk`, please
-[open an issue](https://github.com/puku-sh/puku-ai-sdk/issues).
-
 ## License
 
-MIT
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@puku-ai/sdk",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "PukuAI SDK — drop-in replacement for @anthropic-ai/sdk that routes requests through the Puku AI gateway.",
   "type": "module",
   "main": "./dist/index.js",