affiliate_tracker 0.3.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 825b530c03d5358a02b7c718dea8a983a28b6f7d410708baaadedcd8dd085983
+  data.tar.gz: 540f309d350fd3326c5668fda1101a8212871b1283e3b2858dfd41d790c11658
+SHA512:
+  metadata.gz: 37821ddde6e55a7522546626e1e2a5527dde7e929048573401c46d4b3e94e97ae2e92ea911e663a12da7ed200a0c9bd638642d098cdaf226ee00059b664690dc
+  data.tar.gz: 335f997f6b7da97d732e2d27bd7915ed78bd35b4546b66418f60789b3cea2c44d2c0bf0d11c40dbdb56066cfb996889062f5398317d45c2c3f3fdc101d51d796

data/.rubocop.yml

@@ -0,0 +1,37 @@
+AllCops:
+  TargetRubyVersion: 3.2
+  NewCops: enable
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Layout/LineLength:
+  Max: 140
+
+Metrics/BlockLength:
+  Exclude:
+    - "test/**/*"
+
+Metrics/ClassLength:
+  Max: 150
+
+Metrics/MethodLength:
+  Max: 30
+
+Metrics/ModuleLength:
+  Max: 150
+
+Metrics/AbcSize:
+  Max: 35
+
+Metrics/CyclomaticComplexity:
+  Max: 15
+
+Metrics/PerceivedComplexity:
+  Max: 15
+
+Style/Documentation:
+  Enabled: false

data/.ruby-version

@@ -0,0 +1 @@
+3.4.4

data/.standard.yml

@@ -0,0 +1,3 @@
+# For available configuration options, see:
+#   https://github.com/standardrb/standard
+ruby_version: 3.2

data/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+## [0.3.1] - 2026-03-17
+
+### Changed
+- Redirect status changed from 301 (`:moved_permanently`) to 302 (`:found`). 301s are cached permanently by browsers, which prevents click re-tracking on subsequent visits.
+- IPv6 anonymization: `anonymize_ip` now handles IPv6 addresses by zeroing the last 80 bits (last 5 groups), in addition to the existing IPv4 last-octet zeroing.
+- CI matrix expanded to test Ruby 3.2, 3.3, and 3.4.
+- Gem prepared for RubyGems.org publication: added LICENSE.txt, CHANGELOG.md to gem files, MFA requirement, upper-bound Rails dependency (`< 10`).
+
+## [0.3.0] - 2026-03-17
+
+### Added
+- URL normalization: URLs without a protocol (e.g. `shop.com/page`) are automatically prepended with `https://` both at URL generation time and at redirect time. Prevents broken redirects for malformed destination URLs.
+- Tests for URL normalization in `UrlGenerator` and `ClicksController`.
+
+### Changed
+- `UrlGenerator#initialize` now normalizes destination URLs before encoding.
+- `ClicksController#redirect` normalizes destination URLs before appending UTM params and redirecting.
+
+## [0.2.0] - 2026-01-24
+
+- Per-link metadata override for UTM params (`utm_source`, `utm_medium`).
+- Configurable `after_click` callback.
+- Proc-based `fallback_url` with untrusted payload data.
+- Click deduplication (same IP + URL within 5s).
+
+## [0.1.0] - 2025-12-15
+
+- Initial release with click tracking, UTM injection, and redirect.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Justyna Wojtczak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,240 @@
+# AffiliateTracker
+
+Click tracking for affiliates working with small e-commerce shops. Track your clicks, add UTM params, prove your value.
+
+## Who is this for?
+
+**You're an affiliate/influencer** who promotes products from small shops (Shoplo, Shoper, WooCommerce, IdoSell, etc.) that **don't have their own affiliate system**.
+
+You send traffic via newsletters, blogs, or social media — but you have no way to prove how many clicks you actually sent. The shop owner sees some visits in Google Analytics, but can't tell which came from you.
+
+**This gem solves that:**
+- You track every click on your side (proof for negotiations)
+- Links automatically include UTM parameters (shop sees your traffic in their GA)
+- Optional `ref=` parameter for shops that support simple referral tracking
+
+**Not for:** Amazon, eBay, or platforms with existing affiliate programs (they have their own tracking and often prohibit link masking).
+
+## Problem
+
+```
+You: "I sent you 500 clicks this month"
+Shop: "Google Analytics shows only 200 visits"
+You: "..."
+```
+
+## Solution
+
+```
+Your email → User clicks → AffiliateTracker counts → Redirect with UTM → Shop sees source
+                              ↓
+                    You have proof: 500 clicks
+                    Shop sees: utm_source=yourname
+```
+
+## Features
+
+- Click tracking with metadata (shop, campaign, etc.)
+- Automatic UTM parameter injection
+- Click deduplication (same IP + URL within 5s counted once)
+- Built-in dashboard
+- Rails 8+ / zero configuration
+
+## Installation
+
+```ruby
+gem "affiliate_tracker"
+```
+
+Or, for the latest development version:
+
+```ruby
+gem "affiliate_tracker", git: "https://github.com/justi-blue/affiliate_tracker"
+```
+
+```bash
+rails generate affiliate_tracker:install
+rails db:migrate
+```
+
+## Usage
+
+### affiliate_link helper
+
+```erb
+<%# Simple link %>
+<%= affiliate_link "https://modago.pl/sukienka", "Zobacz sukienkę" %>
+
+<%# With metadata %>
+<%= affiliate_link "https://modago.pl/sukienka", "Zobacz sukienkę",
+      shop: "modago",
+      campaign: "homepage" %>
+
+<%# With CSS classes %>
+<%= affiliate_link "https://modago.pl/sukienka", "Zobacz",
+      shop: "modago",
+      class: "btn btn-primary" %>
+
+<%# Block syntax %>
+<%= affiliate_link "https://modago.pl/sukienka", shop: "modago" do %>
+  <img src="photo.jpg"> Zobacz ofertę
+<% end %>
+```
+
+**Generates:**
+```html
+<a href="https://yourapp.com/a/eyJ...?s=abc" target="_blank" rel="noopener">
+  Zobacz sukienkę
+</a>
+```
+
+### affiliate_url helper (URL only)
+
+```erb
+<a href="<%= affiliate_url 'https://modago.pl/sukienka', shop: 'modago' %>">
+  Custom link
+</a>
+```
+
+### User Tracking
+
+Track which user clicked a link by passing `user_id`:
+
+```erb
+<%# On web pages - use Current.user %>
+<%= affiliate_link "https://shop.com/product", "Buy Now",
+      user_id: Current.user&.id,
+      campaign: "homepage" %>
+
+<%# In mailers - pass user explicitly (Current.user not available in background jobs) %>
+<%= affiliate_link "https://shop.com/product", "View Deal",
+      user_id: @user.id,
+      shop_id: @shop.id,
+      campaign: "daily_digest" %>
+```
+
+Common tracking parameters:
+- `user_id` - User who clicked (for attribution)
+- `shop_id` - Shop identifier
+- `promotion_id` - Specific promotion
+- `campaign` - Campaign name (e.g., "daily_digest", "homepage")
+
+### In Mailers
+
+```erb
+<%# app/views/digest_mailer/weekly.html.erb %>
+<% @promotions.each do |promo| %>
+  <%= affiliate_link promo.shop.website_url, "Zobacz promocję",
+        user_id: @user.id,
+        shop_id: promo.shop.id,
+        promotion_id: promo.id,
+        campaign: "weekly_digest" %>
+<% end %>
+```
+
+### Real Example: Shoplo Store
+
+```erb
+<%# Just the product URL - ref param added automatically from config %>
+<%= affiliate_link "https://demo.shoplo.com/koszulka-bawelniana",
+      "Zobacz koszulkę",
+      shop: "shoplo-demo",
+      campaign: "styczen2025" %>
+```
+
+**User clicks → AffiliateTracker counts → Redirects to:**
+```
+https://demo.shoplo.com/koszulka-bawelniana?ref=partnerJan&utm_source=smartoffers&utm_medium=email&utm_campaign=styczen2025&utm_content=shoplo-demo
+```
+
+The shop sees:
+- `ref=partnerJan` - from `config.ref_param` (automatic)
+- UTM params - in Google Analytics
+
+### Result
+
+1. Generates: `https://yourapp.com/a/eyJ...?s=abc`
+2. On click, redirects to: `https://modago.pl/sukienka?utm_source=smartoffers&utm_medium=email&utm_campaign=weekly_digest&utm_content=modago`
+
+### Configuration
+
+```ruby
+# config/initializers/affiliate_tracker.rb
+AffiliateTracker.configure do |config|
+  # Your brand name (appears in utm_source)
+  config.utm_source = "smartoffers"
+
+  # Default medium
+  config.utm_medium = "email"
+
+  # Referral param (adds ?ref=partnerJan to all links)
+  config.ref_param = "partnerJan"
+
+  # Dashboard auth
+  config.authenticate_dashboard = -> {
+    redirect_to main_app.login_path unless current_user&.admin?
+  }
+end
+```
+
+### Tracking Parameters
+
+| Parameter | Source | Example |
+|-----------|--------|---------|
+| `ref` | `config.ref_param` | `partnerJan` |
+| `utm_source` | `config.utm_source` | `smartoffers` |
+| `utm_medium` | `config.utm_medium` | `email` |
+| `utm_campaign` | `campaign:` in helper | `weekly_digest` |
+| `utm_content` | `shop:` in helper | `modago` |
+
+Override defaults per-link:
+
+```erb
+<%= affiliate_url "https://shop.com",
+      utm_source: "newsletter",
+      utm_medium: "email",
+      campaign: "black_friday" %>
+```
+
+## Dashboard
+
+Access at `/a/dashboard`
+
+Shows:
+- Total clicks
+- Clicks today/this week
+- Top destinations (shops)
+- Recent clicks with metadata
+
+## Security
+
+- Links are signed with **HMAC-SHA256** (128-bit truncated signature per RFC 2104)
+- Signature verification uses constant-time comparison (`ActiveSupport::SecurityUtils`)
+- Invalid or missing signatures result in a **302 redirect** to a configurable fallback URL (default: `/`)
+- Payload is Base64-encoded JSON (not encrypted) — metadata is readable but tamper-proof
+
+### Fallback URL
+
+When a user visits a link with an invalid or missing signature (e.g., bots stripping query params), the gem redirects instead of returning an error:
+
+```ruby
+AffiliateTracker.configure do |config|
+  # Static URL (default)
+  config.fallback_url = "/"
+
+  # Dynamic — receives decoded payload Hash (unverified, treat as untrusted)
+  config.fallback_url = ->(payload) {
+    slug = payload&.dig("shop")
+    slug.present? ? "/shops/#{slug}" : "/"
+  }
+end
+```
+
+## For Shop Owners
+
+Tell your partner shops:
+> "All my links include UTM parameters. Check Google Analytics → Acquisition → Traffic Sources → filter by `utm_source=yourname`"
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: :test

data/TEST_SUITE_TASKS.md

@@ -0,0 +1,238 @@
+# Test Suite Tasks
+
+## Goal
+
+Bring the gem's test suite closer to real user flows, cover missing edge cases, and reduce low-value duplication.
+
+## Priority 1: Cover the real runtime flow
+
+### Task 1: Add integration tests for click redirect happy path
+
+- Add request or integration tests for `AffiliateTracker::ClicksController#redirect`.
+- Verify valid signed URLs:
+  - decode correctly,
+  - create a click record,
+  - redirect to the destination URL,
+  - append expected UTM params,
+  - preserve existing query params.
+- Verify response status and redirect target exactly.
+
+**Why**
+
+Current tests mostly cover URL generation, but not the main production flow after a user clicks a link.
+
+**Suggested assertions**
+
+- click count increases by 1
+- saved `destination_url` matches decoded payload
+- redirect URL contains `utm_source`, `utm_medium`, optional `utm_campaign`, optional `utm_content`
+- existing query params are preserved
+
+### Task 2: Add integration tests for invalid or missing signature
+
+- Test invalid signature redirects to fallback URL.
+- Test missing signature redirects to fallback URL.
+- Test tampered payload redirects to fallback URL.
+- Test fallback works for:
+  - static string config,
+  - proc-based config with decoded untrusted payload,
+  - corrupt payload passed into proc fallback.
+
+**Why**
+
+This is a key resilience path documented in the gem, but it is not covered end-to-end.
+
+### Task 3: Add integration tests for click deduplication
+
+- Exercise two requests through the controller, not directly through `Rails.cache`.
+- Verify same IP + same destination within 5 seconds creates only one click.
+- Verify different IP still records a second click.
+- Verify different destination still records a second click.
+- Verify click is recorded again after dedup window expires or is cleared.
+
+**Why**
+
+Current deduplication tests check cache primitives, not actual dedup behavior in production code.
+
+### Task 4: Add integration tests for `after_click`
+
+- Verify configured `after_click` handler is called after a successful click record.
+- Verify handler receives the created `AffiliateTracker::Click`.
+- Verify exceptions in handler do not break redirect flow.
+
+**Why**
+
+`after_click` is part of the public configuration API and should be regression-safe.
+
+### Task 5: Add integration tests for request metadata handling
+
+- Verify IP is anonymized before persisting.
+- Verify `user_agent` is truncated to 500 chars.
+- Verify `referer` is truncated to 500 chars.
+- Verify metadata is stored as expected.
+
+**Why**
+
+This logic exists in the controller and affects privacy and database safety, but is currently untested.
+
+## Priority 2: Cover dashboard and model behavior
+
+### Task 6: Add controller/integration tests for dashboard access
+
+- Verify `/a/dashboard` resolves correctly.
+- Verify dashboard renders when no auth proc is configured.
+- Verify configured `authenticate_dashboard` proc is executed.
+- Verify auth proc can redirect unauthenticated users.
+
+**Why**
+
+Dashboard access is a user-facing feature and currently has no behavioral coverage.
+
+### Task 7: Add dashboard stats tests
+
+- Seed clicks across different timestamps.
+- Verify:
+  - `total_clicks`
+  - `today_clicks`
+  - `week_clicks`
+  - `unique_destinations`
+  - recent clicks ordering
+  - top destinations counts
+
+**Why**
+
+The dashboard is mostly aggregation logic. That kind of logic regresses easily when queries change.
+
+### Task 8: Add model tests for `AffiliateTracker::Click`
+
+- Test validations for `destination_url` and `clicked_at`.
+- Test `domain` with:
+  - valid URL,
+  - invalid URL,
+  - URL without host if relevant.
+- Test scopes:
+  - `.today`
+  - `.this_week`
+  - `.this_month`
+
+**Why**
+
+The model has public behavior that is not currently covered at all.
+
+## Priority 3: Fix test architecture issues
+
+### Task 9: Stop stubbing the gem's public API in `test/test_helper.rb`
+
+- Load the real `lib/affiliate_tracker.rb` where possible.
+- Remove duplicated test-only implementations of:
+  - `AffiliateTracker.configure`
+  - `AffiliateTracker.track_url`
+  - `AffiliateTracker.url`
+- Keep only the minimal Rails test scaffolding needed by the gem.
+
+**Why**
+
+Current tests can pass even if the real entry point breaks, especially around `default_metadata`.
+
+### Task 10: Add tests for `default_metadata`
+
+- Verify configured `default_metadata` is merged into generated tracking URLs.
+- Verify explicit per-link metadata overrides default values where expected.
+- Verify non-hash return value falls back to `{}`.
+- Verify exceptions inside `default_metadata` do not break URL generation.
+
+**Why**
+
+This is real logic in the gem entry point and is currently untested because the suite bypasses it.
+
+## Priority 4: Replace low-value indirect tests
+
+### Task 11: Replace route file parsing tests with routing behavior tests
+
+- Replace string-based assertions against `config/routes.rb`.
+- Add routing tests that verify:
+  - `/a/dashboard` routes to dashboard controller,
+  - `/a/:payload` routes to click redirect,
+  - dashboard route is not swallowed by payload route.
+
+**Why**
+
+Parsing the routes file as text is brittle and does not prove the router behaves correctly.
+
+### Task 12: Remove or rewrite the Base64 `dashboard` test
+
+- Delete or replace the test asserting `"dashboard"` is not valid Base64 payload.
+- If kept, justify it with actual runtime behavior.
+
+**Why**
+
+That test does not meaningfully protect routing behavior.
+
+## Priority 5: Reduce redundant coverage
+
+### Task 13: Consolidate overlapping URL generation tests
+
+- Review overlap between:
+  - `ConfigurationTest`
+  - `UrlGeneratorTest`
+  - `ViewHelpersTest`
+- Keep one focused place for:
+  - signature format,
+  - `/a/` URL structure,
+  - same input => same output,
+  - different input => different signature.
+
+**Why**
+
+The suite repeats the same contract several times with little extra protection.
+
+### Task 14: Trim repetitive helper tests
+
+- Keep tests that cover real helper-specific behavior:
+  - HTML escaping,
+  - block syntax,
+  - HTML attributes vs tracking metadata split,
+  - default `target` and `rel`,
+  - overriding `target` and `rel`.
+- Reduce repeated cases that only re-prove `UrlGenerator.decode`.
+
+**Why**
+
+`ViewHelpersTest` is large, but much of it duplicates lower-level URL generator coverage.
+
+## Optional: Installer and engine coverage
+
+### Task 15: Add tests for engine helper inclusion
+
+- Verify helpers are available in Action View.
+- Verify helpers are available in Action Mailer if the gem promises that behavior.
+
+### Task 16: Add generator tests
+
+- Verify install generator:
+  - creates initializer,
+  - creates migration,
+  - mounts engine route.
+
+**Why**
+
+For a gem, installation and framework integration are part of the product surface.
+
+## Suggested execution order
+
+1. Add redirect integration tests.
+2. Add deduplication and fallback tests.
+3. Add dashboard and model tests.
+4. Fix `test_helper` to use the real gem entry point.
+5. Replace indirect route tests.
+6. Remove redundant helper and URL tests.
+
+## Definition of done
+
+- Main click flow is covered end-to-end.
+- Failure paths are covered end-to-end.
+- Public config hooks are covered.
+- Dashboard behavior is covered.
+- Model behavior is covered.
+- Tests execute against real production entry points, not test-only rewrites.
+- Redundant tests are reduced without losing regression protection.

data/app/controllers/affiliate_tracker/application_controller.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module AffiliateTracker
+  class ApplicationController < ActionController::Base
+    protect_from_forgery with: :exception
+  end
+end