loyalty_ref 0.1.0

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

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+LoyaltyRef.configure do |config|
+  # Define which model represents your app's user/customer
+  config.reference_class_name = 'User' # or 'Customer', 'Account', etc.
+
+  # Custom earning rule - earn points based on events
+  config.earning_rule = ->(user, event) do
+    # Example: earn 10 points per ₹100 spent
+    # event.amount / 10
+    
+    # Default: earn 1 point per event
+    1
+  end
+
+  # Custom redeem rule - how many points to deduct
+  config.redeem_rule = ->(user, offer) do
+    # Example: offer.cost_in_points
+    offer&.cost_in_points || 100
+  end
+
+  # Define tier thresholds
+  config.tier_thresholds = {
+    "Silver" => 500,
+    "Gold" => 1000,
+    "Platinum" => 2500
+  }
+
+  # Reward modifier based on tier
+  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
+
+  # Referral reward logic
+  config.referral_reward = ->(referrer, referee) do
+    LoyaltyRef.earn_points(referrer, 100)
+    LoyaltyRef.earn_points(referee, 50)
+  end
+
+  # Points expiration (in days)
+  config.points_expiry_days = 90
+
+  # Referral code length
+  config.referral_code_length = 8
+
+  # Admin dashboard route path
+  config.admin_route_path = "/loyalty"
+
+  # Device tracking and analytics
+  config.enable_device_tracking = true  # Enable device detection
+  config.collect_geo_location = false   # Enable geo-location (requires user consent)
+
+  # Optional: Callback when user's tier changes
+  config.on_tier_changed = ->(user, old_tier, new_tier) do
+    # Example: Send notification email
+    # UserMailer.tier_changed(user, old_tier, new_tier).deliver_later
+  end
+end 

data/lib/generators/loyalty_ref/install/templates/user_model.rb

@@ -0,0 +1,45 @@
+ # frozen_string_literal: true
+
+class User < ApplicationRecord
+  # Add these columns to your users table:
+  # add_column :users, :referral_code, :string
+  # add_column :users, :tier, :string
+  # add_index :users, :referral_code, unique: true
+
+  has_many :loyalty_ref_transactions, class_name: 'LoyaltyRef::Transaction', as: :user
+  has_many :referrals, class_name: 'User', foreign_key: 'referrer_id'
+  belongs_to :referrer, class_name: 'User', optional: true
+
+  before_create :generate_referral_code
+
+  def points_balance
+    LoyaltyRef.balance(self)
+  end
+
+  def current_tier
+    LoyaltyRef.tier(self)
+  end
+
+  def referral_link
+    "#{Rails.application.routes.url_helpers.root_url}?ref=#{referral_code}"
+  end
+
+  def total_referrals
+    referrals.count
+  end
+
+  def successful_referrals
+    referrals.joins(:loyalty_ref_transactions).distinct.count
+  end
+
+  private
+
+  def generate_referral_code
+    return if referral_code.present?
+
+    loop do
+      self.referral_code = SecureRandom.alphanumeric(LoyaltyRef.configuration.referral_code_length).upcase
+      break unless User.exists?(referral_code: referral_code)
+    end
+  end
+end 

data/lib/loyalty_ref/configuration.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module LoyaltyRef
+  class Configuration
+    attr_accessor :reference_class_name,
+                  :earning_rule,
+                  :redeem_rule,
+                  :tier_thresholds,
+                  :reward_modifier,
+                  :referral_reward,
+                  :on_tier_changed,
+                  :points_expiry_days,
+                  :referral_code_length,
+                  :admin_route_path,
+                  :enable_device_tracking,
+                  :collect_geo_location
+
+    def initialize
+      @reference_class_name = "User"
+      @tier_thresholds = {
+        "Silver" => 500,
+        "Gold" => 1000,
+        "Platinum" => 2500
+      }
+      @points_expiry_days = 90
+      @referral_code_length = 8
+      @admin_route_path = "/loyalty"
+      @enable_device_tracking = true
+      @collect_geo_location = false  # Default to false for privacy
+    end
+  end
+end 

data/lib/loyalty_ref/engine.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+
+module LoyaltyRef
+  class Engine < ::Rails::Engine
+    isolate_namespace LoyaltyRef
+
+    config.generators do |g|
+      g.test_framework :rspec, fixture: false
+      g.fixture_replacement :factory_bot, dir: "spec/factories"
+      g.assets false
+      g.helper false
+    end
+
+    initializer "loyalty_ref.assets" do |app|
+      app.config.assets.precompile += %w[loyalty_ref_manifest.js]
+    end
+
+    initializer "loyalty_ref.routes" do |app|
+      app.routes.prepend do
+        mount LoyaltyRef::Engine => LoyaltyRef.configuration.admin_route_path
+      end
+    end
+
+    initializer "loyalty_ref.migrations" do |app|
+      unless app.root.to_s.match root.to_s
+        config.paths["db/migrate"].expanded.each do |expanded_path|
+          app.config.paths["db/migrate"] << expanded_path
+        end
+      end
+    end
+  end
+end 

data/lib/loyalty_ref/models/referral_log.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module LoyaltyRef
+  class ReferralLog < ActiveRecord::Base
+    self.table_name = "loyalty_ref_referral_logs"
+
+    belongs_to :referee, polymorphic: true, optional: true
+
+    validates :referral_code, presence: true
+    validates :clicked_at, presence: true
+
+    scope :clicked, -> { where.not(clicked_at: nil) }
+    scope :signed_up, -> { where.not(signed_up_at: nil) }
+    scope :converted, -> { where.not(signed_up_at: nil).where.not(referee_id: nil) }
+
+    def converted?
+      signed_up_at.present? && referee_id.present?
+    end
+
+    def conversion_rate
+      return 0 if clicked_count.zero?
+      (converted_count.to_f / clicked_count * 100).round(2)
+    end
+
+    def self.clicked_count
+      clicked.count
+    end
+
+    def self.converted_count
+      converted.count
+    end
+
+    def self.conversion_rate
+      return 0 if clicked_count.zero?
+      (converted_count.to_f / clicked_count * 100).round(2)
+    end
+
+    # Device detection methods - use stored data or fallback to user_agent parsing
+    def device_type
+      return self[:device_type] if self[:device_type].present?
+      return detect_device_type_from_user_agent if user_agent.present?
+      nil
+    end
+
+    def browser
+      return self[:browser] if self[:browser].present?
+      return detect_browser_from_user_agent if user_agent.present?
+      nil
+    end
+
+    # Geo-location methods (if using a geo service)
+    def country
+      return geo_data["country"] if geo_data&.dig("country").present?
+      return nil unless ip_address.present?
+      # You can integrate with services like MaxMind GeoIP2 or similar
+      # For now, return nil - users can implement their own geo service
+      nil
+    end
+
+    def city
+      return geo_data["city"] if geo_data&.dig("city").present?
+      return nil unless ip_address.present?
+      # Implement with your preferred geo service
+      nil
+    end
+
+    def latitude
+      geo_data&.dig("latitude")
+    end
+
+    def longitude
+      geo_data&.dig("longitude")
+    end
+
+    private
+
+    def detect_device_type_from_user_agent
+      return nil unless user_agent.present?
+      
+      user_agent = user_agent.downcase
+      
+      if user_agent.include?("mobile") || user_agent.include?("android") || user_agent.include?("iphone")
+        "mobile"
+      elsif user_agent.include?("tablet") || user_agent.include?("ipad")
+        "tablet"
+      else
+        "desktop"
+      end
+    end
+
+    def detect_browser_from_user_agent
+      return nil unless user_agent.present?
+      
+      user_agent = user_agent.downcase
+      
+      if user_agent.include?("chrome")
+        "Chrome"
+      elsif user_agent.include?("firefox")
+        "Firefox"
+      elsif user_agent.include?("safari")
+        "Safari"
+      elsif user_agent.include?("edge")
+        "Edge"
+      else
+        "Other"
+      end
+    end
+  end
+end 

data/lib/loyalty_ref/models/transaction.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module LoyaltyRef
+  class Transaction < ActiveRecord::Base
+    self.table_name = "loyalty_ref_transactions"
+
+    belongs_to :user, polymorphic: true
+
+    validates :points, presence: true, numericality: { other_than: 0 }
+    validates :transaction_type, presence: true, inclusion: { in: %w[earn redeem adjust] }
+
+    scope :earned, -> { where(transaction_type: "earn") }
+    scope :redeemed, -> { where(transaction_type: "redeem") }
+    scope :active, -> { where("expires_at IS NULL OR expires_at > ?", Time.current) }
+    scope :expired, -> { where("expires_at IS NOT NULL AND expires_at <= ?", Time.current) }
+
+    def expired?
+      expires_at.present? && expires_at <= Time.current
+    end
+
+    def active?
+      !expired?
+    end
+
+    def earned?
+      transaction_type == "earn"
+    end
+
+    def redeemed?
+      transaction_type == "redeem"
+    end
+
+    def adjusted?
+      transaction_type == "adjust"
+    end
+  end
+end 

data/lib/loyalty_ref/version.rb

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

data/lib/loyalty_ref.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require "rails"
+require "active_record"
+require "action_view"
+require "action_pack"
+
+require_relative "loyalty_ref/version"
+require_relative "loyalty_ref/engine"
+require_relative "loyalty_ref/configuration"
+require_relative "loyalty_ref/models/transaction"
+require_relative "loyalty_ref/models/referral_log"
+
+module LoyaltyRef
+  class << self
+    def configure
+      yield configuration
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def earn_points(user, amount, event: nil)
+      return false unless user && amount.positive?
+
+      # Apply reward modifier based on tier
+      modifier = configuration.reward_modifier&.call(user) || 1.0
+      final_amount = (amount * modifier).round
+
+      # Calculate expiration date
+      expiry_days = configuration.points_expiry_days
+      expires_at = expiry_days ? Time.current + expiry_days.days : nil
+
+      # Create transaction
+      transaction = Transaction.create!(
+        user: user,
+        points: final_amount,
+        transaction_type: "earn",
+        event_data: event&.as_json,
+        expires_at: expires_at,
+        description: "Earned #{final_amount} points"
+      )
+
+      # Update user tier if needed
+      update_user_tier(user)
+
+      transaction
+    rescue => e
+      Rails.logger.error "LoyaltyRef: Failed to earn points: #{e.message}"
+      false
+    end
+
+    def redeem_points(user, points, offer: nil)
+      return false unless user && points.positive?
+
+      current_balance = balance(user)
+      return false if current_balance < points
+
+      # Calculate cost using custom rule if provided
+      cost = if configuration.redeem_rule
+        configuration.redeem_rule.call(user, offer)
+      else
+        points
+      end
+
+      # Create transaction
+      transaction = Transaction.create!(
+        user: user,
+        points: -cost,
+        transaction_type: "redeem",
+        offer_data: offer&.as_json,
+        description: "Redeemed #{cost} points"
+      )
+
+      transaction
+    rescue => e
+      Rails.logger.error "LoyaltyRef: Failed to redeem points: #{e.message}"
+      false
+    end
+
+    def balance(user)
+      return 0 unless user
+
+      Transaction.where(user: user)
+                .where("expires_at IS NULL OR expires_at > ?", Time.current)
+                .sum(:points)
+    end
+
+    def tier(user)
+      return nil unless user && configuration.tier_thresholds.present?
+
+      balance = self.balance(user)
+      thresholds = configuration.tier_thresholds
+
+      # Find the highest tier the user qualifies for
+      thresholds.sort_by { |_, points| points }.reverse.each do |tier_name, required_points|
+        return tier_name if balance >= required_points
+      end
+
+      nil
+    end
+
+    def track_referral(ref_code:, user_agent: nil, ip_address: nil, referrer: nil, device_data: nil)
+      return false unless ref_code.present?
+
+      # Extract device and geo data from device_data parameter
+      device_type = device_data&.dig("device_type")
+      browser = device_data&.dig("browser")
+      geo_data = device_data&.dig("geo_data")
+      device_info = device_data&.except("device_type", "browser", "geo_data", "collected_at")
+
+      ReferralLog.create!(
+        referral_code: ref_code,
+        user_agent: user_agent,
+        ip_address: ip_address,
+        referrer: referrer,
+        clicked_at: Time.current,
+        device_type: device_type,
+        browser: browser,
+        geo_data: geo_data,
+        device_data: device_info
+      )
+    rescue => e
+      Rails.logger.error "LoyaltyRef: Failed to track referral: #{e.message}"
+      false
+    end
+
+    def process_referral_signup(referee, ref_code)
+      return false unless referee && ref_code.present?
+
+      # Find the referral log
+      referral_log = ReferralLog.where(referral_code: ref_code)
+                               .where(referee_id: nil)
+                               .order(clicked_at: :desc)
+                               .first
+
+      return false unless referral_log
+
+      # Find the referrer
+      referrer = find_user_by_referral_code(ref_code)
+      return false unless referrer
+
+      # Update referral log
+      referral_log.update!(
+        referee: referee,
+        signed_up_at: Time.current
+      )
+
+      # Update referee's referrer
+      referee.update!(referrer: referrer)
+
+      # Process referral rewards
+      if configuration.referral_reward
+        configuration.referral_reward.call(referrer, referee)
+      end
+
+      true
+    rescue => e
+      Rails.logger.error "LoyaltyRef: Failed to process referral signup: #{e.message}"
+      false
+    end
+
+    private
+
+    def update_user_tier(user)
+      old_tier = user.tier
+      new_tier = tier(user)
+
+      return if old_tier == new_tier
+
+      # Update user's tier in database
+      user.update!(tier: new_tier)
+
+      # Call tier change callback if configured
+      if configuration.on_tier_changed
+        configuration.on_tier_changed.call(user, old_tier, new_tier)
+      end
+    end
+
+    def find_user_by_referral_code(code)
+      return nil unless configuration.reference_class_name
+
+      user_class = configuration.reference_class_name.constantize
+      user_class.find_by(referral_code: code)
+    rescue NameError
+      Rails.logger.error "LoyaltyRef: User class '#{configuration.reference_class_name}' not found"
+      nil
+    end
+  end
+end