psiguard 1.0.0

package/README.md

@@ -0,0 +1,151 @@
+# PsiGuard JavaScript / TypeScript SDK
+
+The official Node client for the [PsiGuard](https://psiguard.net) guarded-chat API.
+
+PsiGuard wraps a language model with a live structural monitor. You send it a
+prompt; it runs the model, watches the generation as it happens, and hands you
+back a clean answer plus one coarse signal telling you whether it had to step
+in. Everything about *how* it decides stays on PsiGuard's servers — this client
+only ever sees the answer and that one signal.
+
+Written in TypeScript, ships with types, works from plain JavaScript too.
+Requires Node 18+ and has **no runtime dependencies** (it uses the built-in
+`fetch`).
+
+## Install
+
+```bash
+npm install psiguard
+```
+
+## Quick start
+
+```ts
+import { PsiGuard } from "psiguard";
+
+const client = new PsiGuard({ apiKey: "psg_live_your_key_here" });
+
+const result = await client.guard("What is your return policy?");
+console.log(result.answer);      // the reply to show your user
+console.log(result.protection);  // "safe" | "caution" | "intervened"
+```
+
+Plain JavaScript (CommonJS) works the same way:
+
+```js
+const { PsiGuard } = require("psiguard");
+```
+
+Set `PSIGUARD_API_KEY` in your environment and you can skip passing the key:
+
+```ts
+const client = new PsiGuard();   // reads PSIGUARD_API_KEY
+```
+
+Get a key from your dashboard at **psiguard.net/dashboard/keys**.
+
+> **Keep your key server-side.** Like a password, anyone holding it can spend
+> against your account. Use this SDK from your back end, not from browser code.
+
+## Give your assistant a personality
+
+```ts
+const result = await client.guard("Do you ship to Canada?", {
+  systemPrompt: "You are a friendly support agent for Acme Tools.",
+  conversationId: "cust-8472",
+});
+```
+
+## Multi-turn conversations
+
+The `conversation()` helper reuses one id and accumulates history for you, so
+each turn carries the ones before it:
+
+```ts
+const chat = client.conversation({ systemPrompt: "You are Acme's assistant." });
+
+await chat.send("Hi, my order hasn't arrived.");
+const reply = await chat.send("It's order 1234.");  // remembers the turn before
+
+console.log(reply.answer);
+```
+
+## Reading the protection signal
+
+Every turn comes back with one of three values. A simple integration can ignore
+it and just show `answer`.
+
+| value | meaning |
+|---|---|
+| `safe` | Clean run. PsiGuard didn't need to act. |
+| `caution` | PsiGuard steered the response back on course. `answer` is the corrected one. |
+| `intervened` | PsiGuard withheld the response. `answer` is a neutral refusal, safe to show as-is. |
+
+```ts
+const result = await client.guard(prompt);
+if (result.intervened) {
+  console.log("PsiGuard stepped in on this turn");
+}
+showToUser(result.answer);
+```
+
+## Handling errors
+
+Everything the client throws extends `PsiGuardError`, so you can catch broadly
+or narrowly:
+
+```ts
+import {
+  PsiGuard, AuthenticationError,
+  RateLimitError, UsageLimitError, PsiGuardError,
+} from "psiguard";
+
+try {
+  const result = await client.guard(prompt);
+} catch (e) {
+  if (e instanceof AuthenticationError) {
+    // key missing, invalid, or revoked
+  } else if (e instanceof RateLimitError) {
+    // too many requests — slow down and retry shortly
+  } else if (e instanceof UsageLimitError) {
+    // monthly cap or provider budget reached — a stop sign, not a retry
+    // e.scope, e.plan, e.provider, e.used, e.limit, e.month
+  } else if (e instanceof PsiGuardError) {
+    // anything else
+  } else {
+    throw e;
+  }
+}
+```
+
+The client automatically retries the failures that are safe to retry (network
+errors and 5xx), and never retries the ones that aren't (4xx and usage caps).
+Tune it with `new PsiGuard({ maxRetries: 2, timeoutMs: 60000 })`.
+
+## Verify a key
+
+```ts
+const who = await client.whoami();   // runs no model, isn't metered
+console.log(who.account);
+```
+
+## Configuration reference
+
+| Option | Default | Notes |
+|---|---|---|
+| `apiKey` | `$PSIGUARD_API_KEY` | Your `psg_live_…` key. |
+| `baseUrl` | `$PSIGUARD_BASE_URL` or `https://psiguard.net` | Your PsiGuard host. |
+| `timeoutMs` | `60000` | Per-request timeout in milliseconds. |
+| `maxRetries` | `2` | Extra attempts for retryable failures only. |
+
+## A note on what's inside
+
+This client is a courier, not the engine. It contains none of PsiGuard's
+internal workings — no metrics, no thresholds, no scoring. It speaks only the
+public contract: a prompt goes out, an answer and a protection signal come
+back. PsiGuard's monitoring framework is proprietary and confidential,
+protected as a trade secret of PsiCo, LLC.
+
+---
+
+© PsiCo, LLC. Licensed for use through the PsiGuard API.

package/dist/index.d.ts

@@ -0,0 +1,233 @@
+/**
+ * PsiGuard JavaScript / TypeScript SDK
+ * ====================================
+ *
+ * The official Node client for the PsiGuard guarded-chat API.
+ *
+ * PsiGuard wraps a language model with a live structural monitor. You send it a
+ * prompt; it runs the model, watches the generation as it happens, and hands
+ * you back a clean answer plus one coarse signal telling you whether it had to
+ * step in. Everything about *how* it decides stays on PsiGuard's servers — this
+ * client only ever sees the answer and that one signal.
+ *
+ * Quick start
+ * -----------
+ *   import { PsiGuard } from "psiguard";
+ *
+ *   const client = new PsiGuard({ apiKey: "psg_live_your_key_here" });
+ *   const result = await client.guard("What is your return policy?");
+ *   console.log(result.answer);      // the reply to show your user
+ *   console.log(result.protection);  // "safe" | "caution" | "intervened"
+ *
+ * Set PSIGUARD_API_KEY in your environment and you can skip passing the key:
+ *
+ *   const client = new PsiGuard();   // reads PSIGUARD_API_KEY
+ *
+ * This client is a courier, not the engine. It contains none of PsiGuard's
+ * inner workings — no metrics, no thresholds, no scoring. It speaks only the
+ * public contract: a prompt goes out, an answer and a protection signal come
+ * back.
+ *
+ * Keep your API key server-side. Like a password, anyone holding it can spend
+ * against your account — so this SDK is built for Node/back-end use, not for
+ * shipping a key into a browser.
+ *
+ * Requires Node 18+ (uses the built-in fetch). No runtime dependencies.
+ */
+export declare const VERSION = "1.0.0";
+/** The value of a turn's `protection` field. */
+export type ProtectionValue = "safe" | "caution" | "intervened";
+/** Named constants for the three protection values. */
+export declare const Protection: {
+    /** Clean run; PsiGuard didn't need to act. */
+    readonly SAFE: "safe";
+    /** Steered back on course mid-generation. */
+    readonly CAUTION: "caution";
+    /** Response withheld; answer is a neutral refusal. */
+    readonly INTERVENED: "intervened";
+};
+/** One prior turn, as the model should see it. */
+export interface HistoryMessage {
+    role: string;
+    content: string;
+}
+/** Options for a single guarded turn. */
+export interface GuardOptions {
+    /**
+     * Your assistant's personality, scope, or instructions. Omit to run the
+     * model with no steering (still guarded).
+     */
+    systemPrompt?: string;
+    /**
+     * A caller-chosen id that groups turns into one thread, so monitoring
+     * carries context across a conversation. Reuse the same id for every turn
+     * in a chat. Omit and the server uses "default".
+     */
+    conversationId?: string;
+    /**
+     * Prior turns you want the model to see. You own and store the transcript;
+     * PsiGuard doesn't retain it.
+     */
+    history?: HistoryMessage[];
+}
+/** Options for constructing a client. */
+export interface ClientOptions {
+    /** Your PsiGuard API key (looks like "psg_live_…"). Falls back to PSIGUARD_API_KEY. */
+    apiKey?: string;
+    /** Your PsiGuard host. Falls back to PSIGUARD_BASE_URL, then https://psiguard.net. */
+    baseUrl?: string;
+    /** Per-request timeout in milliseconds. Default 60000. */
+    timeoutMs?: number;
+    /** Extra attempts for retryable failures (network + 5xx). Default 2. */
+    maxRetries?: number;
+}
+/** Options for starting a conversation. */
+export interface ConversationOptions {
+    /** The thread id to use. A random one is generated if omitted. */
+    conversationId?: string;
+    /** An assistant personality applied to every turn in this conversation. */
+    systemPrompt?: string;
+}
+/** The outcome of one guarded turn. */
+export declare class GuardResult {
+    /**
+     * The reply to show your user. On an intervention this is a neutral refusal,
+     * indistinguishable from an ordinary model decline — safe to display as-is.
+     */
+    readonly answer: string;
+    /** One of "safe", "caution", or "intervened". */
+    readonly protection: ProtectionValue;
+    /** An echo of the id this turn belongs to. */
+    readonly conversationId: string;
+    /** The exact JSON object the API returned. */
+    readonly raw: Record<string, unknown>;
+    constructor(data: Record<string, unknown>, fallbackConversationId: string);
+    /** True when PsiGuard did not need to act on this turn. */
+    get safe(): boolean;
+    /** True when PsiGuard steered the response back on course. */
+    get caution(): boolean;
+    /** True when PsiGuard withheld the response (answer is a refusal). */
+    get intervened(): boolean;
+}
+/** Who an API key belongs to, as reported by a verify check. */
+export interface Account {
+    account: string;
+    authVia: string;
+    raw: Record<string, unknown>;
+}
+/** Base class for everything this SDK throws. */
+export declare class PsiGuardError extends Error {
+    constructor(message: string);
+}
+/** The client was set up wrong (e.g. no API key). No request was made. */
+export declare class ConfigurationError extends PsiGuardError {
+}
+/** The request never got a reply — network error or timeout. Safe to retry. */
+export declare class APIConnectionError extends PsiGuardError {
+}
+/** The API replied with a non-success HTTP status. */
+export declare class APIStatusError extends PsiGuardError {
+    /** The HTTP status (e.g. 400, 401, 429, 502). */
+    readonly statusCode: number;
+    /** The short machine-readable code from the body's `error` field, if present. */
+    readonly errorCode?: string;
+    /** The full parsed response body. */
+    readonly body: Record<string, unknown>;
+    constructor(message: string, statusCode: number, errorCode: string | undefined, body: Record<string, unknown>);
+}
+/** 400 — the request was malformed or the account has no model configured. */
+export declare class BadRequestError extends APIStatusError {
+}
+/** 401 — the API key was missing, invalid, or revoked. */
+export declare class AuthenticationError extends APIStatusError {
+}
+/** 429 — too many requests in a short window. Slow down and retry shortly. */
+export declare class RateLimitError extends APIStatusError {
+}
+/**
+ * 429 — a usage limit was reached (a stop sign, not a retry).
+ *
+ * Distinct from RateLimitError: you've hit either the account's monthly cap or
+ * a provider budget. Retrying won't help — raise the cap or bring your own
+ * provider key.
+ */
+export declare class UsageLimitError extends APIStatusError {
+    /** "account" for a monthly cap, "provider" for a provider budget. */
+    readonly scope: "account" | "provider";
+    /** The account's plan (account cap only). */
+    readonly plan?: string;
+    /** The provider whose budget was reached (provider budget only). */
+    readonly provider?: string;
+    /** How much has been used this month. */
+    readonly used?: number;
+    /** The cap or budget that was reached. */
+    readonly limit?: number;
+    /** The month the counter applies to. */
+    readonly month?: string;
+    constructor(message: string, statusCode: number, errorCode: string | undefined, body: Record<string, unknown>);
+}
+/** 5xx — the server or the underlying model failed. Usually safe to retry. */
+export declare class ServerError extends APIStatusError {
+}
+/**
+ * A connection to the PsiGuard API.
+ *
+ *   const client = new PsiGuard({ apiKey: "psg_live_…" });
+ *   const result = await client.guard("hello");
+ *
+ * The client is safe to keep and reuse for the life of your process.
+ */
+export declare class PsiGuard {
+    readonly apiKey: string;
+    readonly baseUrl: string;
+    readonly timeoutMs: number;
+    readonly maxRetries: number;
+    constructor(options?: ClientOptions);
+    /**
+     * Run one guarded turn and return the answer.
+     *
+     * This is the call most integrations only ever need.
+     */
+    guard(prompt: string, options?: GuardOptions): Promise<GuardResult>;
+    /**
+     * Confirm the API key is valid and see which account it belongs to.
+     * Runs no model and isn't metered. Throws AuthenticationError if the key is bad.
+     */
+    whoami(): Promise<Account>;
+    /**
+     * Start a multi-turn conversation that manages its own thread.
+     *
+     * The returned Conversation reuses one conversationId and accumulates history
+     * for you, so each send() carries the turns before it.
+     */
+    conversation(options?: ConversationOptions): Conversation;
+    private get headers();
+    /**
+     * Make one API call, retrying the failures that are safe to retry.
+     * Retried: network errors, timeouts, and 5xx. Never: 4xx and usage caps.
+     */
+    private request;
+}
+/** Alias so `new Client(...)` works too, matching the Python SDK's name. */
+export { PsiGuard as Client };
+/**
+ * An ongoing guarded conversation on a single thread.
+ *
+ * Holds a conversationId and a running transcript so each turn carries the ones
+ * before it. Make one with `client.conversation()` rather than directly.
+ */
+export declare class Conversation {
+    readonly client: PsiGuard;
+    readonly conversationId: string;
+    readonly systemPrompt?: string;
+    /** The running transcript: two entries per turn (user prompt, assistant answer). */
+    history: HistoryMessage[];
+    constructor(client: PsiGuard, options: {
+        conversationId: string;
+        systemPrompt?: string;
+    });
+    /** Send the next turn and record both sides in the transcript. */
+    send(prompt: string): Promise<GuardResult>;
+    /** Forget the transcript but keep the same conversationId. */
+    reset(): void;
+}

package/dist/index.js

@@ -0,0 +1,360 @@
+"use strict";
+/**
+ * PsiGuard JavaScript / TypeScript SDK
+ * ====================================
+ *
+ * The official Node client for the PsiGuard guarded-chat API.
+ *
+ * PsiGuard wraps a language model with a live structural monitor. You send it a
+ * prompt; it runs the model, watches the generation as it happens, and hands
+ * you back a clean answer plus one coarse signal telling you whether it had to
+ * step in. Everything about *how* it decides stays on PsiGuard's servers — this
+ * client only ever sees the answer and that one signal.
+ *
+ * Quick start
+ * -----------
+ *   import { PsiGuard } from "psiguard";
+ *
+ *   const client = new PsiGuard({ apiKey: "psg_live_your_key_here" });
+ *   const result = await client.guard("What is your return policy?");
+ *   console.log(result.answer);      // the reply to show your user
+ *   console.log(result.protection);  // "safe" | "caution" | "intervened"
+ *
+ * Set PSIGUARD_API_KEY in your environment and you can skip passing the key:
+ *
+ *   const client = new PsiGuard();   // reads PSIGUARD_API_KEY
+ *
+ * This client is a courier, not the engine. It contains none of PsiGuard's
+ * inner workings — no metrics, no thresholds, no scoring. It speaks only the
+ * public contract: a prompt goes out, an answer and a protection signal come
+ * back.
+ *
+ * Keep your API key server-side. Like a password, anyone holding it can spend
+ * against your account — so this SDK is built for Node/back-end use, not for
+ * shipping a key into a browser.
+ *
+ * Requires Node 18+ (uses the built-in fetch). No runtime dependencies.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Conversation = exports.Client = exports.PsiGuard = exports.ServerError = exports.UsageLimitError = exports.RateLimitError = exports.AuthenticationError = exports.BadRequestError = exports.APIStatusError = exports.APIConnectionError = exports.ConfigurationError = exports.PsiGuardError = exports.GuardResult = exports.Protection = exports.VERSION = void 0;
+exports.VERSION = "1.0.0";
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+const DEFAULT_BASE_URL = "https://psiguard.net";
+const DEFAULT_TIMEOUT_MS = 60000; // a guarded turn runs a full model call
+const DEFAULT_MAX_RETRIES = 2; // retryable failures only
+const RETRY_BACKOFF_MS = 750; // grows each retry: 750ms, 1.5s, 3s, …
+const USER_AGENT = `psiguard-js/${exports.VERSION}`;
+/** Named constants for the three protection values. */
+exports.Protection = {
+    /** Clean run; PsiGuard didn't need to act. */
+    SAFE: "safe",
+    /** Steered back on course mid-generation. */
+    CAUTION: "caution",
+    /** Response withheld; answer is a neutral refusal. */
+    INTERVENED: "intervened",
+};
+// ---------------------------------------------------------------------------
+// Results
+// ---------------------------------------------------------------------------
+/** The outcome of one guarded turn. */
+class GuardResult {
+    constructor(data, fallbackConversationId) {
+        this.answer = typeof data.answer === "string" ? data.answer : "";
+        this.protection = data.protection ?? "safe";
+        this.conversationId =
+            typeof data.conversation_id === "string"
+                ? data.conversation_id
+                : fallbackConversationId;
+        this.raw = data;
+    }
+    /** True when PsiGuard did not need to act on this turn. */
+    get safe() {
+        return this.protection === "safe";
+    }
+    /** True when PsiGuard steered the response back on course. */
+    get caution() {
+        return this.protection === "caution";
+    }
+    /** True when PsiGuard withheld the response (answer is a refusal). */
+    get intervened() {
+        return this.protection === "intervened";
+    }
+}
+exports.GuardResult = GuardResult;
+// ---------------------------------------------------------------------------
+// Errors
+//
+// One base class so callers can `catch (e) { if (e instanceof PsiGuardError) }`
+// and be done, plus specific subclasses for the cases worth handling apart.
+// ---------------------------------------------------------------------------
+/** Base class for everything this SDK throws. */
+class PsiGuardError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+        // Keep `instanceof` working across compile targets / bundlers.
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.PsiGuardError = PsiGuardError;
+/** The client was set up wrong (e.g. no API key). No request was made. */
+class ConfigurationError extends PsiGuardError {
+}
+exports.ConfigurationError = ConfigurationError;
+/** The request never got a reply — network error or timeout. Safe to retry. */
+class APIConnectionError extends PsiGuardError {
+}
+exports.APIConnectionError = APIConnectionError;
+/** The API replied with a non-success HTTP status. */
+class APIStatusError extends PsiGuardError {
+    constructor(message, statusCode, errorCode, body) {
+        super(message);
+        this.statusCode = statusCode;
+        this.errorCode = errorCode;
+        this.body = body;
+    }
+}
+exports.APIStatusError = APIStatusError;
+/** 400 — the request was malformed or the account has no model configured. */
+class BadRequestError extends APIStatusError {
+}
+exports.BadRequestError = BadRequestError;
+/** 401 — the API key was missing, invalid, or revoked. */
+class AuthenticationError extends APIStatusError {
+}
+exports.AuthenticationError = AuthenticationError;
+/** 429 — too many requests in a short window. Slow down and retry shortly. */
+class RateLimitError extends APIStatusError {
+}
+exports.RateLimitError = RateLimitError;
+/**
+ * 429 — a usage limit was reached (a stop sign, not a retry).
+ *
+ * Distinct from RateLimitError: you've hit either the account's monthly cap or
+ * a provider budget. Retrying won't help — raise the cap or bring your own
+ * provider key.
+ */
+class UsageLimitError extends APIStatusError {
+    constructor(message, statusCode, errorCode, body) {
+        super(message, statusCode, errorCode, body);
+        this.scope = errorCode === "provider_budget_reached" ? "provider" : "account";
+        this.plan = body.plan;
+        this.provider = body.provider;
+        this.used = body.used;
+        // The body names the ceiling "cap" for accounts and "budget" for providers.
+        this.limit = (body.cap ?? body.budget);
+        this.month = body.month;
+    }
+}
+exports.UsageLimitError = UsageLimitError;
+/** 5xx — the server or the underlying model failed. Usually safe to retry. */
+class ServerError extends APIStatusError {
+}
+exports.ServerError = ServerError;
+/** Usage-cap error codes that mean "stop", not "slow down". */
+const USAGE_CODES = new Set(["monthly_cap_reached", "provider_budget_reached"]);
+// ---------------------------------------------------------------------------
+// The client
+// ---------------------------------------------------------------------------
+/**
+ * A connection to the PsiGuard API.
+ *
+ *   const client = new PsiGuard({ apiKey: "psg_live_…" });
+ *   const result = await client.guard("hello");
+ *
+ * The client is safe to keep and reuse for the life of your process.
+ */
+class PsiGuard {
+    constructor(options = {}) {
+        const key = options.apiKey ?? process.env.PSIGUARD_API_KEY;
+        if (!key) {
+            throw new ConfigurationError("No API key. Pass { apiKey } or set the PSIGUARD_API_KEY environment " +
+                "variable. Create a key at https://psiguard.net/dashboard/keys");
+        }
+        this.apiKey = key.trim();
+        const host = options.baseUrl ?? process.env.PSIGUARD_BASE_URL ?? DEFAULT_BASE_URL;
+        this.baseUrl = host.replace(/\/+$/, "");
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.maxRetries = Math.max(0, options.maxRetries ?? DEFAULT_MAX_RETRIES);
+    }
+    /**
+     * Run one guarded turn and return the answer.
+     *
+     * This is the call most integrations only ever need.
+     */
+    async guard(prompt, options = {}) {
+        if (typeof prompt !== "string" || prompt.trim() === "") {
+            throw new ConfigurationError("guard() needs a non-empty 'prompt' string.");
+        }
+        const body = { prompt };
+        if (options.systemPrompt)
+            body.system_prompt = options.systemPrompt;
+        if (options.conversationId)
+            body.conversation_id = options.conversationId;
+        if (options.history)
+            body.history = cleanHistory(options.history);
+        const data = await this.request("POST", "/v1/guard", body);
+        return new GuardResult(data, options.conversationId ?? "default");
+    }
+    /**
+     * Confirm the API key is valid and see which account it belongs to.
+     * Runs no model and isn't metered. Throws AuthenticationError if the key is bad.
+     */
+    async whoami() {
+        const data = await this.request("GET", "/v1/whoami");
+        return {
+            account: typeof data.account === "string" ? data.account : "",
+            authVia: typeof data.auth_via === "string" ? data.auth_via : "",
+            raw: data,
+        };
+    }
+    /**
+     * Start a multi-turn conversation that manages its own thread.
+     *
+     * The returned Conversation reuses one conversationId and accumulates history
+     * for you, so each send() carries the turns before it.
+     */
+    conversation(options = {}) {
+        return new Conversation(this, {
+            conversationId: options.conversationId ?? newConversationId(),
+            systemPrompt: options.systemPrompt,
+        });
+    }
+    // -- internals ----------------------------------------------------------
+    get headers() {
+        return {
+            Authorization: `Bearer ${this.apiKey}`,
+            "Content-Type": "application/json",
+            Accept: "application/json",
+            "User-Agent": USER_AGENT,
+        };
+    }
+    /**
+     * Make one API call, retrying the failures that are safe to retry.
+     * Retried: network errors, timeouts, and 5xx. Never: 4xx and usage caps.
+     */
+    async request(method, path, jsonBody) {
+        const url = this.baseUrl + path;
+        let attempt = 0;
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            attempt += 1;
+            let resp;
+            try {
+                resp = await fetch(url, {
+                    method,
+                    headers: this.headers,
+                    body: jsonBody !== undefined ? JSON.stringify(jsonBody) : undefined,
+                    signal: AbortSignal.timeout(this.timeoutMs),
+                });
+            }
+            catch (e) {
+                // No response at all (network error or timeout). Retry if attempts remain.
+                if (attempt <= this.maxRetries) {
+                    await sleepBackoff(attempt);
+                    continue;
+                }
+                throw new APIConnectionError(`Could not reach PsiGuard at ${url}: ${e.message}`);
+            }
+            // A 5xx is the model or server faltering — retry it.
+            if (resp.status >= 500 && attempt <= this.maxRetries) {
+                await sleepBackoff(attempt);
+                continue;
+            }
+            return await handleResponse(resp);
+        }
+    }
+}
+exports.PsiGuard = PsiGuard;
+exports.Client = PsiGuard;
+// ---------------------------------------------------------------------------
+// Multi-turn helper
+// ---------------------------------------------------------------------------
+/**
+ * An ongoing guarded conversation on a single thread.
+ *
+ * Holds a conversationId and a running transcript so each turn carries the ones
+ * before it. Make one with `client.conversation()` rather than directly.
+ */
+class Conversation {
+    constructor(client, options) {
+        /** The running transcript: two entries per turn (user prompt, assistant answer). */
+        this.history = [];
+        this.client = client;
+        this.conversationId = options.conversationId;
+        this.systemPrompt = options.systemPrompt;
+    }
+    /** Send the next turn and record both sides in the transcript. */
+    async send(prompt) {
+        const result = await this.client.guard(prompt, {
+            systemPrompt: this.systemPrompt,
+            conversationId: this.conversationId,
+            history: this.history,
+        });
+        this.history.push({ role: "user", content: prompt });
+        this.history.push({ role: "assistant", content: result.answer });
+        return result;
+    }
+    /** Forget the transcript but keep the same conversationId. */
+    reset() {
+        this.history = [];
+    }
+}
+exports.Conversation = Conversation;
+// ---------------------------------------------------------------------------
+// Small helpers
+// ---------------------------------------------------------------------------
+function cleanHistory(history) {
+    return history.map((m, i) => {
+        if (m &&
+            typeof m.role === "string" &&
+            m.role &&
+            typeof m.content === "string" &&
+            m.content) {
+            return { role: m.role, content: m.content };
+        }
+        throw new ConfigurationError(`history[${i}] must be an object with non-empty string 'role' and 'content'.`);
+    });
+}
+async function handleResponse(resp) {
+    let body = {};
+    try {
+        const parsed = await resp.json();
+        body = parsed && typeof parsed === "object" ? parsed : { raw: parsed };
+    }
+    catch {
+        body = {};
+    }
+    const status = resp.status;
+    if (status >= 200 && status < 300)
+        return body;
+    const code = typeof body.error === "string" ? body.error : undefined;
+    const message = (typeof body.message === "string" && body.message) ||
+        code ||
+        `PsiGuard request failed with status ${status}`;
+    switch (true) {
+        case status === 400:
+            throw new BadRequestError(message, status, code, body);
+        case status === 401:
+            throw new AuthenticationError(message, status, code, body);
+        case status === 429:
+            if (code && USAGE_CODES.has(code)) {
+                throw new UsageLimitError(message, status, code, body);
+            }
+            throw new RateLimitError(message, status, code, body);
+        case status >= 500:
+            throw new ServerError(message, status, code, body);
+        default:
+            throw new APIStatusError(message, status, code, body);
+    }
+}
+function newConversationId() {
+    // A short, unique-enough id for a fresh thread.
+    return "conv-" + Math.random().toString(36).slice(2, 10) + Date.now().toString(36).slice(-6);
+}
+function sleepBackoff(attempt) {
+    const ms = RETRY_BACKOFF_MS * 2 ** (attempt - 1);
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "psiguard",
+  "version": "1.0.0",
+  "description": "Official JavaScript/TypeScript client for the PsiGuard guarded-chat API.",
+  "author": "PsiCo, LLC",
+  "license": "UNLICENSED",
+  "homepage": "https://psiguard.net",
+  "keywords": [
+    "psiguard",
+    "llm",
+    "ai-safety",
+    "guardrails",
+    "monitoring"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "tsc"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "@types/node": "^18.19.0"
+  }
+}