@odla-ai/ai 0.3.0 → 0.3.2

package/dist/{openai-NTQCF577.js → openai-3XRICNAW.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-U7F6VJCV.js";
 import {
   toolInput
-} from "./chunk-OX4TA4ZH.js";
+} from "./chunk-6YJM5YZG.js";
 import {
   CapabilityError,
   ToolInputError,
@@ -12,7 +12,7 @@ import {
   mapProviderError,
   normalizeError,
   signalWithDeadline
-} from "./chunk-PXXCN2EU.js";
+} from "./chunk-XVU2W4TU.js";
 
 // src/providers/openai.ts
 import OpenAI from "openai";
@@ -273,4 +273,4 @@ export {
   parseArgs,
   toOpenAIMessages
 };
-//# sourceMappingURL=openai-NTQCF577.js.map
+//# sourceMappingURL=openai-3XRICNAW.js.map

package/llms.txt

@@ -135,6 +135,11 @@ Every error is an OdlaAIError subclass with a stable `code` — branch on err.co
 config, auth, rate_limit, capability_unsupported, context_window, invalid_request,
 tool_input_invalid, cancelled, deadline_exceeded, provider_error.
 
+OdlaAIError.usage is an optional frozen token-usage record. It exists only when
+the provider returned a response before a later forced-tool/schema validation
+failure, and may be absent for every earlier failure. It is intentionally not
+included in toShape() or streaming OracleErrorShape.
+
 ## Models
 
 - `claude-opus-4-8` (anthropic) — text, image, tools, thinking, effort, web-search, structured

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@odla-ai/ai",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "One general-purpose interface for AI inference across Anthropic (Claude), OpenAI, and Google (Gemini) \u2014 text, image, and audio \u2014 plus a tool-use agent engine and eval harness for Node 20+ and Cloudflare Workers.",
   "license": "MIT",
   "homepage": "https://odla.ai/docs/packages/ai",

package/dist/chunk-PXXCN2EU.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/shape/usage.ts","../src/shape/errors.ts","../src/providers/errors.ts","../src/client/abort.ts"],"sourcesContent":["// Token usage accounting. The one runtime island with no dependencies.\n\nexport interface OracleUsage {\n  inputTokens: number;\n  outputTokens: number;\n  cacheCreationTokens?: number;\n  cacheReadTokens?: number;\n}\n\n/** A fresh zeroed usage tally (0 input/output tokens, no cache fields) — the seed for accumulation. */\nexport function emptyUsage(): OracleUsage {\n  return { inputTokens: 0, outputTokens: 0 };\n}\n\n/** Accumulate `more` into `into`, in place. Cache fields sum when present. */\nexport function addUsage(into: OracleUsage, more: OracleUsage): void {\n  into.inputTokens += more.inputTokens;\n  into.outputTokens += more.outputTokens;\n  if (more.cacheCreationTokens !== undefined) {\n    into.cacheCreationTokens = (into.cacheCreationTokens ?? 0) + more.cacheCreationTokens;\n  }\n  if (more.cacheReadTokens !== undefined) {\n    into.cacheReadTokens = (into.cacheReadTokens ?? 0) + more.cacheReadTokens;\n  }\n}\n","// The normalized error taxonomy and the class hierarchy every adapter throws.\n\n/** The closed taxonomy of normalized error codes carried by every OdlaAIError\n *  and by the streaming `error` event. */\nexport type OracleErrorType =\n  | \"invalid_request\"\n  | \"auth\"\n  | \"rate_limit\"\n  | \"context_window\"\n  | \"cancelled\"\n  | \"deadline_exceeded\"\n  | \"tool_input_invalid\"\n  | \"capability_unsupported\"\n  | \"config\"\n  | \"provider_error\";\n\n/** The plain-data error shape used inside the streaming `error` event. */\nexport interface OracleErrorShape {\n  code: OracleErrorType;\n  message: string;\n  /** HTTP status from the upstream provider, when applicable. */\n  providerStatus?: number;\n  /** Seconds until a retry might succeed (rate limit / overload). */\n  retryAfter?: number;\n}\n\n/** Base class for every error odla-ai throws. Carries a stable string `code`\n *  (the odla ecosystem convention — see odla-db's AuthError/RuleError) so\n *  callers branch on `err.code`, never on message text. */\nexport class OdlaAIError extends Error {\n  readonly code: OracleErrorType;\n  readonly providerStatus?: number;\n  readonly retryAfter?: number;\n\n  constructor(\n    code: OracleErrorType,\n    message: string,\n    opts?: { providerStatus?: number; retryAfter?: number; cause?: unknown },\n  ) {\n    super(message, opts?.cause !== undefined ? { cause: opts.cause } : undefined);\n    this.name = new.target.name;\n    this.code = code;\n    this.providerStatus = opts?.providerStatus;\n    this.retryAfter = opts?.retryAfter;\n  }\n\n  toShape(): OracleErrorShape {\n    return {\n      code: this.code,\n      message: this.message,\n      providerStatus: this.providerStatus,\n      retryAfter: this.retryAfter,\n    };\n  }\n}\n\n/** A provider/model is not configured — e.g. no API key for its provider, or an\n *  unknown canonical model id. The library analog of odla-db's 501 gating. */\nexport class ConfigError extends OdlaAIError {\n  constructor(message: string) {\n    super(\"config\", message);\n  }\n}\n\n/** Authentication with the provider failed (bad/missing key). */\nexport class AuthError extends OdlaAIError {\n  constructor(message: string, opts?: { providerStatus?: number; cause?: unknown }) {\n    super(\"auth\", message, opts);\n  }\n}\n\n/** The provider rate-limited or is overloaded; check `retryAfter`. */\nexport class RateLimitError extends OdlaAIError {\n  constructor(message: string, opts?: { providerStatus?: number; retryAfter?: number; cause?: unknown }) {\n    super(\"rate_limit\", message, opts);\n  }\n}\n\n/** The request asked a model to do something it cannot — audio to Claude, tools\n *  to a text-only model, web search where unsupported, etc. Raised before any\n *  network call by `validateRequest`. */\nexport class CapabilityError extends OdlaAIError {\n  constructor(message: string) {\n    super(\"capability_unsupported\", message);\n  }\n}\n\n/** The request exceeded the model's context window. */\nexport class ContextWindowError extends OdlaAIError {\n  constructor(message: string, opts?: { providerStatus?: number; cause?: unknown }) {\n    super(\"context_window\", message, opts);\n  }\n}\n\n/** The request was malformed / rejected as invalid by the provider. */\nexport class InvalidRequestError extends OdlaAIError {\n  constructor(message: string, opts?: { providerStatus?: number; cause?: unknown }) {\n    super(\"invalid_request\", message, opts);\n  }\n}\n\n/** A provider returned tool arguments that are malformed or do not satisfy the\n * declared JSON Schema. Tool handlers are never invoked for this error. */\nexport class ToolInputError extends OdlaAIError {\n  readonly tool?: string;\n\n  constructor(message: string, opts?: { tool?: string; cause?: unknown }) {\n    super(\"tool_input_invalid\", message, { cause: opts?.cause });\n    this.tool = opts?.tool;\n  }\n}\n\n/** The caller cancelled a request. This is not an upstream failure and should\n * not be retried unless the caller explicitly starts a new operation. */\nexport class CancelledError extends OdlaAIError {\n  constructor(message = \"AI request was cancelled.\", opts?: { cause?: unknown }) {\n    super(\"cancelled\", message, opts);\n  }\n}\n\n/** The request's absolute deadline elapsed. Callers may choose a new deadline,\n * but should not classify this as a provider outage. */\nexport class DeadlineExceededError extends OdlaAIError {\n  constructor(message = \"AI request deadline was exceeded.\", opts?: { cause?: unknown }) {\n    super(\"deadline_exceeded\", message, opts);\n  }\n}\n\n/** Any other upstream provider failure (5xx, transport, unexpected shape). */\nexport class ProviderError extends OdlaAIError {\n  constructor(message: string, opts?: { providerStatus?: number; cause?: unknown }) {\n    super(\"provider_error\", message, opts);\n  }\n}\n","// Normalize a thrown provider-SDK error into the odla-ai error taxonomy. Kept\n// dependency-light: it duck-types the HTTP status / retry-after off the error\n// object rather than importing each SDK's error classes, so it works uniformly\n// across @anthropic-ai/sdk, openai, and @google/genai.\n\nimport {\n  AuthError,\n  CancelledError,\n  ContextWindowError,\n  DeadlineExceededError,\n  InvalidRequestError,\n  OdlaAIError,\n  ProviderError,\n  RateLimitError,\n  type ProviderId,\n} from \"../shape/index\";\n\nfunction statusOf(err: unknown): number | undefined {\n  if (err && typeof err === \"object\") {\n    const rec = err as Record<string, unknown>;\n    for (const k of [\"status\", \"statusCode\", \"code\"]) {\n      const v = rec[k];\n      if (typeof v === \"number\") return v;\n    }\n  }\n  return undefined;\n}\n\nfunction retryAfterOf(err: unknown): number | undefined {\n  if (err && typeof err === \"object\") {\n    const headers = (err as { headers?: unknown }).headers;\n    if (headers && typeof headers === \"object\") {\n      const raw = (headers as Record<string, unknown>)[\"retry-after\"];\n      const n = typeof raw === \"string\" ? Number(raw) : typeof raw === \"number\" ? raw : NaN;\n      if (Number.isFinite(n)) return n;\n    }\n  }\n  return undefined;\n}\n\nfunction messageOf(err: unknown): string {\n  if (err instanceof Error) return err.message;\n  if (typeof err === \"string\") return err;\n  return \"unknown provider error\";\n}\n\n/** Map any provider error to an OdlaAIError, returning it (does not throw).\n *  Re-returns an OdlaAIError unchanged (already normalized). */\nexport function normalizeError(err: unknown, provider: ProviderId, signal?: AbortSignal): OdlaAIError {\n  if (err instanceof OdlaAIError) return err;\n  const cancellation = cancellationError(signal?.aborted ? signal.reason : err);\n  if (signal?.aborted || cancellation) return cancellation ?? new CancelledError(undefined, { cause: err });\n\n  const status = statusOf(err);\n  const message = messageOf(err);\n  const tagged = `[${provider}] ${message}`;\n\n  if (status === 401 || status === 403) return new AuthError(tagged, { providerStatus: status, cause: err });\n  if (status === 429) {\n    return new RateLimitError(tagged, { providerStatus: status, retryAfter: retryAfterOf(err), cause: err });\n  }\n  if (status === 400 || status === 422) {\n    if (/context|token limit|too long|maximum context/i.test(message)) {\n      return new ContextWindowError(tagged, { providerStatus: status, cause: err });\n    }\n    return new InvalidRequestError(tagged, { providerStatus: status, cause: err });\n  }\n  return new ProviderError(tagged, { providerStatus: status, cause: err });\n}\n\n/**\n * Normalize and throw. The `never` return lets call sites write\n * `catch (e) { mapProviderError(e, id); }` with no fallthrough.\n */\nexport function mapProviderError(err: unknown, provider: ProviderId, signal?: AbortSignal): never {\n  throw normalizeError(err, provider, signal);\n}\n\nfunction cancellationError(reason: unknown): CancelledError | DeadlineExceededError | undefined {\n  if (reason instanceof DeadlineExceededError || reason instanceof CancelledError) return reason;\n  if (!reason || typeof reason !== \"object\") return undefined;\n  const rec = reason as { name?: unknown; code?: unknown; message?: unknown };\n  if (rec.name === \"TimeoutError\") return new DeadlineExceededError(undefined, { cause: reason });\n  if (rec.name === \"AbortError\" || rec.name === \"APIUserAbortError\" || rec.code === \"ABORT_ERR\") {\n    return new CancelledError(undefined, { cause: reason });\n  }\n  return undefined;\n}\n","import { CancelledError, ConfigError, DeadlineExceededError } from \"../shape/errors\";\n\n/** Combine a caller signal with an absolute deadline. Kept provider-neutral so\n * every adapter and the agent loop observes the same cancellation contract. */\nexport function signalWithDeadline(signal?: AbortSignal, deadline?: number): AbortSignal | undefined {\n  if (deadline === undefined) return signal;\n  if (!Number.isSafeInteger(deadline)) throw new ConfigError(\"deadline must be a finite integer Unix timestamp in milliseconds.\");\n  const remaining = deadline - Date.now();\n  if (remaining <= 0) {\n    const expired = new AbortController();\n    expired.abort(new DeadlineExceededError());\n    return signal ? AbortSignal.any([signal, expired.signal]) : expired.signal;\n  }\n  const timeout = AbortSignal.timeout(remaining);\n  return signal ? AbortSignal.any([signal, timeout]) : timeout;\n}\n\n/** Fail synchronously before beginning a local side effect when a run was\n * cancelled or its deadline elapsed. Handlers must still observe the signal\n * while in flight; this closes the already-aborted race at invocation time. */\nexport function throwIfAborted(signal?: AbortSignal): void {\n  if (!signal?.aborted) return;\n  const reason = signal.reason;\n  if (reason instanceof DeadlineExceededError || reason instanceof CancelledError) throw reason;\n  if (reason && typeof reason === \"object\" && (reason as { name?: unknown }).name === \"TimeoutError\") {\n    throw new DeadlineExceededError(undefined, { cause: reason });\n  }\n  throw new CancelledError(undefined, { cause: reason });\n}\n"],"mappings":"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","names":[]}