feat: add instrumentation system for API cost tracking

- Add EventRegistry with thread-safe wildcard pattern subscriptions
- Add BaseSubscriber base class for custom event subscribers
- Add CostTracker built-in subscriber for tracking API costs
- Emit exa.request.start, exa.request.complete, exa.request.error events
- Add Endpoint T::Enum for typed endpoint identification
- Unify CostDollars types into shared lib/exa/responses/cost.rb
- Update all response types to use fully-typed CostDollars struct
- Add comprehensive tests for instrumentation system
- Update README with instrumentation documentation

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: vicentereig

README.md

@@ -23,7 +23,8 @@ This README is intentionally exhaustive—LLM agents and humans alike should be
    - [Events, Imports, Webhooks](#events-imports-webhooks)
 6. [Structured Output via Sorbet + dspy-schema](#structured-output-via-sorbet--dspy-schema)
 7. [Streaming & Transport Helpers](#streaming--transport-helpers)
-8. [Testing & TDD Plan](#testing--tdd-plan)
+8. [Instrumentation & Cost Tracking](#instrumentation--cost-tracking)
+9. [Testing & TDD Plan](#testing--tdd-plan)
 
 ---
 
@@ -367,6 +368,150 @@ See `test/transport/stream_test.rb` for examples.
 
 ---
 
+## Instrumentation & Cost Tracking
+
+The gem includes a built-in instrumentation system for tracking API usage and costs. Events are emitted around every API request, and you can subscribe to them for logging, monitoring, or cost management.
+
+### Basic Cost Tracking
+
+```ruby
+require "exa"
+
+client = Exa::Client.new(api_key: ENV.fetch("EXA_API_KEY"))
+
+# Create and subscribe a cost tracker
+tracker = Exa::Instrumentation::CostTracker.new
+tracker.subscribe
+
+# Make API calls - costs are tracked automatically
+response = client.search.search(query: "AI papers", num_results: 10)
+puts response.cost_dollars&.total  # => 0.005
+
+client.search.contents(urls: ["https://example.com"], text: true)
+
+# Check accumulated costs
+puts tracker.total_cost     # => 0.006
+puts tracker.request_count  # => 2
+puts tracker.average_cost   # => 0.003
+
+# Get breakdown by endpoint
+tracker.summary.each do |endpoint, cost|
+  puts "#{endpoint.serialize}: $#{cost}"
+end
+# => search: $0.005
+# => contents: $0.001
+
+# Print a formatted report
+puts tracker.report
+
+# Reset tracking
+tracker.reset!
+
+# Unsubscribe when done
+tracker.unsubscribe
+```
+
+### Custom Event Subscribers
+
+Subscribe to specific events using wildcard patterns:
+
+```ruby
+# Subscribe to all request events
+Exa.instrumentation.subscribe("exa.request.*") do |event_name, payload|
+  case event_name
+  when "exa.request.start"
+    puts "Starting #{payload.endpoint.serialize} request..."
+  when "exa.request.complete"
+    puts "Completed in #{payload.duration_ms.round(2)}ms, cost: $#{payload.cost_dollars}"
+  when "exa.request.error"
+    puts "Error: #{payload.error_class} - #{payload.error_message}"
+  end
+end
+
+# Subscribe to specific events
+Exa.instrumentation.subscribe("exa.request.error") do |_name, payload|
+  ErrorTracker.notify(payload.error_class, payload.error_message)
+end
+```
+
+### Building Custom Subscribers
+
+Extend `BaseSubscriber` for reusable instrumentation:
+
+```ruby
+class BudgetGuard < Exa::Instrumentation::BaseSubscriber
+  def initialize(budget_limit)
+    @budget = budget_limit
+    @spent = 0.0
+    @mutex = Mutex.new
+    super()
+  end
+
+  def subscribe
+    add_subscription("exa.request.complete") do |_name, payload|
+      next unless payload.cost_dollars
+
+      @mutex.synchronize do
+        @spent += payload.cost_dollars
+        raise "Budget exceeded! Spent $#{@spent} of $#{@budget}" if @spent > @budget
+      end
+    end
+  end
+
+  attr_reader :spent
+end
+
+guard = BudgetGuard.new(1.00)  # $1 budget
+guard.subscribe
+# ... make API calls ...
+guard.unsubscribe
+```
+
+### Event Types
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `exa.request.start` | `RequestStart` | Emitted when a request begins |
+| `exa.request.complete` | `RequestComplete` | Emitted on successful completion |
+| `exa.request.error` | `RequestError` | Emitted when a request fails |
+
+**RequestStart** fields: `request_id`, `endpoint`, `http_method`, `path`, `timestamp`
+
+**RequestComplete** fields: `request_id`, `endpoint`, `duration_ms`, `status`, `cost_dollars`, `timestamp`
+
+**RequestError** fields: `request_id`, `endpoint`, `duration_ms`, `error_class`, `error_message`, `timestamp`
+
+### Async Compatibility
+
+The instrumentation system is thread-safe and works inside `Async` blocks:
+
+```ruby
+require "async"
+require "exa/internal/transport/async_requester"
+
+tracker = Exa::Instrumentation::CostTracker.new
+tracker.subscribe
+
+Async do
+  requester = Exa::Internal::Transport::AsyncRequester.new
+  client = Exa::Client.new(api_key: ENV.fetch("EXA_API_KEY"), requester: requester)
+
+  # Concurrent requests - all tracked safely
+  tasks = 5.times.map do |i|
+    Async { client.search.search(query: "query #{i}", num_results: 3) }
+  end
+  tasks.each(&:wait)
+
+  puts "Total cost for #{tracker.request_count} requests: $#{tracker.total_cost}"
+ensure
+  requester.close
+end
+
+tracker.unsubscribe
+```
+
+---
+
 ## Testing & TDD Plan
 
 Run the suite:

lib/exa.rb

@@ -12,3 +12,30 @@
 require_relative "exa/types"
 require_relative "exa/responses"
 require_relative "exa/resources"
+require_relative "exa/instrumentation"
+
+module Exa
+  class << self
+    # Returns the global instrumentation event registry.
+    # Use this to subscribe to API events for cost tracking, logging, etc.
+    #
+    # @example Subscribe to all request events
+    #   Exa.instrumentation.subscribe('exa.request.*') do |event_name, payload|
+    #     puts "#{event_name}: #{payload.inspect}"
+    #   end
+    #
+    # @return [Exa::Instrumentation::EventRegistry]
+    def instrumentation
+      @instrumentation ||= Instrumentation::EventRegistry.new
+    end
+
+    # Emit an event to all subscribers.
+    # Primarily used internally by the transport layer.
+    #
+    # @param event_name [String] The event name (e.g., 'exa.request.complete')
+    # @param payload [Object] The event payload
+    def emit(event_name, payload)
+      instrumentation.notify(event_name, payload)
+    end
+  end
+end

lib/exa/instrumentation.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Exa
+  module Instrumentation
+    # Thread-safe event registry for subscribing to and emitting API events.
+    # Supports wildcard pattern matching (e.g., 'exa.request.*').
+    class EventRegistry
+      def initialize
+        @listeners = {}
+        @mutex = Mutex.new
+      end
+
+      # Subscribe to events matching a pattern.
+      # @param pattern [String] Event pattern (supports '*' wildcard)
+      # @yield [event_name, payload] Block called when matching events are emitted
+      # @return [String] Subscription ID for later unsubscription
+      def subscribe(pattern, &block)
+        return unless block_given?
+
+        subscription_id = SecureRandom.uuid
+        @mutex.synchronize do
+          @listeners[subscription_id] = {
+            pattern: pattern,
+            block: block
+          }
+        end
+
+        subscription_id
+      end
+
+      # Unsubscribe from events.
+      # @param subscription_id [String] The ID returned from subscribe
+      def unsubscribe(subscription_id)
+        @mutex.synchronize do
+          @listeners.delete(subscription_id)
+        end
+      end
+
+      # Clear all listeners.
+      def clear_listeners
+        @mutex.synchronize do
+          @listeners.clear
+        end
+      end
+
+      # Emit an event to all matching subscribers.
+      # @param event_name [String] The event name (e.g., 'exa.request.complete')
+      # @param payload [Object] The event payload (usually a typed struct)
+      def notify(event_name, payload)
+        # Take a snapshot of current listeners to avoid holding the mutex during execution
+        matching_listeners = @mutex.synchronize do
+          @listeners.select do |_id, listener|
+            pattern_matches?(listener[:pattern], event_name)
+          end.dup
+        end
+
+        matching_listeners.each do |_id, listener|
+          listener[:block].call(event_name, payload)
+        rescue StandardError
+          # Silently ignore listener errors to avoid breaking the main flow
+        end
+      end
+
+      # Returns the count of registered listeners.
+      def listener_count
+        @mutex.synchronize { @listeners.size }
+      end
+
+      private
+
+      def pattern_matches?(pattern, event_name)
+        if pattern.include?("*")
+          # Convert wildcard pattern to regex
+          # exa.request.* becomes ^exa\.request\..*$
+          regex_pattern = "^#{Regexp.escape(pattern).gsub('\\*', '.*')}$"
+          Regexp.new(regex_pattern).match?(event_name)
+        else
+          # Exact match
+          pattern == event_name
+        end
+      end
+    end
+
+    # Base class for creating event subscribers.
+    # Subclasses should implement #subscribe to add subscriptions.
+    #
+    # @example
+    #   class MyCostTracker < Exa::Instrumentation::BaseSubscriber
+    #     def initialize
+    #       @total = 0.0
+    #       super()
+    #     end
+    #
+    #     def subscribe
+    #       add_subscription('exa.request.complete') do |_, payload|
+    #         @total += payload.cost_dollars || 0
+    #       end
+    #     end
+    #   end
+    class BaseSubscriber
+      def initialize
+        @subscriptions = []
+      end
+
+      # Override to add subscriptions. Called automatically after initialize.
+      def subscribe
+        raise NotImplementedError, "Subclasses must implement #subscribe"
+      end
+
+      # Unsubscribe from all registered subscriptions.
+      def unsubscribe
+        @subscriptions.each { |id| Exa.instrumentation.unsubscribe(id) }
+        @subscriptions.clear
+      end
+
+      protected
+
+      # Add a subscription to the global event registry.
+      # @param pattern [String] Event pattern to match
+      # @yield [event_name, payload] Block called for matching events
+      # @return [String] Subscription ID
+      def add_subscription(pattern, &block)
+        subscription_id = Exa.instrumentation.subscribe(pattern, &block)
+        @subscriptions << subscription_id
+        subscription_id
+      end
+    end
+  end
+end
+
+require_relative "instrumentation/events"
+require_relative "instrumentation/cost_tracker"