@turnstileai/sdk 0.1.2 → 0.1.4

package/README.md

@@ -1,34 +1,99 @@
-\# @turnstileai/sdk
+# @turnstileai/sdk
 
+TypeScript SDK for TurnstileAI.
 
+TurnstileAI is a verification-focused AI gateway SDK for working with routed model requests, run records, provider health, and usage analytics.
 
-Official TypeScript SDK for TurnstileAI.
+## Install
 
+```bash
+npm install @turnstileai/sdk
+```
 
+## Quick start
 
-\## Install
+```ts
+import { TurnstileAI } from "@turnstileai/sdk";
 
+const client = new TurnstileAI({
+  apiKey: process.env.TURNSTILEAI_API_KEY!
+});
+```
 
+## Fetch a run record
 
-```bash
+```ts
+const record = await client.records.get("rr_123");
+console.log(record);
+```
 
-npm install @turnstileai/sdk
+## Verify a run record
+
+```ts
+const verification = await client.records.verify("rr_123");
+console.log(verification.status);
+```
+
+## List providers
+
+```ts
+const providers = await client.providers.list();
+console.log(providers);
+```
 
+## Usage overview
+
+```ts
+const usage = await client.usage.overview("month");
+console.log(usage);
 ```
 
+## CLI
 
+After installing globally or linking locally, you can use:
 
-\## Usage
+```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`
 
-```ts
+## Ledger modes
 
-import { hello } from "@turnstileai/sdk";
+- `none`
+- `solana`
 
+## Development
 
+Build the package:
 
-console.log(hello());
+```bash
+npm run build
+```
 
+Run tests:
+
+```bash
+npm test
 ```
 
+## Publish updates
+
+When you change the SDK or README, publish a new version:
+
+```bash
+npm version patch
+npm publish --access public
+```

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const client_1 = require("./client");
+const errors_1 = require("./errors");
+const args = process.argv.slice(2);
+const command = args[0];
+const subcommand = args[1];
+function readKey() {
+    const inline = args.find((arg) => arg.startsWith("--key="));
+    if (inline)
+        return inline.replace("--key=", "");
+    if (process.env.TURNSTILEAI_API_KEY)
+        return process.env.TURNSTILEAI_API_KEY;
+    console.error("Missing API key. Use --key=ts_... or set TURNSTILEAI_API_KEY");
+    process.exit(1);
+}
+function help() {
+    console.log(`
+turnstileai <command>
+
+Commands:
+  auth check
+  record get <id>
+  record list
+  record verify <id>
+  providers list
+  usage overview
+
+Examples:
+  turnstileai auth check --key=ts_live_xxx
+  turnstileai record verify rr_123 --key=ts_live_xxx
+  turnstileai usage overview
+`);
+}
+async function main() {
+    if (!command || command === "--help" || command === "-h") {
+        help();
+        return;
+    }
+    const apiKey = readKey();
+    const client = new client_1.TurnstileAI({ apiKey });
+    try {
+        if (command === "auth" && subcommand === "check") {
+            console.log("Authentication ok");
+            return;
+        }
+        if (command === "record" && subcommand === "get") {
+            const id = args[2];
+            if (!id) {
+                console.error("Usage: turnstileai record get <id>");
+                process.exit(1);
+            }
+            const record = await client.records.get(id);
+            console.log(JSON.stringify(record, null, 2));
+            return;
+        }
+        if (command === "record" && subcommand === "list") {
+            const records = await client.records.list({ limit: 10 });
+            for (const item of records) {
+                console.log(`${item.id}  ${item.model}  ${item.provider}  ${item.totalTokens} tokens  $${item.costUsd.toFixed(5)}`);
+            }
+            return;
+        }
+        if (command === "record" && subcommand === "verify") {
+            const id = args[2];
+            if (!id) {
+                console.error("Usage: turnstileai record verify <id>");
+                process.exit(1);
+            }
+            const result = await client.records.verify(id);
+            console.log(`signature: ${result.signatureOk}`);
+            console.log(`digest: ${result.digestOk}`);
+            console.log(`ledger: ${result.ledgerOk}`);
+            console.log(`status: ${result.status}`);
+            console.log(result.message);
+            return;
+        }
+        if (command === "providers" && subcommand === "list") {
+            const providers = await client.providers.list();
+            for (const p of providers) {
+                console.log(`${p.label}  ${p.trustTier}  ${p.uptimePercent}% uptime  ${p.avgLatencyMs}ms`);
+            }
+            return;
+        }
+        if (command === "usage" && subcommand === "overview") {
+            const usage = await client.usage.overview("month");
+            console.log(JSON.stringify(usage, null, 2));
+            return;
+        }
+        help();
+    }
+    catch (err) {
+        if (err instanceof errors_1.TurnstileAuthError) {
+            console.error(`Auth error: ${err.message}`);
+            process.exit(1);
+        }
+        if (err instanceof errors_1.TurnstileRequestError) {
+            console.error(`Request error ${err.statusCode}: ${err.message}`);
+            process.exit(1);
+        }
+        console.error(String(err));
+        process.exit(1);
+    }
+}
+main();

package/dist/client.d.ts

@@ -0,0 +1,30 @@
+import OpenAI from "openai";
+import type { TurnstileConfig, RunRecord, VerificationResult, ProviderHealth, UsageOverview } from "./types";
+export declare class TurnstileAI {
+    private readonly apiKey;
+    private readonly baseURL;
+    private readonly timeout;
+    private readonly http;
+    readonly chat: OpenAI["chat"];
+    readonly completions: OpenAI["completions"];
+    readonly models: OpenAI["models"];
+    constructor(config: TurnstileConfig);
+    records: {
+        get: (recordId: string) => Promise<RunRecord>;
+        list: (params?: {
+            limit?: number;
+            offset?: number;
+            model?: string;
+            provider?: string;
+        }) => Promise<RunRecord[]>;
+        verify: (recordId: string) => Promise<VerificationResult>;
+    };
+    providers: {
+        list: () => Promise<ProviderHealth[]>;
+        get: (providerId: string) => Promise<ProviderHealth>;
+    };
+    usage: {
+        overview: (period?: "day" | "week" | "month") => Promise<UsageOverview>;
+    };
+    private request;
+}

package/dist/client.js

@@ -0,0 +1,88 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TurnstileAI = void 0;
+const openai_1 = __importDefault(require("openai"));
+const errors_1 = require("./errors");
+const DEFAULT_BASE_URL = "https://api.turnstileai.com/v1";
+class TurnstileAI {
+    constructor(config) {
+        this.records = {
+            get: async (recordId) => {
+                return this.request(`/records/${recordId}`);
+            },
+            list: async (params) => {
+                const qs = new URLSearchParams();
+                if (params?.limit)
+                    qs.set("limit", String(params.limit));
+                if (params?.offset)
+                    qs.set("offset", String(params.offset));
+                if (params?.model)
+                    qs.set("model", params.model);
+                if (params?.provider)
+                    qs.set("provider", params.provider);
+                const suffix = qs.toString() ? `?${qs.toString()}` : "";
+                return this.request(`/records${suffix}`);
+            },
+            verify: async (recordId) => {
+                return this.request(`/records/${recordId}/verify`);
+            },
+        };
+        this.providers = {
+            list: async () => {
+                return this.request("/providers");
+            },
+            get: async (providerId) => {
+                return this.request(`/providers/${providerId}`);
+            },
+        };
+        this.usage = {
+            overview: async (period = "month") => {
+                return this.request(`/usage/overview?period=${period}`);
+            },
+        };
+        if (!config.apiKey) {
+            throw new errors_1.TurnstileAuthError("Missing TurnstileAI API key.");
+        }
+        this.apiKey = config.apiKey;
+        this.baseURL = config.baseURL ?? DEFAULT_BASE_URL;
+        this.timeout = config.timeout ?? 60000;
+        this.http = new openai_1.default({
+            apiKey: this.apiKey,
+            baseURL: this.baseURL,
+            timeout: this.timeout,
+            defaultHeaders: {
+                "X-TurnstileAI-SDK": "@turnstileai/sdk",
+            },
+        });
+        this.chat = this.http.chat;
+        this.completions = this.http.completions;
+        this.models = this.http.models;
+    }
+    async request(path, init) {
+        const res = await fetch(`${this.baseURL}${path}`, {
+            ...init,
+            headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+                "Content-Type": "application/json",
+                "X-TurnstileAI-SDK": "@turnstileai/sdk",
+                ...(init?.headers ?? {}),
+            },
+        });
+        if (res.status === 401) {
+            throw new errors_1.TurnstileAuthError("Invalid or expired TurnstileAI API key.");
+        }
+        if (!res.ok) {
+            let body = {};
+            try {
+                body = await res.json();
+            }
+            catch { }
+            throw new errors_1.TurnstileRequestError(body?.message ?? `Request failed with status ${res.status}`, res.status, body?.code);
+        }
+        return res.json();
+    }
+}
+exports.TurnstileAI = TurnstileAI;

package/dist/errors.d.ts

@@ -0,0 +1,15 @@
+export declare class TurnstileError extends Error {
+    constructor(message: string);
+}
+export declare class TurnstileAuthError extends TurnstileError {
+    constructor(message: string);
+}
+export declare class TurnstileRequestError extends TurnstileError {
+    statusCode: number;
+    code?: string;
+    constructor(message: string, statusCode: number, code?: string);
+}
+export declare class TurnstileVerificationError extends TurnstileError {
+    recordId: string;
+    constructor(message: string, recordId: string);
+}

package/dist/errors.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TurnstileVerificationError = exports.TurnstileRequestError = exports.TurnstileAuthError = exports.TurnstileError = void 0;
+class TurnstileError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "TurnstileError";
+    }
+}
+exports.TurnstileError = TurnstileError;
+class TurnstileAuthError extends TurnstileError {
+    constructor(message) {
+        super(message);
+        this.name = "TurnstileAuthError";
+    }
+}
+exports.TurnstileAuthError = TurnstileAuthError;
+class TurnstileRequestError extends TurnstileError {
+    constructor(message, statusCode, code) {
+        super(message);
+        this.name = "TurnstileRequestError";
+        this.statusCode = statusCode;
+        this.code = code;
+    }
+}
+exports.TurnstileRequestError = TurnstileRequestError;
+class TurnstileVerificationError extends TurnstileError {
+    constructor(message, recordId) {
+        super(message);
+        this.name = "TurnstileVerificationError";
+        this.recordId = recordId;
+    }
+}
+exports.TurnstileVerificationError = TurnstileVerificationError;

package/dist/index.d.ts

@@ -1 +1,3 @@
-export declare const hello: () => string;
+export { TurnstileAI } from "./client";
+export { TurnstileError, TurnstileAuthError, TurnstileRequestError, TurnstileVerificationError, } from "./errors";
+export type { TurnstileConfig, InferenceOptions, RunRecord, LedgerCheckpoint, VerificationResult, ProviderHealth, UsageOverview, RouteMode, LedgerMode, TurnstileApiErrorBody, } from "./types";

package/dist/index.js

@@ -1,5 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.hello = void 0;
-const hello = () => "hello from TurnstileAI";
-exports.hello = hello;
+exports.TurnstileVerificationError = exports.TurnstileRequestError = exports.TurnstileAuthError = exports.TurnstileError = exports.TurnstileAI = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "TurnstileAI", { enumerable: true, get: function () { return client_1.TurnstileAI; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "TurnstileError", { enumerable: true, get: function () { return errors_1.TurnstileError; } });
+Object.defineProperty(exports, "TurnstileAuthError", { enumerable: true, get: function () { return errors_1.TurnstileAuthError; } });
+Object.defineProperty(exports, "TurnstileRequestError", { enumerable: true, get: function () { return errors_1.TurnstileRequestError; } });
+Object.defineProperty(exports, "TurnstileVerificationError", { enumerable: true, get: function () { return errors_1.TurnstileVerificationError; } });

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

@@ -0,0 +1,75 @@
+export type RouteMode = "cost-first" | "speed-first" | "trust-first" | "attested-only" | "provider-pinned" | "budget-guarded";
+export type LedgerMode = "none" | "solana";
+export interface TurnstileConfig {
+    apiKey: string;
+    baseURL?: string;
+    timeout?: number;
+    defaultRouteMode?: RouteMode;
+    defaultLedgerMode?: LedgerMode;
+}
+export interface InferenceOptions {
+    checkpoint?: boolean;
+    ledger?: LedgerMode;
+    routeMode?: RouteMode;
+    provider?: string;
+    maxSpendUsd?: number;
+    tags?: string[];
+}
+export interface LedgerCheckpoint {
+    chain: "solana";
+    txId: string;
+    slot: number;
+    explorerUrl: string;
+    confirmedAt: string | null;
+}
+export interface RunRecord {
+    id: string;
+    createdAt: string;
+    model: string;
+    provider: string;
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    latencyMs: number;
+    costUsd: number;
+    requestDigest: string;
+    responseDigest: string;
+    signature: string;
+    routeMode: RouteMode;
+    verified: boolean;
+    ledgerCheckpoint: LedgerCheckpoint | null;
+    metadata?: Record<string, unknown>;
+}
+export interface VerificationResult {
+    recordId: string;
+    signatureOk: boolean;
+    digestOk: boolean;
+    ledgerOk: boolean | null;
+    status: "verified" | "pending" | "failed";
+    message: string;
+}
+export interface ProviderHealth {
+    id: string;
+    label: string;
+    uptimePercent: number;
+    avgLatencyMs: number;
+    errorRatePercent: number;
+    attested: boolean;
+    trustTier: "A+" | "A" | "B+" | "B" | "C";
+    lastUpdatedAt: string;
+}
+export interface UsageOverview {
+    period: "day" | "week" | "month";
+    requests: number;
+    verifiedRuns: number;
+    totalTokens: number;
+    totalCostUsd: number;
+    averageLatencyMs: number;
+    from: string;
+    to: string;
+}
+export interface TurnstileApiErrorBody {
+    code?: string;
+    message?: string;
+    details?: unknown;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,26 +1,34 @@
 {
   "name": "@turnstileai/sdk",
-  "version": "0.1.2",
-  "description": "Official TypeScript SDK for TurnstileAI",
+  "version": "0.1.4",
+  "description": "Original TypeScript SDK for TurnstileAI",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "bin": {
+    "turnstileai": "dist/cli.js"
+  },
   "files": [
     "dist",
     "README.md"
   ],
   "scripts": {
     "build": "tsc",
+    "test": "npm run build && node --test dist/test/**/*.test.js",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
     "ai",
     "sdk",
-    "typescript",
     "llm",
+    "typescript",
     "turnstileai"
   ],
   "license": "MIT",
+  "dependencies": {
+    "openai": "^4.0.0"
+  },
   "devDependencies": {
-    "typescript": "^6.0.3"
+    "@types/node": "^24.0.0",
+    "typescript": "^5.0.0"
   }
 }