[NET-1367] feat: Add support for capturing cache-write tokens in OpenAI

CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+- **Opt-in prompt caching** — `Netra.prompts.getPrompt()` accepts `useCache` and `cacheTtl`. When `useCache` is true, responses are served from an in-memory TTL cache (default TTL: `PROMPT_CACHE_TTL_SECONDS` = 60). Caching is off by default.
+- **Models API** — `Netra.models.getModelPricing()` fetches model pricing (optional `name` filter) with the same opt-in cache pattern (`useCache`, `cacheTtl`; default TTL: `MODEL_PRICING_CACHE_TTL_SECONDS` = 300).
+- **Cache lifecycle** — `Netra.shutdown()` clears prompts and models in-memory caches. `clearCache()` is also available on each client.
+- **Exported cache constants** — `PROMPT_CACHE_TTL_SECONDS` and `MODEL_PRICING_CACHE_TTL_SECONDS` are public exports.
+
+### Changed
+
+- **Prompt cache TTL** — Default TTL is the module constant `PROMPT_CACHE_TTL_SECONDS` (60). Override per call with `cacheTtl`. Removed unused `cacheTtlSeconds` init config and `NETRA_CACHE_TTL_SECONDS` env var.
+
 ## [1.5.0] - 2026-07-10
 
 ### Added
@@ -55,6 +68,56 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **CommonJS (CJS) Support for LLM Provider Instrumentations**: Fixed instrumentation for Anthropic, Google GenAI, Groq, and Mistral AI so they patch correctly under CommonJS module resolution, resolving instrumentation failures in CJS applications.
 
+## [1.5.0] - 2026-07-10
+
+### Added
+
+- **Google GenAI Instrumentation**: Added instrumentation support for the Google GenAI (`@google/genai`) SDK, with a shared `base-instrumentor` abstraction and a separate `google-generative-ai` module.
+
+### Fixed
+
+- **OpenAI Agents Cache Tokens**: Captured cache token details (`cached_tokens`, `cache_write_tokens`, `reasoning_tokens`) for Claude models in OpenAI Agents instrumentation.
+- **Raw Chat Completions Response**: Added a helper to handle usage from the Chat Completions API naming (`prompt_tokens`/`completion_tokens` and their token details) alongside the Responses API naming, so `OpenAIChatCompletionsModel` usage is captured correctly.
+- **Span Input/Output on Active and Root Spans**: Updated utility functions so input and output attributes are set correctly on both the active span and the root span.
+
+## [1.4.0] - 2026-07-02
+
+### Added
+
+- **Anthropic Tool Runner Support**: Added span capture for the Anthropic tool-runner flow, so tool-execution turns within an agentic Anthropic run are traced.
+- **Attribute Size Limit Processor**: New `AttributeSizeLimitProcessor` enforces a hard per-attribute size cap (default 32KB, configurable via `NETRA_SPAN_ATTRIBUTE_MAX_SIZE`) by wrapping `setAttribute` on span start, preventing "entity too large" errors during export.
+- **Resource Attributes Propagation**: `Config` now sets `OTEL_RESOURCE_ATTRIBUTES` so the `TracerProvider` resource carries `service.name` and `deployment.environment`, with precedence order: pre-existing env value > config `resourceAttributes` > Netra defaults.
+
+### Changed
+
+- **SDK Version Source**: `Config.LIBRARY_VERSION` now derives from `SDK_VERSION` in `src/version.ts` instead of a hardcoded string, keeping the reported library version in sync with the package version.
+
+## [1.3.0] - 2026-07-01
+
+### Added
+
+- **NativeTracingMode**: Replaced the boolean `disableNativeTracing` option with a `NativeTracingMode` (`"both" | "netra" | "netra-strict"`) for granular control over where OpenAI Agents traces are sent. Configurable per-instrument or via the `NATIVE_TRACING_MODE` environment variable. `"netra"` routes traces to Netra only (falling back to additive mode with a warning if SDK APIs are unavailable), `"netra-strict"` (default) never falls back to native, and `"both"` sends to Netra and native.
+
+### Fixed
+
+- **Netra-only OpenAI Agents Tracing**: Added `canSet` gating and a restore fallback so the OpenAI Agents processor can be swapped safely, and included `OPENAI_AGENTS` in the root-span instrument allowlist (`DEFAULT_INSTRUMENTS_FOR_ROOT`) so agent runs are captured as root spans.
+
+## [1.2.0] - 2026-06-23
+
+### Added
+
+- **Simulation File Handling**: The simulation workflow now supports file attachments on user messages. The SDK parses `attachments` metadata from the API (`FileData`), downloads the referenced content via pre-signed URLs, and delivers it to user tasks as base64-encoded `ProcessedFile` objects. `ProcessedFile` is now exported from the package root.
+
+## [1.1.0] - 2026-06-16
+
+### Added
+
+- **Context Propagation Helpers**: Exported `netraExpressMiddleware` and `runWithExtractedContext` for distributed tracing. These utilities extract incoming W3C Trace Context from HTTP headers and run code within that context, covering cases where auto-instrumentation is unavailable (ESM load-order issues, missing peer dependencies, or non-Express frameworks).
+
+### Fixed
+
+- **CommonJS (CJS) Support for LLM Provider Instrumentations**: Fixed instrumentation for Anthropic, Google GenAI, Groq, and Mistral AI so they patch correctly under CommonJS module resolution, resolving instrumentation failures in CJS applications.
+
 ## [1.1.0-beta.1] - 2026-06-09
 
 ### Fixed

README.md

@@ -10,6 +10,7 @@
 - 🔧 **Multi-Provider Support**: Works with OpenAI, Google GenAI, Mistral, Anthropic, and more
 - 📈 **Session Management**: Track user sessions and custom attributes
 - 🌐 **Automatic Instrumentation**: Zero-code instrumentation for popular frameworks and libraries
+- ⚡ **Opt-in Read Caching**: In-memory TTL caching for read-heavy SDK calls (`getPrompt`, `getModelPricing`)
 
 ## 📦 Installation
 
@@ -184,6 +185,73 @@ async function generateContent(prompt: string) {
 }
 ```
 
+## 📝 Prompts API
+
+Fetch prompt versions from Prompt Studio via `Netra.prompts.getPrompt()`. Caching is **opt-in per call** — omit `useCache` (or set it to `false`) to always hit the API.
+
+Default TTL is **60 seconds** (`PROMPT_CACHE_TTL_SECONDS`). Override TTL for a single call with `cacheTtl`.
+
+```typescript
+import { Netra } from "netra-sdk";
+
+await Netra.init({
+  appName: "my-ai-app",
+});
+
+// Always fetches from the API (default)
+const prompt = await Netra.prompts.getPrompt({ name: "my-prompt" });
+
+// Cached for 60s (default TTL)
+const cached = await Netra.prompts.getPrompt({
+  name: "my-prompt",
+  useCache: true,
+});
+
+// Cached for 30s for this call only
+const shortLived = await Netra.prompts.getPrompt({
+  name: "my-prompt",
+  label: "production", // default label when omitted
+  useCache: true,
+  cacheTtl: 30,
+});
+```
+
+> **Note**: Cached prompts may be stale for up to the TTL after dashboard edits. Use `useCache: false` when you need the latest version immediately. `Netra.shutdown()` clears in-memory caches.
+
+## 💰 Models API
+
+Fetch model pricing via `Netra.models.getModelPricing()`. Caching is **opt-in per call** — omit `useCache` (or set it to `false`) to always hit the API.
+
+Default TTL is **300 seconds** (`MODEL_PRICING_CACHE_TTL_SECONDS`). Override TTL for a single call with `cacheTtl`.
+
+```typescript
+import { Netra } from "netra-sdk";
+
+await Netra.init({
+  appName: "my-ai-app",
+});
+
+// Always fetches from the API (default)
+const pricing = await Netra.models.getModelPricing();
+
+// Optional name filter
+const gptPricing = await Netra.models.getModelPricing({ name: "gpt-4o" });
+
+// Cached for 300s (default TTL)
+const cached = await Netra.models.getModelPricing({
+  useCache: true,
+});
+
+// Cached for 60s for this call only
+const shortLived = await Netra.models.getModelPricing({
+  name: "gpt-4o",
+  useCache: true,
+  cacheTtl: 60,
+});
+```
+
+> **Note**: Cached pricing may be stale for up to the TTL after dashboard edits. Use `useCache: false` when you need the latest values immediately. `Netra.shutdown()` clears in-memory caches.
+
 ## 🔧 Environment Variables
 
 You can configure the SDK using environment variables: