@turnstileai/sdk 0.1.4 → 0.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +47 -59
  2. package/dist/types.d.ts +23 -0
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,16 +1,16 @@
1
1
  # @turnstileai/sdk
2
2
 
3
- TypeScript SDK for TurnstileAI.
3
+ The official TypeScript/JavaScript SDK for TurnstileAI, a verification-first AI gateway for routed completions, run records, and optional ledger-backed checkpoints.
4
4
 
5
- TurnstileAI is a verification-focused AI gateway SDK for working with routed model requests, run records, provider health, and usage analytics.
6
-
7
- ## Install
5
+ ## Installation
8
6
 
9
7
  ```bash
10
8
  npm install @turnstileai/sdk
11
9
  ```
12
10
 
13
- ## Quick start
11
+ ## Quickstart
12
+
13
+ Initialize the client and send verification-enabled inference completions:
14
14
 
15
15
  ```ts
16
16
  import { TurnstileAI } from "@turnstileai/sdk";
@@ -18,40 +18,61 @@ import { TurnstileAI } from "@turnstileai/sdk";
18
18
  const client = new TurnstileAI({
19
19
  apiKey: process.env.TURNSTILEAI_API_KEY!
20
20
  });
21
- ```
22
21
 
23
- ## Fetch a run record
22
+ const result = await client.chat({
23
+ model: "openrouter/llama-3.1-70b",
24
+ messages: [
25
+ { role: "user", content: "Explain zero-knowledge rollups simply." }
26
+ ],
27
+ receipt: true,
28
+ anchor: "solana",
29
+ routeMode: "trust-first"
30
+ });
24
31
 
25
- ```ts
26
- const record = await client.records.get("rr_123");
27
- console.log(record);
32
+ console.log(result.output);
33
+ console.log(JSON.stringify(result.record, null, 2));
34
+ console.log(JSON.stringify(result.verification, null, 2));
28
35
  ```
29
36
 
30
- ## Verify a run record
37
+ ## Sandboxed Local Testing (No Server Needed)
31
38
 
32
- ```ts
33
- const verification = await client.records.verify("rr_123");
34
- console.log(verification.status);
35
- ```
39
+ 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.
36
40
 
37
- ## List providers
41
+ ## Config Parameters
38
42
 
39
- ```ts
40
- const providers = await client.providers.list();
41
- console.log(providers);
42
- ```
43
+ | Parameter | Type | Description |
44
+ | --- | --- | --- |
45
+ | `apiKey` | `string` | Your TurnstileAI API key. |
46
+ | `baseURL` | `string` | The TurnstileAI API base URL, defaults to `https://api.turnstileai.com/v1`. |
47
+ | `timeout` | `number` | Request timeout in milliseconds. |
48
+ | `defaultRouteMode` | `RouteMode` | Optional default routing strategy. |
49
+ | `defaultLedgerMode` | `LedgerMode` | Optional default ledger/checkpoint mode. |
50
+
51
+ ## Chat Options
43
52
 
44
- ## Usage overview
53
+ | Option | Type | Default | Description |
54
+ | --- | --- | --- | --- |
55
+ | `model` | `string` | Required | Model routing path such as `openai/gpt-4o-mini` or `openrouter/llama-3.1-70b`. |
56
+ | `messages` | `Array` | Required | Message array with `role` and `content`. |
57
+ | `receipt` | `boolean` | `true` | Include a verification-oriented run record in the response. |
58
+ | `anchor` | `string` | `"off-chain"` | Checkpoint mode: `"solana"`, `"off-chain"`, or `"none"`. |
59
+ | `routeMode` | `string` | `"trust-first"` | Routing strategy for provider selection. |
60
+ | `provider` | `string` | Optional | Pin inference to a provider. |
61
+ | `maxSpendUsd` | `number` | Optional | Set a maximum spend cap for a request. |
62
+ | `temperature` | `number` | Optional | Sampling temperature for completion generation. |
63
+ | `maxTokens` | `number` | Optional | Output token limit. |
64
+
65
+ ## Record APIs
45
66
 
46
67
  ```ts
68
+ const record = await client.records.get("rr_123");
69
+ const verification = await client.records.verify("rr_123");
70
+ const providers = await client.providers.list();
47
71
  const usage = await client.usage.overview("month");
48
- console.log(usage);
49
72
  ```
50
73
 
51
74
  ## CLI
52
75
 
53
- After installing globally or linking locally, you can use:
54
-
55
76
  ```bash
56
77
  turnstileai auth check --key=ts_live_xxx
57
78
  turnstileai record get rr_123 --key=ts_live_xxx
@@ -61,39 +82,6 @@ turnstileai providers list --key=ts_live_xxx
61
82
  turnstileai usage overview --key=ts_live_xxx
62
83
  ```
63
84
 
64
- ## Route modes
65
-
66
- - `cost-first`
67
- - `speed-first`
68
- - `trust-first`
69
- - `attested-only`
70
- - `provider-pinned`
71
- - `budget-guarded`
72
-
73
- ## Ledger modes
74
-
75
- - `none`
76
- - `solana`
77
-
78
- ## Development
79
-
80
- Build the package:
81
-
82
- ```bash
83
- npm run build
84
- ```
85
-
86
- Run tests:
87
-
88
- ```bash
89
- npm test
90
- ```
91
-
92
- ## Publish updates
85
+ ## License
93
86
 
94
- When you change the SDK or README, publish a new version:
95
-
96
- ```bash
97
- npm version patch
98
- npm publish --access public
99
- ```
87
+ MIT
package/dist/types.d.ts CHANGED
@@ -73,3 +73,26 @@ export interface TurnstileApiErrorBody {
73
73
  message?: string;
74
74
  details?: unknown;
75
75
  }
76
+ export interface TurnstileChatMessage {
77
+ role: "system" | "user" | "assistant";
78
+ content: string;
79
+ }
80
+ export interface TurnstileChatRequest {
81
+ model: string;
82
+ messages: TurnstileChatMessage[];
83
+ receipt?: boolean;
84
+ anchor?: "solana" | "off-chain" | "none";
85
+ routeMode?: RouteMode;
86
+ provider?: string;
87
+ maxSpendUsd?: number;
88
+ temperature?: number;
89
+ maxTokens?: number;
90
+ }
91
+ export interface TurnstileChatResult {
92
+ id: string;
93
+ model: string;
94
+ provider: string;
95
+ output: string;
96
+ record: RunRecord | null;
97
+ verification: VerificationResult | null;
98
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@turnstileai/sdk",
3
- "version": "0.1.4",
3
+ "version": "0.1.5",
4
4
  "description": "Original TypeScript SDK for TurnstileAI",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",