track_relay 1.0.0

data/UPGRADING.md

@@ -0,0 +1,85 @@
+# Upgrading track_relay
+
+This document summarizes breaking changes between `track_relay` releases
+and how to migrate. For the full release history, see
+[CHANGELOG.md](CHANGELOG.md).
+
+## 0.1.0 → 0.2.0
+
+No breaking changes to the Ruby gem surface. New features added:
+
+- `TrackRelay::Subscribers::Ga4MeasurementProtocol` — wire with
+  `config.ga4_measurement_id` and `config.ga4_api_secret`.
+- `config.client_id_resolvers` — ordered chain (GA cookie, Ahoy
+  visitor, session fallback). Default chain preserves existing
+  `_ga` cookie behavior.
+- Subscriber-side `only:` / `except:` filters added to
+  `TrackRelay.subscribe(klass, only:, except:)`.
+- New rake task: `track_relay:lint:ga4` — audits your catalog
+  against GA4 constraints (snake_case, max 40 chars per event name,
+  max 25 custom params per event, reserved-name refusal).
+
+No host-app code changes are required. Optional adoption:
+`bundle exec rake track_relay:lint:ga4` and add the GA4 subscriber if
+you use Google Analytics.
+
+## 0.2.0 → 0.3.0
+
+**One BREAKING change (JavaScript client only). Ruby gem surface is
+unaffected.**
+
+### BREAKING: `init({ manifestUrl })` no longer requires `measurementId`
+
+In `@track_relay/client`, the `init({ manifestUrl })` call no longer
+requires a `measurementId` parameter. If your code relied on the
+missing-`measurementId` throw to detect misconfiguration, add an
+explicit assertion before calling `init`:
+
+```javascript
+import { init } from "@track_relay/client";
+
+const measurementId = process.env.GA4_MEASUREMENT_ID;
+if (!measurementId) {
+  throw new Error("GA4_MEASUREMENT_ID is required");
+}
+
+init({ manifestUrl: "/track_relay_catalog.json", measurementId });
+```
+
+### New features in 0.3.0
+
+- `TrackRelay::Subscribers::Ahoy` — server-side subscriber that uses
+  only the public Ahoy API (`controller.ahoy.track` /
+  `current_visit.track`). Wire with
+  `config.subscribe TrackRelay::Subscribers::Ahoy.new` (requires the
+  `ahoy_matey` gem).
+- `AhoyJs` export added in `@track_relay/client` — wraps
+  `window.ahoy.track` using the same event names as the server.
+
+## 0.3.0 → 1.0.0
+
+**No breaking changes.** 1.0.0 adds:
+
+- Three Rails generators: `track_relay:install`, `track_relay:event`,
+  `track_relay:subscriber`. Run
+  `bin/rails generate track_relay:install` in your existing app —
+  the inject step is idempotent and skips if
+  `include TrackRelay::ControllerTracking` is already present.
+- Public-API stability guarantee. See [README.md](README.md#public-api-stability)
+  for the stable surface; classes outside that list (`EventPayload`,
+  `Instrumenter`, `Dispatcher`, `Catalog`, `Current`, `DeliveryJob`,
+  `ClientId::*`) are internal and may change without a major bump.
+- E2E test coverage proving the install generator's output works
+  end-to-end through a real controller call.
+- Documentation: getting-started guide at [USAGE.md](USAGE.md).
+
+To upgrade:
+
+1. Bump your Gemfile pin to `gem "track_relay", "~> 1.0"`.
+2. `bundle update track_relay`.
+3. (Optional but recommended) Run
+   `bin/rails generate track_relay:install` to refresh your initializer
+   with the latest comments and ApplicationSubscriber base class.
+   Existing files will trigger a Thor "overwrite?" prompt; the inject
+   step is idempotent regardless.
+4. `bundle exec rake test` — should pass without further changes.

data/USAGE.md

@@ -0,0 +1,192 @@
+# track_relay — Getting Started
+
+A walkthrough of the typical install path, from `bundle install` to your
+first asserted-tracked event.
+
+## 1. Install
+
+Add to your Gemfile:
+
+```ruby
+gem "track_relay", "~> 1.0"
+```
+
+Then run:
+
+```bash
+bundle install
+bin/rails generate track_relay:install
+```
+
+The install generator scaffolds:
+- `config/initializers/track_relay.rb` — richly commented; one Logger
+  subscriber active by default, plus commented-out scaffolds for Test,
+  GA4, and Ahoy.
+- `config/track_relay/sample.rb` — a working `event :hello_world`
+  declaration to prove your install works.
+- `app/track_relay/subscribers/application_subscriber.rb` — base class
+  for your custom subscribers.
+- `include TrackRelay::ControllerTracking` injected into
+  `app/controllers/application_controller.rb` (idempotent — no-ops if
+  already present).
+
+Verify it works:
+
+```bash
+bundle exec rake test
+```
+
+This should pass cleanly.
+
+## 2. Define your first event
+
+The install generator created `config/track_relay/sample.rb`:
+
+```ruby
+TrackRelay.catalog do
+  event :hello_world do
+    string :message, required: true
+  end
+end
+```
+
+You can add more events to the same file, or generate one per file:
+
+```bash
+bin/rails generate track_relay:event ArticleViewed
+```
+
+That writes `config/track_relay/article_viewed.rb`:
+
+```ruby
+TrackRelay.catalog do
+  event :article_viewed do
+    # integer :id, required: true
+    # string  :slug, required: true
+  end
+end
+```
+
+Uncomment and edit the typed param stubs as needed. Supported types:
+`integer`, `string`, `float`, `boolean`, `datetime`. Validators:
+`required:`, `max:`, `in:`, `format:`, `sanitize:`.
+
+## 3. Track from a controller
+
+The install generator already added the `ControllerTracking` concern to
+your `ApplicationController`. Inside any controller action:
+
+```ruby
+class ArticlesController < ApplicationController
+  def show
+    track :article_viewed, id: params[:id].to_i, slug: "the-slug"
+    # ... render normally
+  end
+end
+```
+
+Tracking is fire-and-forget; subscribers run via ActiveJob unless they
+opt into `synchronous!`.
+
+## 4. Add subscribers
+
+The default install enables `TrackRelay::Subscribers::Logger` so every
+event hits `Rails.logger`. Edit `config/initializers/track_relay.rb` to
+wire additional destinations.
+
+For a custom subscriber:
+
+```bash
+bin/rails generate track_relay:subscriber Slack
+```
+
+That writes `app/track_relay/subscribers/slack_subscriber.rb`. Edit the
+`#deliver(payload)` body, then register in
+`config/initializers/track_relay.rb`:
+
+```ruby
+TrackRelay.configure do |config|
+  config.subscribe SlackSubscriber.new
+end
+```
+
+Built-in subscribers:
+- `TrackRelay::Subscribers::Test` — in-memory capture for tests
+- `TrackRelay::Subscribers::Logger` — Rails.logger sink
+- `TrackRelay::Subscribers::Ga4MeasurementProtocol` — GA4 server-side
+  (requires `ga4_measurement_id` + `ga4_api_secret` config)
+- `TrackRelay::Subscribers::Ahoy` — ahoy_matey integration (requires
+  the `ahoy_matey` gem in your Gemfile)
+
+> **Heads up — Ahoy bot exclusion.** ahoy_matey silently drops events
+> from requests that look bot-like (logged as `[ahoy] Event excluded`).
+> If you're testing via `curl`, Postman, or anything with a non-browser
+> User-Agent, no row will land in `ahoy_events`. Use a real browser or
+> pass a Chrome/Firefox UA header. This is Ahoy's behavior, not
+> track_relay's.
+
+## 5. Test your events
+
+`track_relay` ships Minitest and RSpec test helpers. In Minitest:
+
+```ruby
+require "track_relay/testing/helpers"
+
+class ArticlesControllerTest < ActionDispatch::IntegrationTest
+  include TrackRelay::Testing::Helpers
+
+  test "show tracks article_viewed" do
+    get article_path(42)
+    assert_tracked :article_viewed, id: 42, slug: "the-slug"
+  end
+end
+```
+
+The helpers auto-call `TrackRelay.test_mode!` in setup and
+`test_mode_off!` in teardown.
+
+For RSpec, use the `have_tracked(:event).with(params)` matcher exposed
+by `TrackRelay::Testing::RSpec` — see the README for full details.
+
+## 6. Untyped events and the linter
+
+By default, `untyped_events_allowed = true` — `track :anything` works
+without a catalog entry. To audit untyped events, enable the JSONL log:
+
+```ruby
+config.untyped_log_path = Rails.root.join("tmp/track_relay_untyped.jsonl")
+```
+
+Then run:
+
+```bash
+bundle exec rake track_relay:lint
+```
+
+This reports every untyped event seen, with file and line context, so
+you can promote them to typed catalog entries.
+
+## 7. GA4 + client-side
+
+For GA4 server-side, set the credentials and subscribe:
+
+```ruby
+config.ga4_measurement_id = ENV.fetch("GA4_MEASUREMENT_ID")
+config.ga4_api_secret     = ENV.fetch("GA4_API_SECRET")
+config.subscribe TrackRelay::Subscribers::Ga4MeasurementProtocol.new
+```
+
+Then run `bundle exec rake track_relay:lint:ga4` to audit your catalog
+against GA4 constraints (snake_case names, max 40 chars, max 25 custom
+params per event, reserved-name refusal).
+
+For client-side, install `@track_relay/client` from npm and call
+`init({ manifestUrl: "/track_relay_catalog.json" })` after the manifest
+is generated by `bundle exec rake track_relay:manifest` (or
+automatically by the Railtie's asset-precompile hook).
+
+## Next
+
+- [README.md](README.md) — full feature reference
+- [UPGRADING.md](UPGRADING.md) — migration notes if upgrading from 0.x
+- [CHANGELOG.md](CHANGELOG.md) — release history

data/lib/generators/track_relay/event/event_generator.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module TrackRelay
+  module Generators
+    class EventGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a typed catalog entry stub at config/track_relay/<name>.rb."
+
+      def create_event_file
+        template "event.rb.tt", "config/track_relay/#{file_name}.rb"
+      end
+    end
+  end
+end

data/lib/generators/track_relay/event/templates/event.rb.tt

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# <%= class_name %> event — defined here so the track_relay Railtie
+# autoloads it from config/track_relay/ at boot.
+#
+# Track this event from a controller or job:
+#   track :<%= file_name %>, # required + optional params here
+#
+# Run `bundle exec rake track_relay:lint:ga4` to audit GA4 constraints.
+
+TrackRelay.catalog do
+  event :<%= file_name %> do
+    # Uncomment and edit:
+    # integer :id,    required: true
+    # string  :label, required: true
+    # string  :category
+    # float   :value
+    # boolean :active
+    # datetime :occurred_at
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module TrackRelay
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a TrackRelay initializer, sample catalog, and ApplicationSubscriber, and includes TrackRelay::ControllerTracking in ApplicationController."
+
+      def create_initializer
+        template "initializer.rb.tt", "config/initializers/track_relay.rb"
+      end
+
+      def create_sample_catalog
+        template "sample_catalog.rb.tt", "config/track_relay/sample.rb"
+      end
+
+      def create_application_subscriber
+        template "application_subscriber.rb.tt", "app/track_relay/subscribers/application_subscriber.rb"
+      end
+
+      def inject_controller_tracking
+        controller_path = "app/controllers/application_controller.rb"
+        unless File.exist?(File.join(destination_root, controller_path))
+          say_status :skip, "#{controller_path} not found; add `include TrackRelay::ControllerTracking` manually", :yellow
+          return
+        end
+
+        existing = File.read(File.join(destination_root, controller_path))
+        if existing.include?("TrackRelay::ControllerTracking")
+          say_status :identical, "#{controller_path} already includes TrackRelay::ControllerTracking", :blue
+          return
+        end
+
+        inject_into_class controller_path, "ApplicationController", "  include TrackRelay::ControllerTracking\n"
+      end
+
+      def post_install_message
+        say ""
+        say "TrackRelay installed.", :green
+        say "  Edit config/initializers/track_relay.rb to wire subscribers."
+        say "  Edit config/track_relay/sample.rb (or rails g track_relay:event NAME) to define events."
+        say "  Run `bundle exec rake test` — it should pass cleanly out of the box."
+      end
+    end
+  end
+end

data/lib/generators/track_relay/install/templates/application_subscriber.rb.tt

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# ApplicationSubscriber — base class for your custom track_relay subscribers.
+#
+# Subclass this to add your own destinations:
+#
+#   class MyAnalyticsSubscriber < ApplicationSubscriber
+#     def deliver(payload)
+#       # send payload.name + payload.params somewhere
+#     end
+#   end
+#
+# Register in config/initializers/track_relay.rb:
+#
+#   TrackRelay.configure do |config|
+#     config.subscribe MyAnalyticsSubscriber.new
+#   end
+#
+# Run `rails g track_relay:subscriber NAME` to scaffold a subscriber.
+class ApplicationSubscriber < TrackRelay::Subscribers::Base
+  # Uncomment to run inline instead of via DeliveryJob:
+  # synchronous!
+
+  # payload.name      => :event_name (Symbol)
+  # payload.params    => { key: value, ... } (typed and coerced)
+  # payload.context   => { controller:, action:, client_id:, user:, ... }
+  # payload.timestamp => Time
+  def deliver(payload)
+    raise NotImplementedError, "#{self.class.name} must implement #deliver(payload)"
+  end
+end

data/lib/generators/track_relay/install/templates/initializer.rb.tt

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# TrackRelay configuration
+# See https://github.com/dchuk/track_relay#readme for full documentation.
+# Run `bundle exec rake track_relay:lint` to audit untyped events.
+
+TrackRelay.configure do |config|
+  # ----- Subscribers --------------------------------------------------------
+  # Logger subscriber: writes every event to Rails.logger and (optionally)
+  # captures untyped events to a JSONL file for audit.
+  config.subscribe TrackRelay::Subscribers::Logger.new
+
+  # Test subscriber: in-memory capture for use with `assert_tracked`.
+  # Prefer `TrackRelay.test_mode!` in test setup over registering this here.
+  # config.subscribe TrackRelay::Subscribers::Test.new if Rails.env.test?
+
+  # ----- GA4 Measurement Protocol (server-side) ----------------------------
+  # config.ga4_measurement_id = ENV.fetch("GA4_MEASUREMENT_ID", nil)
+  # config.ga4_api_secret     = ENV.fetch("GA4_API_SECRET", nil)
+  # config.ga4_use_eu_endpoint = false
+  # config.subscribe TrackRelay::Subscribers::Ga4MeasurementProtocol.new
+
+  # ----- Ahoy (server-side) ------------------------------------------------
+  # Requires the `ahoy_matey` gem in your Gemfile.
+  # config.subscribe TrackRelay::Subscribers::Ahoy.new
+
+  # ----- Untyped events ----------------------------------------------------
+  # Allow tracking calls for events not yet declared in the catalog.
+  # When false, untyped events raise in dev/test and log in production.
+  # config.untyped_events_allowed = true
+
+  # Path for the untyped-events audit log (used by `rake track_relay:lint`).
+  # config.untyped_log_path = Rails.root.join("tmp/track_relay_untyped.jsonl")
+
+  # ----- Validation behavior -----------------------------------------------
+  # In production, subscriber errors are swallowed and logged (default true).
+  # In development/test, they are re-raised after fan-out (default false).
+  # config.swallow_subscriber_errors = false
+
+  # Raise on schema validation errors (default true in dev/test, false in prod).
+  # config.raise_on_validation_error = true
+end

data/lib/generators/track_relay/install/templates/sample_catalog.rb.tt

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# Sample catalog — define your events here.
+#
+# The Railtie autoloads every *.rb file under config/track_relay/ at boot
+# and reloads them on every code reload in development.
+#
+# Run `rails g track_relay:event NAME` to scaffold a new event in its own file.
+
+TrackRelay.catalog do
+  # Tutorial event: prove your install works.
+  #   In a controller action: `track :hello_world, message: "hi"`
+  #   In a test: `assert_tracked :hello_world, message: "hi"`
+  event :hello_world do
+    string :message, required: true
+  end
+end

data/lib/generators/track_relay/subscriber/subscriber_generator.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module TrackRelay
+  module Generators
+    class SubscriberGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a subscriber class stub at app/track_relay/subscribers/<name>_subscriber.rb."
+
+      def create_subscriber_file
+        template "subscriber.rb.tt", "app/track_relay/subscribers/#{file_name}_subscriber.rb"
+      end
+    end
+  end
+end

data/lib/generators/track_relay/subscriber/templates/subscriber.rb.tt

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# <%= class_name %>Subscriber — custom track_relay subscriber.
+#
+# Register in config/initializers/track_relay.rb:
+#
+#   TrackRelay.configure do |config|
+#     config.subscribe <%= class_name %>Subscriber.new
+#   end
+#
+# If you ran `rails g track_relay:install`, you can subclass
+# ApplicationSubscriber instead of TrackRelay::Subscribers::Base
+# to share behavior across your subscribers.
+class <%= class_name %>Subscriber < TrackRelay::Subscribers::Base
+  # Uncomment to run inline instead of via DeliveryJob:
+  # synchronous!
+
+  # Filter to specific events only:
+  # filter only: %i[<%= file_name %>]
+
+  # payload.name      => :event_name (Symbol)
+  # payload.params    => { key: value, ... } (typed and coerced)
+  # payload.context   => { controller:, action:, client_id:, user:, ... }
+  # payload.timestamp => Time
+  def deliver(payload)
+    # TODO: send payload to your destination
+  end
+end

data/lib/tasks/track_relay.rake

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+# Audit untyped (non-catalog) events captured in the JSONL sink written
+# by {TrackRelay::Subscribers::Logger}.
+#
+# Both tasks ABORT WITH NONZERO exit when
+# `TrackRelay.config.untyped_log_path` is unset. From 01-CONTEXT.md /
+# the plan's must_haves: a silent exit-0 on a misconfigured audit task
+# is a footgun (the user thinks the audit "passed" when in fact nothing
+# was ever recorded). When the path IS set, the task exits 0 — lint is
+# a report, not a gate.
+
+# Loaded via require_relative (not the gem's umbrella `require
+# "track_relay"`) so this rake file stays file-disjoint with Plan 02-02
+# — `lib/track_relay.rb` is owned by that plan in the same wave.
+require_relative "../track_relay/manifest"
+
+namespace :track_relay do
+  desc "Audit untyped events captured in the JSONL sink (config.untyped_log_path)"
+  task lint: :environment do
+    path = TrackRelay.config.untyped_log_path
+    if path.nil?
+      abort <<~MSG
+        track_relay: untyped_log_path is not configured.
+        Set it in config/initializers/track_relay.rb:
+
+          TrackRelay.configure do |c|
+            c.untyped_log_path = Rails.root.join("tmp/track_relay_untyped.jsonl")
+            c.subscribe TrackRelay::Subscribers::Logger.new
+          end
+      MSG
+    end
+
+    TrackRelay::Linter.new(path).print
+  end
+
+  desc "Audit untyped events and emit JSON report to stdout"
+  task "lint:json" => :environment do
+    path = TrackRelay.config.untyped_log_path
+    abort "track_relay: untyped_log_path is not configured" if path.nil?
+
+    puts TrackRelay::Linter.new(path).to_json
+  end
+
+  desc "Audit untyped events for GA4 event-name constraint violations"
+  task "lint:ga4" => :environment do
+    path = TrackRelay.config.untyped_log_path
+    if path.nil?
+      abort <<~MSG
+        track_relay: untyped_log_path is not configured.
+        Set it in config/initializers/track_relay.rb:
+
+          TrackRelay.configure do |c|
+            c.untyped_log_path = Rails.root.join("tmp/track_relay_untyped.jsonl")
+            c.subscribe TrackRelay::Subscribers::Logger.new
+          end
+      MSG
+    end
+
+    clean = TrackRelay::Linter.new(path).print_ga4
+    # Exit non-zero when violations exist, zero when clean. Lets CI
+    # pipelines gate on `rake track_relay:lint:ga4` without parsing
+    # output.
+    exit(clean ? 0 : 1)
+  end
+
+  desc "Generate public/track_relay_catalog.json from the loaded catalog"
+  task manifest: :environment do
+    # Footgun guard (RISK-04): an empty manifest tells the JS client
+    # "no schema, accept everything" — silently. Abort loudly so the
+    # operator notices the catalog never loaded.
+    if TrackRelay::Catalog.all.empty?
+      abort "[track_relay] aborting: catalog is empty (no events registered — check config/track_relay/**/*.rb)"
+    end
+
+    path = TrackRelay::Manifest.write!
+    count = TrackRelay::Catalog.all.size
+    puts "[track_relay] manifest written to #{path} (#{count} #{(count == 1) ? "event" : "events"})"
+  end
+end

data/lib/track_relay/catalog.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "track_relay/errors"
+
+module TrackRelay
+  # Process-wide registry of event definitions and user properties.
+  #
+  # The {DSL::EventBuilder} pushes definitions in via {register}; the
+  # rest of the gem (and host applications) read them out via {lookup},
+  # {defined?}, and {all}.
+  #
+  # State is module-level by design — the gem assumes one catalog per
+  # Ruby process, populated during boot. Tests that need isolation call
+  # {clear!} in `setup` / `teardown` to reset between cases.
+  #
+  # @example Registering and looking up an event
+  #   TrackRelay.catalog do
+  #     event :article_viewed do
+  #       integer :article_id, required: true
+  #     end
+  #   end
+  #
+  #   TrackRelay::Catalog.lookup(:article_viewed)
+  #   # => #<TrackRelay::EventDefinition name=:article_viewed ...>
+  module Catalog
+    @definitions = {}
+    @user_properties = {}
+
+    class << self
+      # @return [Hash{Symbol => Symbol}] catalog-wide user properties
+      attr_reader :user_properties
+
+      # Register a new {EventDefinition} in the catalog.
+      #
+      # @param definition [EventDefinition]
+      # @raise [TrackRelay::CatalogError] when an event with the same
+      #   name is already registered (defensive guard against catalog
+      #   bugs that could silently shadow events)
+      # @return [EventDefinition]
+      def register(definition)
+        if @definitions.key?(definition.name)
+          raise CatalogError,
+            "Event #{definition.name.inspect} is already registered. Call TrackRelay::Catalog.clear! before re-registering (e.g. in tests)."
+        end
+        @definitions[definition.name] = definition
+      end
+
+      # Register a catalog-wide user property.
+      #
+      # @param name [Symbol]
+      # @param type [Symbol]
+      # @return [Symbol] the type, for chaining
+      def register_user_property(name, type)
+        @user_properties[name] = type
+      end
+
+      # @param name [Symbol]
+      # @return [EventDefinition, nil]
+      def lookup(name)
+        @definitions[name]
+      end
+
+      # @param name [Symbol]
+      # @return [Boolean] whether an event with the given name is
+      #   registered
+      def defined?(name)
+        @definitions.key?(name)
+      end
+
+      # @return [Array<EventDefinition>] frozen array of all registered
+      #   definitions
+      def all
+        @definitions.values.freeze
+      end
+
+      # Reset the registry. Intended for test isolation; do not call in
+      # production code.
+      #
+      # @return [void]
+      def clear!
+        @definitions = {}
+        @user_properties = {}
+      end
+    end
+  end
+end