referral_box 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ee4006fbe4caff6e1727695dd94283356d36fcb405164d3845f9084c4c1ca581
+  data.tar.gz: 2f29cb7b61c05f1935581579d18bc79d79754485fa9b654c2f916db7398413e7
+SHA512:
+  metadata.gz: 6bd9ff77d31909ff80e5d64e862ffd9ab41242cebb8a17e4ff4c1002d00a9a715a85ed9ffdae120a8537bbcf948fd21a53783aece4a5a1d02dbe88d2124d29c1
+  data.tar.gz: 0bb70dacb0c2261cbcd77194e75d2bccd51f897c148e0c72c6d291001e074687464b7f371408833e01f7945eab04b7b73883eba29987e26bbe901cea701e87cc

data/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2025-01-XX
+
+### Added
+- Initial release of ReferralBox gem
+- Points system with customizable earning/redeem rules
+- Dynamic tier levels (Silver, Gold, Platinum)
+- Unique referral codes and multi-level tracking
+- Built-in tracking for signups, geo, device (no Redis needed)
+- Admin dashboard with ERB views
+- Support for any user model (User, Customer, Account, etc.)
+- Rails generator for easy installation
+- Comprehensive configuration system
+- Transaction logging and analytics
+- Referral sharing with full analytics
+- Points expiration system
+- Tier change callbacks
+- Device and browser detection
+- Conversion rate tracking 

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Kapil Pal
+
+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,194 @@
+# ReferralBox 📦
+
+A flexible Ruby gem for building loyalty and referral systems in Rails apps.
+
+* 🎁 Reward users with points based on their activity
+* 🧱 Create dynamic tier levels (Silver, Gold, Platinum)
+* 🤝 Add referral rewards with unique referral codes
+* 🔧 Fully customizable and configurable
+* 🎛️ Admin dashboard (ERB based)
+* 🔄 Supports any user model: `User`, `Customer`, `Account`, etc.
+
+---
+
+## 📚 Documentation
+
+- **[Quick Start Guide](QUICK_START.md)** - Get running in 5 minutes
+- **[Complete Documentation](DOCUMENTATION.md)** - Full developer guide with examples
+- **[API Reference](DOCUMENTATION.md#api-reference)** - All methods and options
+
+---
+
+## 🚀 Installation
+
+```ruby
+# Gemfile
+gem 'referral_box'
+```
+
+```bash
+$ bundle install
+$ rails generate referral_box:install
+$ rails db:migrate
+```
+
+---
+
+## 🛠️ Configuration
+
+Create your configuration block in an initializer:
+
+```ruby
+# config/initializers/referral_box.rb
+
+ReferralBox.configure do |config|
+  # Define which model represents your app's user/customer
+  config.reference_class_name = 'User' # or 'Customer', 'Account', etc.
+
+  config.earning_rule = ->(user, event) do
+    # Example: earn 10 points per ₹100 spent
+    event.amount / 10
+  end
+
+  config.redeem_rule = ->(user, offer) do
+    offer.cost_in_points
+  end
+
+  config.tier_thresholds = {
+    "Silver" => 500,
+    "Gold" => 1000,
+    "Platinum" => 2500
+  }
+
+  config.reward_modifier = ->(user) do
+    case user.tier
+    when "Silver" then 1.0
+    when "Gold" then 1.2
+    when "Platinum" then 1.5
+    else 1.0
+    end
+  end
+
+  config.referral_reward = ->(referrer, referee) do
+    ReferralBox.earn_points(referrer, 100)
+    ReferralBox.earn_points(referee, 50)
+  end
+end
+```
+
+---
+
+## ✅ Features
+
+### 🎁 Loyalty Program
+
+| Feature              | Description                   |
+| -------------------- | ----------------------------- |
+| Points system        | Earn points via config lambda |
+| Custom earning rules | Define rules per event/user   |
+| Redeem points        | Redeem points for offers      |
+| Manual adjustment    | Admins can modify balances    |
+| Points expiration    | e.g. 90 days                  |
+| Transaction logging  | All activity is logged        |
+| Check balance        | Easy method to check          |
+
+### 🧱 Tier System (Dynamic)
+
+| Feature                 | Description                 |
+| ----------------------- | --------------------------- |
+| Dynamic definitions     | e.g. Silver => 500 points   |
+| Auto tier assignment    | Based on balance            |
+| Callbacks on promotion  | `on_tier_changed` hook      |
+| Reward modifier by tier | e.g. Gold users get +20%    |
+| DB persistence          | Can store or calculate tier |
+
+### 🤝 Referral System
+
+| Feature               | Description                                                   |
+| --------------------- | ------------------------------------------------------------- |
+| Unique referral codes | Auto-generated or custom                                      |
+| ?ref=code tracking    | Via signup links                                              |
+| Multi-level referrals | Parent/child tree                                             |
+| Referral rewards      | Custom logic supported                                        |
+| Referral analytics    | Track clicks, accepted signups, geo-location, and device type |
+
+### ⚙️ Core Gem Features
+
+* Developer config block
+* Extensible models
+* Simple public API: `earn_points`, `redeem_points`, `balance`, `track_referral`
+* Rails generators for setup
+* Support for any user model (User, Account, Customer, etc.)
+
+### 🖥️ Admin UI
+
+* Mountable engine with ERB templates
+* Routes like `/referral_box`
+* Views to list users, transactions, referrals
+
+---
+
+## 🔮 Future Scope
+
+### 📊 Analytics & Admin
+
+* Leaderboards by points
+* Referral tree visualizer
+* ActiveAdmin / custom dashboard
+* Export CSV/JSON of logs
+
+### 🔔 Engagement
+
+* Email / in-app notifications
+* Badges based on milestones
+* Activity calendar
+* Social sharing for referral links
+
+---
+
+## 📂 Folder Structure (Gem)
+
+```
+lib/
+├── referral_box.rb
+├── referral_box/
+│   ├── engine.rb
+│   ├── configuration.rb
+│   ├── version.rb
+│   ├── models/
+│   │   ├── transaction.rb
+│   │   ├── referral_log.rb
+│   └── controllers/
+│       ├── dashboard_controller.rb
+app/views/referral_box/dashboard/
+  ├── index.html.erb
+  ├── show.html.erb
+```
+
+---
+
+## 🧪 Usage Examples
+
+```ruby
+# Earn points
+ReferralBox.earn_points(current_user, event: order)
+
+# Redeem points
+ReferralBox.redeem_points(current_user, offer: coupon)
+
+# Check balance
+ReferralBox.balance(current_user)
+
+# Track referral
+ReferralBox.track_referral(ref_code: params[:ref])
+```
+
+---
+
+## 📬 Contribution
+
+PRs are welcome 🙌 — help improve the gem or suggest features.
+
+## 📜 License
+
+MIT © 2025 Kapil Pal 

data/app/assets/javascripts/referral_box.js

@@ -0,0 +1,138 @@
+// ReferralBox - Device Detection and Geo-location Collection
+// This script automatically collects device and location data when users click referral links
+
+(function() {
+  'use strict';
+
+  // Check if ReferralBox tracking is enabled
+  if (typeof window.ReferralBoxConfig === 'undefined' || !window.ReferralBoxConfig.enabled) {
+    return;
+  }
+
+  // Device detection
+  function detectDevice() {
+    const userAgent = navigator.userAgent.toLowerCase();
+    
+    // Device type detection
+    let deviceType = 'desktop';
+    if (/mobile|android|iphone|ipod|blackberry|windows phone/.test(userAgent)) {
+      deviceType = 'mobile';
+    } else if (/tablet|ipad/.test(userAgent)) {
+      deviceType = 'tablet';
+    }
+
+    // Browser detection
+    let browser = 'Other';
+    if (userAgent.includes('chrome')) {
+      browser = 'Chrome';
+    } else if (userAgent.includes('firefox')) {
+      browser = 'Firefox';
+    } else if (userAgent.includes('safari') && !userAgent.includes('chrome')) {
+      browser = 'Safari';
+    } else if (userAgent.includes('edge')) {
+      browser = 'Edge';
+    } else if (userAgent.includes('opera')) {
+      browser = 'Opera';
+    }
+
+    return {
+      device_type: deviceType,
+      browser: browser,
+      screen_width: screen.width,
+      screen_height: screen.height,
+      viewport_width: window.innerWidth,
+      viewport_height: window.innerHeight,
+      language: navigator.language,
+      platform: navigator.platform,
+      cookie_enabled: navigator.cookieEnabled,
+      online: navigator.onLine
+    };
+  }
+
+  // Geo-location detection (if enabled and user consents)
+  function detectLocation() {
+    return new Promise((resolve) => {
+      if (!window.ReferralBoxConfig.collect_geo || !navigator.geolocation) {
+        resolve(null);
+        return;
+      }
+
+      navigator.geolocation.getCurrentPosition(
+        function(position) {
+          resolve({
+            latitude: position.coords.latitude,
+            longitude: position.coords.longitude,
+            accuracy: position.coords.accuracy,
+            timestamp: position.timestamp
+          });
+        },
+        function(error) {
+          console.log('ReferralBox: Geolocation not available or denied');
+          resolve(null);
+        },
+        {
+          enableHighAccuracy: false,
+          timeout: 5000,
+          maximumAge: 60000
+        }
+      );
+    });
+  }
+
+  // Collect all device and location data
+  async function collectDeviceData() {
+    const deviceData = detectDevice();
+    const locationData = await detectLocation();
+
+    return {
+      ...deviceData,
+      geo_data: locationData,
+      collected_at: new Date().toISOString()
+    };
+  }
+
+  // Enhanced referral tracking
+  function enhanceReferralTracking() {
+    // Find all referral links
+    const referralLinks = document.querySelectorAll('a[href*="?ref="], a[href*="&ref="]');
+    
+    referralLinks.forEach(link => {
+      link.addEventListener('click', async function(e) {
+        // Only enhance if it's a referral link
+        if (!this.href.includes('ref=')) return;
+
+        try {
+          // Collect device and location data
+          const deviceData = await collectDeviceData();
+          
+          // Store in sessionStorage for the next page load
+          sessionStorage.setItem('referral_box_device_data', JSON.stringify(deviceData));
+          
+          // Add a small delay to ensure data is stored
+          setTimeout(() => {
+            // Continue with normal link navigation
+            return true;
+          }, 100);
+          
+        } catch (error) {
+          console.error('ReferralBox: Error collecting device data:', error);
+        }
+      });
+    });
+  }
+
+  // Initialize when DOM is ready
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', enhanceReferralTracking);
+  } else {
+    enhanceReferralTracking();
+  }
+
+  // Make functions available globally for manual use
+  window.ReferralBox = {
+    detectDevice: detectDevice,
+    detectLocation: detectLocation,
+    collectDeviceData: collectDeviceData
+  };
+
+})(); 

data/app/controllers/referral_box/dashboard_controller.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module ReferralBox
+  class DashboardController < ActionController::Base
+    layout "referral_box/dashboard"
+
+    before_action :authenticate_user!
+    before_action :ensure_admin_access!
+
+    def index
+      @total_users = user_class.count
+      @total_transactions = ReferralBox::Transaction.count
+      @total_referrals = ReferralBox::ReferralLog.count
+      @conversion_rate = ReferralBox::ReferralLog.conversion_rate
+      
+      @recent_transactions = ReferralBox::Transaction.includes(:user)
+                                                   .order(created_at: :desc)
+                                                   .limit(10)
+      
+      @top_users = user_class.joins(:referral_box_transactions)
+                            .group("users.id")
+                            .order("SUM(referral_box_transactions.points) DESC")
+                            .limit(10)
+    end
+
+    def users
+      @users = safe_paginate(user_class.includes(:referral_box_transactions)
+                        .order(created_at: :desc), 20)
+    end
+
+    def user
+      @user = user_class.find(params[:id])
+      @transactions = safe_paginate(@user.referral_box_transactions
+                          .order(created_at: :desc), 20)
+      @balance = ReferralBox.balance(@user)
+      @tier = ReferralBox.tier(@user)
+    end
+
+    def transactions
+      @transactions = safe_paginate(ReferralBox::Transaction.includes(:user)
+                                            .order(created_at: :desc), 50)
+    end
+
+    def referrals
+      @referrals = safe_paginate(ReferralBox::ReferralLog.order(clicked_at: :desc), 50)
+    end
+
+    def analytics
+      @total_clicks = ReferralBox::ReferralLog.clicked_count
+      @total_conversions = ReferralBox::ReferralLog.converted_count
+      @conversion_rate = ReferralBox::ReferralLog.conversion_rate
+      
+      @referrals_by_device = ReferralBox::ReferralLog.group(:device_type).count
+      @referrals_by_browser = ReferralBox::ReferralLog.group(:browser).count
+      
+      @daily_clicks = ReferralBox::ReferralLog.group("DATE(clicked_at)")
+                                            .count
+                                            .sort_by { |date, _| date }
+                                            .last(30)
+    end
+
+    private
+
+    def user_class
+      ReferralBox.configuration.reference_class_name.constantize
+    end
+
+    def safe_paginate(relation, per_page = 20)
+      if defined?(Kaminari) && relation.respond_to?(:page)
+        relation.page(params[:page]).per(per_page)
+      else
+        # Fallback pagination without Kaminari
+        page = (params[:page] || 1).to_i
+        offset = (page - 1) * per_page
+        relation.offset(offset).limit(per_page)
+      end
+    end
+
+    def authenticate_user!
+      # Override this method in your app to implement authentication
+      # For example: redirect_to login_path unless current_user
+      true
+    end
+
+    def ensure_admin_access!
+      # Override this method in your app to implement admin authorization
+      # For example: redirect_to root_path unless current_user&.admin?
+      true
+    end
+  end
+end 

data/app/controllers/referral_box/tracking_controller.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module ReferralBox
+  class TrackingController < ActionController::Base
+    skip_before_action :verify_authenticity_token, only: [:track_referral]
+    
+    def track_referral
+      ref_code = params[:ref_code]
+      device_data = params[:device_data]
+      
+      if ref_code.present?
+        success = ReferralBox.track_referral(
+          ref_code: ref_code,
+          user_agent: request.user_agent,
+          ip_address: request.remote_ip,
+          referrer: request.referer,
+          device_data: device_data
+        )
+        
+        if success
+          render json: { success: true, message: "Referral tracked successfully" }
+        else
+          render json: { success: false, message: "Failed to track referral" }, status: 422
+        end
+      else
+        render json: { success: false, message: "Referral code is required" }, status: 400
+      end
+    end
+  end
+end 

data/app/helpers/referral_box/application_helper.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module ReferralBox
+  module ApplicationHelper
+    # Include ReferralBox JavaScript and configuration
+    def referral_box_javascript_tag
+      return unless ReferralBox.configuration.enable_device_tracking
+      
+      config = {
+        enabled: ReferralBox.configuration.enable_device_tracking,
+        collect_geo: ReferralBox.configuration.collect_geo_location,
+        api_endpoint: referral_box_track_referral_path
+      }
+      
+      content_tag(:script, "window.ReferralBoxConfig = #{config.to_json};", type: 'application/javascript') +
+      javascript_include_tag('referral_box', 'data-turbolinks-track': 'reload')
+    end
+
+    # Generate a referral link with enhanced tracking
+    def referral_box_referral_link(user, options = {})
+      return unless user.respond_to?(:referral_code) && user.referral_code.present?
+      
+      base_url = options[:base_url] || root_url
+      ref_param = options[:ref_param] || 'ref'
+      
+      "#{base_url}#{base_url.include?('?') ? '&' : '?'}#{ref_param}=#{user.referral_code}"
+    end
+
+    # Generate a referral link button with styling
+    def referral_box_referral_button(user, text = nil, options = {})
+      text ||= "Share Referral Link"
+      link_text = options[:icon] ? "#{options[:icon]} #{text}" : text
+      
+      link_to(
+        link_text,
+        referral_box_referral_link(user, options),
+        options.merge(
+          class: "referral-box-referral-link #{options[:class]}".strip,
+          target: options[:target] || '_blank',
+          rel: options[:rel] || 'noopener'
+        )
+      )
+    end
+
+    # Display user's referral stats
+    def referral_box_user_stats(user)
+      return unless user.respond_to?(:points_balance)
+      
+      content_tag(:div, class: 'referral-box-user-stats') do
+        concat(content_tag(:div, "Points: #{user.points_balance}", class: 'points'))
+        concat(content_tag(:div, "Tier: #{user.current_tier || 'None'}", class: 'tier'))
+        concat(content_tag(:div, "Referrals: #{user.total_referrals rescue 0}", class: 'referrals'))
+      end
+    end
+  end
+end 

data/app/helpers/referral_box/dashboard_helper.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module ReferralBox
+  module DashboardHelper
+    def referral_box_paginate(collection)
+      if defined?(Kaminari) && collection.respond_to?(:current_page)
+        paginate(collection)
+      else
+        # Simple pagination without Kaminari
+        render_simple_pagination(collection)
+      end
+    end
+
+    private
+
+    def render_simple_pagination(collection)
+      return unless collection.respond_to?(:limit_value) && collection.respond_to?(:offset_value)
+      
+      current_page = (collection.offset_value / collection.limit_value) + 1
+      
+      # For fallback pagination, we need to get total count differently
+      # Since we don't have total_count method, we'll just show basic navigation
+      content_tag(:div, class: 'pagination') do
+        links = []
+        
+        # Previous page
+        if current_page > 1
+          links << link_to('Previous', url_for(page: current_page - 1), class: 'pagination-link')
+        end
+        
+        # Current page
+        links << content_tag(:span, "Page #{current_page}", class: 'pagination-current')
+        
+        # Next page (we'll always show this for fallback)
+        links << link_to('Next', url_for(page: current_page + 1), class: 'pagination-link')
+        
+        links.join.html_safe
+      end
+    end
+  end
+end