flexinference 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 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

@@ -69,6 +69,13 @@ export declare class FlexInferenceError extends Error {
     readonly param: 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

@@ -100,6 +100,13 @@ export class FlexInferenceError extends Error {
         this.param = err?.param;
     }
 }
+/**
+ * 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
@@ -218,6 +225,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.3.0",
   "description": "Official TypeScript SDK for FlexInference - a deadline-aware, OpenAI-compatible inference router.",
   "license": "MIT",
   "author": "Aditya Perswal <adityaperswal@gmail.com>",