apidepth 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 48290c633c238b8bbfcaff2a1f98cb4ffa26a3d0c02853ef0f345841425b463e
-  data.tar.gz: b3564982b79da91fe2ad976c913aa8bf94efbd35928f78a52d934e43b02eb4d0
+  metadata.gz: d59e0f9e95678afd4a0f9ce173de1b63ac893ab01cbc68fc1d6bbcedc44bfaad
+  data.tar.gz: 29524e4a1687cafb241caa6c07dbb2c1139ef2e44bc92f8ded25dc15c1305a92
 SHA512:
-  metadata.gz: 7a932948137e2d17f75d346686e60f0287c06f2702ec03a7adf3458c521604d9691e7803921726d391f1e161c59f77bce15063a5eeda93800093d7bb7d75e3ac
-  data.tar.gz: d262bd3e9b0668a1f5c667160efba8a41b99b850fcf177d3ccf3a5398b7179a005d9b141fb1ef62e1e3a86d55533fce7cf7eaf96c71f01a059ba96d98888ff9e
+  metadata.gz: a4a88ac5df80e6af2987cfa29d354c67c5275c02e30caacbae086558d2a0ee1fe1304a42c11b679b2ec6a1358a1cd0e69c3969a5d9d400c246723592df448599
+  data.tar.gz: 2005a0c7164ed0b20da0e1013cdc250be7d09f66fdfdd65f465168f38f4a105bfa6370e3a98bef015502f7cb2ba961a99189a6232e0098eb47ca11c588d90ed4

data/README.md

@@ -56,6 +56,46 @@ Get your API key at [apidepth.io](https://apidepth.io).
 
 ---
 
+## CLI
+
+The gem ships two subcommands for setup and connectivity verification.
+
+### `bundle exec apidepth setup`
+
+Interactive wizard that detects your framework (Rails, Sinatra, or generic), generates the correct initializer snippet, and optionally writes it to disk.
+
+```bash
+bundle exec apidepth setup
+```
+
+For CI/CD pipelines, skip all prompts:
+
+```bash
+bundle exec apidepth setup --api-key $APIDEPTH_API_KEY --no-prompt
+```
+
+| Flag | Description |
+|---|---|
+| `--api-key <key>` | Inject your API key into the generated snippet. |
+| `--no-prompt` | Non-interactive mode — print snippet to stdout and exit. |
+| `--framework <name>` | Override auto-detection (`rails`, `sinatra`, `generic`). |
+| `--ignored-hosts <patterns>` | Comma-separated host patterns to add to `ignored_hosts` (glob wildcards supported). |
+| `--collector-url <url>` | Override the collector URL in the generated snippet. |
+
+### `bundle exec apidepth test`
+
+Sends a synthetic test event to the collector and confirms the pipeline is working end-to-end. Reads `APIDEPTH_API_KEY` (and optionally `APIDEPTH_COLLECTOR_URL`) from the environment. Prints the round-trip time on success, or a per-failure-mode error message with next steps on failure.
+
+```bash
+bundle exec apidepth test
+# ✓ received in 142ms
+# Visit your dashboard: https://apidepth.io/dashboard
+```
+
+Exits with code 1 on any error (bad key, unreachable, SSL failure, timeout).
+
+---
+
 ## Configuration
 
 All options with their defaults:

data/lib/apidepth/configuration.rb

@@ -18,9 +18,10 @@ module Apidepth
                   :registry_refresh_interval,
                   :registry_cache_path,
                   :on_flush_error,
-                  :environment,      # e.g. "production" — set by Railtie from Rails.env
-                  :sample_rate,      # Float 0.0–1.0, default 1.0 (100% of events captured)
-                  :extra_vendors     # Hash of vendor_name => host, e.g. { "my-api" => "api.myservice.com" }
+                  :environment,        # e.g. "production" — set by Railtie from Rails.env
+                  :sample_rate,        # Float 0.0–1.0, default 1.0 (100% of events captured)
+                  :extra_vendors,      # Hash of vendor_name => host, e.g. { "my-api" => "api.myservice.com" }
+                  :capture_model_names # Boolean — read model field from AI vendor JSON responses
 
     attr_reader :ignored_hosts, :collector_url
 
@@ -35,6 +36,7 @@ module Apidepth
       @environment               = nil   # Railtie sets this to Rails.env at boot
       @sample_rate               = 1.0   # capture everything by default
       @extra_vendors             = {}    # customer-defined host mappings
+      @capture_model_names       = true  # read model field from AI vendor JSON responses
       _rebuild_ignored_hosts
     end
 

data/lib/apidepth/model_name_extractor.rb

@@ -0,0 +1,51 @@
+# lib/apidepth/model_name_extractor.rb
+require "json"
+require "set"
+#
+# Extracts the model name from AI vendor JSON response bodies.
+#
+# WHY response body rather than headers?
+# AI vendors (OpenAI, Anthropic, Gemini, Mistral, Cohere) return the active
+# model in the response body ({"model":"claude-3-opus-20240229",...}), not in
+# headers. This is the only reliable source.
+#
+# WHY only for known AI vendor hosts?
+# Body reads add a tiny overhead. Scoping to a hard-coded allowlist keeps the
+# hot path for non-AI vendors completely unaffected.
+#
+# Body safety: Net::HTTP::HTTPResponse#body memoizes after the first read.
+# Calling it here and returning the response to the application is safe — the
+# application receives the same cached body bytes.
+#
+# Streaming safety: streamed responses have Content-Type: text/event-stream, not
+# application/json. The content-type guard exits early before any body read.
+# The 8KB truncation is a belt-and-suspenders guard against unusually large bodies.
+
+module Apidepth
+  module ModelNameExtractor
+    AI_VENDOR_HOSTS = %w[
+      api.openai.com
+      api.anthropic.com
+      generativelanguage.googleapis.com
+      api.mistral.ai
+      api.cohere.com
+    ].to_set.freeze
+
+    MAX_BODY_BYTES = 8_192
+
+    def self.extract(host, response)
+      return nil unless Apidepth.configuration.capture_model_names
+      return nil unless AI_VENDOR_HOSTS.include?(host)
+      return nil unless response["content-type"]&.include?("application/json")
+
+      body = response.body
+      return nil if body.nil? || body.empty?
+
+      parsed = JSON.parse(body.byteslice(0, MAX_BODY_BYTES), symbolize_names: true)
+      model = parsed[:model]
+      model.is_a?(String) && !model.empty? ? model : nil
+    rescue JSON::ParserError, Encoding::UndefinedConversionError, TypeError
+      nil
+    end
+  end
+end

data/lib/apidepth/net_http_instrumentation.rb

@@ -72,21 +72,23 @@ module Apidepth
 
       now_ms = Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond)
       rl = Apidepth::RateLimitHeaders.extract(response, now_ms)
+      model_name = Apidepth::ModelNameExtractor.extract(address, response)
+
+      event_attrs = {
+        vendor: vendor,
+        endpoint: normalized_path,
+        method: req.method,
+        status: status,
+        outcome: outcome,
+        duration_ms: duration_ms,
+        cold_start: cold_start,
+        env: resolve_env,
+        ts: now_ms
+      }.merge(rl || {})
+      event_attrs[:model_name] = model_name if model_name
 
       Apidepth::Collector.instance.record(
-        Apidepth::Event.build(
-          {
-            vendor: vendor,
-            endpoint: normalized_path,
-            method: req.method,
-            status: status,
-            outcome: outcome,
-            duration_ms: duration_ms,
-            cold_start: cold_start,
-            env: resolve_env,
-            ts: now_ms
-          }.merge(rl || {})
-        )
+        Apidepth::Event.build(event_attrs)
       )
     rescue StandardError => e
       Apidepth.logger&.debug("[Apidepth] Instrumentation error: #{e.class}: #{e.message}")

data/lib/apidepth/version.rb

@@ -1,5 +1,5 @@
 # lib/apidepth/version.rb
 
 module Apidepth
-  VERSION = "0.4.0".freeze
+  VERSION = "0.5.0".freeze
 end

data/lib/apidepth.rb

@@ -1,14 +1,15 @@
 # lib/apidepth.rb
 #
 # Main entry point. Require order matters:
-#   1. version       — no dependencies
-#   2. configuration — no dependencies
-#   3. vendor_registry — no dependencies, boots from BUNDLED_BASELINE immediately
-#   4. rate_limit_headers — no dependencies; used by net_http_instrumentation
-#   5. net_http_instrumentation — depends on vendor_registry + collector (via lazy reference)
-#   5. collector     — depends on configuration
-#   6. registry_loader — depends on collector + vendor_registry
-#   7. railtie       — depends on all of the above; only loaded in a Rails context
+#   1. version             — no dependencies
+#   2. configuration       — no dependencies
+#   3. vendor_registry     — no dependencies, boots from BUNDLED_BASELINE immediately
+#   4. rate_limit_headers  — no dependencies; used by net_http_instrumentation
+#   5. model_name_extractor — no dependencies; used by net_http_instrumentation
+#   6. net_http_instrumentation — depends on vendor_registry + collector (via lazy reference)
+#   7. collector           — depends on configuration
+#   8. registry_loader     — depends on collector + vendor_registry
+#   9. railtie             — depends on all of the above; only loaded in a Rails context
 
 require "logger"
 require "apidepth/version"
@@ -16,6 +17,7 @@ require "apidepth/configuration"
 require "apidepth/event"
 require "apidepth/vendor_registry"
 require "apidepth/rate_limit_headers"
+require "apidepth/model_name_extractor"
 require "apidepth/net_http_instrumentation"
 require "apidepth/collector"
 require "apidepth/registry_loader"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: apidepth
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Apidepth
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-30 00:00:00.000000000 Z
+date: 2026-06-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -129,6 +129,7 @@ files:
 - lib/apidepth/collector.rb
 - lib/apidepth/configuration.rb
 - lib/apidepth/event.rb
+- lib/apidepth/model_name_extractor.rb
 - lib/apidepth/net_http_instrumentation.rb
 - lib/apidepth/railtie.rb
 - lib/apidepth/rate_limit_headers.rb