@gullabs/google 0.12.0 → 0.13.0

package/dist/index.d.cts

@@ -134,6 +134,8 @@ interface GeminiUsageMetadataShape {
     cachedContentTokenCount?: number;
     thoughtsTokenCount?: number;
     totalTokenCount?: number;
+    /** Provider-echoed actual tier; can differ from the requested tier. */
+    serviceTier?: string;
 }
 /**
  * Structural equivalent of @google/genai's GenerateContentResponse.
@@ -455,10 +457,10 @@ declare const defaultGeminiRegistry: ModelRegistry;
  *
  * Provides `geminiPricingSource` — a factory returning a `PricingSource` port
  * implementation backed by the frozen Gemini pricing snapshot ({@link
- * GEMINI_PRICING}). Walks the rates table (exact-then-longest-prefix match)
- * and delegates the actual arithmetic to `@gullabs/core`'s `computeCost`,
- * supplying this package's rates table + tier-factor map as explicit
- * parameters — core itself carries zero Gemini pricing knowledge.
+ * GEMINI_PRICING}). Uses exact priced model identifiers,
+ * resolves the concrete per-tier rates, and delegates the arithmetic to
+ * `@gullabs/core`'s `computeCost`. Core itself carries zero Gemini pricing
+ * knowledge and applies no tier multiplier.
  *
  * @module
  */
@@ -490,27 +492,28 @@ declare function geminiPricingSource(): PricingSource;
  * All rates are in **micro-USD per million tokens** (µUSD/M).
  * To get the cost for N tokens: `cost_µUSD = N * ratePerM / 1_000_000`.
  *
- * **Service tiers.** Rates below are STANDARD-tier. Google's **Batch** tier is a
- * flat 50% discount on standard, and **Flex** matches Batch pricing. The cost
- * engine applies the {@link TIER_FACTOR} multiplier — this snapshot stores
- * standard rates only.
+ * **Service tiers.** Each model stores concrete `standard`, `flex`, and
+ * `batch` rates transcribed from Google's pricing page. Flex and batch are
+ * not a flat 50% of standard: on several models the cached lane stays at the
+ * standard cached rate (or a published rate that is not half). A tier that
+ * is not one of those three is unpriced (reject-don't-map). `priority` is
+ * intentionally absent — it needs downgrade accounting and is a backlog item.
  *
- * **Long-context tier.** Gemini Pro models charge a premium when the GROSS input
- * token count exceeds 200,000. Selected by `inputTokens` (incl. cached), not by
- * billable input.
+ * **Long-context tier.** Gemini Pro models charge a premium when the GROSS
+ * input token count exceeds 200,000. Selected by `inputTokens` (incl. cached),
+ * not by billable input. Core's selector uses `> 200_000`.
  *
  * **Thinking tokens.** Already inside `outputTokens` (GROSS convention) and
- * billed at the standard output rate — no separate thinking lane.
+ * billed at the output rate — no separate thinking lane.
  *
- * **Modality caveat (v1 = text).** Gemini 2.5 Flash / Flash-Lite charge a higher
- * INPUT rate for audio tokens than for text/image/video. v1 is text-only and uses
- * the text/img/vid input rate. Per-modality input pricing is a deferred seam
- * (see DESIGN.md) — revisit when audio input is supported.
+ * **Modality caveat (v1 = text).** Gemini 2.5 Flash / Flash-Lite / 3.1
+ * Flash-Lite charge a higher INPUT rate for audio tokens
+ * than for text/image/video. v1 is text-only and uses the text/img/vid input
+ * rate. Per-modality input pricing is a deferred seam (see DESIGN.md).
  *
- * Re-verified against https://ai.google.dev/gemini-api/docs/pricing on 2026-08-12.
- * Existing registered-model standard rates were unchanged from the 2026-06-28
- * snapshot. `gemini-3.6-flash` appears on that page but is not a registered
- * model in this package.
+ * Re-verified against https://ai.google.dev/gemini-api/docs/pricing on
+ * 2026-09-25. Standard token rates for already-registered models were
+ * unchanged from the 2026-08-12 snapshot; flex/batch cached rates were not.
  *
  * @module
  */
@@ -522,30 +525,27 @@ declare function geminiPricingSource(): PricingSource;
  * core concept — it lives here (not `@gullabs/core`) alongside the rates it
  * dates.
  */
-declare const pricingVersion: "gemini-2026-08-12";
-/**
- * Service-tier price multipliers. Batch and Flex are a flat 50% of standard
- * (per Google's pricing page: "Batch API — 50% cost reduction"; Flex matches Batch).
- *
- * `serviceTier` is an opaque, provider-defined string end-to-end — this map is
- * the *only* place a tier name is resolved to a multiplier. A tier key not
- * present here is never coerced to `standard`: `computeCost` (`@gullabs/core`)
- * treats that as an unpriced call (reject-don't-map), not a mapping to this
- * table's default. `undefined` (no tier requested) is the one case that
- * legitimately defaults to `standard` — that is documented default behavior,
- * not a guess.
- */
-declare const TIER_FACTOR: Readonly<Record<string, number>>;
+declare const pricingVersion: "gemini-2026-09-25";
+/** Tiers this snapshot prices. Anything else is unpriced. */
+declare const GEMINI_PRICED_TIERS: readonly ["standard", "flex", "batch"];
+type GeminiPricedTier = (typeof GEMINI_PRICED_TIERS)[number];
+/** Concrete per-tier rates for one model. */
+interface GeminiTierRates {
+    standard: ModelRates;
+    flex: ModelRates;
+    batch: ModelRates;
+}
 /**
- * Frozen Gemini pricing snapshot (STANDARD tier; per-1M in µUSD).
+ * Frozen Gemini pricing snapshot (per-1M in µUSD), keyed by model id, then
+ * by priced tier. Every number is transcribed from the pricing page.
  *
- * Keys are model-string prefixes / exact identifiers used in routing. The cost
- * engine matches exact first, then longest-prefix (see `lookupRates` in
- * `cost.ts`).
+ * Keys are exact priced model identifiers. Unlisted variants are unpriced.
  *
- * Source: https://ai.google.dev/gemini-api/docs/pricing (re-verified 2026-08-12).
+ * Source: https://ai.google.dev/gemini-api/docs/pricing (re-verified 2026-09-25).
  */
-declare const GEMINI_PRICING: Readonly<Record<string, ModelRates>>;
+declare const GEMINI_PRICING: Readonly<Record<string, GeminiTierRates>>;
+/** Resolve the concrete {@link ModelRates} `computeCost` should apply. */
+declare function resolveGeminiRates(model: string, tier: string | undefined): ModelRates | undefined;
 
 declare function isGeminiCapacityError(err: LlmError): boolean;
 
@@ -974,4 +974,4 @@ interface GeminiContentToMessagesResult {
  */
 declare function geminiContentToMessages(input: GeminiContentToMessagesInput): GeminiContentToMessagesResult;
 
-export { type CacheKey, FLEX_DEFAULT_TIMEOUT_MS, type FileDeleteOptions, GEMINI_PRICING, type GeminiAdapterOptions, type GeminiCachesClientLike, type GeminiClientLike, type GeminiContentToMessagesInput, type GeminiContentToMessagesResult, type GeminiCountTokensParams, type GeminiCountTokensResponseShape, type GeminiFilesClientLike, type GoogleCacheHandle, GoogleCacheStore, type GoogleCacheStoreOptions, type GoogleFileHandle, GoogleFileStore, type GoogleFileStoreOptions, type GoogleProviderOptions, type GoogleSafetySetting, type GoogleSearchTool, STANDARD_DEFAULT_TIMEOUT_MS, TIER_FACTOR, TRANSPORT_TIMEOUT_BUFFER_MS, buildGoogleClient, defaultGeminiRegistry, geminiAdapter, geminiContentToMessages, geminiModelDescriptors, geminiPricingSource, gemmaModelDescriptors, googleProvider, isGeminiCapacityError, pricingVersion, requireApiKey };
+export { type CacheKey, FLEX_DEFAULT_TIMEOUT_MS, type FileDeleteOptions, GEMINI_PRICED_TIERS, GEMINI_PRICING, type GeminiAdapterOptions, type GeminiCachesClientLike, type GeminiClientLike, type GeminiContentToMessagesInput, type GeminiContentToMessagesResult, type GeminiCountTokensParams, type GeminiCountTokensResponseShape, type GeminiFilesClientLike, type GeminiPricedTier, type GeminiTierRates, type GoogleCacheHandle, GoogleCacheStore, type GoogleCacheStoreOptions, type GoogleFileHandle, GoogleFileStore, type GoogleFileStoreOptions, type GoogleProviderOptions, type GoogleSafetySetting, type GoogleSearchTool, STANDARD_DEFAULT_TIMEOUT_MS, TRANSPORT_TIMEOUT_BUFFER_MS, buildGoogleClient, defaultGeminiRegistry, geminiAdapter, geminiContentToMessages, geminiModelDescriptors, geminiPricingSource, gemmaModelDescriptors, googleProvider, isGeminiCapacityError, pricingVersion, requireApiKey, resolveGeminiRates };

package/dist/index.d.ts

@@ -134,6 +134,8 @@ interface GeminiUsageMetadataShape {
     cachedContentTokenCount?: number;
     thoughtsTokenCount?: number;
     totalTokenCount?: number;
+    /** Provider-echoed actual tier; can differ from the requested tier. */
+    serviceTier?: string;
 }
 /**
  * Structural equivalent of @google/genai's GenerateContentResponse.
@@ -455,10 +457,10 @@ declare const defaultGeminiRegistry: ModelRegistry;
  *
  * Provides `geminiPricingSource` — a factory returning a `PricingSource` port
  * implementation backed by the frozen Gemini pricing snapshot ({@link
- * GEMINI_PRICING}). Walks the rates table (exact-then-longest-prefix match)
- * and delegates the actual arithmetic to `@gullabs/core`'s `computeCost`,
- * supplying this package's rates table + tier-factor map as explicit
- * parameters — core itself carries zero Gemini pricing knowledge.
+ * GEMINI_PRICING}). Uses exact priced model identifiers,
+ * resolves the concrete per-tier rates, and delegates the arithmetic to
+ * `@gullabs/core`'s `computeCost`. Core itself carries zero Gemini pricing
+ * knowledge and applies no tier multiplier.
  *
  * @module
  */
@@ -490,27 +492,28 @@ declare function geminiPricingSource(): PricingSource;
  * All rates are in **micro-USD per million tokens** (µUSD/M).
  * To get the cost for N tokens: `cost_µUSD = N * ratePerM / 1_000_000`.
  *
- * **Service tiers.** Rates below are STANDARD-tier. Google's **Batch** tier is a
- * flat 50% discount on standard, and **Flex** matches Batch pricing. The cost
- * engine applies the {@link TIER_FACTOR} multiplier — this snapshot stores
- * standard rates only.
+ * **Service tiers.** Each model stores concrete `standard`, `flex`, and
+ * `batch` rates transcribed from Google's pricing page. Flex and batch are
+ * not a flat 50% of standard: on several models the cached lane stays at the
+ * standard cached rate (or a published rate that is not half). A tier that
+ * is not one of those three is unpriced (reject-don't-map). `priority` is
+ * intentionally absent — it needs downgrade accounting and is a backlog item.
  *
- * **Long-context tier.** Gemini Pro models charge a premium when the GROSS input
- * token count exceeds 200,000. Selected by `inputTokens` (incl. cached), not by
- * billable input.
+ * **Long-context tier.** Gemini Pro models charge a premium when the GROSS
+ * input token count exceeds 200,000. Selected by `inputTokens` (incl. cached),
+ * not by billable input. Core's selector uses `> 200_000`.
  *
  * **Thinking tokens.** Already inside `outputTokens` (GROSS convention) and
- * billed at the standard output rate — no separate thinking lane.
+ * billed at the output rate — no separate thinking lane.
  *
- * **Modality caveat (v1 = text).** Gemini 2.5 Flash / Flash-Lite charge a higher
- * INPUT rate for audio tokens than for text/image/video. v1 is text-only and uses
- * the text/img/vid input rate. Per-modality input pricing is a deferred seam
- * (see DESIGN.md) — revisit when audio input is supported.
+ * **Modality caveat (v1 = text).** Gemini 2.5 Flash / Flash-Lite / 3.1
+ * Flash-Lite charge a higher INPUT rate for audio tokens
+ * than for text/image/video. v1 is text-only and uses the text/img/vid input
+ * rate. Per-modality input pricing is a deferred seam (see DESIGN.md).
  *
- * Re-verified against https://ai.google.dev/gemini-api/docs/pricing on 2026-08-12.
- * Existing registered-model standard rates were unchanged from the 2026-06-28
- * snapshot. `gemini-3.6-flash` appears on that page but is not a registered
- * model in this package.
+ * Re-verified against https://ai.google.dev/gemini-api/docs/pricing on
+ * 2026-09-25. Standard token rates for already-registered models were
+ * unchanged from the 2026-08-12 snapshot; flex/batch cached rates were not.
  *
  * @module
  */
@@ -522,30 +525,27 @@ declare function geminiPricingSource(): PricingSource;
  * core concept — it lives here (not `@gullabs/core`) alongside the rates it
  * dates.
  */
-declare const pricingVersion: "gemini-2026-08-12";
-/**
- * Service-tier price multipliers. Batch and Flex are a flat 50% of standard
- * (per Google's pricing page: "Batch API — 50% cost reduction"; Flex matches Batch).
- *
- * `serviceTier` is an opaque, provider-defined string end-to-end — this map is
- * the *only* place a tier name is resolved to a multiplier. A tier key not
- * present here is never coerced to `standard`: `computeCost` (`@gullabs/core`)
- * treats that as an unpriced call (reject-don't-map), not a mapping to this
- * table's default. `undefined` (no tier requested) is the one case that
- * legitimately defaults to `standard` — that is documented default behavior,
- * not a guess.
- */
-declare const TIER_FACTOR: Readonly<Record<string, number>>;
+declare const pricingVersion: "gemini-2026-09-25";
+/** Tiers this snapshot prices. Anything else is unpriced. */
+declare const GEMINI_PRICED_TIERS: readonly ["standard", "flex", "batch"];
+type GeminiPricedTier = (typeof GEMINI_PRICED_TIERS)[number];
+/** Concrete per-tier rates for one model. */
+interface GeminiTierRates {
+    standard: ModelRates;
+    flex: ModelRates;
+    batch: ModelRates;
+}
 /**
- * Frozen Gemini pricing snapshot (STANDARD tier; per-1M in µUSD).
+ * Frozen Gemini pricing snapshot (per-1M in µUSD), keyed by model id, then
+ * by priced tier. Every number is transcribed from the pricing page.
  *
- * Keys are model-string prefixes / exact identifiers used in routing. The cost
- * engine matches exact first, then longest-prefix (see `lookupRates` in
- * `cost.ts`).
+ * Keys are exact priced model identifiers. Unlisted variants are unpriced.
  *
- * Source: https://ai.google.dev/gemini-api/docs/pricing (re-verified 2026-08-12).
+ * Source: https://ai.google.dev/gemini-api/docs/pricing (re-verified 2026-09-25).
  */
-declare const GEMINI_PRICING: Readonly<Record<string, ModelRates>>;
+declare const GEMINI_PRICING: Readonly<Record<string, GeminiTierRates>>;
+/** Resolve the concrete {@link ModelRates} `computeCost` should apply. */
+declare function resolveGeminiRates(model: string, tier: string | undefined): ModelRates | undefined;
 
 declare function isGeminiCapacityError(err: LlmError): boolean;
 
@@ -974,4 +974,4 @@ interface GeminiContentToMessagesResult {
  */
 declare function geminiContentToMessages(input: GeminiContentToMessagesInput): GeminiContentToMessagesResult;
 
-export { type CacheKey, FLEX_DEFAULT_TIMEOUT_MS, type FileDeleteOptions, GEMINI_PRICING, type GeminiAdapterOptions, type GeminiCachesClientLike, type GeminiClientLike, type GeminiContentToMessagesInput, type GeminiContentToMessagesResult, type GeminiCountTokensParams, type GeminiCountTokensResponseShape, type GeminiFilesClientLike, type GoogleCacheHandle, GoogleCacheStore, type GoogleCacheStoreOptions, type GoogleFileHandle, GoogleFileStore, type GoogleFileStoreOptions, type GoogleProviderOptions, type GoogleSafetySetting, type GoogleSearchTool, STANDARD_DEFAULT_TIMEOUT_MS, TIER_FACTOR, TRANSPORT_TIMEOUT_BUFFER_MS, buildGoogleClient, defaultGeminiRegistry, geminiAdapter, geminiContentToMessages, geminiModelDescriptors, geminiPricingSource, gemmaModelDescriptors, googleProvider, isGeminiCapacityError, pricingVersion, requireApiKey };
+export { type CacheKey, FLEX_DEFAULT_TIMEOUT_MS, type FileDeleteOptions, GEMINI_PRICED_TIERS, GEMINI_PRICING, type GeminiAdapterOptions, type GeminiCachesClientLike, type GeminiClientLike, type GeminiContentToMessagesInput, type GeminiContentToMessagesResult, type GeminiCountTokensParams, type GeminiCountTokensResponseShape, type GeminiFilesClientLike, type GeminiPricedTier, type GeminiTierRates, type GoogleCacheHandle, GoogleCacheStore, type GoogleCacheStoreOptions, type GoogleFileHandle, GoogleFileStore, type GoogleFileStoreOptions, type GoogleProviderOptions, type GoogleSafetySetting, type GoogleSearchTool, STANDARD_DEFAULT_TIMEOUT_MS, TRANSPORT_TIMEOUT_BUFFER_MS, buildGoogleClient, defaultGeminiRegistry, geminiAdapter, geminiContentToMessages, geminiModelDescriptors, geminiPricingSource, gemmaModelDescriptors, googleProvider, isGeminiCapacityError, pricingVersion, requireApiKey, resolveGeminiRates };