affiliate_tracker 0.3.1

data/app/controllers/affiliate_tracker/clicks_controller.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+module AffiliateTracker
+  class ClicksController < ApplicationController
+    skip_before_action :verify_authenticity_token, only: [:redirect]
+
+    def redirect
+      payload = params[:payload]
+      signature = params[:s]
+
+      begin
+        data = UrlGenerator.decode(payload, signature)
+        destination_url = data[:destination_url]
+        metadata = data[:metadata]
+
+        # Record the click
+        record_click(destination_url, metadata)
+
+        # Normalize URL protocol
+        destination_url = "https://#{destination_url}" unless destination_url.match?(%r{\A[a-zA-Z][a-zA-Z0-9+\-.]*://})
+
+        # Build final URL with UTM parameters
+        final_url = append_utm_params(destination_url, metadata)
+
+        # Redirect to destination (302 so browsers don't cache and we can re-track clicks)
+        redirect_to final_url, allow_other_host: true, status: :found
+      rescue AffiliateTracker::Error => e
+        Rails.logger.warn "[AffiliateTracker] Invalid tracking URL: #{e.message} from #{request.remote_ip}"
+        redirect_to AffiliateTracker.configuration.resolve_fallback_url(payload), allow_other_host: true
+      end
+    end
+
+    private
+
+    def record_click(destination_url, metadata)
+      dedup_key = "affiliate_tracker:#{request.remote_ip}:#{destination_url}"
+
+      # Deduplication using Rails.cache (5 seconds window)
+      return if Rails.cache.exist?(dedup_key)
+
+      Rails.cache.write(dedup_key, true, expires_in: 5.seconds)
+
+      click = Click.create!(
+        destination_url: destination_url,
+        ip_address: anonymize_ip(request.remote_ip),
+        user_agent: request.user_agent&.truncate(500),
+        referer: request.referer&.truncate(500),
+        metadata: metadata,
+        clicked_at: Time.current
+      )
+
+      # Call custom handler if configured
+      if (handler = AffiliateTracker.configuration.after_click)
+        handler.call(click)
+      end
+    rescue StandardError => e
+      Rails.logger.error "[AffiliateTracker] Failed to record click: #{e.message}"
+    end
+
+    def append_utm_params(url, metadata)
+      uri = URI.parse(url)
+      params = URI.decode_www_form(uri.query || '')
+
+      # Add ref and UTM params (metadata overrides defaults)
+      config = AffiliateTracker.configuration
+      tracking_params = {
+        'ref' => config.ref_param,
+        'utm_source' => metadata['utm_source'] || config.utm_source,
+        'utm_medium' => metadata['utm_medium'] || config.utm_medium,
+        'utm_campaign' => metadata['campaign'],
+        'utm_content' => metadata['shop']
+      }.compact
+
+      # Merge with existing params (don't overwrite if already present)
+      existing_keys = params.map(&:first)
+      tracking_params.each do |key, value|
+        params << [key, value] unless existing_keys.include?(key)
+      end
+
+      uri.query = URI.encode_www_form(params) if params.any?
+      uri.to_s
+    rescue URI::InvalidURIError
+      url
+    end
+
+    def anonymize_ip(ip)
+      return nil if ip.blank?
+
+      if ip.include?(':')
+        # IPv6: zero the last 80 bits (last 5 groups)
+        groups = ip.split(':')
+        if groups.size >= 8
+          (3..7).each { |i| groups[i] = '0' }
+          groups.join(':')
+        else
+          ip
+        end
+      else
+        # IPv4: zero the last octet
+        parts = ip.split('.')
+        return ip unless parts.size == 4
+
+        parts[3] = '0'
+        parts.join('.')
+      end
+    end
+  end
+end

data/app/controllers/affiliate_tracker/dashboard_controller.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module AffiliateTracker
+  class DashboardController < ApplicationController
+    before_action :authenticate!
+
+    def index
+      @stats = {
+        total_clicks: Click.count,
+        today_clicks: Click.where("clicked_at >= ?", Time.current.beginning_of_day).count,
+        week_clicks: Click.where("clicked_at >= ?", 1.week.ago).count,
+        unique_destinations: Click.distinct.count(:destination_url)
+      }
+
+      @recent_clicks = Click.order(clicked_at: :desc).limit(20)
+      @top_destinations = Click.group(:destination_url)
+                               .order("count_all DESC")
+                               .limit(10)
+                               .count
+    end
+
+    private
+
+    def authenticate!
+      if (auth = AffiliateTracker.configuration.authenticate_dashboard)
+        instance_exec(&auth)
+      end
+    end
+  end
+end

data/app/models/affiliate_tracker/click.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module AffiliateTracker
+  class Click < ActiveRecord::Base
+    self.table_name = "affiliate_tracker_clicks"
+
+    validates :destination_url, presence: true
+    validates :clicked_at, presence: true
+
+    # metadata is native JSON column - no serialize needed in Rails 8
+
+    scope :today, -> { where("clicked_at >= ?", Time.current.beginning_of_day) }
+    scope :this_week, -> { where("clicked_at >= ?", 1.week.ago) }
+    scope :this_month, -> { where("clicked_at >= ?", 1.month.ago) }
+
+    def domain
+      URI.parse(destination_url).host
+    rescue URI::InvalidURIError
+      nil
+    end
+  end
+end

data/app/views/affiliate_tracker/dashboard/index.html.erb

@@ -0,0 +1,91 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Affiliate Tracker Dashboard</title>
+  <style>
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #f5f5f5; color: #333; }
+    .container { max-width: 1200px; margin: 0 auto; padding: 20px; }
+    h1 { font-size: 24px; margin-bottom: 20px; color: #111; }
+    .stats { display: grid; grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); gap: 16px; margin-bottom: 24px; }
+    .stat { background: white; padding: 20px; border-radius: 8px; box-shadow: 0 1px 3px rgba(0,0,0,0.1); }
+    .stat-value { font-size: 32px; font-weight: 700; color: #111; }
+    .stat-label { font-size: 14px; color: #666; margin-top: 4px; }
+    .section { background: white; border-radius: 8px; box-shadow: 0 1px 3px rgba(0,0,0,0.1); padding: 20px; margin-bottom: 24px; }
+    .section h2 { font-size: 18px; margin-bottom: 16px; color: #111; }
+    table { width: 100%; border-collapse: collapse; }
+    th, td { text-align: left; padding: 12px; border-bottom: 1px solid #eee; }
+    th { font-weight: 600; color: #666; font-size: 12px; text-transform: uppercase; }
+    td { font-size: 14px; }
+    .url { max-width: 400px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+    .time { color: #666; }
+    .badge { display: inline-block; padding: 2px 8px; background: #e0f2e9; color: #0d6939; border-radius: 4px; font-size: 12px; }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <h1>Affiliate Tracker</h1>
+
+    <div class="stats">
+      <div class="stat">
+        <div class="stat-value"><%= @stats[:total_clicks] %></div>
+        <div class="stat-label">Total Clicks</div>
+      </div>
+      <div class="stat">
+        <div class="stat-value"><%= @stats[:today_clicks] %></div>
+        <div class="stat-label">Today</div>
+      </div>
+      <div class="stat">
+        <div class="stat-value"><%= @stats[:week_clicks] %></div>
+        <div class="stat-label">This Week</div>
+      </div>
+      <div class="stat">
+        <div class="stat-value"><%= @stats[:unique_destinations] %></div>
+        <div class="stat-label">Unique Destinations</div>
+      </div>
+    </div>
+
+    <div class="section">
+      <h2>Top Destinations</h2>
+      <table>
+        <thead>
+          <tr>
+            <th>URL</th>
+            <th>Clicks</th>
+          </tr>
+        </thead>
+        <tbody>
+          <% @top_destinations.each do |url, count| %>
+            <tr>
+              <td class="url"><%= url %></td>
+              <td><span class="badge"><%= count %></span></td>
+            </tr>
+          <% end %>
+        </tbody>
+      </table>
+    </div>
+
+    <div class="section">
+      <h2>Recent Clicks</h2>
+      <table>
+        <thead>
+          <tr>
+            <th>Time</th>
+            <th>Destination</th>
+            <th>Metadata</th>
+          </tr>
+        </thead>
+        <tbody>
+          <% @recent_clicks.each do |click| %>
+            <tr>
+              <td class="time"><%= click.clicked_at.strftime("%Y-%m-%d %H:%M") %></td>
+              <td class="url"><%= click.destination_url %></td>
+              <td><code><%= click.metadata.to_json if click.metadata.present? %></code></td>
+            </tr>
+          <% end %>
+        </tbody>
+      </table>
+    </div>
+  </div>
+</body>
+</html>

data/config/routes.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+AffiliateTracker::Engine.routes.draw do
+  get "/dashboard", to: "dashboard#index", as: :dashboard
+  get "/:payload", to: "clicks#redirect", as: :track
+end

data/lib/affiliate_tracker/configuration.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module AffiliateTracker
+  class Configuration
+    # Dashboard authentication proc (optional)
+    attr_accessor :authenticate_dashboard
+
+    # Custom click handler (optional)
+    attr_accessor :after_click
+
+    # Default UTM source (your brand name)
+    attr_accessor :utm_source
+
+    # Default UTM medium
+    attr_accessor :utm_medium
+
+    # Referral parameter (e.g., "partnerJan" adds ?ref=partnerJan)
+    attr_accessor :ref_param
+
+    # Default metadata proc - called when generating URLs
+    # Example: -> { { user_id: Current.user&.id } }
+    attr_accessor :default_metadata
+
+    # Fallback URL when signature is missing or invalid.
+    # Can be a String (static URL) or a Proc that receives the decoded payload Hash.
+    # The payload is decoded WITHOUT signature verification, so treat it as untrusted.
+    # Default: "/" (homepage)
+    #
+    # Examples:
+    #   config.fallback_url = "/oops"
+    #   config.fallback_url = ->(payload) { payload&.dig("shop") ? "/#{payload["shop"]}" : "/" }
+    attr_accessor :fallback_url
+
+    def initialize
+      @authenticate_dashboard = nil
+      @after_click = nil
+      @utm_source = 'affiliate'
+      @utm_medium = 'referral'
+      @ref_param = nil
+      @default_metadata = nil
+      @fallback_url = '/'
+    end
+
+    # Resolve fallback URL from config. Safely decodes payload (unverified) and
+    # passes it to the proc. Returns "/" if anything goes wrong.
+    def resolve_fallback_url(raw_payload)
+      payload_data = decode_payload_unsafe(raw_payload)
+
+      if @fallback_url.respond_to?(:call)
+        result = @fallback_url.call(payload_data)
+        result.presence || '/'
+      else
+        @fallback_url.to_s.presence || '/'
+      end
+    rescue StandardError
+      '/'
+    end
+
+    def resolve_default_metadata
+      return {} unless @default_metadata.respond_to?(:call)
+
+      result = @default_metadata.call
+      result.is_a?(Hash) ? result : {}
+    rescue StandardError
+      {}
+    end
+
+    def base_url
+      # Try routes first, then ActionMailer::Base as fallback (Rails 8 way)
+      options = Rails.application.routes.default_url_options.presence ||
+                ActionMailer::Base.default_url_options.presence ||
+                {}
+
+      host = options[:host]
+      unless host
+        raise Error,
+              "Set config.action_mailer.default_url_options = { host: 'example.com' } in config/environments/*.rb"
+      end
+
+      protocol = options[:protocol] || 'https'
+      "#{protocol}://#{host}"
+    end
+
+    def secret_key
+      Rails.application.key_generator.generate_key('affiliate_tracker', 32)
+    end
+
+    private
+
+    # Decode Base64 payload without verifying signature.
+    # Used only for building fallback URLs — treat result as untrusted.
+    def decode_payload_unsafe(raw_payload)
+      return nil if raw_payload.blank?
+
+      JSON.parse(Base64.urlsafe_decode64(raw_payload))
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/affiliate_tracker/engine.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module AffiliateTracker
+  class Engine < ::Rails::Engine
+    isolate_namespace AffiliateTracker
+
+    initializer "affiliate_tracker.helpers" do
+      ActiveSupport.on_load(:action_view) do
+        include AffiliateTracker::ViewHelpers
+      end
+
+      ActiveSupport.on_load(:action_mailer) do
+        include AffiliateTracker::ViewHelpers
+      end
+    end
+  end
+end
+
+require_relative "view_helpers"

data/lib/affiliate_tracker/url_generator.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'openssl'
+require 'json'
+require 'active_support/security_utils'
+
+module AffiliateTracker
+  class UrlGenerator
+    attr_reader :destination_url, :metadata
+
+    def initialize(destination_url, metadata = {})
+      @destination_url = normalize_url(destination_url)
+      @metadata = metadata.transform_keys(&:to_s)
+    end
+
+    def generate
+      payload = encode_payload
+      signature = sign(payload)
+      "#{base_url}#{route_path}/#{payload}?s=#{signature}"
+    end
+
+    private
+
+    def normalize_url(url)
+      return url if url.blank? || url.match?(%r{\A[a-zA-Z][a-zA-Z0-9+\-.]*://})
+      "https://#{url}"
+    end
+
+    def encode_payload
+      data = { u: destination_url }.merge(metadata)
+      Base64.urlsafe_encode64(data.to_json, padding: false)
+    end
+
+    def sign(payload)
+      OpenSSL::HMAC.hexdigest('SHA256', secret_key, payload).first(32)
+    end
+
+    def base_url
+      AffiliateTracker.configuration.base_url or raise Error, 'base_url not configured'
+    end
+
+    def route_path
+      '/a'
+    end
+
+    def secret_key
+      AffiliateTracker.configuration.secret_key or raise Error, 'secret_key not configured'
+    end
+
+    class << self
+      def decode(payload, signature)
+        raise Error, 'Missing payload' if payload.nil? || payload.empty?
+        raise Error, 'Missing signature' if signature.nil? || signature.empty?
+
+        expected_sig = OpenSSL::HMAC.hexdigest(
+          'SHA256',
+          AffiliateTracker.configuration.secret_key,
+          payload
+        ).first(32)
+
+        raise Error, 'Invalid signature' unless ActiveSupport::SecurityUtils.secure_compare(expected_sig, signature)
+
+        data = JSON.parse(Base64.urlsafe_decode64(payload))
+        {
+          destination_url: data.delete('u'),
+          metadata: data
+        }
+      end
+    end
+  end
+end

data/lib/affiliate_tracker/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module AffiliateTracker
+  VERSION = "0.3.1"
+end

data/lib/affiliate_tracker/view_helpers.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module AffiliateTracker
+  module ViewHelpers
+    # Generate a trackable affiliate link
+    #
+    # @param url [String] Destination URL
+    # @param text [String] Link text
+    # @param options [Hash] Tracking metadata (stored in click record)
+    #
+    # Common tracking options:
+    #   user_id:      - ID of user who will click (for attribution)
+    #   shop_id:      - Shop/store identifier
+    #   promotion_id: - Specific promotion being clicked
+    #   campaign:     - Campaign name (e.g., "daily_digest", "weekly_email")
+    #
+    # HTML options (applied to <a> tag, not stored):
+    #   class:, id:, style:, target:, rel:, data:, aria:
+    #
+    # Examples:
+    #   # Basic link
+    #   affiliate_link("https://shop.com", "Shop Now")
+    #
+    #   # With user tracking (recommended for emails)
+    #   affiliate_link("https://shop.com", "Shop Now", user_id: @user.id, campaign: "email")
+    #
+    #   # Full tracking
+    #   affiliate_link("https://shop.com", "View Deal",
+    #     user_id: @user.id,
+    #     shop_id: @shop.id,
+    #     promotion_id: @promotion.id,
+    #     campaign: "daily_digest")
+    #
+    #   # With block
+    #   affiliate_link("https://shop.com", user_id: @user.id) { "Shop Now" }
+    #
+    def affiliate_link(url, text_or_options = nil, options = {}, html_options = {}, &block)
+      if block_given?
+        options = text_or_options || {}
+        text = capture(&block)
+      else
+        text = text_or_options
+      end
+
+      html_keys = [:class, :id, :style, :target, :rel, :data, :aria]
+      tracking_url = AffiliateTracker.url(url, **options.except(*html_keys))
+      html_opts = { href: tracking_url, target: "_blank", rel: "noopener" }
+      html_opts.merge!(html_options)
+      html_opts.merge!(options.slice(*html_keys))
+
+      content_tag(:a, text, html_opts)
+    end
+
+    # Generate just the tracking URL (useful for emails or manual links)
+    #
+    # @param url [String] Destination URL
+    # @param metadata [Hash] Tracking data (see affiliate_link for common options)
+    #
+    # Examples:
+    #   affiliate_url("https://shop.com")
+    #   affiliate_url("https://shop.com", user_id: @user.id, campaign: "email_weekly")
+    #
+    def affiliate_url(url, **metadata)
+      AffiliateTracker.url(url, **metadata)
+    end
+  end
+end

data/lib/affiliate_tracker.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "affiliate_tracker/version"
+require_relative "affiliate_tracker/configuration"
+
+module AffiliateTracker
+  class Error < StandardError; end
+
+  class << self
+    attr_writer :configuration
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    # Generate a trackable affiliate URL
+    def track_url(destination_url, metadata = {})
+      merged_metadata = configuration.resolve_default_metadata.merge(metadata)
+      UrlGenerator.new(destination_url, merged_metadata).generate
+    end
+
+    # Shorthand for track_url
+    def url(destination_url, **metadata)
+      track_url(destination_url, metadata)
+    end
+  end
+end
+
+require_relative "affiliate_tracker/engine" if defined?(Rails)
+require_relative "affiliate_tracker/url_generator"

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module AffiliateTracker
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      def self.next_migration_number(dirname)
+        ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+
+      def copy_migration
+        migration_template "create_affiliate_tracker_clicks.rb.tt",
+                           "db/migrate/create_affiliate_tracker_clicks.rb"
+      end
+
+      def create_initializer
+        template "initializer.rb", "config/initializers/affiliate_tracker.rb"
+      end
+
+      def mount_engine
+        routes_path = "config/routes.rb"
+        mount_line = 'mount AffiliateTracker::Engine, at: "/a"'
+
+        return if File.exist?(routes_path) && File.read(routes_path).include?(mount_line)
+
+        route mount_line
+      end
+
+      def show_readme
+        readme "README" if behavior == :invoke
+      end
+    end
+  end
+end

data/lib/generators/affiliate_tracker/install/templates/README

@@ -0,0 +1,19 @@
+
+===============================================================================
+
+AffiliateTracker has been installed!
+
+Next steps:
+1. Run migrations:
+   $ rails db:migrate
+
+2. Configure in config/initializers/affiliate_tracker.rb
+
+3. Use in your views/mailers:
+   <%= affiliate_link "https://shop.com", "Shop Now", shop_id: 1 %>
+   <%= affiliate_url "https://shop.com", campaign: "email" %>
+
+4. Access dashboard at:
+   /a/dashboard
+
+===============================================================================

data/lib/generators/affiliate_tracker/install/templates/create_affiliate_tracker_clicks.rb.tt

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+class CreateAffiliateTrackerClicks < ActiveRecord::Migration[8.0]
+  def change
+    create_table :affiliate_tracker_clicks do |t|
+      t.string :destination_url, null: false
+      t.string :ip_address
+      t.string :user_agent
+      t.string :referer
+      t.json :metadata
+      t.datetime :clicked_at, null: false
+
+      t.timestamps
+    end
+
+    add_index :affiliate_tracker_clicks, :destination_url
+    add_index :affiliate_tracker_clicks, :clicked_at
+    add_index :affiliate_tracker_clicks, :created_at
+  end
+end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+AffiliateTracker.configure do |config|
+  # Your brand name (appears in utm_source)
+  # config.utm_source = "mybrand"
+
+  # Default medium (appears in utm_medium)
+  # config.utm_medium = "email"
+
+  # Referral param (adds ?ref=yourname to all links)
+  # config.ref_param = "yourname"
+
+  # Dashboard authentication (optional)
+  # config.authenticate_dashboard = -> {
+  #   redirect_to main_app.login_path unless current_user&.admin?
+  # }
+
+  # Fallback URL for invalid/missing signatures (default: "/")
+  # String: static URL
+  # Proc: receives decoded payload Hash (unverified — treat as untrusted)
+  # config.fallback_url = "/"
+  # config.fallback_url = ->(payload) {
+  #   slug = payload&.dig("shop")
+  #   slug.present? ? "/#{slug}" : "/"
+  # }
+end