helios-tracker 0.0.0 → 0.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a496bc5169788a1c1fc3655f928f7b493137b4421d2138666686b2d921a35802
-  data.tar.gz: 7eb796537bca7f003082b13002bb6fb2b950c48d4a5698f9e53c6f4aa5e92a71
+  metadata.gz: bfbf5eff1c6c46819373a06aed86d64e3d0ed9b267fee8832c22ceabd5f0d618
+  data.tar.gz: 0c80b7f065b45b086bbfabfa91d3993bab8372cffc6638e100ab9070b5c59375
 SHA512:
-  metadata.gz: 379ec3dd8d9c8cfe760fc853668f4c285381ee732984cd28904bd9ad66511d1cfba16066f178dc164cfc3b78381c5f525ec7cad0e7abc6548609b20cc5750c82
-  data.tar.gz: 278e4be3f8374e22657b89fdfc9bf49fe011364f1102b4354e60adaf74ba81b1ac4cc2b370e16ab9cbedd112b1a4aa1a572e87b758ce00c6053ff442e7e7c53d
+  metadata.gz: 54e55ca996db4f656a856434275b31c9884f91721f999752e49af7c59cd76351430ccee6e857c899914b8ad049030c398b71f79ba2f0e244f3f762b30dda297c
+  data.tar.gz: 594d5ae967a43ce5dad2f644f9decd463b47c68af82675cff271a3d9a23b1bddbcd0fbf107611ed9b7c87b2b71745a04fb81c002cc7894b9319282373dececb6

data/.gitignore

@@ -0,0 +1 @@
+helios-tracker-*.gem

data/Gemfile.lock

@@ -0,0 +1,233 @@
+PATH
+  remote: .
+  specs:
+    helios-tracker (0.0.0)
+      ffaker (~> 2.16)
+      rails (> 5.1)
+      universal-track-manager (~> 0.8)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    action_text-trix (2.1.18)
+      railties
+    actioncable (8.1.3)
+      actionpack (= 8.1.3)
+      activesupport (= 8.1.3)
+      nio4r (~> 2.0)
+      websocket-driver (>= 0.6.1)
+      zeitwerk (~> 2.6)
+    actionmailbox (8.1.3)
+      actionpack (= 8.1.3)
+      activejob (= 8.1.3)
+      activerecord (= 8.1.3)
+      activestorage (= 8.1.3)
+      activesupport (= 8.1.3)
+      mail (>= 2.8.0)
+    actionmailer (8.1.3)
+      actionpack (= 8.1.3)
+      actionview (= 8.1.3)
+      activejob (= 8.1.3)
+      activesupport (= 8.1.3)
+      mail (>= 2.8.0)
+      rails-dom-testing (~> 2.2)
+    actionpack (8.1.3)
+      actionview (= 8.1.3)
+      activesupport (= 8.1.3)
+      nokogiri (>= 1.8.5)
+      rack (>= 2.2.4)
+      rack-session (>= 1.0.1)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+      useragent (~> 0.16)
+    actiontext (8.1.3)
+      action_text-trix (~> 2.1.15)
+      actionpack (= 8.1.3)
+      activerecord (= 8.1.3)
+      activestorage (= 8.1.3)
+      activesupport (= 8.1.3)
+      globalid (>= 0.6.0)
+      nokogiri (>= 1.8.5)
+    actionview (8.1.3)
+      activesupport (= 8.1.3)
+      builder (~> 3.1)
+      erubi (~> 1.11)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+    activejob (8.1.3)
+      activesupport (= 8.1.3)
+      globalid (>= 0.3.6)
+    activemodel (8.1.3)
+      activesupport (= 8.1.3)
+    activerecord (8.1.3)
+      activemodel (= 8.1.3)
+      activesupport (= 8.1.3)
+      timeout (>= 0.4.0)
+    activestorage (8.1.3)
+      actionpack (= 8.1.3)
+      activejob (= 8.1.3)
+      activerecord (= 8.1.3)
+      activesupport (= 8.1.3)
+      marcel (~> 1.0)
+    activesupport (8.1.3)
+      base64
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.3.1)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      json
+      logger (>= 1.4.2)
+      minitest (>= 5.1)
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0, >= 2.0.5)
+      uri (>= 0.13.1)
+    base64 (0.3.0)
+    bigdecimal (4.1.2)
+    builder (3.3.0)
+    concurrent-ruby (1.3.6)
+    connection_pool (3.0.2)
+    crass (1.0.6)
+    date (3.5.1)
+    drb (2.2.3)
+    erb (6.0.4)
+    erubi (1.13.1)
+    ffaker (2.25.0)
+    globalid (1.3.0)
+      activesupport (>= 6.1)
+    i18n (1.14.8)
+      concurrent-ruby (~> 1.0)
+    io-console (0.8.2)
+    irb (1.18.0)
+      pp (>= 0.6.0)
+      prism (>= 1.3.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    json (2.19.5)
+    logger (1.7.0)
+    loofah (2.25.1)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.12.0)
+    mail (2.9.0)
+      logger
+      mini_mime (>= 0.1.1)
+      net-imap
+      net-pop
+      net-smtp
+    marcel (1.1.0)
+    mini_mime (1.1.5)
+    minitest (6.0.6)
+      drb (~> 2.0)
+      prism (~> 1.5)
+    net-imap (0.6.4)
+      date
+      net-protocol
+    net-pop (0.1.2)
+      net-protocol
+    net-protocol (0.2.2)
+      timeout
+    net-smtp (0.5.1)
+      net-protocol
+    nio4r (2.7.5)
+    nokogiri (1.19.3-aarch64-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.19.3-aarch64-linux-musl)
+      racc (~> 1.4)
+    nokogiri (1.19.3-arm-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.19.3-arm-linux-musl)
+      racc (~> 1.4)
+    nokogiri (1.19.3-arm64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.19.3-x86_64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.19.3-x86_64-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.19.3-x86_64-linux-musl)
+      racc (~> 1.4)
+    pp (0.6.3)
+      prettyprint
+    prettyprint (0.2.0)
+    prism (1.9.0)
+    psych (5.3.1)
+      date
+      stringio
+    racc (1.8.1)
+    rack (3.2.6)
+    rack-session (2.1.2)
+      base64 (>= 0.1.0)
+      rack (>= 3.0.0)
+    rack-test (2.2.0)
+      rack (>= 1.3)
+    rackup (2.3.1)
+      rack (>= 3)
+    rails (8.1.3)
+      actioncable (= 8.1.3)
+      actionmailbox (= 8.1.3)
+      actionmailer (= 8.1.3)
+      actionpack (= 8.1.3)
+      actiontext (= 8.1.3)
+      actionview (= 8.1.3)
+      activejob (= 8.1.3)
+      activemodel (= 8.1.3)
+      activerecord (= 8.1.3)
+      activestorage (= 8.1.3)
+      activesupport (= 8.1.3)
+      bundler (>= 1.15.0)
+      railties (= 8.1.3)
+    rails-dom-testing (2.3.0)
+      activesupport (>= 5.0.0)
+      minitest
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.7.0)
+      loofah (~> 2.25)
+      nokogiri (>= 1.15.7, != 1.16.7, != 1.16.6, != 1.16.5, != 1.16.4, != 1.16.3, != 1.16.2, != 1.16.1, != 1.16.0.rc1, != 1.16.0)
+    railties (8.1.3)
+      actionpack (= 8.1.3)
+      activesupport (= 8.1.3)
+      irb (~> 1.13)
+      rackup (>= 1.0.0)
+      rake (>= 12.2)
+      thor (~> 1.0, >= 1.2.2)
+      tsort (>= 0.2)
+      zeitwerk (~> 2.6)
+    rake (13.4.2)
+    rdoc (7.2.0)
+      erb
+      psych (>= 4.0.0)
+      tsort
+    reline (0.6.3)
+      io-console (~> 0.5)
+    securerandom (0.4.1)
+    stringio (3.2.0)
+    thor (1.5.0)
+    timeout (0.6.1)
+    tsort (0.2.0)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    universal-track-manager (0.8.0.1)
+      rails (> 5.1)
+    uri (1.1.1)
+    useragent (0.16.11)
+    websocket-driver (0.8.0)
+      base64
+      websocket-extensions (>= 0.1.0)
+    websocket-extensions (0.1.5)
+    zeitwerk (2.7.5)
+
+PLATFORMS
+  aarch64-linux-gnu
+  aarch64-linux-musl
+  arm-linux-gnu
+  arm-linux-musl
+  arm64-darwin
+  x86_64-darwin
+  x86_64-linux-gnu
+  x86_64-linux-musl
+
+DEPENDENCIES
+  helios-tracker!
+
+BUNDLED WITH
+   2.6.9

data/README.md

@@ -0,0 +1,197 @@
+# Helios Tracker
+
+A Rails engine that exposes your app's user, visit, and email-suppression data as JSON API endpoints for [Helios Crusader](https://heliosflow.ai/) to consume.
+
+Helios pulls from these endpoints daily to track signups, logins, click-throughs, and blocked emails — automatically moving targets from cold to warm to hot based on engagement.
+
+## Requirements
+
+- Rails >= 5.1
+- Ruby >= 2.7
+- [Universal Track Manager](https://github.com/jasonfb/universal_track_manager) (installed automatically)
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "helios-tracker"
+```
+
+Then run:
+
+```sh
+bundle install
+rails generate helios_tracker:install
+rails db:migrate
+```
+
+The install generator will:
+
+1. Install and configure Universal Track Manager (visit tracking)
+2. Add `include UniversalTrackManagerConcern` to your `ApplicationController`
+3. Create a `blocked_emails` migration
+4. Generate `config/initializers/helios_tracker.rb`
+5. Mount the engine in your routes
+
+If Universal Track Manager is already installed, the generator will detect it and skip that step.
+
+### Generator Options
+
+```sh
+# Specify your User model class (default: "User")
+rails generate helios_tracker:install --user-class=Account
+
+# Skip UTM installation if already set up
+rails generate helios_tracker:install --skip-utm
+```
+
+## Configuration
+
+Set your API key in your environment (`.env`, credentials, or server config):
+
+```
+HELIOS_TRACKER_API_KEY=your_secret_key_here
+```
+
+Then edit `config/initializers/helios_tracker.rb`:
+
+```ruby
+HeliosTracker.configure do |config|
+  # ---- Users ----
+
+  config.user_class_name = "User"
+
+  # Return users updated since query_start.
+  # Receives (query_start, params). Must return an ActiveRecord relation.
+  config.user_scope = ->(query_start, params) {
+    User.where.not(email: "")
+        .where("updated_at > ?", query_start)
+  }
+
+  # Map API field names to model attributes or lambdas.
+  # :email is required. All others are optional.
+  config.user_fields = {
+    email:                      :email,
+    created_at:                 :created_at,
+    source_ip:                  :source_ip,
+    login_count:                :login_count,
+    accounts_owned_count:       ->(user) { user.accounts_owned_count },
+    free_accounts_count:        ->(user) { user.free_accounts_count },
+    unsubscribe_nonce:          :unsubscribe_nonce,
+    first_unconfirmed_visit_id: :first_unconfirmed_visit_id,
+    login_attempt_count:        :login_attempt_count,
+    app_open_days_count:        :app_open_days_count,
+  }
+
+  # ---- Visits ----
+
+  config.visit_scope = ->(query_start, params) {
+    UniversalTrackManager::Visit.where.not(hmid: nil)
+        .where("updated_at > ?", query_start)
+  }
+
+  # :hmid is required.
+  config.visit_fields = {
+    hmid:                  :hmid,
+    visited_download_page: ->(visit) { visit.visited_download_page? },
+  }
+
+  # ---- Blocked Emails ----
+
+  config.blocked_email_class_name = "BlockedEmail"
+
+  config.blocked_email_scope = ->(query_start, params) {
+    BlockedEmail.where("created_at > ?", query_start)
+  }
+
+  config.blocked_email_fields = {
+    email:  :email,
+    source: :source,
+  }
+
+end
+```
+
+### Field Mapping
+
+Each field in `user_fields`, `visit_fields`, and `blocked_email_fields` can be either:
+
+- **A symbol** — calls that method on the record (e.g., `:email` calls `user.email`)
+- **A lambda** — receives the record and returns a value (e.g., `->(user) { user.accounts.count }`)
+
+Fields you don't include in the hash are silently omitted from the API response.
+
+### Scoping with Lambdas
+
+The `user_scope`, `visit_scope`, and `blocked_email_scope` lambdas receive two arguments:
+
+| Argument      | Description                                           |
+|---------------|-------------------------------------------------------|
+| `query_start` | A `YYYY-MM-DD` date string sent by Helios             |
+| `params`      | The full request params (includes `domain_name`, etc.) |
+
+Use these to filter your records however your app requires:
+
+```ruby
+# Multi-domain example
+config.user_scope = ->(query_start, params) {
+  domain = Domain.find_by(name: params[:domain_name])
+  User.where.not(email: "")
+      .where(domain_id: domain&.id)
+      .where("updated_at > ?", query_start)
+}
+```
+
+## API Endpoints
+
+All endpoints require authentication via `HELIOS_TRACKER_API_KEY`, passed as either:
+
+- **Header:** `Authorization: Bearer <API_KEY>`
+- **Query parameter:** `?api_key=<API_KEY>`
+
+### GET /api/all_users.json
+
+Returns users updated since `query_start`.
+
+| Parameter    | Required | Description                          |
+|------------- |----------|--------------------------------------|
+| `query_start`| yes      | `YYYY-MM-DD` — records from this date onward |
+| `domain_name`| no       | Domain filter (if your app is multi-domain)  |
+| `api_key`    | yes      | Shared API key                       |
+
+### GET /api/all_visits.json
+
+Returns visits with a non-null `hmid` since `query_start`.
+
+| Parameter    | Required | Description                          |
+|------------- |----------|--------------------------------------|
+| `query_start`| yes      | `YYYY-MM-DD` — visits from this date onward  |
+| `api_key`    | yes      | Shared API key                       |
+
+### GET /api/blocked_emails.json
+
+Returns suppressed emails (bounces, unsubscribes) since `query_start`.
+
+| Parameter    | Required | Description                          |
+|------------- |----------|--------------------------------------|
+| `query_start`| yes      | `YYYY-MM-DD` — blocks from this date onward  |
+| `api_key`    | yes      | Shared API key                       |
+
+## How It Works
+
+Helios calls your endpoints once per day (9:00 AM UTC). Each call includes a `query_start` date — your scopes should return records created or updated on or after that date.
+
+**Important for window-based fields:** `login_count`, `accounts_owned_count`, and `app_open_days_count` should return only counts within the `query_start..now` window. Helios accumulates these across successive pulls. Returning lifetime totals will result in double-counting.
+
+Helios handles duplicates gracefully (find-or-create logic), so returning the same records on a re-request is safe.
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.
+
+## Links
+
+- [Helios Flow](https://heliosflow.ai/)
+- [Universal Track Manager](https://github.com/jasonfb/universal_track_manager)
+- [Source Code](https://github.com/heliosdev-shop/helios-tracker)

data/app/controllers/concerns/helios_tracker_concern.rb

@@ -0,0 +1,17 @@
+module HeliosTrackerConcern
+  extend ActiveSupport::Concern
+
+  included do
+    before_action :track_hmid
+  end
+
+  private
+
+  def track_hmid
+    return unless params['hmid'].present?
+    return unless session['visit_id'].present?
+
+    visit = UniversalTrackManager::Visit.find_by(id: session['visit_id'])
+    visit&.update(hmid: params['hmid'])
+  end
+end

data/app/controllers/helios_tracker/api/all_users_controller.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module HeliosTracker
+  module Api
+    class AllUsersController < BaseController
+      def index
+        return unless require_query_start!
+
+        config = HeliosTracker.config
+
+        if config.user_scope.nil?
+          render json: { error: 'HeliosTracker.user_scope is not configured' }, status: :internal_server_error
+          return
+        end
+
+        users = config.user_scope.call(query_start, params)
+        render json: users.map { |user| config.serialize_record(user, config.user_fields) }
+      end
+    end
+  end
+end

data/app/controllers/helios_tracker/api/all_visits_controller.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module HeliosTracker
+  module Api
+    class AllVisitsController < BaseController
+      def index
+        return unless require_query_start!
+
+        config = HeliosTracker.config
+
+        if config.visit_scope.nil?
+          render json: { error: 'HeliosTracker.visit_scope is not configured' }, status: :internal_server_error
+          return
+        end
+
+        visits = config.visit_scope.call(query_start, params)
+        render json: visits.map { |visit| config.serialize_record(visit, config.visit_fields) }
+      end
+    end
+  end
+end

data/app/controllers/helios_tracker/api/base_controller.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module HeliosTracker
+  module Api
+    class BaseController < ActionController::API
+      before_action :authenticate_api!
+
+      private
+
+      def authenticate_api!
+        api_key = ENV['HELIOS_TRACKER_API_KEY']
+
+        if api_key.blank?
+          raise "No HELIOS_TRACKER_API_KEY set in environment. Set this in your .env or production config."
+        end
+
+        header_token = request.headers['Authorization']&.sub(/^Bearer\s+/, '')
+
+        if header_token != api_key && params[:api_key] != api_key
+          render json: { error: 'Unauthorized' }, status: :unauthorized
+        end
+      end
+
+      def query_start
+        params[:query_start]
+      end
+
+      def require_query_start!
+        if query_start.blank?
+          render json: { error: 'No `query_start` date specified' }, status: :bad_request
+          false
+        else
+          true
+        end
+      end
+    end
+  end
+end

data/app/controllers/helios_tracker/api/blocked_emails_controller.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module HeliosTracker
+  module Api
+    class BlockedEmailsController < BaseController
+      def index
+        return unless require_query_start!
+
+        config = HeliosTracker.config
+
+        if config.blocked_email_scope.nil?
+          render json: []
+          return
+        end
+
+        records = config.blocked_email_scope.call(query_start, params)
+        render json: records.map { |record| config.serialize_record(record, config.blocked_email_fields) }
+      end
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,7 @@
+HeliosTracker::Engine.routes.draw do
+  namespace :api do
+    resources :all_users, only: [:index]
+    resources :all_visits, only: [:index]
+    resources :blocked_emails, only: [:index]
+  end
+end

data/lib/generators/helios_tracker/install_generator.rb

@@ -0,0 +1,118 @@
+require 'rails/generators'
+require 'rails/generators/migration'
+
+module HeliosTracker
+  class InstallGenerator < Rails::Generators::Base
+    include Rails::Generators::Migration
+
+    source_root File.expand_path('templates', __dir__)
+
+    class_option :user_class, type: :string, default: "User",
+      desc: "The name of your User model class"
+
+    class_option :skip_utm, type: :boolean, default: false,
+      desc: "Skip Universal Track Manager installation"
+
+    def self.next_migration_number(path)
+      # Find the highest existing migration number and increment by 1,
+      # avoiding collisions with UTM migrations created in the same second.
+      existing = Dir.glob("#{path}/[0-9]*_*.rb").map { |f| File.basename(f).split("_", 2).first.to_i }
+      candidate = Time.now.utc.strftime("%Y%m%d%H%M%S").to_i
+      [candidate, *existing].max + 1
+    end
+
+    def install_universal_track_manager
+      if options[:skip_utm]
+        say "Skipping Universal Track Manager installation (--skip-utm)", :yellow
+        return
+      end
+
+      if File.exist?("config/initializers/universal_track_manager.rb")
+        say "Universal Track Manager initializer already exists, skipping UTM install", :yellow
+      else
+        say "Installing Universal Track Manager...", :green
+        generate "universal_track_manager:install"
+      end
+    end
+
+    def add_utm_concern_to_application_controller
+      if options[:skip_utm]
+        say "Skipping UTM concern injection (--skip-utm)", :yellow
+        return
+      end
+
+      app_controller = "app/controllers/application_controller.rb"
+      if File.exist?(app_controller)
+        content = File.read(app_controller)
+        if content.include?("UniversalTrackManagerConcern")
+          say "UniversalTrackManagerConcern already included in ApplicationController", :yellow
+        else
+          inject_into_class app_controller, "ApplicationController",
+            "  include UniversalTrackManagerConcern\n"
+          say "Added UniversalTrackManagerConcern to ApplicationController", :green
+        end
+      else
+        say "Could not find #{app_controller} — please add `include UniversalTrackManagerConcern` manually", :red
+      end
+    end
+
+    def add_helios_tracker_concern_to_application_controller
+      app_controller = "app/controllers/application_controller.rb"
+      if File.exist?(app_controller)
+        content = File.read(app_controller)
+        if content.include?("HeliosTrackerConcern")
+          say "HeliosTrackerConcern already included in ApplicationController", :yellow
+        else
+          inject_into_class app_controller, "ApplicationController",
+            "  include HeliosTrackerConcern\n"
+          say "Added HeliosTrackerConcern to ApplicationController", :green
+        end
+      else
+        say "Could not find #{app_controller} — please add `include HeliosTrackerConcern` manually", :red
+      end
+    end
+
+    def create_add_hmid_to_visits_migration
+      migration_template "add_hmid_to_visits.rb.erb",
+        "db/migrate/add_hmid_to_visits.rb"
+    end
+
+    def create_blocked_emails_migration
+      migration_template "create_blocked_emails.rb.erb",
+        "db/migrate/create_blocked_emails.rb"
+    end
+
+    def create_initializer
+      @user_class = options[:user_class]
+      template "helios_tracker.rb.erb", "config/initializers/helios_tracker.rb"
+    end
+
+    def mount_engine_routes
+      route_file = "config/routes.rb"
+      content = File.read(route_file)
+      if content.include?("mount HeliosTracker::Engine")
+        say "HeliosTracker engine already mounted in routes", :yellow
+      else
+        route "mount HeliosTracker::Engine, at: '/'"
+        say "Mounted HeliosTracker::Engine at '/' in routes", :green
+      end
+    end
+
+    def print_post_install
+      say ""
+      say "=" * 60, :green
+      say "Helios Tracker installed successfully!", :green
+      say "=" * 60, :green
+      say ""
+      say "Next steps:", :yellow
+      say "  1. Run `rails db:migrate`"
+      say "  2. Set HELIOS_TRACKER_API_KEY in your environment (.env or production config)"
+      say "  3. Edit config/initializers/helios_tracker.rb to configure your user scope and fields"
+      say "  4. Your API endpoints are now available at:"
+      say "     GET /api/all_users.json"
+      say "     GET /api/all_visits.json"
+      say "     GET /api/blocked_emails.json"
+      say ""
+    end
+  end
+end

data/lib/generators/helios_tracker/templates/add_hmid_to_visits.rb.erb

@@ -0,0 +1,6 @@
+class AddHmidToVisits < ActiveRecord::Migration<%= "[#{ActiveRecord::Migration.current_version}]" %>
+  def change
+    add_column :visits, :hmid, :string
+    add_index :visits, :hmid
+  end
+end

data/lib/generators/helios_tracker/templates/create_blocked_emails.rb.erb

@@ -0,0 +1,12 @@
+class CreateBlockedEmails < ActiveRecord::Migration<%= "[#{ActiveRecord::Migration.current_version}]" %>
+  def change
+    create_table :blocked_emails, id: :uuid do |t|
+      t.string :email, null: false
+      t.string :source, null: false
+      t.timestamps
+    end
+
+    add_index :blocked_emails, :email
+    add_index :blocked_emails, :created_at
+  end
+end

data/lib/generators/helios_tracker/templates/helios_tracker.rb.erb

@@ -0,0 +1,69 @@
+HeliosTracker.configure do |config|
+  # -----------------------------------------------------------------------
+  # User Configuration
+  # -----------------------------------------------------------------------
+
+  # The name of your User model class
+  config.user_class_name = "<%= @user_class %>"
+
+  # A lambda that returns users to expose via GET /api/all_users.json
+  # Receives (query_start, params) — query_start is a YYYY-MM-DD string.
+  # Must return an ActiveRecord relation.
+  config.user_scope = ->(query_start, params) {
+    <%= @user_class %>.where.not(email: "")
+        .where("updated_at > ?", query_start)
+  }
+
+  # Map API response field names to your model's attributes or lambdas.
+  # :email is required by the Helios API. All other fields are optional —
+  # simply remove any lines you don't need.
+  config.user_fields = {
+    email:                      :email,
+    created_at:                 :created_at,
+    # source_ip:                :source_ip,
+    # first_unconfirmed_visit_id: :first_unconfirmed_visit_id,
+    # login_attempt_count:      :login_attempt_count,
+    # login_count:              :login_count,
+    # accounts_owned_count:     ->(user) { user.accounts_owned_count },
+    # free_accounts_count:      ->(user) { user.free_accounts_count },
+    # unsubscribe_nonce:        :unsubscribe_nonce,
+    # app_open_days_count:      :app_open_days_count,
+  }
+
+  # -----------------------------------------------------------------------
+  # Visit Configuration (requires Universal Track Manager)
+  # -----------------------------------------------------------------------
+
+  # A lambda that returns visits to expose via GET /api/all_visits.json
+  # Visits with a nil hmid are skipped by Helios, so filter them out here.
+  config.visit_scope = ->(query_start, params) {
+    UniversalTrackManager::Visit.where.not(hmid: nil)
+        .where("updated_at > ?", query_start)
+  }
+
+  # Map API response field names to your visit model's attributes or lambdas.
+  # :hmid is required by the Helios API.
+  config.visit_fields = {
+    hmid: :hmid,
+    # visited_download_page: ->(visit) { visit.visited_download_page? },
+  }
+
+  # -----------------------------------------------------------------------
+  # Blocked Emails Configuration
+  # -----------------------------------------------------------------------
+
+  # The class used for blocked/suppressed emails
+  config.blocked_email_class_name = "BlockedEmail"
+
+  # A lambda that returns blocked emails via GET /api/blocked_emails.json
+  config.blocked_email_scope = ->(query_start, params) {
+    BlockedEmail.where("created_at > ?", query_start)
+  }
+
+  config.blocked_email_fields = {
+    email:      :email,
+    source:     :source,
+    created_at: :created_at,
+  }
+
+end

data/lib/helios-tracker.rb

@@ -0,0 +1 @@
+require "helios_tracker"

data/lib/helios_tracker/configuration.rb

@@ -0,0 +1,124 @@
+module HeliosTracker
+  class Configuration
+    # Required: the User class name as a string, e.g. "User"
+    attr_accessor :user_class_name
+
+    # Required: a lambda that receives (query_start, params) and returns an
+    # ActiveRecord relation of user records to expose via the API.
+    #
+    # Example:
+    #   config.user_scope = ->(query_start, params) {
+    #     User.where.not(email: "")
+    #         .where("updated_at > ?", query_start)
+    #   }
+    attr_accessor :user_scope
+
+    # Optional: a lambda that receives (query_start, params) and returns an
+    # ActiveRecord relation of visit records. Defaults to UTM visits with hmid.
+    #
+    # Example:
+    #   config.visit_scope = ->(query_start, params) {
+    #     UniversalTrackManager::Visit.where.not(hmid: nil)
+    #         .where("updated_at > ?", query_start)
+    #   }
+    attr_accessor :visit_scope
+
+    # Optional: a lambda that receives (query_start, params) and returns an
+    # ActiveRecord relation of blocked email records.
+    #
+    # Example:
+    #   config.blocked_email_scope = ->(query_start, params) {
+    #     BlockedEmail.where("created_at > ?", query_start)
+    #   }
+    attr_accessor :blocked_email_scope
+
+    # Optional user fields — map API field names to model attributes or lambdas.
+    # :email is always required and included automatically.
+    #
+    # Example:
+    #   config.user_fields = {
+    #     email:                      :email,
+    #     created_at:                 :created_at,
+    #     source_ip:                  ->(user) { user.try(:source_ip) },
+    #     first_unconfirmed_visit_id: :first_unconfirmed_visit_id,
+    #     login_attempt_count:        :login_attempt_count,
+    #     login_count:                :login_count,
+    #     accounts_owned_count:       ->(user) { user.accounts_owned_count },
+    #     free_accounts_count:        ->(user) { user.free_accounts_count },
+    #     unsubscribe_nonce:          :unsubscribe_nonce,
+    #     app_open_days_count:        :app_open_days_count,
+    #   }
+    attr_accessor :user_fields
+
+    # Optional visit fields — map API field names to model attributes or lambdas.
+    # :hmid is always required and included automatically.
+    #
+    # Example:
+    #   config.visit_fields = {
+    #     hmid:                   :hmid,
+    #     visited_download_page:  ->(visit) { visit.visited_download_page? },
+    #   }
+    attr_accessor :visit_fields
+
+    # Optional blocked email fields — map API field names to model attributes or lambdas.
+    # :email and :source are always required and included automatically.
+    #
+    # Example:
+    #   config.blocked_email_fields = {
+    #     email:      :email,
+    #     source:     :source,
+    #     created_at: :created_at,
+    #   }
+    attr_accessor :blocked_email_fields
+
+    # Optional: the class name for blocked emails, e.g. "BlockedEmail"
+    attr_accessor :blocked_email_class_name
+
+
+    def initialize
+      @user_class_name = "User"
+      @blocked_email_class_name = nil
+
+      @user_fields = {
+        email: :email,
+        created_at: :created_at,
+      }
+
+      @visit_fields = {
+        hmid: :hmid,
+      }
+
+      @blocked_email_fields = {
+        email: :email,
+        source: :source,
+        created_at: :created_at,
+      }
+
+      # Default scopes
+      @user_scope = nil
+      @visit_scope = nil
+      @blocked_email_scope = nil
+    end
+
+    def user_class
+      @user_class_name.constantize
+    end
+
+    def blocked_email_class
+      return nil unless @blocked_email_class_name
+      @blocked_email_class_name.constantize
+    end
+
+    # Serialize a single record using a fields hash.
+    # Fields can be symbols (attribute names) or lambdas.
+    def serialize_record(record, fields)
+      fields.each_with_object({}) do |(key, mapping), hash|
+        hash[key] = if mapping.respond_to?(:call)
+                      mapping.call(record)
+                    else
+                      record.public_send(mapping)
+                    end
+      end
+    end
+  end
+end

data/lib/helios_tracker/version.rb

@@ -1,5 +1,5 @@
 module HeliosTracker
   class Version
-    CURRENT = '0.0.0'
+    CURRENT = '0.0.1'
   end
 end

data/lib/helios_tracker.rb

@@ -0,0 +1,27 @@
+require "helios_tracker/version"
+require "helios_tracker/configuration"
+
+# UTM's entry point (universal-track-manager.rb) loads models before defining
+# the module, which breaks on Rails 8+. We pre-define the module so models
+# can reference UniversalTrackManager:: constants, then load the full entry
+# point which brings in models, concerns, and finally reopens the module
+# to add .configure and friends.
+module UniversalTrackManager; end unless defined?(UniversalTrackManager)
+require "universal-track-manager"
+
+module HeliosTracker
+  class << self
+    attr_accessor :configuration
+
+    def configure
+      self.configuration ||= Configuration.new
+      yield(configuration)
+    end
+
+    def config
+      configuration || Configuration.new
+    end
+  end
+end
+
+require "helios_tracker/engine" if defined?(Rails::Engine)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: helios-tracker
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.0.1
 platform: ruby
 authors:
 - Jason Fleetwood-Boldt
@@ -39,19 +39,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '2.16'
 - !ruby/object:Gem::Dependency
-  name: universal_track_manager
+  name: universal-track-manager
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.16'
+        version: '0.8'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.16'
+        version: '0.8'
 description: Tracks click rates, signups, logins, and daily app interactions via REST
   API. Targets automatically move from cold to warm or warm to hot as they engage
   — increasing Crusader send frequency in real time.
@@ -60,9 +60,25 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".gitignore"
 - ".ruby-version"
 - Gemfile
+- Gemfile.lock
+- README.md
+- app/controllers/concerns/helios_tracker_concern.rb
+- app/controllers/helios_tracker/api/all_users_controller.rb
+- app/controllers/helios_tracker/api/all_visits_controller.rb
+- app/controllers/helios_tracker/api/base_controller.rb
+- app/controllers/helios_tracker/api/blocked_emails_controller.rb
 - config/database.yml
+- config/routes.rb
+- lib/generators/helios_tracker/install_generator.rb
+- lib/generators/helios_tracker/templates/add_hmid_to_visits.rb.erb
+- lib/generators/helios_tracker/templates/create_blocked_emails.rb.erb
+- lib/generators/helios_tracker/templates/helios_tracker.rb.erb
+- lib/helios-tracker.rb
+- lib/helios_tracker.rb
+- lib/helios_tracker/configuration.rb
 - lib/helios_tracker/engine.rb
 - lib/helios_tracker/version.rb
 homepage: https://heliosflow.ai?utm_source=rubygems.org&utm_campaign=rubygems_link
@@ -80,7 +96,7 @@ post_install_message: |
     rails db:migrate
 
   Then set your API key in your environment:
-    SELF_API_KEY=your_secret_key_here
+    HELIOS_TRACKER_API_KEY=your_secret_key_here
 
   Edit config/initializers/helios_tracker.rb to configure
   your user scope, fields, and visit tracking.