hanzoai 8.5.621 → 8.5.640

package/dist/transport.js

@@ -0,0 +1,195 @@
+"use strict";
+// transport — the Configuration this package exports.
+//
+// It is the generated Configuration plus one thing: a request a generated *Api
+// class sends with it that comes back 402 or 429 with a usage refusal in the
+// body throws that refusal's typed error (usage.ts). Every other answer passes
+// through untouched — a 400 is still the AxiosError it was.
+//
+// The error path is axios's own: one response interceptor on the axios instance
+// the generated classes use by default, installed by the first Configuration
+// built. It acts only on requests marked as this package's, and the mark rides
+// in `baseOptions`, which the generated client spreads into every request it
+// builds — so the caller's other axios traffic, adapters and transforms are left
+// as they were. An axios instance passed as an *Api's third argument has
+// interceptors of its own, and a refusal through it stays an AxiosError.
+//
+// hanzo.ts exports this class under the generated one's name, so
+// `new Configuration({ accessToken })` from 'hanzoai' is this one, and so is
+// `Client.configuration`.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Configuration = void 0;
+const axios_1 = __importDefault(require("axios"));
+const configuration_1 = require("./configuration");
+const usage_1 = require("./usage");
+/**
+ * The request option that marks a request as sent with this Configuration. Its
+ * value is this module's own interceptor, so two copies of the package sharing
+ * one axios each type only their own requests, with their own classes.
+ */
+const MARK = 'hanzoUsage';
+/** A stream body is read this far at most; a refusal is a few hundred bytes of JSON. */
+const CAP = 1 << 16;
+class Configuration extends configuration_1.Configuration {
+    constructor(param = {}) {
+        super(param);
+        this.baseOptions = { ...this.baseOptions, [MARK]: refused };
+        // Checked, not remembered: a test teardown's `interceptors.response.clear()`
+        // removes it, and the next Configuration puts it back.
+        const installed = axios_1.default.interceptors.response.handlers?.some((h) => h?.rejected === refused);
+        if (!installed)
+            axios_1.default.interceptors.response.use(undefined, refused);
+    }
+}
+exports.Configuration = Configuration;
+/** Rethrow a marked 402 or 429 as the usage refusal its body names; anything else as it came. */
+async function refused(err) {
+    const e = err;
+    const res = e?.response;
+    const config = e?.config;
+    if (!res || config?.[MARK] !== refused || (res.status !== 402 && res.status !== 429))
+        throw err;
+    let parsed;
+    try {
+        parsed = await body(res, config);
+    }
+    catch {
+        // A body that cannot be read names nothing: the answer is the one axios gave.
+        throw err;
+    }
+    throw (0, usage_1.limited)(res.status, parsed, (0, usage_1.header)(res.headers, 'x-request-id'), err) ?? err;
+}
+/**
+ * The body as JSON where it is JSON. axios hands it over parsed by default and
+ * raw when the caller asked for a buffer, a blob or a stream. A stream is read
+ * only when it says it is JSON — a refusal is, an event stream never is — at
+ * most CAP bytes, no longer than the caller's signal and timeout allow, and
+ * without taking it from the caller: `res.data` is left holding a stream of the
+ * same family that yields every byte again.
+ */
+async function body(res, config) {
+    let data = res.data;
+    if (web(data) || node(data)) {
+        if (!/json/i.test((0, usage_1.header)(res.headers, 'content-type') ?? ''))
+            return undefined;
+        const read = web(data) ? peekWeb(data, config) : peekNode(data, config);
+        const { text, again } = await read;
+        res.data = again;
+        data = text;
+    }
+    else if (typeof Blob !== 'undefined' && data instanceof Blob) {
+        data = await data.text();
+    }
+    else if (data instanceof ArrayBuffer || ArrayBuffer.isView(data)) {
+        data = new TextDecoder().decode(data);
+    }
+    if (typeof data !== 'string')
+        return data;
+    try {
+        return JSON.parse(data);
+    }
+    catch {
+        return data;
+    }
+}
+/** A WHATWG stream: the fetch and xhr adapters' `responseType: 'stream'`. */
+const web = (v) => typeof v?.tee === 'function' && typeof v.getReader === 'function';
+const node = (v) => typeof v?.pipe === 'function' &&
+    typeof v[Symbol.asyncIterator] === 'function' &&
+    typeof v.constructor?.from === 'function';
+/** Read a WHATWG stream through `peek`, and hand back a WHATWG stream that replays it. */
+async function peekWeb(stream, config) {
+    const reader = stream.getReader();
+    const { text, rest } = await peek(() => reader.read(), config);
+    const again = new ReadableStream({
+        async pull(controller) {
+            const step = await rest.next();
+            if (step.done)
+                controller.close();
+            else
+                controller.enqueue(step.value);
+        },
+        cancel: (reason) => reader.cancel(reason),
+    });
+    return { text, again };
+}
+/** Read a Node stream through `peek`; `Readable.from` comes off its own constructor, so no bundle gains node:stream. */
+async function peekNode(stream, config) {
+    const it = stream[Symbol.asyncIterator]();
+    const { text, rest } = await peek(() => it.next(), config);
+    return { text, again: stream.constructor.from(rest) };
+}
+const STOP = Symbol('stop');
+/**
+ * Read chunks until the end, CAP bytes, the caller's abort or its timeout,
+ * whichever comes first. `text` is the whole body only when the end was
+ * reached — anything less names no refusal. `rest` yields every chunk read and
+ * then whatever is left, including a read still in flight and a failure, so the
+ * caller's stream loses nothing.
+ */
+async function peek(next, config) {
+    const seen = [];
+    const decoder = new TextDecoder();
+    let text = '';
+    let done = false;
+    let failed;
+    let pending;
+    let timer;
+    let quit;
+    const stop = new Promise((resolve) => {
+        quit = () => resolve(STOP);
+        const signal = config.signal;
+        if (signal && typeof signal.addEventListener === 'function') {
+            if (signal.aborted)
+                resolve(STOP);
+            signal.addEventListener('abort', () => resolve(STOP), { once: true });
+        }
+        if (config.timeout && config.timeout > 0)
+            timer = setTimeout(() => resolve(STOP), config.timeout);
+    });
+    try {
+        while (text.length < CAP) {
+            pending = next();
+            const step = await Promise.race([pending, stop]);
+            if (step === STOP)
+                break;
+            pending = undefined;
+            if (step.done) {
+                done = true;
+                break;
+            }
+            seen.push(step.value);
+            text += typeof step.value === 'string' ? step.value : decoder.decode(step.value, { stream: true });
+        }
+    }
+    catch (error) {
+        pending = undefined;
+        failed = { error };
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        quit?.();
+    }
+    async function* rest() {
+        yield* seen;
+        if (failed)
+            throw failed.error;
+        if (pending) {
+            const step = await pending;
+            if (step.done)
+                return;
+            yield step.value;
+        }
+        while (!done) {
+            const step = await next();
+            if (step.done)
+                return;
+            yield step.value;
+        }
+    }
+    return { text: done ? text : undefined, rest: rest() };
+}

package/dist/usage.d.ts

@@ -0,0 +1,98 @@
+import { type Obj } from './read';
+/** One way out of a usage refusal, in the order to offer them. */
+export interface UsageAction {
+    /** upgrade | switch | credits | topup. */
+    kind: string;
+    /** The words to put on the button. */
+    label?: string;
+    /** Where to go: the pay page, or `/v1/ai/limits` for "continue with credits". */
+    url?: string;
+    /** The plan an `upgrade` moves to. */
+    plan?: string;
+    /** The model a `switch` moves to. */
+    model?: string;
+}
+/** A priced request refused because nothing the caller holds may pay for it. */
+export declare class UsageLimitError extends Error {
+    name: string;
+    /** 402 or 429. */
+    readonly status: number;
+    /** The machine code — one per subclass. */
+    readonly code: string;
+    /** `billing_error` or `rate_limit_error`. */
+    readonly type: string | undefined;
+    /** The class of usage refused: premium, ours or free. */
+    readonly usageClass: string | undefined;
+    /** The model the refusal is about. */
+    readonly model: string | undefined;
+    /** The model that answers instead, where there is one. */
+    readonly fallback: string | undefined;
+    /** When the refusal lifts by itself. */
+    readonly resetsAt: Date | undefined;
+    /** The upgrade page. */
+    readonly upgradeUrl: string | undefined;
+    readonly actions: UsageAction[];
+    /** `x-request-id` — the handle that finds this call in the audit trail. */
+    readonly request: string | undefined;
+    /** What the transport raised: the AxiosError on the generated client, nothing on the six. */
+    readonly cause: unknown;
+    constructor(status: number, error: Obj, request?: string, cause?: unknown);
+}
+/** 402 `plan_allowance_used` — the plan's included usage of the class is used, and nothing else may pay. */
+export declare class PlanAllowanceUsedError extends UsageLimitError {
+    name: string;
+}
+/** 402 `paid_plan_required` — the model needs a paid plan or prepaid balance. */
+export declare class PaidPlanRequiredError extends UsageLimitError {
+    name: string;
+}
+/** 429 `free_plan_cap` — the free plan's daily cap on the model is used; it lifts at `resetsAt`. */
+export declare class FreePlanCapError extends UsageLimitError {
+    name: string;
+}
+/** 402 `model_cap` — the model has used its share of the plan; `fallback` answers instead. */
+export declare class ModelCapError extends UsageLimitError {
+    name: string;
+}
+/** 429 `usage_cap_exceeded` — a session or day request window is spent. */
+export declare class UsageCapExceededError extends UsageLimitError {
+    name: string;
+}
+/** 402 `insufficient_balance` — the known wallet balance cannot cover the request. */
+export declare class InsufficientBalanceError extends UsageLimitError {
+    name: string;
+}
+/**
+ * The typed error a refusal names, or undefined: only a 402 or 429 whose
+ * `error.code` is one of the six is one. Anything else stays whatever error its
+ * transport already raises.
+ */
+export declare function limited(status: number, body: unknown, request?: string, cause?: unknown): UsageLimitError | undefined;
+/** What the X-Hanzo-* headers on one answer say. Each is undefined where the header is absent. */
+export interface Usage {
+    /** X-Hanzo-Usage: ok | near | limited — where the class stands. */
+    usage: string | undefined;
+    /** X-Hanzo-Usage-Class: premium | ours | free. */
+    usageClass: string | undefined;
+    /** X-Hanzo-Paid-By: plan | credits | free. Prepaid and granted credit both read `credits`. */
+    paidBy: string | undefined;
+    /** X-Hanzo-Fallback: the model that answered instead (limited mode). */
+    fallback: string | undefined;
+    /** X-Hanzo-Served: the Hanzo SKU that answered. */
+    served: string | undefined;
+    /** X-Hanzo-Usage-Reason: the refusal code that caused a fallback. */
+    reason: string | undefined;
+}
+/** A fetch `Headers`, axios's `AxiosHeaders`, or any record of header name to value. */
+export type HeaderSource = {
+    get(name: string): unknown;
+} | Record<string, unknown>;
+/**
+ * Read the usage headers off one answer: `readUsage(res.headers)` for an axios
+ * response or a fetch Response alike. Names match case-insensitively. A header
+ * that is absent, or present and empty, reads undefined — never 0 or "", which
+ * would claim the server said something it did not.
+ */
+export declare function readUsage(headers: HeaderSource | null | undefined): Usage;
+/** One header by lower-case name, matched case-insensitively; undefined where absent or empty. */
+export declare function header(headers: HeaderSource | null | undefined, name: string): string | undefined;

package/dist/usage.js

@@ -0,0 +1,174 @@
+"use strict";
+// usage — how a priced request was paid for, and the refusals when it cannot be.
+//
+// Every AI answer says where the caller's plan stands in six headers, never a
+// figure: X-Hanzo-Usage (ok | near | limited), -Usage-Class (premium | ours |
+// free), -Paid-By (plan | credits | free), -Fallback (the model that answered
+// instead), -Served (the Hanzo SKU that answered) and -Usage-Reason (the refusal
+// code that caused a fallback). `readUsage` reads them off whatever headers the
+// caller holds.
+//
+// A request nothing may pay for is refused in the OpenAI envelope,
+//
+//   {"error": {"message", "type", "code", "class"?, "model"?, "fallback"?,
+//              "resets_at"?, "upgrade_url"?, "actions"?}}
+//
+// and six codes in it are six different facts with six different ways out, so
+// each is a class: a caller tells them apart with `instanceof`, never by parsing
+// the sentence. The names are the Python and Go SDKs' names. Both transports
+// throw them from the error path they already had — an axios response
+// interceptor for the generated client (transport.ts) and the six capabilities'
+// Fault (answer.ts) — through `limited`, the one place a body becomes one.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InsufficientBalanceError = exports.UsageCapExceededError = exports.ModelCapError = exports.FreePlanCapError = exports.PaidPlanRequiredError = exports.PlanAllowanceUsedError = exports.UsageLimitError = void 0;
+exports.limited = limited;
+exports.readUsage = readUsage;
+exports.header = header;
+const read_1 = require("./read");
+/** A string the server sent, or undefined where it sent none — never "". */
+const text = (v) => (typeof v === 'string' && v !== '' ? v : undefined);
+/** An RFC 3339 instant, or undefined where none was sent or it does not parse. */
+const instant = (v) => {
+    const s = text(v);
+    if (!s)
+        return undefined;
+    const d = new Date(s);
+    return Number.isNaN(d.getTime()) ? undefined : d;
+};
+/** A priced request refused because nothing the caller holds may pay for it. */
+class UsageLimitError extends Error {
+    constructor(status, error, request, cause) {
+        const code = text(error['code']) ?? '';
+        super(text(error['message']) ?? `HTTP ${status} ${code}`);
+        // Literal, not `new.target.name`, which a minifier renames.
+        this.name = 'UsageLimitError';
+        this.status = status;
+        this.code = code;
+        this.type = text(error['type']);
+        this.usageClass = text(error['class']);
+        this.model = text(error['model']);
+        this.fallback = text(error['fallback']);
+        this.resetsAt = instant(error['resets_at']);
+        this.upgradeUrl = text(error['upgrade_url']);
+        // An entry with no kind is not an action, so it is not offered.
+        this.actions = (0, read_1.list)(error['actions']).flatMap((a) => {
+            const o = (0, read_1.obj)(a);
+            const kind = text(o['kind']);
+            if (!kind)
+                return [];
+            const out = { kind };
+            for (const k of ['label', 'url', 'plan', 'model']) {
+                const v = text(o[k]);
+                if (v !== undefined)
+                    out[k] = v;
+            }
+            return [out];
+        });
+        this.request = request;
+        this.cause = cause;
+    }
+}
+exports.UsageLimitError = UsageLimitError;
+/** 402 `plan_allowance_used` — the plan's included usage of the class is used, and nothing else may pay. */
+class PlanAllowanceUsedError extends UsageLimitError {
+    constructor() {
+        super(...arguments);
+        this.name = 'PlanAllowanceUsedError';
+    }
+}
+exports.PlanAllowanceUsedError = PlanAllowanceUsedError;
+/** 402 `paid_plan_required` — the model needs a paid plan or prepaid balance. */
+class PaidPlanRequiredError extends UsageLimitError {
+    constructor() {
+        super(...arguments);
+        this.name = 'PaidPlanRequiredError';
+    }
+}
+exports.PaidPlanRequiredError = PaidPlanRequiredError;
+/** 429 `free_plan_cap` — the free plan's daily cap on the model is used; it lifts at `resetsAt`. */
+class FreePlanCapError extends UsageLimitError {
+    constructor() {
+        super(...arguments);
+        this.name = 'FreePlanCapError';
+    }
+}
+exports.FreePlanCapError = FreePlanCapError;
+/** 402 `model_cap` — the model has used its share of the plan; `fallback` answers instead. */
+class ModelCapError extends UsageLimitError {
+    constructor() {
+        super(...arguments);
+        this.name = 'ModelCapError';
+    }
+}
+exports.ModelCapError = ModelCapError;
+/** 429 `usage_cap_exceeded` — a session or day request window is spent. */
+class UsageCapExceededError extends UsageLimitError {
+    constructor() {
+        super(...arguments);
+        this.name = 'UsageCapExceededError';
+    }
+}
+exports.UsageCapExceededError = UsageCapExceededError;
+/** 402 `insufficient_balance` — the known wallet balance cannot cover the request. */
+class InsufficientBalanceError extends UsageLimitError {
+    constructor() {
+        super(...arguments);
+        this.name = 'InsufficientBalanceError';
+    }
+}
+exports.InsufficientBalanceError = InsufficientBalanceError;
+// A Map, not an object literal: a code of "constructor" must find nothing.
+const classes = new Map([
+    ['plan_allowance_used', PlanAllowanceUsedError],
+    ['paid_plan_required', PaidPlanRequiredError],
+    ['free_plan_cap', FreePlanCapError],
+    ['model_cap', ModelCapError],
+    ['usage_cap_exceeded', UsageCapExceededError],
+    ['insufficient_balance', InsufficientBalanceError],
+]);
+/**
+ * The typed error a refusal names, or undefined: only a 402 or 429 whose
+ * `error.code` is one of the six is one. Anything else stays whatever error its
+ * transport already raises.
+ */
+function limited(status, body, request, cause) {
+    if (status !== 402 && status !== 429)
+        return undefined;
+    const error = (0, read_1.obj)((0, read_1.obj)(body)['error']);
+    const Class = classes.get(text(error['code']) ?? '');
+    return Class ? new Class(status, error, request, cause) : undefined;
+}
+/**
+ * Read the usage headers off one answer: `readUsage(res.headers)` for an axios
+ * response or a fetch Response alike. Names match case-insensitively. A header
+ * that is absent, or present and empty, reads undefined — never 0 or "", which
+ * would claim the server said something it did not.
+ */
+function readUsage(headers) {
+    return {
+        usage: header(headers, 'x-hanzo-usage'),
+        usageClass: header(headers, 'x-hanzo-usage-class'),
+        paidBy: header(headers, 'x-hanzo-paid-by'),
+        fallback: header(headers, 'x-hanzo-fallback'),
+        served: header(headers, 'x-hanzo-served'),
+        reason: header(headers, 'x-hanzo-usage-reason'),
+    };
+}
+/** One header by lower-case name, matched case-insensitively; undefined where absent or empty. */
+function header(headers, name) {
+    const h = headers ?? {};
+    let v;
+    if (typeof h.get === 'function') {
+        v = h.get(name);
+    }
+    else {
+        for (const [k, value] of Object.entries(h))
+            if (k.toLowerCase() === name)
+                v = value;
+    }
+    if (Array.isArray(v))
+        v = v[0];
+    if (typeof v === 'number' || typeof v === 'boolean')
+        v = String(v);
+    return typeof v === 'string' ? text(v.trim()) : undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hanzoai",
-  "version": "8.5.621",
+  "version": "8.5.640",
   "description": "The official TypeScript library for the Hanzo API",
   "author": "Hanzo <dev@hanzo.ai>",
   "license": "Apache-2.0",

package/src/answer.ts

@@ -10,6 +10,7 @@
 // read, so there is no arm for them.
 
 import { list, num, obj, str } from './read';
+import { limited } from './usage';
 
 /** One way out of a refusal, in the order to offer them. */
 export interface Cure {
@@ -143,15 +144,17 @@ const refusals = new Set(['spend_cap_exceeded', 'insufficient_balance']);
 function refusal(body: unknown): { code: string; reason: string; product?: string; cures: Cure[] } {
   const b = obj(body);
   // RFC 9457 spells the code `code` and the sentence `detail`; the spend gate's
-  // own body spells them `error` and `message` and adds `product` and `cure[]`.
-  // Its own `reason` — "unpaid", "unresolved" — names the admit leg that failed
-  // rather than explaining anything to a person, so it is not read. One reader,
-  // named fallbacks — not two paths — so it keeps working unchanged when cloud
-  // settles on the envelope alone.
+  // own body spells them `error` and `message` and adds `product` and `cure[]`;
+  // the AI gateway's OpenAI envelope nests `code` and `message` under `error`.
+  // The spend gate's `reason` — "unpaid", "unresolved" — names the admit leg that
+  // failed rather than explaining anything to a person, so it is not read. One
+  // reader, named fallbacks — not three paths — so it keeps working unchanged
+  // when cloud settles on one envelope.
+  const e = obj(b['error']);
   const product = str(b['product']);
   return {
-    code: str(b['code']) || str(b['error']),
-    reason: str(b['detail']) || str(b['message']),
+    code: str(b['code']) || str(b['error']) || str(e['code']),
+    reason: str(b['detail']) || str(b['message']) || str(e['message']),
     ...(product ? { product } : {}),
     cures: list(b['cure']).map((c) => {
       const cure = obj(c);
@@ -193,14 +196,24 @@ export function arm<T>(r: Reply, read: (body: unknown) => T): Answer<T> {
   if (r.status === 402 || (r.status === 403 && refusals.has(said.code))) {
     return { status: 'denied', ...said, request: r.request };
   }
-  throw new Fault(r.status, said.code, said.reason || `HTTP ${r.status}`, r.request);
+  throw fault(r, said);
 }
 
 /** A read no gate refuses: the value, or a [Fault] because nothing was decided. */
 export function value<T>(r: Reply, read: (body: unknown) => T): T {
   if (r.status >= 200 && r.status < 300) return read(r.body);
-  const said = refusal(r.body);
-  throw new Fault(r.status, said.code, said.reason || `HTTP ${r.status}`, r.request);
+  throw fault(r, refusal(r.body));
+}
+
+/**
+ * What a call that decided nothing throws: the usage refusal the body names
+ * (usage.ts), or a [Fault]. What [arm] reads as [Denied] never reaches here.
+ */
+function fault(r: Reply, said: { code: string; reason: string }): Error {
+  return (
+    limited(r.status, r.body, r.request || undefined) ??
+    new Fault(r.status, said.code, said.reason || `HTTP ${r.status}`, r.request)
+  );
 }
 
 /** `{data, total}` — the page shape every listing on this wire answers with. */