google cost tracking

Author: ndbroadbent

src/costs/calculator.test.ts

@@ -9,6 +9,7 @@ import {
   calculateAIOutputCost,
   calculateEmbeddingCost,
   calculateGeocodingCost,
+  calculateGoogleSearchCost,
   calculatePexelsCost,
   calculatePixabayCost,
   calculatePlacesLookupCost,
@@ -17,6 +18,7 @@ import {
   createAIUsageRecords,
   createEmbeddingUsageRecord,
   createGeocodingUsageRecord,
+  createGoogleSearchUsageRecord,
   createImageUsageRecord,
   formatMicrosAsDollars,
   groupByProvider,
@@ -235,6 +237,43 @@ describe('calculatePexelsCost', () => {
   })
 })
 
+describe('calculateGoogleSearchCost', () => {
+  it('should calculate cost based on query count', () => {
+    // $0.005 per query = 5,000 micro-dollars
+    expect(calculateGoogleSearchCost(1)).toBe(5_000)
+    expect(calculateGoogleSearchCost(10)).toBe(50_000)
+    expect(calculateGoogleSearchCost(1000)).toBe(5_000_000) // $5 for 1000 queries
+  })
+
+  it('should handle zero queries', () => {
+    expect(calculateGoogleSearchCost(0)).toBe(0)
+  })
+})
+
+describe('createGoogleSearchUsageRecord', () => {
+  it('should create record for google search', () => {
+    const record = createGoogleSearchUsageRecord(5)
+    expect(record.resource).toBe('google_search')
+    expect(record.quantity).toBe(5)
+    expect(record.provider).toBe('google_search')
+    expect(record.costMicros).toBe(25_000) // 5 * 5,000
+  })
+
+  it('should include metadata if provided', () => {
+    const record = createGoogleSearchUsageRecord(1, { query: 'test movie' })
+    expect(record.metadata).toEqual({ query: 'test movie' })
+  })
+
+  it('should include timestamp', () => {
+    const before = new Date()
+    const record = createGoogleSearchUsageRecord(1)
+    const after = new Date()
+
+    expect(record.timestamp.getTime()).toBeGreaterThanOrEqual(before.getTime())
+    expect(record.timestamp.getTime()).toBeLessThanOrEqual(after.getTime())
+  })
+})
+
 describe('createImageUsageRecord', () => {
   it('should create record for Google Places photos', () => {
     const record = createImageUsageRecord('google_places', 10)

src/costs/calculator.ts

@@ -7,6 +7,7 @@
 
 import {
   GOOGLE_MAPS_PRICING,
+  GOOGLE_SEARCH_PRICING,
   getAIModelPricing,
   getEmbeddingModelPricing,
   IMAGE_SERVICE_PRICING
@@ -217,6 +218,36 @@ export function createGeocodingUsageRecord(
   return record
 }
 
+// =============================================================================
+// SEARCH COST CALCULATIONS
+// =============================================================================
+
+/**
+ * Calculate cost for Google Programmable Search API.
+ * Pricing: $5.00 per 1,000 queries ($0.005 per query).
+ */
+export function calculateGoogleSearchCost(queryCount: number): MicroDollars {
+  return GOOGLE_SEARCH_PRICING.searchQuery * queryCount
+}
+
+/**
+ * Create a usage record for Google Search.
+ */
+export function createGoogleSearchUsageRecord(
+  queryCount: number,
+  metadata?: Record<string, unknown>
+): UsageRecord {
+  const record: UsageRecord = {
+    resource: 'google_search',
+    provider: 'google_search',
+    quantity: queryCount,
+    costMicros: calculateGoogleSearchCost(queryCount),
+    timestamp: new Date()
+  }
+  if (metadata) record.metadata = metadata
+  return record
+}
+
 // =============================================================================
 // IMAGE COST CALCULATIONS
 // =============================================================================

src/costs/index.ts

@@ -42,6 +42,7 @@ export type {
   MicroDollars,
   ModelPricing,
   Provider,
+  SearchProvider,
   // Usage types
   UsageRecord,
   UsageSummary
@@ -60,6 +61,7 @@ export {
   DEFAULT_GEOCODING_PROVIDER,
   EMBEDDING_MODEL_PRICING,
   GOOGLE_MAPS_PRICING,
+  GOOGLE_SEARCH_PRICING,
   // Pricing helpers
   getAIModelPricing,
   getDefaultAIModel,
@@ -82,6 +84,8 @@ export {
   // Embedding costs
   calculateEmbeddingCost,
   calculateGeocodingCost,
+  // Search costs
+  calculateGoogleSearchCost,
   calculatePexelsCost,
   calculatePixabayCost,
   // Geocoding costs
@@ -92,6 +96,7 @@ export {
   createAIUsageRecords,
   createEmbeddingUsageRecord,
   createGeocodingUsageRecord,
+  createGoogleSearchUsageRecord,
   createImageUsageRecord,
   formatMicrosAsDollars,
   groupByProvider,

src/costs/pricing.ts

@@ -185,6 +185,19 @@ export const GOOGLE_MAPS_PRICING = {
   updatedAt: '2025-01-01'
 } as const
 
+/**
+ * Google Search API pricing (Programmable Search Engine).
+ * Prices are per query in micro-dollars.
+ *
+ * Source: https://developers.google.com/custom-search/v1/overview#pricing
+ * Pricing: $5.00 per 1,000 queries
+ */
+export const GOOGLE_SEARCH_PRICING = {
+  /** Cost per search query ($0.005 per query = 5,000 micro-dollars) */
+  searchQuery: 5_000 as MicroDollars,
+  updatedAt: '2026-01-01'
+} as const
+
 /**
  * Image service pricing.
  * Prices are per request in micro-dollars.

src/costs/types.ts

@@ -18,11 +18,19 @@ export type EmbeddingProvider = 'openai' | 'google'
 /** Geocoding providers */
 export type GeocodingProvider = 'google_places' | 'google_geocoding'
 
+/** Search providers */
+export type SearchProvider = 'google_search'
+
 /** Image providers */
 export type ImageProvider = 'google_places_photos' | 'pixabay' | 'pexels'
 
 /** All provider types */
-export type Provider = AIProvider | EmbeddingProvider | GeocodingProvider | ImageProvider
+export type Provider =
+  | AIProvider
+  | EmbeddingProvider
+  | GeocodingProvider
+  | ImageProvider
+  | SearchProvider
 
 // =============================================================================
 // RESOURCE TYPES
@@ -38,6 +46,7 @@ export type MeteredResource =
   | 'google_places_lookup'
   | 'google_geocoding_lookup'
   | 'google_places_photo'
+  | 'google_search'
   | 'pixabay_search'
   | 'pexels_search'
   // Compute

src/search/classification.ts

@@ -7,6 +7,8 @@
 
 import { generateCacheKey } from '../caching/key'
 import type { ResponseCache } from '../caching/types'
+import { createAIUsageRecords } from '../costs/calculator'
+import type { CostTracker } from '../costs/tracker'
 import { type HttpResponse, httpFetch } from '../http'
 import type { AIClassificationConfig, ClassificationResult, DeferredItem } from './types'
 import { DEFAULT_TIMEOUT } from './types'
@@ -21,6 +23,8 @@ const DEFAULT_MODEL = 'gemini-2.5-flash-preview-05-20'
 export interface ClassificationFullConfig extends AIClassificationConfig {
   /** Response cache for API calls */
   cache?: ResponseCache | undefined
+  /** Cost tracker for API usage billing */
+  costTracker?: CostTracker | undefined
   /** Request timeout in milliseconds */
   timeout?: number | undefined
   /** Custom fetch function (for testing) */
@@ -61,13 +65,26 @@ Return JSON with 1-indexed result numbers, best first:
 Empty array if no result matches the entity (a book by the same author is NOT a match).`
 }
 
+/** Token usage from Gemini API response */
+interface GeminiUsageMetadata {
+  promptTokenCount?: number
+  candidatesTokenCount?: number
+  totalTokenCount?: number
+}
+
+/** Result from Gemini API call including usage */
+interface GeminiCallResult {
+  result: { url_indexes: number[]; explanation: string } | null
+  usage: GeminiUsageMetadata | null
+}
+
 /**
  * Call Gemini API and parse JSON response.
  */
 async function callGemini(
   prompt: string,
   config: ClassificationFullConfig
-): Promise<{ url_indexes: number[]; explanation: string } | null> {
+): Promise<GeminiCallResult> {
   const timeout = config.timeout ?? DEFAULT_TIMEOUT
   const model = config.model ?? DEFAULT_MODEL
 
@@ -100,11 +117,11 @@ async function callGemini(
       })
     }
   } catch {
-    return null
+    return { result: null, usage: null }
   }
 
   if (!response.ok) {
-    return null
+    return { result: null, usage: null }
   }
 
   const data = (await response.json()) as {
@@ -113,17 +130,21 @@ async function callGemini(
         parts?: Array<{ text?: string }>
       }
     }>
+    usageMetadata?: GeminiUsageMetadata
   }
 
   const text = data.candidates?.[0]?.content?.parts?.[0]?.text
+  const usage = data.usageMetadata ?? null
+
   if (!text) {
-    return null
+    return { result: null, usage }
   }
 
   try {
-    return JSON.parse(text) as { url_indexes: number[]; explanation: string }
+    const result = JSON.parse(text) as { url_indexes: number[]; explanation: string }
+    return { result, usage }
   } catch {
-    return null
+    return { result: null, usage }
   }
 }
 
@@ -167,9 +188,24 @@ async function executeClassification(
   config: ClassificationFullConfig
 ): Promise<ClassificationResult> {
   const { title, category, searchResults } = item
+  const model = config.model ?? DEFAULT_MODEL
 
   const prompt = buildPrompt(item)
-  const aiResponse = await callGemini(prompt, config)
+  const { result: aiResponse, usage } = await callGemini(prompt, config)
+
+  // Record AI costs if we have usage data and a cost tracker
+  if (usage && config.costTracker) {
+    const inputTokens = usage.promptTokenCount ?? 0
+    const outputTokens = usage.candidatesTokenCount ?? 0
+    if (inputTokens > 0 || outputTokens > 0) {
+      const usageRecords = createAIUsageRecords(model, inputTokens, outputTokens, {
+        operation: 'entity_classification',
+        title,
+        category
+      })
+      config.costTracker.addRecords(usageRecords)
+    }
+  }
 
   if (!aiResponse) {
     return {