fix: extract Google Gemini token usage and price cached tokens correctly

[MukundaKatta]

Summary

The README, TypeScript types, and CHANGELOG all advertised that defaultExtractUsage (and therefore measureLLM) supported Google Gemini responses, but the extractor only ever inspected a usage key. The Gemini SDK (@google/genai) returns token usage under usageMetadata (promptTokenCount / candidatesTokenCount / cachedContentTokenCount), so a real Gemini response returned null and its tokens were silently recorded as zero cost — exactly the under-reporting this library exists to prevent.

Changes

• Bug fix — Gemini usage extraction. defaultExtractUsage now recognizes the Gemini usageMetadata shape (including when nested under a response property) alongside the existing Anthropic / OpenAI usage shapes.
• Hardening. When a usage/usageMetadata object is present but contains no recognized token fields, the extractor returns null instead of a misleading all-zero record.
• Pricing accuracy. Added cacheRead rates to the Gemini 2.5/2.0 PRICING entries so cached-context tokens are priced at the (much lower) cached rate rather than falling back to the full input rate.
• Flaky-test fix. The measure tracks latency test asserted elapsed >= 5 against a separately-sampled wall clock; Node timers can fire a hair early relative to performance.now(), so it failed intermittently. It now asserts on the library's own recorded step.latencyMs.
• Tests. Added coverage for the Gemini shape, response-nested usage, and the no-known-fields guard. Test count 26 → 29.
• Docs. README API section, src/index.d.ts doc comment, CHANGELOG, and a runnable Gemini call in examples/demo.js.

Validation

• npm run lint — clean (syntax check of src + tests).
• npm test — 29/29 passing, run 5 times consecutively with no flakes.
• npm run test:examples — runs; the new rerank [gemini-2.5-flash] step is now priced ($0.000285) instead of $0.
• Cost-under-report CI smoke check (pinned claude-sonnet-4) still passes.
• Note: the coverage job uses c8 v11, which is incompatible with the very latest local Node (v26); it fails identically on unmodified main and works on CI's Node 22. Not affected by this change.

🤖 Generated with Claude Code