@rouvanpm/rouva 0.5.0 → 0.5.2

package/README.md

@@ -24,7 +24,7 @@ console.log(response.choices[0].message.content)
 
 ## Provider agnostic
 
-Rouva works with all connected providers — Anthropic, OpenAI, Gemini, DeepSeek, Mistral, Moonshot, xAI, Z.ai and Alibaba Qwen. You can request a specific model, force a specific provider, or omit both and let Rouva route to the cheapest capable model automatically.
+Rouva works with all connected providers — Anthropic, OpenAI, Gemini, DeepSeek, Mistral, Moonshot, xAI, Z.ai, Alibaba Qwen and MiniMax. You can request a specific model, force a specific provider, or omit both and let Rouva route to the cheapest capable model automatically.
 
 ```typescript
 // Request a specific model
@@ -98,14 +98,15 @@ const res = await rouva.chat.completions.create({
 })
 ```
 
-- **`temperature`** — sampling temperature between 0 and 1. The gateway omits it for models that only accept their default: OpenAI reasoning models (gpt-5 / gpt-6 families) and the Claude models that reject it (Opus 4.7 and newer, Sonnet 5 and newer, Fable).
+- **`temperature`** — sampling temperature between 0 and 1. The gateway omits it for models that only accept their default: OpenAI reasoning models (gpt-5 / gpt-6 families) and the Claude models that reject it (Opus 4.7 and newer, Sonnet 5 and newer, Haiku 5.5, Fable), and models whose sampling is fixed (Kimi K3 / K3.1 Pro, MiniMax).
 - **`max_tokens`** / **`max_completion_tokens`** — either name works. Values below 1024 also steer auto-routing away from reasoning models, which would otherwise spend the whole budget on hidden reasoning tokens.
 - **`top_p`** — nucleus sampling; `top_p: 1` is treated as omitted. OpenAI reasoning models don't support it: routing avoids them when it's set, and pinning one returns a 400. The gateway omits it for the Claude models that reject it (as for `temperature`).
 - **`stop`** — a string or up to 4 stop sequences (Anthropic receives them as `stop_sequences`). OpenAI and xAI reasoning models (e.g. gpt-5, grok-4.5 / 4.6 / 4.7) reject it: routing avoids them when it's set, and pinning one returns a 400.
 - **`metadata`** — up to 10 string key-value pairs (keys up to 64 characters, values up to 256, no null bytes) stored with the request's usage record; not sent to the provider.
+- **`service_tier`** — `'default'` (or Anthropic's `'standard_only'`) asks the provider for its standard tier; `'auto'`, the same as leaving it out, uses your provider account's own setting. Rouva bills standard prices, so other tiers (`flex`, `priority`, `scale`) are a 400.
 - **`seed`** — best-effort deterministic sampling. Only OpenAI honors it, so it requires an OpenAI `model` and pins the request to that exact model (no routing, no fallbacks).
 - **`response_format`** — JSON mode or a JSON schema; see [Structured output](#structured-output).
-- **`reasoning_effort`** — `'none'` … `'xhigh'`, or `'max'` for Claude. Which values a model takes depends on the model; routing only picks one that takes yours; a listed OpenAI or Claude model you name that doesn't gets a 400, and other providers' models get the value as sent. On gpt-6-luna / gpt-6-sol, `'none'` turns reasoning off. See [the docs](https://rouva.io/docs#reasoning-effort).
+- **`reasoning_effort`** — `'none'` … `'xhigh'`, or `'max'` for Claude. Which values a model takes depends on the model; routing only picks one that takes yours; a listed OpenAI or Claude model you name that doesn't gets a 400, and other providers' models get the value as sent. On gpt-6-luna / gpt-6-sol / gpt-6.1-terra, `'none'` turns reasoning off. See [the docs](https://rouva.io/docs#reasoning-effort).
 - **`parallel_tool_calls`** — with `tools`: `false` allows at most one tool call per turn (Claude included).
 
 Unsupported OpenAI options (`logit_bias`, `logprobs`, `n > 1`, the legacy `functions`/`function_call` fields, …) are rejected by the gateway with an explicit 400 rather than silently ignored.
@@ -130,7 +131,7 @@ Non-tools requests on `/v1` honor the named model exactly unless the workspace o
 
 ## Tool use
 
-Tools are forwarded to your target provider verbatim — define them in the **provider's own format** (OpenAI `{ type: "function", function: {...} }` or Anthropic `{ name, description, input_schema }`) and pin the matching `model`. Tool schemas are provider-specific, so `model` is required and the gateway returns a 400 without it. `gpt-6.1-sol` and `gpt-5.6-*` take tools only through OpenAI's Responses API: the gateway uses it for you and converts both ways, so you still send and receive Chat Completions (`seed`, `stop` and a `max_tokens` below 16 are a 400 there). `rouva.run()` still refuses these models.
+Tools are forwarded to your target provider verbatim — define them in the **provider's own format** (OpenAI `{ type: "function", function: {...} }` or Anthropic `{ name, description, input_schema }`) and pin the matching `model`. Tool schemas are provider-specific, so `model` is required and the gateway returns a 400 without it. `gpt-6.1-sol`, `gpt-6-astra` and `gpt-5.6-*` take tools only through OpenAI's Responses API: the gateway uses it for you and converts both ways, so you still send and receive Chat Completions (`seed`, `stop` and a `max_tokens` below 16 are a 400 there). `rouva.run()` still refuses these models.
 
 A tools request only ever moves to another model of the **same provider**: an account routing override for the task (when it targets the same provider), or — on the `/v1` endpoint with Intelligent Routing enabled — the cheapest capable model within that provider, using the named `model` as a cost ceiling (see [OpenAI-compatible endpoint](#openai-compatible-endpoint)). Otherwise the named model is honored exactly.
 
@@ -258,6 +259,8 @@ Every turn is logged as a usage snapshot in the Rouva dashboard under the shared
 | `max_tokens` | `number` | | Max tokens per turn (default: 4096) |
 | `temperature` | `number` | | Sampling temperature 0–1 |
 | `session_budget_usd` | `number` | | Hard USD cap across all turns |
+| `metadata` | `Record<string, string>` | | Your labels (e.g. `customer_id`), stored with every turn's usage record |
+| `service_tier` | `ServiceTier` | | `'default'` / `'standard_only'` for the standard tier, or `'auto'` |
 
 ### Result shape
 
@@ -407,7 +410,7 @@ try {
   await rouva.chat.completions.create({ messages })
 } catch (e) {
   if (e instanceof RouvaError && e.status === 429) {
-    console.log(e.refusal)     // 'key_cap' | 'member_cap' | 'rate' | … — Rouva refused before calling the provider
+    console.log(e.refusal)     // 'key_cap' | 'plan_limit' | 'rate' | … — Rouva refused before calling the provider
     console.log(e.retryAfter)  // seconds, from Retry-After
     console.log(e.error)       // the gateway's message
     console.log(e.requestId)   // when the request was recorded — rouva.requests.get(e.requestId)
@@ -415,7 +418,7 @@ try {
 }
 ```
 
-`refusal` (header `X-Rouva-Refusal`) names why Rouva itself refused the request before contacting the provider, when the gateway marks it: a monthly spend cap would be exceeded (`key_cap`, `member_cap`), the rate limit (`rate`), for spend-capped keys a model with no known price (`unpriced`) or input or a model whose cost can't be bounded (`unbounded`), or — a `504` — the request ran out of its time budget before the provider was called (`deadline`; nothing was sent, so it's safe to retry, and `retryAfter` is set). Every Rouva refusal is marked, so a `429` or `504` without `refusal` came from the provider, not from Rouva — with one exception: `rouva.run()` returns an unmarked `504` "Run deadline exceeded before completion" when the run runs out of time, because earlier turns were already billed and their tool handlers ran; check what completed before retrying it. Every call also takes `{ signal }` as a second argument to abort it.
+`refusal` (header `X-Rouva-Refusal`) names why Rouva itself refused the request before contacting the provider, when the gateway marks it: a monthly spend cap would be exceeded (`key_cap`, `member_cap`, or `customer_cap` for a `metadata.customer_id` customer), the account is on the Free plan and has used its requests for the month (`plan_limit`, a `429`; `retryAfter` runs to the 1st of next month, UTC, or upgrade the plan), the rate limit (`rate`), for spend-capped keys a model with no known price (`unpriced`) or input or a model whose cost can't be bounded (`unbounded`), or — a `504` — the request ran out of its time budget before the provider was called (`deadline`; nothing was sent, so it's safe to retry, and `retryAfter` is set). Every Rouva refusal is marked, so a `429` or `504` without `refusal` came from the provider, not from Rouva — with one exception: `rouva.run()` returns an unmarked `504` "Run deadline exceeded before completion" when the run runs out of time, because earlier turns were already billed and their tool handlers ran; check what completed before retrying it. Every call also takes `{ signal }` as a second argument to abort it.
 
 ## Getting your API key
 

package/dist/index.d.mts

@@ -50,9 +50,17 @@ interface ContentBlockMessage {
  * valid when `tools` is set on the request.
  */
 type ChatMessage = Message | AssistantToolCallMessage | ToolResultMessage | ContentBlockMessage;
-type RouvaProvider = 'anthropic' | 'openai' | 'gemini' | 'deepseek' | 'mistral' | 'moonshot' | 'xai' | 'zai' | 'alibaba' | (string & {});
+/** `service_tier` values the gateway serves (see `ChatCompletionParams.service_tier`). */
+type ServiceTier = 'auto' | 'default' | 'standard_only';
 /**
- * Supported models across all providers (the gateway's list as of SDK 0.3.0).
+ * Why Rouva itself refused a request (`RouvaError.refusal`, header
+ * `X-Rouva-Refusal`). See `RouvaError.refusal` for each kind. Other strings
+ * are allowed so a newer gateway's kinds still type-check.
+ */
+type RouvaRefusal = 'key_cap' | 'member_cap' | 'customer_cap' | 'plan_limit' | 'rate' | 'unpriced' | 'unbounded' | 'deadline' | (string & {});
+type RouvaProvider = 'anthropic' | 'openai' | 'gemini' | 'deepseek' | 'mistral' | 'moonshot' | 'xai' | 'zai' | 'alibaba' | 'minimax' | (string & {});
+/**
+ * Supported models across all providers (the gateway's list as of SDK 0.5.2).
  * Omit `model` entirely to let Rouva route to the cheapest capable model automatically.
  *
  * Other IDs are accepted by the type for forward compatibility. On
@@ -64,7 +72,7 @@ type RouvaProvider = 'anthropic' | 'openai' | 'gemini' | 'deepseek' | 'mistral'
  *
  * `'gpt-5.6'` is a deprecated alias the gateway maps to `'gpt-5.6-sol'`.
  */
-type RouvaModel = 'claude-fable-5-1' | 'claude-fable-5' | 'claude-opus-5-5' | 'claude-opus-5' | 'claude-opus-4-8' | 'claude-opus-4-7' | 'claude-opus-4-6' | 'claude-sonnet-5-5' | 'claude-sonnet-5' | 'claude-sonnet-4-6' | 'claude-haiku-4-5-20251001' | 'gpt-6.1-sol' | 'gpt-6-sol' | 'gpt-6-luna' | 'gpt-5.6-sol' | 'gpt-5.6-terra' | 'gpt-5.6-luna' | 'gpt-5.6' | 'gpt-5' | 'gpt-5.4-mini' | 'gpt-5-mini' | 'gpt-5-nano' | 'gpt-4.1' | 'gpt-4.1-mini' | 'gpt-4o' | 'gpt-4o-mini' | 'gemini-3.8-flash' | 'gemini-3.7-flash' | 'gemini-3.6-flash' | 'gemini-3.5-flash-lite' | 'gemini-2.5-pro' | 'gemini-2.5-flash' | 'deepseek-flash' | 'deepseek-flash-think' | 'deepseek-v4-pro' | 'mistral-large-latest' | 'mistral-small-latest' | 'kimi-k3' | 'kimi-k2.6' | 'grok-4.7' | 'grok-4.6' | 'grok-4.5' | 'grok-4.3' | 'grok-4.20-0309-reasoning' | 'glm-5.3' | 'glm-5.2' | 'glm-4.7-flash' | 'qwen3.8-omni-flash' | 'qwen3.8-flash' | 'qwen3.7-plus' | 'qwen-max' | 'qwen-plus' | 'qwen-flash' | (string & {});
+type RouvaModel = 'claude-fable-5-1' | 'claude-fable-5' | 'claude-opus-5-5' | 'claude-opus-5' | 'claude-opus-4-8' | 'claude-opus-4-7' | 'claude-opus-4-6' | 'claude-sonnet-5-5' | 'claude-sonnet-5' | 'claude-sonnet-4-6' | 'claude-haiku-5-5' | 'claude-haiku-4-5-20251001' | 'gpt-6-astra' | 'gpt-6.1-sol' | 'gpt-6.1-terra' | 'gpt-6-sol' | 'gpt-6-luna' | 'gpt-5.6-sol' | 'gpt-5.6-terra' | 'gpt-5.6-luna' | 'gpt-5.6' | 'gpt-5' | 'gpt-5.4-mini' | 'gpt-5-mini' | 'gpt-5-nano' | 'gpt-4.1' | 'gpt-4.1-mini' | 'gpt-4o' | 'gpt-4o-mini' | 'gemini-4-argon' | 'gemini-3.8-flash' | 'gemini-3.7-flash' | 'gemini-3.6-flash' | 'gemini-3.5-flash-lite' | 'gemini-2.5-pro' | 'gemini-2.5-flash' | 'deepseek-flash' | 'deepseek-flash-think' | 'deepseek-v4-pro' | 'mistral-large-4' | 'mistral-large-latest' | 'mistral-small-latest' | 'kimi-k3.1-pro' | 'kimi-k3' | 'kimi-k2.6' | 'grok-4.7' | 'grok-4.6' | 'grok-4.5' | 'grok-4.3' | 'grok-4.20-0309-reasoning' | 'glm-5.3' | 'glm-5.2' | 'glm-4.7-flash' | 'qwen3.8-omni-flash' | 'qwen3.8-flash' | 'qwen3.7-plus' | 'qwen-max' | 'qwen-plus' | 'qwen-flash' | 'MiniMax-M3.1-Flash' | 'MiniMax-M3' | (string & {});
 /** Anthropic-style text block — the array form of the `system` param */
 interface SystemTextBlock {
     type: 'text';
@@ -104,11 +112,21 @@ interface ChatCompletionParams {
      * characters, values up to 256 characters, no null bytes.
      */
     metadata?: Record<string, string>;
+    /**
+     * Which provider service tier to use. Rouva bills standard prices, so only
+     * the standard tier is served: `'default'` (OpenAI's name) or
+     * `'standard_only'` (Anthropic's) asks for it — sent in the dialect of
+     * whichever provider the request reaches; `'auto'` (the same as leaving it
+     * out) uses your provider account's own setting. Any other tier (`flex`,
+     * `priority`, `scale`, …) is a 400.
+     */
+    service_tier?: ServiceTier;
     /**
      * Sampling temperature 0–1.
      * The gateway omits it for models that only accept their default: OpenAI
      * reasoning models (gpt-5 / gpt-6 families) and the Claude models that reject
-     * it (Opus 4.7 and newer, Sonnet 5 and newer, Fable).
+     * it (Opus 4.7 and newer, Sonnet 5 and newer, Haiku 5.5, Fable), and for
+     * models whose sampling is fixed (Kimi K3 / K3.1 Pro, MiniMax).
      */
     temperature?: number;
     /**
@@ -116,7 +134,8 @@ interface ChatCompletionParams {
      * default) is treated as omitted. OpenAI reasoning models (gpt-5 / gpt-6
      * families, o-series) don't support it: routing avoids them when top_p is
      * set, and pinning one returns a 400. The gateway omits it for the Claude
-     * models that reject it (Opus 4.7 and newer, Sonnet 5 and newer, Fable).
+     * models that reject it (Opus 4.7 and newer, Sonnet 5 and newer, Haiku 5.5, Fable),
+     * and for models whose sampling is fixed (Kimi K3 / K3.1 Pro, MiniMax).
      */
     top_p?: number;
     /**
@@ -147,11 +166,11 @@ interface ChatCompletionParams {
      * How hard a reasoning model thinks (gateway support since 2026-10-21).
      * OpenAI models take it as is; Claude gets it as `output_config.effort`.
      * Values depend on the model: gpt-5 / -mini / -nano take minimal–high;
-     * gpt-5.4-mini, gpt-5.6-*, gpt-6-luna / -sol take none–xhigh; gpt-6.1-sol
-     * low–xhigh; Claude Sonnet / Opus 4.6 low, medium, high, max; newer Claude
-     * models also xhigh; GPT-4 models and Claude Haiku 4.5 don't take it. Routing
+     * gpt-5.4-mini, gpt-5.6-*, gpt-6-luna / -sol, gpt-6.1-terra take none–xhigh;
+     * gpt-6.1-sol and gpt-6-astra low–xhigh; Claude Sonnet / Opus 4.6 low, medium,
+     * high, max; newer Claude models (incl. Haiku 5.5) also xhigh; GPT-4 models and Claude Haiku 4.5 don't take it. Routing
      * only picks a model that takes the value; a listed OpenAI or Claude model you
-     * name that doesn't is a 400 (other providers' models get the value as sent). On gpt-6-luna / -sol, `'none'` turns reasoning off (temperature,
+     * name that doesn't is a 400 (other providers' models get the value as sent). On gpt-6-luna / -sol and gpt-6.1-terra, `'none'` turns reasoning off (temperature,
      * top_p and tools then work) and any other value turns it on (top_p is then
      * a 400; tools are served through OpenAI's Responses API). `rouva.run()`
      * doesn't accept it.
@@ -176,7 +195,7 @@ interface ChatCompletionParams {
      * Anthropic `{ name, description, input_schema }`). Requires `model`.
      * Tool schemas are provider-specific, so a tools request only ever moves to
      * another model of the SAME provider (a routing override, or cheaper-model
-     * routing on /v1). gpt-6.1-sol and gpt-5.6-* take tools only through
+     * routing on /v1). gpt-6.1-sol, gpt-6-astra and gpt-5.6-* take tools only through
      * OpenAI's Responses API: the gateway uses it for you and converts both ways
      * (you still send and receive Chat Completions), and there `seed`, `stop` and
      * a `max_tokens` below 16 are a 400. `rouva.run()` still refuses these models.
@@ -442,6 +461,23 @@ interface RunParams {
      * all turns reaches this threshold.
      */
     session_budget_usd?: number;
+    /**
+     * Your own labels for the run, stored with every turn's usage record and
+     * not sent to the provider (e.g. `{ customer_id: 'acme' }` for the
+     * dashboard's Customers page and per-customer spend caps): up to 10 string
+     * key-value pairs, keys up to 64 characters, values up to 256 characters,
+     * no null bytes.
+     */
+    metadata?: Record<string, string>;
+    /**
+     * Which provider service tier to use. Rouva bills standard prices, so only
+     * the standard tier is served: `'default'` (OpenAI's name) or
+     * `'standard_only'` (Anthropic's) asks for it — sent in the dialect of
+     * whichever provider the request reaches; `'auto'` (the same as leaving it
+     * out) uses your provider account's own setting. Any other tier (`flex`,
+     * `priority`, `scale`, …) is a 400.
+     */
+    service_tier?: ServiceTier;
 }
 interface RunResult {
     /** Final model response text after all tool loops complete. */
@@ -585,8 +621,11 @@ declare class RouvaError extends Error {
     /**
      * Why Rouva itself refused the request before contacting the provider, when
      * the gateway marks it (header `X-Rouva-Refusal`): `"key_cap"` /
-     * `"member_cap"` (a monthly spend cap would be exceeded), `"rate"` (rate
-     * limit), `"unpriced"` (a capped key can't use a model with no known price),
+     * `"member_cap"` / `"customer_cap"` (a monthly spend cap — the key's, the
+     * workspace member's, or the `metadata.customer_id` customer's — would be
+     * exceeded), `"plan_limit"` (a 429: the account is on the Free plan and has
+     * used its requests for the month; `retryAfter` runs to the 1st of next
+     * month, UTC — or upgrade the plan), `"rate"` (rate limit), `"unpriced"` (a capped key can't use a model with no known price),
      * `"unbounded"` (a capped key can't send input, or use a model, whose cost
      * can't be bounded), `"deadline"` (a 504: the request ran out of its time
      * budget before the provider was called — nothing was sent, so it's safe to
@@ -596,7 +635,7 @@ declare class RouvaError extends Error {
      * Rouva's but deliberately unmarked: earlier turns were billed and their
      * tool handlers ran, so it must not be retried blindly.
      */
-    readonly refusal?: string;
+    readonly refusal?: RouvaRefusal;
     /** Seconds to wait before retrying, from `Retry-After`, when present. */
     readonly retryAfter?: number;
     /** The gateway's error message (`error` field), when the body is JSON. */
@@ -613,4 +652,4 @@ declare class RouvaError extends Error {
     constructor(kind: 'Gateway' | 'Run' | 'Request' | 'Explain', status: number, headers: Headers, rawBody: string);
 }
 
-export { type AssistantToolCallMessage, type ChatCompletion, type ChatCompletionChoice, type ChatCompletionParams, type ChatCompletionUsage, type ChatMessage, type ContentBlockMessage, type ExplainOptions, type FunctionToolCall, type Message, type ReasoningEffort, type RequestOptions, type ResponseFormat, type ResponseMessage, Rouva, RouvaError, type RouvaExplainResult, type RouvaExplainedRefusal, type RouvaExplanation, type RouvaModel, type RouvaOptions, type RouvaProvider, type RouvaRequest, type RouvaRequestStatus, type RouvaResponseMeta, type RouvaRouteReason, type RouvaStream, type RunParams, type RunResult, type SystemTextBlock, type ToolResultMessage };
+export { type AssistantToolCallMessage, type ChatCompletion, type ChatCompletionChoice, type ChatCompletionParams, type ChatCompletionUsage, type ChatMessage, type ContentBlockMessage, type ExplainOptions, type FunctionToolCall, type Message, type ReasoningEffort, type RequestOptions, type ResponseFormat, type ResponseMessage, Rouva, RouvaError, type RouvaExplainResult, type RouvaExplainedRefusal, type RouvaExplanation, type RouvaModel, type RouvaOptions, type RouvaProvider, type RouvaRefusal, type RouvaRequest, type RouvaRequestStatus, type RouvaResponseMeta, type RouvaRouteReason, type RouvaStream, type RunParams, type RunResult, type ServiceTier, type SystemTextBlock, type ToolResultMessage };

package/dist/index.d.ts

@@ -50,9 +50,17 @@ interface ContentBlockMessage {
  * valid when `tools` is set on the request.
  */
 type ChatMessage = Message | AssistantToolCallMessage | ToolResultMessage | ContentBlockMessage;
-type RouvaProvider = 'anthropic' | 'openai' | 'gemini' | 'deepseek' | 'mistral' | 'moonshot' | 'xai' | 'zai' | 'alibaba' | (string & {});
+/** `service_tier` values the gateway serves (see `ChatCompletionParams.service_tier`). */
+type ServiceTier = 'auto' | 'default' | 'standard_only';
 /**
- * Supported models across all providers (the gateway's list as of SDK 0.3.0).
+ * Why Rouva itself refused a request (`RouvaError.refusal`, header
+ * `X-Rouva-Refusal`). See `RouvaError.refusal` for each kind. Other strings
+ * are allowed so a newer gateway's kinds still type-check.
+ */
+type RouvaRefusal = 'key_cap' | 'member_cap' | 'customer_cap' | 'plan_limit' | 'rate' | 'unpriced' | 'unbounded' | 'deadline' | (string & {});
+type RouvaProvider = 'anthropic' | 'openai' | 'gemini' | 'deepseek' | 'mistral' | 'moonshot' | 'xai' | 'zai' | 'alibaba' | 'minimax' | (string & {});
+/**
+ * Supported models across all providers (the gateway's list as of SDK 0.5.2).
  * Omit `model` entirely to let Rouva route to the cheapest capable model automatically.
  *
  * Other IDs are accepted by the type for forward compatibility. On
@@ -64,7 +72,7 @@ type RouvaProvider = 'anthropic' | 'openai' | 'gemini' | 'deepseek' | 'mistral'
  *
  * `'gpt-5.6'` is a deprecated alias the gateway maps to `'gpt-5.6-sol'`.
  */
-type RouvaModel = 'claude-fable-5-1' | 'claude-fable-5' | 'claude-opus-5-5' | 'claude-opus-5' | 'claude-opus-4-8' | 'claude-opus-4-7' | 'claude-opus-4-6' | 'claude-sonnet-5-5' | 'claude-sonnet-5' | 'claude-sonnet-4-6' | 'claude-haiku-4-5-20251001' | 'gpt-6.1-sol' | 'gpt-6-sol' | 'gpt-6-luna' | 'gpt-5.6-sol' | 'gpt-5.6-terra' | 'gpt-5.6-luna' | 'gpt-5.6' | 'gpt-5' | 'gpt-5.4-mini' | 'gpt-5-mini' | 'gpt-5-nano' | 'gpt-4.1' | 'gpt-4.1-mini' | 'gpt-4o' | 'gpt-4o-mini' | 'gemini-3.8-flash' | 'gemini-3.7-flash' | 'gemini-3.6-flash' | 'gemini-3.5-flash-lite' | 'gemini-2.5-pro' | 'gemini-2.5-flash' | 'deepseek-flash' | 'deepseek-flash-think' | 'deepseek-v4-pro' | 'mistral-large-latest' | 'mistral-small-latest' | 'kimi-k3' | 'kimi-k2.6' | 'grok-4.7' | 'grok-4.6' | 'grok-4.5' | 'grok-4.3' | 'grok-4.20-0309-reasoning' | 'glm-5.3' | 'glm-5.2' | 'glm-4.7-flash' | 'qwen3.8-omni-flash' | 'qwen3.8-flash' | 'qwen3.7-plus' | 'qwen-max' | 'qwen-plus' | 'qwen-flash' | (string & {});
+type RouvaModel = 'claude-fable-5-1' | 'claude-fable-5' | 'claude-opus-5-5' | 'claude-opus-5' | 'claude-opus-4-8' | 'claude-opus-4-7' | 'claude-opus-4-6' | 'claude-sonnet-5-5' | 'claude-sonnet-5' | 'claude-sonnet-4-6' | 'claude-haiku-5-5' | 'claude-haiku-4-5-20251001' | 'gpt-6-astra' | 'gpt-6.1-sol' | 'gpt-6.1-terra' | 'gpt-6-sol' | 'gpt-6-luna' | 'gpt-5.6-sol' | 'gpt-5.6-terra' | 'gpt-5.6-luna' | 'gpt-5.6' | 'gpt-5' | 'gpt-5.4-mini' | 'gpt-5-mini' | 'gpt-5-nano' | 'gpt-4.1' | 'gpt-4.1-mini' | 'gpt-4o' | 'gpt-4o-mini' | 'gemini-4-argon' | 'gemini-3.8-flash' | 'gemini-3.7-flash' | 'gemini-3.6-flash' | 'gemini-3.5-flash-lite' | 'gemini-2.5-pro' | 'gemini-2.5-flash' | 'deepseek-flash' | 'deepseek-flash-think' | 'deepseek-v4-pro' | 'mistral-large-4' | 'mistral-large-latest' | 'mistral-small-latest' | 'kimi-k3.1-pro' | 'kimi-k3' | 'kimi-k2.6' | 'grok-4.7' | 'grok-4.6' | 'grok-4.5' | 'grok-4.3' | 'grok-4.20-0309-reasoning' | 'glm-5.3' | 'glm-5.2' | 'glm-4.7-flash' | 'qwen3.8-omni-flash' | 'qwen3.8-flash' | 'qwen3.7-plus' | 'qwen-max' | 'qwen-plus' | 'qwen-flash' | 'MiniMax-M3.1-Flash' | 'MiniMax-M3' | (string & {});
 /** Anthropic-style text block — the array form of the `system` param */
 interface SystemTextBlock {
     type: 'text';
@@ -104,11 +112,21 @@ interface ChatCompletionParams {
      * characters, values up to 256 characters, no null bytes.
      */
     metadata?: Record<string, string>;
+    /**
+     * Which provider service tier to use. Rouva bills standard prices, so only
+     * the standard tier is served: `'default'` (OpenAI's name) or
+     * `'standard_only'` (Anthropic's) asks for it — sent in the dialect of
+     * whichever provider the request reaches; `'auto'` (the same as leaving it
+     * out) uses your provider account's own setting. Any other tier (`flex`,
+     * `priority`, `scale`, …) is a 400.
+     */
+    service_tier?: ServiceTier;
     /**
      * Sampling temperature 0–1.
      * The gateway omits it for models that only accept their default: OpenAI
      * reasoning models (gpt-5 / gpt-6 families) and the Claude models that reject
-     * it (Opus 4.7 and newer, Sonnet 5 and newer, Fable).
+     * it (Opus 4.7 and newer, Sonnet 5 and newer, Haiku 5.5, Fable), and for
+     * models whose sampling is fixed (Kimi K3 / K3.1 Pro, MiniMax).
      */
     temperature?: number;
     /**
@@ -116,7 +134,8 @@ interface ChatCompletionParams {
      * default) is treated as omitted. OpenAI reasoning models (gpt-5 / gpt-6
      * families, o-series) don't support it: routing avoids them when top_p is
      * set, and pinning one returns a 400. The gateway omits it for the Claude
-     * models that reject it (Opus 4.7 and newer, Sonnet 5 and newer, Fable).
+     * models that reject it (Opus 4.7 and newer, Sonnet 5 and newer, Haiku 5.5, Fable),
+     * and for models whose sampling is fixed (Kimi K3 / K3.1 Pro, MiniMax).
      */
     top_p?: number;
     /**
@@ -147,11 +166,11 @@ interface ChatCompletionParams {
      * How hard a reasoning model thinks (gateway support since 2026-10-21).
      * OpenAI models take it as is; Claude gets it as `output_config.effort`.
      * Values depend on the model: gpt-5 / -mini / -nano take minimal–high;
-     * gpt-5.4-mini, gpt-5.6-*, gpt-6-luna / -sol take none–xhigh; gpt-6.1-sol
-     * low–xhigh; Claude Sonnet / Opus 4.6 low, medium, high, max; newer Claude
-     * models also xhigh; GPT-4 models and Claude Haiku 4.5 don't take it. Routing
+     * gpt-5.4-mini, gpt-5.6-*, gpt-6-luna / -sol, gpt-6.1-terra take none–xhigh;
+     * gpt-6.1-sol and gpt-6-astra low–xhigh; Claude Sonnet / Opus 4.6 low, medium,
+     * high, max; newer Claude models (incl. Haiku 5.5) also xhigh; GPT-4 models and Claude Haiku 4.5 don't take it. Routing
      * only picks a model that takes the value; a listed OpenAI or Claude model you
-     * name that doesn't is a 400 (other providers' models get the value as sent). On gpt-6-luna / -sol, `'none'` turns reasoning off (temperature,
+     * name that doesn't is a 400 (other providers' models get the value as sent). On gpt-6-luna / -sol and gpt-6.1-terra, `'none'` turns reasoning off (temperature,
      * top_p and tools then work) and any other value turns it on (top_p is then
      * a 400; tools are served through OpenAI's Responses API). `rouva.run()`
      * doesn't accept it.
@@ -176,7 +195,7 @@ interface ChatCompletionParams {
      * Anthropic `{ name, description, input_schema }`). Requires `model`.
      * Tool schemas are provider-specific, so a tools request only ever moves to
      * another model of the SAME provider (a routing override, or cheaper-model
-     * routing on /v1). gpt-6.1-sol and gpt-5.6-* take tools only through
+     * routing on /v1). gpt-6.1-sol, gpt-6-astra and gpt-5.6-* take tools only through
      * OpenAI's Responses API: the gateway uses it for you and converts both ways
      * (you still send and receive Chat Completions), and there `seed`, `stop` and
      * a `max_tokens` below 16 are a 400. `rouva.run()` still refuses these models.
@@ -442,6 +461,23 @@ interface RunParams {
      * all turns reaches this threshold.
      */
     session_budget_usd?: number;
+    /**
+     * Your own labels for the run, stored with every turn's usage record and
+     * not sent to the provider (e.g. `{ customer_id: 'acme' }` for the
+     * dashboard's Customers page and per-customer spend caps): up to 10 string
+     * key-value pairs, keys up to 64 characters, values up to 256 characters,
+     * no null bytes.
+     */
+    metadata?: Record<string, string>;
+    /**
+     * Which provider service tier to use. Rouva bills standard prices, so only
+     * the standard tier is served: `'default'` (OpenAI's name) or
+     * `'standard_only'` (Anthropic's) asks for it — sent in the dialect of
+     * whichever provider the request reaches; `'auto'` (the same as leaving it
+     * out) uses your provider account's own setting. Any other tier (`flex`,
+     * `priority`, `scale`, …) is a 400.
+     */
+    service_tier?: ServiceTier;
 }
 interface RunResult {
     /** Final model response text after all tool loops complete. */
@@ -585,8 +621,11 @@ declare class RouvaError extends Error {
     /**
      * Why Rouva itself refused the request before contacting the provider, when
      * the gateway marks it (header `X-Rouva-Refusal`): `"key_cap"` /
-     * `"member_cap"` (a monthly spend cap would be exceeded), `"rate"` (rate
-     * limit), `"unpriced"` (a capped key can't use a model with no known price),
+     * `"member_cap"` / `"customer_cap"` (a monthly spend cap — the key's, the
+     * workspace member's, or the `metadata.customer_id` customer's — would be
+     * exceeded), `"plan_limit"` (a 429: the account is on the Free plan and has
+     * used its requests for the month; `retryAfter` runs to the 1st of next
+     * month, UTC — or upgrade the plan), `"rate"` (rate limit), `"unpriced"` (a capped key can't use a model with no known price),
      * `"unbounded"` (a capped key can't send input, or use a model, whose cost
      * can't be bounded), `"deadline"` (a 504: the request ran out of its time
      * budget before the provider was called — nothing was sent, so it's safe to
@@ -596,7 +635,7 @@ declare class RouvaError extends Error {
      * Rouva's but deliberately unmarked: earlier turns were billed and their
      * tool handlers ran, so it must not be retried blindly.
      */
-    readonly refusal?: string;
+    readonly refusal?: RouvaRefusal;
     /** Seconds to wait before retrying, from `Retry-After`, when present. */
     readonly retryAfter?: number;
     /** The gateway's error message (`error` field), when the body is JSON. */
@@ -613,4 +652,4 @@ declare class RouvaError extends Error {
     constructor(kind: 'Gateway' | 'Run' | 'Request' | 'Explain', status: number, headers: Headers, rawBody: string);
 }
 
-export { type AssistantToolCallMessage, type ChatCompletion, type ChatCompletionChoice, type ChatCompletionParams, type ChatCompletionUsage, type ChatMessage, type ContentBlockMessage, type ExplainOptions, type FunctionToolCall, type Message, type ReasoningEffort, type RequestOptions, type ResponseFormat, type ResponseMessage, Rouva, RouvaError, type RouvaExplainResult, type RouvaExplainedRefusal, type RouvaExplanation, type RouvaModel, type RouvaOptions, type RouvaProvider, type RouvaRequest, type RouvaRequestStatus, type RouvaResponseMeta, type RouvaRouteReason, type RouvaStream, type RunParams, type RunResult, type SystemTextBlock, type ToolResultMessage };
+export { type AssistantToolCallMessage, type ChatCompletion, type ChatCompletionChoice, type ChatCompletionParams, type ChatCompletionUsage, type ChatMessage, type ContentBlockMessage, type ExplainOptions, type FunctionToolCall, type Message, type ReasoningEffort, type RequestOptions, type ResponseFormat, type ResponseMessage, Rouva, RouvaError, type RouvaExplainResult, type RouvaExplainedRefusal, type RouvaExplanation, type RouvaModel, type RouvaOptions, type RouvaProvider, type RouvaRefusal, type RouvaRequest, type RouvaRequestStatus, type RouvaResponseMeta, type RouvaRouteReason, type RouvaStream, type RunParams, type RunResult, type ServiceTier, type SystemTextBlock, type ToolResultMessage };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rouvanpm/rouva",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Official Node.js SDK for Rouva — managed AI gateway with intelligent routing and spend tracking",
   "main": "dist/index.js",
   "module": "dist/index.mjs",