@zils/sdk 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zils contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,36 @@
-# Temporary Holding Version
+# Zils TypeScript SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Node.js 20+. Typed decisions using the existing Zils API and TypeSafe-compatible
+questions. Install it in your application:
+
+```sh
+npm install @zils/sdk
+```
+
+Set the server's `ZILS_API_KEY`, then use either ESM `import` or CommonJS `require`:
+
+```ts
+import { ZilsClient, choice } from '@zils/sdk';
+
+const client = new ZilsClient();
+const result = await client.systemOne({
+  state: 'Please refund the duplicate charge.',
+  questions: {
+    team: choice('Which team?', { billing: 'Payments', support: 'Product help' }),
+  },
+});
+console.log(result.answers.team.choice);
+console.log(result.usage.billable_input_tokens);
+```
+
+Explicit `apiKey`, `baseURL`, and `defaultModel` override `ZILS_API_KEY`,
+`ZILS_BASE_URL`, and `ZILS_DEFAULT_MODEL`. Defaults are
+`https://training.zils.ai/decision` and `zils-shared`. Timeout is 60,000ms and
+automatic retries are off; a repeated decision can incur another charge.
+Browser use is disabled to avoid exposing API keys. CLI login files are not read.
+
+`client.models.list()` returns model cards. `noul`, `choice`, and `score` preserve
+question-specific answer types. `usage.input_tokens` counts model resources;
+optional `usage.billable_input_tokens` is Zils's logical billing count.
+
+[Complete guide](https://github.com/ooo-hq/zils-sdk/blob/main/docs/developer-tools.md).

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+import { TypeSafeClient, type TypeSafeClientConfig, type APIPromise, type Questions, type SystemOneRequest, type SystemOneResult as BaseResult, type RequestOptions, type Usage as BaseUsage } from '@typesafe-ai/sdk';
+export { noul, choice, score, APIError, APIConnectionError, APITimeoutError, APIUserAbortError, AuthenticationError, RateLimitError, TypeSafeError as ZilsError, } from '@typesafe-ai/sdk';
+export type { Question, Questions, SystemOneRequest, RequestOptions, RetryPolicy, ModelCard, NoulQuestion, ChoiceQuestion, ScoreQuestion, NoulResponse, ChoiceResponse, ScoreResponse, JsonValue, EntryType, } from '@typesafe-ai/sdk';
+export interface Usage extends BaseUsage {
+    /** Logical billing tokens; absent on older runtimes. input_tokens counts resources. */
+    readonly billable_input_tokens?: number;
+}
+export interface SystemOneResult<Q extends Questions> extends BaseResult<Q> {
+    readonly usage: Usage;
+}
+export type ZilsClientConfig = Omit<TypeSafeClientConfig, 'dangerouslyAllowBrowser'>;
+/** Zils defaults over the compatible TypeSafe client; automatic retries are off. */
+export declare class ZilsClient extends TypeSafeClient {
+    constructor(config?: ZilsClientConfig);
+    systemOne<const Q extends Questions>(request: SystemOneRequest<Q>, options?: RequestOptions): APIPromise<SystemOneResult<Q>>;
+}

package/dist/index.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZilsClient = exports.ZilsError = exports.RateLimitError = exports.AuthenticationError = exports.APIUserAbortError = exports.APITimeoutError = exports.APIConnectionError = exports.APIError = exports.score = exports.choice = exports.noul = void 0;
+const sdk_1 = require("@typesafe-ai/sdk");
+var sdk_2 = require("@typesafe-ai/sdk");
+Object.defineProperty(exports, "noul", { enumerable: true, get: function () { return sdk_2.noul; } });
+Object.defineProperty(exports, "choice", { enumerable: true, get: function () { return sdk_2.choice; } });
+Object.defineProperty(exports, "score", { enumerable: true, get: function () { return sdk_2.score; } });
+Object.defineProperty(exports, "APIError", { enumerable: true, get: function () { return sdk_2.APIError; } });
+Object.defineProperty(exports, "APIConnectionError", { enumerable: true, get: function () { return sdk_2.APIConnectionError; } });
+Object.defineProperty(exports, "APITimeoutError", { enumerable: true, get: function () { return sdk_2.APITimeoutError; } });
+Object.defineProperty(exports, "APIUserAbortError", { enumerable: true, get: function () { return sdk_2.APIUserAbortError; } });
+Object.defineProperty(exports, "AuthenticationError", { enumerable: true, get: function () { return sdk_2.AuthenticationError; } });
+Object.defineProperty(exports, "RateLimitError", { enumerable: true, get: function () { return sdk_2.RateLimitError; } });
+Object.defineProperty(exports, "ZilsError", { enumerable: true, get: function () { return sdk_2.TypeSafeError; } });
+const DEFAULT_BASE_URL = 'https://training.zils.ai/decision';
+function env(name) {
+    return typeof process === 'undefined' ? undefined : process.env[name]?.trim() || undefined;
+}
+function baseURL(value) {
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        throw new Error('Use a valid HTTPS base URL.');
+    }
+    const loopback = parsed.hostname === 'localhost' || parsed.hostname === '[::1]' || /^127(?:\.\d{1,3}){3}$/.test(parsed.hostname);
+    if ((parsed.protocol !== 'https:' && !(parsed.protocol === 'http:' && loopback)) ||
+        parsed.username || parsed.password || parsed.search || parsed.hash || /\s/.test(value) || parsed.port === '0') {
+        throw new Error('Use an HTTPS base URL without credentials, query, or fragment; HTTP is allowed only on loopback.');
+    }
+    return parsed.href.replace(/\/+$/, '');
+}
+/** Zils defaults over the compatible TypeSafe client; automatic retries are off. */
+class ZilsClient extends sdk_1.TypeSafeClient {
+    constructor(config = {}) {
+        const apiKey = config.apiKey ?? env('ZILS_API_KEY') ?? '';
+        if (!/^[\x21-\x7E]+$/.test(apiKey))
+            throw new Error('Set ZILS_API_KEY to a nonempty API key without whitespace.');
+        const model = config.defaultModel ?? env('ZILS_DEFAULT_MODEL') ?? 'zils-shared';
+        if (!model.trim() || model.length > 128)
+            throw new Error('Model must contain 1–128 characters.');
+        const transport = config.fetch ?? globalThis.fetch;
+        super({
+            ...config, apiKey,
+            baseURL: baseURL(config.baseURL ?? env('ZILS_BASE_URL') ?? DEFAULT_BASE_URL),
+            defaultModel: model,
+            timeout: config.timeout ?? 60_000,
+            retry: { ...config.retry, maxRetries: config.retry?.maxRetries ?? 0 },
+            logLevel: config.logLevel ?? 'off',
+            dangerouslyAllowBrowser: false,
+            // Decisions are paid requests: never forward them through an HTTP redirect.
+            fetch: (url, init) => transport(url, { ...init, redirect: 'error' }),
+        });
+    }
+    systemOne(request, options) {
+        return super.systemOne(request, options);
+    }
+}
+exports.ZilsClient = ZilsClient;

package/package.json

@@ -1,6 +1,25 @@
 {
   "name": "@zils/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Typed JavaScript and TypeScript client for Zils decisions",
+  "license": "MIT",
+  "homepage": "https://zils.ai",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ooo-hq/zils-sdk.git",
+    "directory": "packages/typescript"
+  },
+  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": { ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" } },
+  "files": ["dist", "README.md", "LICENSE"],
+  "engines": { "node": ">=20" },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && tsc -p tsconfig.test.json && node --test test/*.test.mjs",
+    "prepack": "npm run build"
+  },
+  "dependencies": { "@typesafe-ai/sdk": "0.6.0" },
+  "devDependencies": { "typescript": "~5.9.3", "@types/node": "^22.0.0" }
+}