F-sdk-cost-estimate: Pre-request cost estimation

[peterkacerik]

Summary

• Add estimateCost() synchronous convenience wrapper for pre-request cost estimation
• Add refreshPricing() async function for fetching live prices from AISpendGuard API with 24h cache
• Add CostEstimate and CostEstimateInput types with structured breakdown (input/output/tool costs)

Task

Task file: aispendguard-tasks/active/features/F-sdk-cost-estimate.md

Changes

• src/types.ts — Added CostEstimate and CostEstimateInput type definitions
• src/pricing.ts — Added estimateCost(), refreshPricing(), API price cache with 24h TTL
• src/index.ts — Exported new functions and types
• tests/pricing.test.mjs — 6 new tests: structured breakdown, unknown model, batch mode, cached tokens, custom pricing, web search fees
• README.md — Added cost estimation example and API entries

Implementation Coverage

• Step 1 (types): CostEstimate and CostEstimateInput added to src/types.ts
• Step 2 (implementation): estimateCost() and refreshPricing() added to src/pricing.ts
• Step 3 (exports): Added to src/index.ts
• Step 4 (tests): 6 tests added to tests/pricing.test.mjs
• Step 5 (docs): SDK docs page updated in aispendguard-app PR #165

Sentinel Notes Addressed

• N1: Added toolCostUsd field to CostEstimate for complete breakdown
• N2: Used json.models ?? [] for defensive parsing in refreshPricing()
• N3: Added estimateCost to existing destructuring on L6 of test file

Testing

• npm run build passes
• npm test passes (64 pass, 0 fail, 1 skip)
• New tests added for: estimateCost structured breakdown, unknown model, batch mode, cached tokens, custom pricing, web search fees with toolCostUsd

Documentation

• SDK README updated with estimateCost() example
• App docs page updated (PR #165)

[peterkacerik]

Sentinel Code Review — APPROVED

All checks passed. Security, quality, and documentation verified.

Implementation Completeness

All 5 deliverables verified:

1. ✅ types.ts — CostEstimate (with toolCostUsd per N1) and CostEstimateInput
2. ✅ pricing.ts — estimateCost(), refreshPricing() with 24h API cache, defensive json.models ?? [] per N2
3. ✅ index.ts — All exports added
4. ✅ tests/pricing.test.mjs — 6 new tests in existing destructuring per N3
5. ✅ README.md — Cost estimation example and API entries

Security

• No injection, no hardcoded secrets, privacy invariant preserved
• Synthetic event uses dummy tags, never sent to API
• refreshPricing() runs in user environment — no SSRF risk to AISpendGuard infra
• Error paths return bundled fallback, don't leak internals

Quality

• Build: tsc clean ✅
• Tests: 64/64 pass (1 skipped — live integration) ✅
• Breakdown sum: inputCostUsd + outputCostUsd + toolCostUsd ≈ estimatedCostUsd ✅
• No N+1 queries, no DB changes, zero new dependencies

Regression Check

Patterns #1-#11: no matches.