omnitrack-rb 0.1.0

data/USAGE.md

@@ -0,0 +1,276 @@
+# OmniTrack — where to put code and which methods to use
+
+This guide is a **placement map** for a Rails app: which files to touch, and how the public API fits together. For platform-specific credentials, see the main [README.md](README.md).
+
+---
+
+## 1. What runs automatically (no code from you)
+
+| Piece | What it does |
+|--------|----------------|
+| **Railtie** | Loads the gem with Rails, registers adapters, and wires the parts below. |
+| **Rack middleware** `Omnitrack::Middleware::RequestTracker` | On each request, builds `Omnitrack::Context` from the incoming request, stores it in **thread-local** storage for that request, then clears it after the response. |
+| **Context capture** (when `config.auto_capture = true`) | Reads query params and common headers for `gclid`, `fbclid`, `ttclid`, `sclid`, `msclkid`, UTM fields, `User-Agent`, client IP, and (full-stack) cookies. |
+| **Controller helpers** | The concern `Omnitrack::Controller` is **included for you** in `ActionController` via the Railtie. You get `omnitrack_context`, `omnitrack_event`, and similar unless you opt out. |
+
+You do **not** manually “start the tracker” in `ApplicationController` for basic use — middleware + initializer are enough.
+
+---
+
+## 2. Where you add configuration (once per app)
+
+| File | Purpose |
+|------|--------|
+| `config/initializers/omnitrack.rb` | **Primary place.** `Omnitrack.configure do |config| … end` — adapters, `mode`, `async`, `log_level`, `auto_capture`, retries, `on_error`, etc. |
+| `Gemfile` | `gem "omnitrack-rb"` |
+| **Environment** | ENV vars (or `Rails.application.credentials`) referenced from the initializer — no secret keys in the repo. |
+
+Run once:
+
+```bash
+rails generate omnitrack:install
+```
+
+That copies a starter `config/initializers/omnitrack.rb` you should edit for your stack.
+
+---
+
+## 3. Server-side API — three entry points (use anywhere in the app)
+
+These are the main methods. They fan out to **each enabled adapter** in `config.adapters` and return an `Omnitrack::MultiResult` (never raise into your app in normal use).
+
+| Method | Use when | Typical payload |
+|--------|-----------|-----------------|
+| `Omnitrack.track(event_name, **payload_hash)` | Any named event (e.g. `"purchase"`, `"lead"`, `"add_to_cart"`). | `value`, `currency`, `gclid`, `fbclid`, `order_id`, `email`, etc. (see main README) |
+| `Omnitrack.track_conversion(data_hash)` | You want a **conversion**-shaped call (adapters map it; often same as a purchase/lead). | Same hash style as a conversion: `value`, `currency`, `order_id`, click IDs, etc. |
+| `Omnitrack.identify(user_hash)` | Associate PII to the current journey before/after events (hashed by adapters that need it). | `email`, `phone`, `first_name`, `last_name`, `external_id` |
+
+**Where to call them**
+
+| Location | When to use |
+|----------|-------------|
+| **Controllers** | Right after a successful action: order created, form submitted, signup completed. |
+| **Service objects / interactors** | Preferred for fat domain logic: call `Omnitrack.track(...)` from your service after the business work succeeds. |
+| **ActiveJob** | Work already off the main thread: enqueue a job that calls `Omnitrack.track` (or set `config.async` so the gem enqueues for you; see [README](README.md#async--background-jobs)). |
+| **Models** | Possible, but most teams avoid this; prefer services or callbacks that delegate to a small tracker service. |
+
+**API-only / mobile clients:** your API never needs cookies for the server-side APIs. Pass `gclid` / `fbclid` / `ttclid` in the JSON body or as headers; merge them into the hash you pass to `Omnitrack.track`. The middleware will still set context from params when present.
+
+---
+
+## 4. Controller convenience methods (same as the API, with context merged)
+
+Included via `Omnitrack::Controller` (or `include Omnitrack::Controller` in a base class if you disabled auto-include).
+
+| Method | Maps to | What it does extra |
+|--------|---------|--------------------|
+| `omnitrack_context` | — | Returns `Omnitrack::Context.current` (or builds from `request` if needed). |
+| `omnitrack_event("name", payload)` | `Omnitrack.track` | Merges `__context__` (IP, click IDs, etc.) so adapters see the full request picture. |
+| `omnitrack_conversion(data)` | `Omnitrack.track_conversion` | Same merge as above. |
+| `omnitrack_identify(user_data)` | `Omnitrack.identify` | Same merge pattern. |
+| `omnitrack_set(extra_hash)` | — | Merges custom keys into the current context for the **rest of this request** (not across requests). |
+
+**Where to put them:** any `ActionController` action after a success path, e.g. `app/controllers/orders_controller.rb`, `app/controllers/api/v1/orders_controller.rb`.
+
+---
+
+## 5. View helpers (full-stack, browser + pixels)
+
+Only relevant when the app is **not** API-only in practice and `Omnitrack.frontend_mode?` is true (see `config.mode` and `effective_mode` in the main README).
+
+| Helper | Where to put it | Role |
+|--------|------------------|------|
+| `omnitrack_tags` | Layout `<head>`, e.g. `app/views/layouts/application.html.erb` | Injects base scripts / pixels (GA4, Meta, TikTok, Snapchat) for enabled adapters. |
+| `omnitrack_event_tag("event", **options)` | Specific pages, e.g. order confirmation / thank-you view | Pushes a client-side event to the injected stacks. |
+
+---
+
+## 6. How “the tracker” ties together (mental model)
+
+1. **Request comes in** → middleware builds **one `Context` per request** (thread-local).
+2. **Your code** calls `Omnitrack.track` (or the controller helpers) with business fields + optional click IDs.
+3. **Dispatcher** runs each **enabled** adapter in turn; one adapter failing does not break the others.
+4. **Logger** (if not `:none`) writes JSON lines to **`log/omnitrack.log`** (or `config.log_file`).
+5. If **`config.async` is true**, the public methods enqueue `Omnitrack::Jobs::TrackingJob` instead of calling adapters inline (when ActiveJob and the job class are loaded).
+
+```text
+Request → Middleware (Context) → Your controller/service → Omnitrack.track
+                                                      → Adapters (Google, Meta, …)
+                                                      → log/omnitrack.log
+```
+
+---
+
+## 7. Quick copy-paste checklist
+
+- [ ] `config/initializers/omnitrack.rb` — set `config.adapters` and credentials.
+- [ ] Full-stack: `<%= omnitrack_tags %>` in the main layout head.
+- [ ] On conversion: `Omnitrack.track("purchase", ...)` or `omnitrack_event("purchase", ...)` in the controller, or a service you call from the controller.
+- [ ] API: pass click IDs in params/body; keep using `Omnitrack.track` the same way.
+- [ ] Production: configure `config.async` and an ActiveJob queue if you need non-blocking tracking.
+- [ ] Set ENV from [`.env.example`](.env.example) (see [AI_GEM_SETUP.md](AI_GEM_SETUP.md) for `dotenv-rails` and production).
+
+For errors, custom adapters, and Rake tasks, see [README.md](README.md).
+
+---
+
+## 8. Concrete examples — which file, where the call goes
+
+### A. Full-stack: layout (pixels / gtag, once per app)
+
+**File:** `app/views/layouts/application.html.erb` (or your main HTML layout) — inside `<head>`:
+
+```erb
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>My App</title>
+    <%= csrf_meta_tags %>
+    <%= csp_meta_tag if respond_to?(:csp_meta_tag) %>
+    <%= omnitrack_tags %>
+    <%= stylesheet_link_tag "application", "data-turbo-track": "reload" %>
+  </head>
+  <body>
+    <%= yield %>
+  </body>
+</html>
+```
+
+If you use a different layout (e.g. `layouts/shop.html.erb`), put `<%= omnitrack_tags %>` in that file’s `<head>` instead.
+
+---
+
+### B. Controller: purchase / conversion (server-side, same request as the redirect or JSON)
+
+**File:** `app/controllers/orders_controller.rb`
+
+```ruby
+# frozen_string_literal: true
+
+class OrdersController < ApplicationController
+  def create
+    @order = Order.create!(order_params)
+
+    # Context (gclid, IP, etc.) is merged for you; safe if an adapter is disabled
+    omnitrack_event("purchase",
+      value:     @order.total,
+      currency:  @order.currency,
+      order_id:  @order.id,
+      gclid:     params[:gclid],   # optional if not already on the query string
+      email:     current_user.email)
+
+    redirect_to @order
+  end
+
+  private
+
+  def order_params
+    params.require(:order).permit(:total, :currency)
+  end
+end
+```
+
+Equivalent using the module API directly (no `omnitrack_*` merge — pass what you need):
+
+```ruby
+Omnitrack.track("purchase",
+  value:     @order.total,
+  currency:  @order.currency,
+  order_id:  @order.id)
+```
+
+---
+
+### C. API-only JSON controller (no layout tags)
+
+**File:** `app/controllers/api/v1/orders_controller.rb`
+
+```ruby
+# frozen_string_literal: true
+
+module Api
+  module V1
+    class OrdersController < ApplicationController
+      def create
+        @order = Order.create!(order_params)
+
+        Omnitrack.track("purchase",
+          value:     @order.total,
+          currency:  @order.currency,
+          order_id:  @order.id,
+          gclid:     order_params[:gclid],
+          fbclid:    order_params[:fbclid],
+          ttclid:    order_params[:ttclid])
+
+        render json: @order, status: :created
+      end
+
+      private
+
+      def order_params
+        params.require(:order).permit(:total, :currency, :gclid, :fbclid, :ttclid)
+      end
+    end
+  end
+end
+```
+
+---
+
+### D. Service object (keeps controllers thin) — **recommended** for real apps
+
+**File:** `app/services/marketing/record_purchase.rb` (create the `marketing` directory if it does not exist)
+
+```ruby
+# frozen_string_literal: true
+
+module Marketing
+  class RecordPurchase
+    def self.call(order:)
+      new(order: order).call
+    end
+
+    def initialize(order:)
+      @order = order
+    end
+
+    def call
+      Omnitrack.track("purchase",
+        value:     @order.total,
+        currency:  @order.currency,
+        order_id:  @order.id,
+        email:     @order.user_email)
+    end
+  end
+end
+```
+
+**File:** `app/controllers/orders_controller.rb` (one line in `create` after the order is saved)
+
+```ruby
+Marketing::RecordPurchase.call(order: @order)
+```
+
+Autoload: Rails 6+ with `app/services` — ensure `config.autoload_paths` includes `app/services` if you use a custom structure (default Zeitwerk will load `app/services/**/*.rb`).
+
+---
+
+### E. View: client-side event on a thank-you page (full-stack)
+
+**File:** `app/views/orders/show.html.erb` (or your confirmation view)
+
+```erb
+<% if @order.paid? %>
+  <%= omnitrack_event_tag("Purchase", value: @order.total, currency: @order.currency) %>
+<% end %>
+```
+
+---
+
+### F. “Where not to” put tracking
+
+| Avoid | Prefer |
+|--------|--------|
+| `config/application.rb` (manual `Omnitrack.configure` outside an initializer) | `config/initializers/omnitrack.rb` only |
+| `before_action` for every request without a reason | Call after a **successful** business action (order paid, form submitted) |
+| Hard-coded tokens in the repo | `ENV` (see [`.env.example`](.env.example) + [AI_GEM_SETUP.md](AI_GEM_SETUP.md)) |

data/lib/generators/omnitrack/install/install_generator.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Omnitrack
+  class InstallGenerator < Rails::Generators::Base
+    source_root File.expand_path("templates", __dir__)
+
+    desc "Creates an Omnitrack initializer and adds it to your application"
+
+    def create_initializer_file
+      template "initializer.rb", "config/initializers/omnitrack.rb"
+    end
+
+    def create_env_example
+      return if File.exist?(File.join(destination_root, ".env.example"))
+
+      copy_file "env.example", ".env.example"
+    end
+
+    def show_readme
+      readme "README" if behavior == :invoke
+    end
+
+    private
+
+    def readme(path)
+      say <<~MSG
+
+        ============================================================
+         OmniTrack installed successfully! 🎯
+        ============================================================
+
+        Next steps:
+          1. Copy .env.example to .env (gitignore .env) and set *_ENABLED + secrets
+          2. Optional: add gem "dotenv-rails" in development to load .env
+          3. Edit config/initializers/omnitrack.rb
+          4. Place <%= omnitrack_tags %> in your layout <head> (full-stack)
+          5. Call Omnitrack.track(...) from controllers/services (see USAGE.md)
+
+        Full docs: README.md — integration checklist: AI_GEM_SETUP.md
+        ============================================================
+
+      MSG
+    end
+  end
+end

data/lib/generators/omnitrack/install/templates/README

@@ -0,0 +1,19 @@
+================================================================================
+ OmniTrack
+================================================================================
+
+The installer created:
+
+  config/initializers/omnitrack.rb
+
+Next steps:
+
+  1. Set platform credentials (ENV, credentials, or inline in the initializer)
+  2. Full-stack apps: add <%= omnitrack_tags %> to your layout <head>
+  3. From controllers: use omnitrack_event / omnitrack_conversion / omnitrack_identify
+     or call Omnitrack.track(...) from services
+  4. Optional: set config.async in production to enqueue tracking (ActiveJob)
+
+Full documentation: see the omnitrack-rb README in the gem or your copy in the project.
+
+================================================================================

data/lib/generators/omnitrack/install/templates/env.example

@@ -0,0 +1,43 @@
+# OmniTrack (omnitrack-rb) — copy to .env in your Rails app and fill real values.
+# Never commit .env. Use "cp .env.example .env" and enable only what you need.
+#
+# Enable flags: set to the string "true" to turn an adapter on (see config/initializers/omnitrack.rb).
+
+# ---------------------------------------------------------------------------
+# Google Ads (server: Click Conversion Upload API)
+# ---------------------------------------------------------------------------
+GOOGLE_ADS_ENABLED=false
+GOOGLE_ADS_CUSTOMER_ID=
+GOOGLE_ADS_DEVELOPER_TOKEN=
+GOOGLE_ADS_ACCESS_TOKEN=
+GOOGLE_ADS_CONVERSION_ACTION_ID=
+# GOOGLE_ADS_LOGIN_CUSTOMER_ID=          # MCC / manager account only
+
+# ---------------------------------------------------------------------------
+# Google Analytics 4 (server: Measurement Protocol; browser: gtag in layout)
+# ---------------------------------------------------------------------------
+GA4_ENABLED=false
+GA4_MEASUREMENT_ID=
+GA4_API_SECRET=
+
+# ---------------------------------------------------------------------------
+# Meta (Facebook / Instagram) Conversions API + pixel
+# ---------------------------------------------------------------------------
+META_ENABLED=false
+META_PIXEL_ID=
+META_ACCESS_TOKEN=
+# META_TEST_EVENT_CODE=                  # optional: Events Manager test tool
+
+# ---------------------------------------------------------------------------
+# TikTok Ads
+# ---------------------------------------------------------------------------
+TIKTOK_ENABLED=false
+TIKTOK_PIXEL_ID=
+TIKTOK_ACCESS_TOKEN=
+
+# ---------------------------------------------------------------------------
+# Snapchat Ads
+# ---------------------------------------------------------------------------
+SNAPCHAT_ENABLED=false
+SNAPCHAT_PIXEL_ID=
+SNAPCHAT_ACCESS_TOKEN=

data/lib/generators/omnitrack/install/templates/initializer.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+# ==============================================================================
+# OmniTrack Configuration
+# Generated by: rails generate omnitrack:install
+# Docs: https://github.com/yourorg/omnitrack-rb
+# ==============================================================================
+
+Omnitrack.configure do |config|
+  # ---------------------------------------------------------------------------
+  # Mode
+  # ---------------------------------------------------------------------------
+  # :auto     — auto-detect (API-only Rails → :backend, otherwise :frontend)
+  # :frontend — inject JS tags, use cookies/session
+  # :backend  — server-side only (Conversions API / Measurement Protocol)
+  # :hybrid   — both simultaneously (recommended for full-stack apps)
+  config.mode = :auto
+
+  # ---------------------------------------------------------------------------
+  # Adapter Configuration
+  # ---------------------------------------------------------------------------
+  # Set enabled: true only for platforms you actively use.
+  # Missing credentials will be logged as warnings, not exceptions.
+
+  config.adapters = {
+    # ------ Google Ads -------------------------------------------------------
+    google_ads: {
+      enabled:              ENV["GOOGLE_ADS_ENABLED"] == "true",
+      customer_id:          ENV["GOOGLE_ADS_CUSTOMER_ID"],
+      developer_token:      ENV["GOOGLE_ADS_DEVELOPER_TOKEN"],
+      access_token:         ENV["GOOGLE_ADS_ACCESS_TOKEN"],
+      conversion_action_id: ENV["GOOGLE_ADS_CONVERSION_ACTION_ID"]
+      # login_customer_id:  ENV["GOOGLE_ADS_LOGIN_CUSTOMER_ID"]   # MCC accounts only
+    },
+
+    # ------ Google Analytics 4 -----------------------------------------------
+    google_analytics: {
+      enabled:        ENV["GA4_ENABLED"] == "true",
+      measurement_id: ENV["GA4_MEASUREMENT_ID"],   # e.g. G-XXXXXXXXXX
+      api_secret:     ENV["GA4_API_SECRET"]
+      # debug_mode: true   # Uncomment to use the GA4 validation endpoint
+    },
+
+    # ------ Meta (Facebook / Instagram) --------------------------------------
+    meta: {
+      enabled:         ENV["META_ENABLED"] == "true",
+      pixel_id:        ENV["META_PIXEL_ID"],
+      access_token:    ENV["META_ACCESS_TOKEN"]
+      # test_event_code: ENV["META_TEST_EVENT_CODE"]   # Events Manager test tool
+    },
+
+    # ------ TikTok Ads -------------------------------------------------------
+    tiktok: {
+      enabled:      ENV["TIKTOK_ENABLED"] == "true",
+      pixel_id:     ENV["TIKTOK_PIXEL_ID"],
+      access_token: ENV["TIKTOK_ACCESS_TOKEN"]
+    },
+
+    # ------ Snapchat Ads -----------------------------------------------------
+    snapchat: {
+      enabled:      ENV["SNAPCHAT_ENABLED"] == "true",
+      pixel_id:     ENV["SNAPCHAT_PIXEL_ID"],
+      access_token: ENV["SNAPCHAT_ACCESS_TOKEN"]
+    }
+
+    # ------ Custom adapter example -------------------------------------------
+    # my_platform: {
+    #   enabled:   true,
+    #   api_key:   ENV["MY_PLATFORM_API_KEY"]
+    # }
+  }
+
+  # ---------------------------------------------------------------------------
+  # Data Capture
+  # ---------------------------------------------------------------------------
+  # Automatically capture gclid, fbclid, ttclid, sclid, UTMs from every request
+  config.auto_capture = true
+
+  # ---------------------------------------------------------------------------
+  # Logging
+  # ---------------------------------------------------------------------------
+  # Writes structured JSON to log/omnitrack.log (separate from Rails main log)
+  config.log_level = Rails.env.production? ? :info : :debug
+
+  # Uncomment to write to a custom path:
+  # config.log_file = Rails.root.join("log", "omnitrack.log").to_s
+
+  # ---------------------------------------------------------------------------
+  # Async / Background Jobs
+  # ---------------------------------------------------------------------------
+  # When true, tracking calls are dispatched via ActiveJob (non-blocking).
+  # Requires ActiveJob to be configured with a real queue adapter in production.
+  config.async       = Rails.env.production?
+  config.queue_name  = :omnitrack
+
+  # ---------------------------------------------------------------------------
+  # Reliability
+  # ---------------------------------------------------------------------------
+  config.timeout     = 5   # seconds
+  config.max_retries = 3
+  config.retry_delay = 1   # seconds (exponential back-off applied automatically)
+
+  # ---------------------------------------------------------------------------
+  # Error hook (optional)
+  # ---------------------------------------------------------------------------
+  # Called with (error, adapter_instance) on every adapter failure.
+  # Useful for routing errors to Sentry, Honeybadger, etc.
+  #
+  # config.on_error = ->(error, adapter) {
+  #   Sentry.capture_exception(error, tags: { adapter: adapter.name })
+  # }
+end

data/lib/omnitrack/adapters/base.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module Omnitrack
+  module Adapters
+    # All platform adapters inherit from this class.
+    #
+    # Subclasses MUST implement:
+    #   - #track_event(event_name, payload)
+    #   - #track_conversion(data)
+    #   - #identify_user(user_data)
+    #
+    # Subclasses MAY override:
+    #   - #enabled?        — to add extra guards
+    #   - #validate_config — to check required keys
+    #
+    class Base
+      # Name used in logs, config lookup, and error messages.
+      # Override in subclass: self.adapter_name = :google_ads
+      class << self
+        attr_writer :adapter_name
+
+        def adapter_name
+          @adapter_name || name.to_s.split("::").last.underscore.to_sym
+        end
+
+        # Convenience: register a custom adapter with the dispatcher
+        def inherited(subclass)
+          super
+          Omnitrack::Registry.register(subclass) if defined?(Omnitrack::Registry)
+        end
+      end
+
+      attr_reader :config, :logger
+
+      def initialize(config: {}, logger: nil)
+        @config = config.transform_keys(&:to_sym)
+        @logger = logger || Omnitrack.logger
+        validate_config
+      end
+
+      # -------------------------------------------------------------------
+      # Interface — subclasses MUST implement these
+      # -------------------------------------------------------------------
+
+      # Track a named event.
+      # @param event_name [String, Symbol]
+      # @param payload    [Hash]  event-specific data
+      # @return [Omnitrack::Result]
+      def track_event(event_name, payload = {})
+        raise NotImplementedError, "#{self.class}#track_event not implemented"
+      end
+
+      # Track a conversion (purchase, lead, etc.).
+      # @param data [Hash]
+      # @return [Omnitrack::Result]
+      def track_conversion(data = {})
+        raise NotImplementedError, "#{self.class}#track_conversion not implemented"
+      end
+
+      # Identify / associate a user.
+      # @param user_data [Hash]  may include :email, :phone, :external_id
+      # @return [Omnitrack::Result]
+      def identify_user(user_data = {})
+        raise NotImplementedError, "#{self.class}#identify_user not implemented"
+      end
+
+      # -------------------------------------------------------------------
+      # Helpers available to subclasses
+      # -------------------------------------------------------------------
+
+      def enabled?
+        config.fetch(:enabled, false)
+      end
+
+      def name
+        self.class.adapter_name
+      end
+
+      protected
+
+      # Validate required config keys. Override to add adapter-specific checks.
+      def validate_config
+        # No-op in base; subclasses add their own required-key checks
+      end
+
+      # Assert that config contains a required key (raises ConfigurationError otherwise)
+      def require_config!(key, hint: nil)
+        return if config[key.to_sym].present? || (config[key.to_sym].is_a?(String) && !config[key.to_sym].empty?)
+
+        msg = "Omnitrack::Adapters::#{self.class.adapter_name} requires config[:#{key}]"
+        msg += " — #{hint}" if hint
+        raise Omnitrack::ConfigurationError, msg
+      end
+
+      # Safely execute a block, logging errors and returning an error Result
+      def safe_execute(event_name, &block)
+        logger.log_request(adapter: name, event: event_name)
+        started = monotonic_now
+
+        result = with_retries { block.call }
+
+        duration = elapsed_ms(started)
+        logger.log_response(adapter: name, event: event_name,
+                             status: result.status, duration_ms: duration)
+        result
+      rescue Omnitrack::AdapterError => e
+        logger.log_error(adapter: name, event: event_name, error: e)
+        notify_error(e)
+        Omnitrack::Result.failure(error: e, adapter: name)
+      rescue StandardError => e
+        wrapped = Omnitrack::AdapterError.new(e.message, original: e)
+        logger.log_error(adapter: name, event: event_name, error: wrapped)
+        notify_error(wrapped)
+        Omnitrack::Result.failure(error: wrapped, adapter: name)
+      end
+
+      # HTTP helper — performs a JSON POST with timeout + error wrapping
+      def http_post(url, body:, headers: {})
+        uri      = URI.parse(url)
+        timeout  = Omnitrack.config.timeout
+        use_ssl  = uri.scheme == "https"
+
+        Net::HTTP.start(uri.host, uri.port, use_ssl: use_ssl,
+                                            open_timeout: timeout,
+                                            read_timeout: timeout) do |http|
+          req = Net::HTTP::Post.new(uri.request_uri)
+          req["Content-Type"] = "application/json"
+          req["Accept"]       = "application/json"
+          headers.each { |k, v| req[k.to_s] = v }
+          req.body = JSON.generate(body)
+
+          response = http.request(req)
+
+          unless response.is_a?(Net::HTTPSuccess)
+            raise Omnitrack::AdapterError,
+                  "HTTP #{response.code} from #{uri.host}: #{response.body.to_s[0, 200]}"
+          end
+
+          response
+        end
+      rescue Net::OpenTimeout, Net::ReadTimeout => e
+        raise Omnitrack::AdapterError, "Timeout calling #{url}: #{e.message}"
+      rescue Omnitrack::AdapterError
+        raise
+      rescue StandardError => e
+        raise Omnitrack::AdapterError, "Network error calling #{url}: #{e.message}"
+      end
+
+      # SHA-256 hash helper (for PII normalization required by many platforms)
+      def sha256(value)
+        require "digest"
+        Digest::SHA256.hexdigest(value.to_s.strip.downcase)
+      end
+
+      private
+
+      def with_retries(&block)
+        max     = Omnitrack.config.max_retries.to_i
+        delay   = Omnitrack.config.retry_delay.to_f
+        attempt = 0
+
+        begin
+          attempt += 1
+          block.call
+        rescue Omnitrack::AdapterError => e
+          if attempt <= max
+            logger.warn("adapter.retry",
+                        adapter: name, attempt: attempt,
+                        error: e.message, retry_in_s: delay * (2**(attempt - 1)))
+            sleep(delay * (2**(attempt - 1)))
+            retry
+          end
+          raise
+        end
+      end
+
+      def notify_error(error)
+        cb = Omnitrack.config.on_error
+        cb.call(error, self) if cb.respond_to?(:call)
+      rescue StandardError
+        # Swallow errors in the error callback — never blow up
+      end
+
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def elapsed_ms(started)
+        ((monotonic_now - started) * 1000).round(2)
+      end
+    end
+  end
+end