/** * Jev (TypeSafe System One) — zero-dependency HTTP client * * One POST, three primitives (choice / score / noul), typed answers with calibrated * probabilities. No npm dependency: Node >= 20.12 global `fetch` + `AbortSignal.timeout`. * * Safety rules enforced here: * - the API key value never appears in an error message, a log line or the usage ledger; * - the serialized state passes through {@link redactSecrets} before ANY request; * - questions are validated locally BEFORE any network call (cheap 422 avoidance); * - 429 / 529 / transport failures retry with exponential backoff, everything else fails fast. * * @module core/jev/client */ import { type JevConfig, type JevProvider } from './config.js'; export type Json = string | number | boolean | null | Json[] | { [k: string]: Json; }; export type Question = { type: 'choice'; instructions: Json; criteria: Record; } | { type: 'score'; instructions: Json; criteria: Json[]; } | { type: 'noul'; instructions: Json; criteria?: { true?: Json; false?: Json; }; }; export type Answer = { type: 'choice'; choice: string; probabilities: Record; confidence: number; } | { type: 'score'; score: number; probabilities: Record; legend?: Record; confidence: number; } | { type: 'noul'; noul: number; }; export interface JevResponse { provider: JevProvider; model: string; answers: Record; usage: { input_tokens: number; output_tokens: number; cost?: number; }; latencyMs: number; id?: string; requestId?: string; evidenceHash?: string; /** How many secret-shaped spans {@link redactSecrets} masked out of the state. */ redactions?: number; } export type JevErrorCode = 'disabled' | 'no_key' | 'auth' | 'validation' | 'rate_limit' | 'overloaded' | 'transport' | 'timeout' | 'schema' | 'refusal'; export declare class JevError extends Error { readonly code: JevErrorCode; readonly status?: number; readonly retryable: boolean; constructor(code: JevErrorCode, message: string, opts?: { status?: number; retryable?: boolean; }); } export interface JevClientOptions { apiKey?: string; fetch?: typeof fetch; projectRoot?: string; usageLog?: boolean; kind?: string; /** Base backoff in ms (300 by default); lowered by tests. */ backoffMs?: number; } /** API limits (TypeSafe, verified 2026-09-21). */ export declare const JEV_LIMITS: { readonly maxChoiceOptions: 255; readonly minChoiceOptions: 2; readonly minScoreLevels: 2; readonly maxScoreLevels: 10; }; /** * Validate questions locally so a malformed catalog fails as `validation` * before we spend a request (and before anything reaches the wire). */ export declare function validateQuestions(questions: Record): void; /** Map an HTTP status to a JevErrorCode. */ export declare function statusToCode(status: number): JevErrorCode; export declare class JevClient { readonly config: JevConfig; private readonly apiKey; private readonly fetchImpl; private readonly projectRoot?; private readonly usageLog; private readonly kind; private readonly backoffMs; constructor(cfg: JevConfig, opts?: JevClientOptions); /** * Ask one or more questions about a piece of state. Independent questions run in * parallel inside a single request — fan out rather than making N calls. */ ask(state: Json, questions: Record, opts?: { timeoutMs?: number; retries?: number; kind?: string; usageLog?: boolean; }): Promise; private requestPayload; /** One tiny noul, no retries, no ledger entry. Never throws. */ ping(): Promise<{ ok: boolean; latencyMs: number; model?: string; error?: string; }>; /** Read a short error body without ever echoing credentials back. */ private detail; private redact; private toJevError; private log; } /** * Build a client for a project, or null when Jev is disabled or no key is available. * Callers treat null as "continue without Jev" — never as an error. */ export declare function createJevClient(projectRoot?: string, opts?: JevClientOptions): JevClient | null; //# sourceMappingURL=client.d.ts.map