@turnstileai/sdk 0.1.3 → 0.1.5

package/README.md

@@ -1,52 +1,70 @@
 # @turnstileai/sdk
 
-TypeScript SDK for TurnstileAI, a verification-first AI gateway.
+The official TypeScript/JavaScript SDK for TurnstileAI, a verification-first AI gateway for routed completions, run records, and optional ledger-backed checkpoints.
 
-TurnstileAI sits between your application and model providers, then returns
-structured run records with routing, latency, usage, cost, digests, signatures,
-and optional ledger checkpoints.
-
-## Install
+## Installation
 
 ```bash
 npm install @turnstileai/sdk
 ```
 
-## Quick start
+## Quickstart
+
+Initialize the client and send verification-enabled inference completions:
 
 ```ts
-import OpenAI from "openai";
+import { TurnstileAI } from "@turnstileai/sdk";
 
-const client = new OpenAI({
-  apiKey: process.env.TURNSTILEAI_API_KEY,
-  baseURL: "https://api.turnstileai.com/v1"
+const client = new TurnstileAI({
+  apiKey: process.env.TURNSTILEAI_API_KEY!
 });
 
-const response = await client.chat.completions.create({
+const result = await client.chat({
   model: "openrouter/llama-3.1-70b",
   messages: [
-    { role: "user", content: "Explain Solana finality simply." }
+    { role: "user", content: "Explain zero-knowledge rollups simply." }
   ],
-  extra_body: {
-    checkpoint: true,
-    ledger: "solana",
-    routeMode: "trust-first"
-  }
+  receipt: true,
+  anchor: "solana",
+  routeMode: "trust-first"
 });
 
-console.log(response.choices.message.content);
-console.log(response.run_record);
+console.log(result.output);
+console.log(JSON.stringify(result.record, null, 2));
+console.log(JSON.stringify(result.verification, null, 2));
 ```
 
-## SDK client
+## Sandboxed Local Testing (No Server Needed)
 
-```ts
-import { TurnstileAI } from "@turnstileai/sdk";
+If the SDK detects an API key starting with `ts_test_` or the environment variable `TURNSTILEAI_MOCK=true` is set, it can fall back to local mock mode for offline development and integration testing.
 
-const client = new TurnstileAI({
-  apiKey: process.env.TURNSTILEAI_API_KEY!
-});
+## Config Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `apiKey` | `string` | Your TurnstileAI API key. |
+| `baseURL` | `string` | The TurnstileAI API base URL, defaults to `https://api.turnstileai.com/v1`. |
+| `timeout` | `number` | Request timeout in milliseconds. |
+| `defaultRouteMode` | `RouteMode` | Optional default routing strategy. |
+| `defaultLedgerMode` | `LedgerMode` | Optional default ledger/checkpoint mode. |
+
+## Chat Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `model` | `string` | Required | Model routing path such as `openai/gpt-4o-mini` or `openrouter/llama-3.1-70b`. |
+| `messages` | `Array` | Required | Message array with `role` and `content`. |
+| `receipt` | `boolean` | `true` | Include a verification-oriented run record in the response. |
+| `anchor` | `string` | `"off-chain"` | Checkpoint mode: `"solana"`, `"off-chain"`, or `"none"`. |
+| `routeMode` | `string` | `"trust-first"` | Routing strategy for provider selection. |
+| `provider` | `string` | Optional | Pin inference to a provider. |
+| `maxSpendUsd` | `number` | Optional | Set a maximum spend cap for a request. |
+| `temperature` | `number` | Optional | Sampling temperature for completion generation. |
+| `maxTokens` | `number` | Optional | Output token limit. |
 
+## Record APIs
+
+```ts
 const record = await client.records.get("rr_123");
 const verification = await client.records.verify("rr_123");
 const providers = await client.providers.list();
@@ -57,22 +75,13 @@ const usage = await client.usage.overview("month");
 
 ```bash
 turnstileai auth check --key=ts_live_xxx
+turnstileai record get rr_123 --key=ts_live_xxx
 turnstileai record list --key=ts_live_xxx
 turnstileai record verify rr_123 --key=ts_live_xxx
 turnstileai providers list --key=ts_live_xxx
 turnstileai usage overview --key=ts_live_xxx
 ```
 
-## Route modes
-
-- `cost-first`
-- `speed-first`
-- `trust-first`
-- `attested-only`
-- `provider-pinned`
-- `budget-guarded`
-
-## Ledger modes
+## License
 
-- `none`
-- `solana`
+MIT

package/dist/test/client.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/client.test.js

@@ -0,0 +1,20 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_test_1 = __importDefault(require("node:test"));
+const strict_1 = __importDefault(require("node:assert/strict"));
+const client_1 = require("../client");
+(0, node_test_1.default)("TurnstileAI throws when apiKey is missing", () => {
+    strict_1.default.throws(() => {
+        new client_1.TurnstileAI({ apiKey: "" });
+    }, /Missing TurnstileAI API key/);
+});
+(0, node_test_1.default)("TurnstileAI creates a client with valid apiKey", () => {
+    const client = new client_1.TurnstileAI({ apiKey: "ts_test_123" });
+    strict_1.default.ok(client);
+    strict_1.default.ok(client.records);
+    strict_1.default.ok(client.providers);
+    strict_1.default.ok(client.usage);
+});

package/dist/types.d.ts

@@ -73,3 +73,26 @@ export interface TurnstileApiErrorBody {
     message?: string;
     details?: unknown;
 }
+export interface TurnstileChatMessage {
+    role: "system" | "user" | "assistant";
+    content: string;
+}
+export interface TurnstileChatRequest {
+    model: string;
+    messages: TurnstileChatMessage[];
+    receipt?: boolean;
+    anchor?: "solana" | "off-chain" | "none";
+    routeMode?: RouteMode;
+    provider?: string;
+    maxSpendUsd?: number;
+    temperature?: number;
+    maxTokens?: number;
+}
+export interface TurnstileChatResult {
+    id: string;
+    model: string;
+    provider: string;
+    output: string;
+    record: RunRecord | null;
+    verification: VerificationResult | null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turnstileai/sdk",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Original TypeScript SDK for TurnstileAI",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -13,6 +13,7 @@
   ],
   "scripts": {
     "build": "tsc",
+    "test": "npm run build && node --test dist/test/**/*.test.js",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -24,10 +25,10 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "openai": "^6.44.0"
+    "openai": "^4.0.0"
   },
   "devDependencies": {
-    "@types/node": "^26.0.0",
-    "typescript": "^6.0.3"
+    "@types/node": "^24.0.0",
+    "typescript": "^5.0.0"
   }
 }