flexinference 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 1.4.0
+
+Surfaces the router's **`doc_url`** on `FlexInferenceError` as a new `docUrl` field: a deep
+link straight to the docs row for that error's `code` (when the router supplied one), so an
+error caught in code can point a developer -- or an agent reading the message -- at the fix.
+Also enriches the local `start_within` validation messages with concrete examples. Additive;
+no breaking changes.
+
+## 1.3.0
+
+Adds a typed **`PaymentRequiredError`** (a subclass of `FlexInferenceError`) thrown on
+HTTP `402`, which the router returns when billing is past due and billable flex is paused
+(free routing still works). Catch it on its own to prompt the user to update payment;
+existing `catch (err instanceof FlexInferenceError)` handlers keep catching 402s because
+it is a subclass. No other API or type changes.
+
 ## 1.2.0
 
 Adds the **Messages** caller format (`client.messages.create`), the fourth format

package/README.md

@@ -1,6 +1,6 @@
 # FlexInference (TypeScript)
 
-The official TypeScript SDK for [FlexInference](https://flexinference.com) - a deadline-aware, OpenAI-compatible inference router. Send the OpenAI requests you already send, bring your own OpenAI key, and set one required field - `start_within` - to trade latency for cost.
+The official TypeScript SDK for [FlexInference](https://flexinference.com) - a deadline-aware inference router across **OpenAI, Google Gemini, and Anthropic**. Send the OpenAI requests you already send, bring your own provider key, and set one required field - `start_within` - to trade latency for cost. Four caller formats are supported: `responses`, `chat.completions`, `interactions` (Gemini shape), and `messages` (Anthropic shape) - any of them reaches any provider.
 
 ```bash
 npm install flexinference
@@ -26,14 +26,15 @@ Responses come back as the **raw OpenAI JSON** (we never reshape the body), so t
 
 `start_within` is **required** on every request. It takes `"default"`, `"priority"`, `"auto"`, or a duration `"HHh-MMm-SSs"` (5s-10m). The duration races OpenAI's flex tier on a flex-capable model and falls back to standard if it can't start in time; `"default"`, `"priority"`, and `"auto"` map to those OpenAI service tiers and proxy any model. It is typed, so a missing value or a value outside the allowed shapes is a **compile-time** error; a duration that fits the shape but is malformed or out of range is caught at **runtime**, the same check plain-JavaScript callers get. See the [docs](https://flexinference.mintlify.app/deadline-routing).
 
-## Providers (OpenAI and Gemini)
+## Providers (OpenAI, Gemini, and Anthropic)
 
-FlexInference routes to **OpenAI** and **Google Gemini**. Send the same OpenAI-shaped request and pass whichever model id you want - `gpt-5.5`, `o4-mini`, `gemini-3.5-flash`, and so on. We run Gemini through its Interactions API and translate it back to the OpenAI shape, so your code is identical for both.
+FlexInference routes to **OpenAI**, **Google Gemini**, and **Anthropic**. Send the same OpenAI-shaped request and pass whichever model id you want - `gpt-5.5`, `o4-mini`, `gemini-3.5-flash`, `claude-opus-4-8`, and so on. We translate Gemini and Anthropic to and from the OpenAI shape, so your code is identical for all three.
 
 - **OpenAI:** `default` (standard tier), `priority`, `auto`, and the flex race (a duration) on flex-capable models.
 - **Gemini:** `default` maps to Gemini's **standard** tier, plus `priority` and the flex race on the Gemini flex models (`gemini-3.5-flash`, `gemini-3.1-flash-lite`, `gemini-3.1-pro-preview`, `gemini-3-flash-preview`, `gemini-2.5-pro`, `gemini-2.5-flash`, `gemini-2.5-flash-lite`). Gemini has no `auto` tier, so `start_within: "auto"` on a Gemini model returns `400`.
+- **Anthropic (Claude):** proxy-only. `default`, `priority`, and `auto` work; there is **no flex race**, so a duration `start_within` on a `claude-*` model returns `400 flex_unsupported_for_anthropic`. Anthropic requires a token cap, so set `max_output_tokens` (`max_completion_tokens` on Chat, `max_tokens` on Messages) or you get `400 missing_max_tokens`. You keep the unified API and tier control, and draw down your own Anthropic credits.
 
-Add the provider key you'll use (OpenAI and/or Gemini) in the [dashboard](https://www.flexinference.com/dashboard). Text, streaming, structured outputs, function calling, image input, and web search work on both providers (send a Responses `web_search` tool; we map it to Gemini's `google_search`).
+Add the provider key you'll use (OpenAI, Gemini, and/or Anthropic) in the [dashboard](https://www.flexinference.com/dashboard). Text, streaming, structured outputs, function calling, image input, and web search work across providers (send a Responses `web_search` tool; we map it to Gemini's `google_search`).
 
 Don't send `service_tier` - the router controls the tier from `start_within` and rejects a caller-supplied `service_tier` with `400 service_tier_not_allowed`.
 
@@ -64,6 +65,39 @@ const res = await client.chat.completions.create({
 });
 ```
 
+## Interactions (Gemini shape)
+
+Speak Google's Interactions shape and reach any model. `interactionText(res)` pulls the assistant text out of the interaction's `steps`.
+
+```ts
+import { interactionText } from "flexinference";
+
+const res = await client.interactions.create({
+  model: "gemini-3.5-flash",
+  input: "Summarize this contract.",
+  start_within: "00h-01m-00s",
+});
+
+console.log(interactionText(res));
+```
+
+## Messages (Anthropic shape)
+
+Speak Anthropic's Messages shape and reach any model. `max_tokens` is required (Anthropic requires it). `messageText(res)` pulls the assistant text out of the message `content`.
+
+```ts
+import { messageText } from "flexinference";
+
+const res = await client.messages.create({
+  model: "claude-opus-4-8",
+  max_tokens: 1024,
+  messages: [{ role: "user", content: "Summarize this contract." }],
+  start_within: "default",
+});
+
+console.log(messageText(res));
+```
+
 ## Timeouts and cancellation
 
 Every client has a built-in timeout: **10 seconds to connect** and **600 seconds (10 min) total**, matching the router's budget, so a request can never hang forever. Override the total with the `timeout` option (raise it for very long streams):
@@ -102,6 +136,31 @@ try {
 }
 ```
 
+## Billing / 402
+
+If your account's billing is past due, the router pauses **billable flex** and returns
+`402 Payment Required` on those requests; free routing keeps working. The SDK throws a
+typed `PaymentRequiredError` (a subclass of `FlexInferenceError`) for HTTP 402, so you
+can catch it on its own and prompt the user to update payment while letting other errors
+propagate:
+
+```ts
+import { PaymentRequiredError } from "flexinference";
+
+try {
+  await client.responses.create({ model: "gpt-5.5", input: "hi", start_within: "00h-00m-30s" });
+} catch (err) {
+  if (err instanceof PaymentRequiredError) {
+    console.log("Billing is past due - update payment in the dashboard to resume flex.");
+  } else {
+    throw err;
+  }
+}
+```
+
+Because `PaymentRequiredError extends FlexInferenceError`, existing
+`catch (err instanceof FlexInferenceError)` handlers keep catching 402s too.
+
 ## Configuration
 
 | Option    | Default                            | Description                                      |

package/dist/index.d.ts

@@ -60,6 +60,7 @@ export interface FlexErrorBody {
         type: string;
         code?: string | null;
         param?: string | null;
+        doc_url?: string | null;
     };
 }
 export declare class FlexInferenceError extends Error {
@@ -67,8 +68,17 @@ export declare class FlexInferenceError extends Error {
     readonly type: string | undefined;
     readonly code: string | null | undefined;
     readonly param: string | null | undefined;
+    /** Deep link into the docs for this error's code, when the router supplied one. */
+    readonly docUrl: string | null | undefined;
     constructor(status: number, body: Partial<FlexErrorBody> | undefined, fallback: string);
 }
+/**
+ * Thrown on HTTP 402: billing is past due, so billable flex is paused. Free routing
+ * still works. A subclass of FlexInferenceError, so existing `catch (err instanceof
+ * FlexInferenceError)` handlers keep working; narrow to this to handle 402 specially.
+ */
+export declare class PaymentRequiredError extends FlexInferenceError {
+}
 export interface ClientOptions {
     apiKey: string;
     /** Base URL of the FlexInference router. Defaults to the hosted endpoint. */

package/dist/index.js

@@ -90,6 +90,8 @@ export class FlexInferenceError extends Error {
     type;
     code;
     param;
+    /** Deep link into the docs for this error's code, when the router supplied one. */
+    docUrl;
     constructor(status, body, fallback) {
         const err = body?.error;
         super(err?.message ?? fallback);
@@ -98,8 +100,16 @@ export class FlexInferenceError extends Error {
         this.type = err?.type;
         this.code = err?.code;
         this.param = err?.param;
+        this.docUrl = err?.doc_url;
     }
 }
+/**
+ * Thrown on HTTP 402: billing is past due, so billable flex is paused. Free routing
+ * still works. A subclass of FlexInferenceError, so existing `catch (err instanceof
+ * FlexInferenceError)` handlers keep working; narrow to this to handle 402 specially.
+ */
+export class PaymentRequiredError extends FlexInferenceError {
+}
 const DEFAULT_BASE_URL = "https://api.flexinference.com/v1";
 const DEFAULT_TIMEOUT_MS = 600_000; // 10 min total budget, matching the router's generosity
 const CONNECT_TIMEOUT_MS = 10_000; // fail fast if the router is unreachable
@@ -117,16 +127,18 @@ function assertStartWithin(body) {
         ? body["start_within"]
         : undefined;
     if (value === undefined) {
-        throw new Error(`FlexInference: \`start_within\` is required. Set it to ${START_WITHIN_VALUES}.`);
+        throw new Error(`FlexInference: \`start_within\` is required on every request. Set it to ${START_WITHIN_VALUES}, ` +
+            `for example "start_within": "default" for standard-tier behavior or "00h-00m-30s" for a 30-second flex race.`);
     }
     if (typeof value !== "string") {
-        throw new Error(`FlexInference: \`start_within\` must be a string (${START_WITHIN_VALUES}).`);
+        throw new Error(`FlexInference: \`start_within\` must be a string (${START_WITHIN_VALUES}), for example "default".`);
     }
     if (value === "default" || value === "priority" || value === "auto")
         return;
     const match = DURATION_RE.exec(value);
     if (match === null) {
-        throw new Error(`FlexInference: \`start_within\` "${value}" is not ${START_WITHIN_VALUES}.`);
+        throw new Error(`FlexInference: \`start_within\` "${value}" is not ${START_WITHIN_VALUES}. ` +
+            `A duration is two digits each for hours, minutes, and seconds, for example "00h-05m-00s" for a 5-minute deadline.`);
     }
     const seconds = Number(match[1]) * SECONDS_PER_HOUR + Number(match[2]) * SECONDS_PER_MINUTE + Number(match[3]);
     if (seconds < MIN_DEADLINE_SECONDS || seconds > MAX_DEADLINE_SECONDS) {
@@ -218,6 +230,9 @@ export class FlexInference {
             finally {
                 cleanup();
             }
+            if (res.status === 402) {
+                throw new PaymentRequiredError(res.status, parsed, `HTTP ${String(res.status)} ${res.statusText}`);
+            }
             throw new FlexInferenceError(res.status, parsed, `HTTP ${String(res.status)} ${res.statusText}`);
         }
         return { res, cleanup };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flexinference",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Official TypeScript SDK for FlexInference - a deadline-aware, OpenAI-compatible inference router.",
   "license": "MIT",
   "author": "Aditya Perswal <adityaperswal@gmail.com>",