refer 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 624b2aea9ec3f2ea9f987b3ae23e56c96a0f2fa82d42931d98b50e407bc205e3
-  data.tar.gz: 0f1647e0c4a2f9abb635f754807d12fd47ef7b696114bbd753fc491eca4d6944
+  metadata.gz: 736ad28aa8233ae7dd3de16fe4f735931fa626b24f2875d2f60ac0d2791e1c05
+  data.tar.gz: c114325825aebd3e62fc5f2a0f29cf8ec7b562b646b2597c326a6631efd5920e
 SHA512:
-  metadata.gz: 6c08b0b4c669d9122ab9caf190ab71d7fe1b87621d1b767d5c61a78801e3d3c1785545506cf6c06e06fd55a91f9b1db7e6833731712d9556fcba22a74e5a3a05
-  data.tar.gz: 14ea41363df007c0ca068538554b19f8a582f6fb3d2b1ba5e0b6cd0e242de5350ced79e84b299f66f6a64a0315c12cf33453241b6d3a9019416b85143957e0df
+  metadata.gz: 2929027d9b24206e3ed98c6e6b8858bc5efa9e0df3c094edd272dd80c318f764fe83761a6540d045faf6f9628adf537e94109e4fc88b9108ffb2b71d91fa3969
+  data.tar.gz: ab6a96074eba0db0bd0319c4233aae91418a506182dc93ccf6937debd1a8f909a20485fbd238defa6d3ebf261d866554783360d1c16a634c1b25e3330cfce670

data/README.md

@@ -1,10 +1,8 @@
 # Refer
-Referral Codes for Ruby on Rails applications.
 
-## Usage
-How to use my plugin.
+Referral codes for Ruby on Rails applications.
 
-## Installation
+## 📦 Installation
 Add this line to your application's Gemfile:
 
 ```ruby
@@ -16,13 +14,135 @@ And then execute:
 $ bundle
 ```
 
-Or install it yourself as:
+And add Refer to your model:
 ```bash
-$ gem install refer
+bin/rails generate refer:model User
 ```
 
-## Contributing
-Contribution directions go here.
+## 🧑‍💻 Usage
 
-## License
+Refer adds a models to your Rails application for tracking referrals and referral codes.
+
+To track referrals, you'll need to
+
+1. Create a referral code
+2. Set a cookie with the referral code
+3. Create the referral
+4. (Optional) Provide a reward for successful referral
+
+##### Create a referral code
+
+You can create referral codes through the association:
+
+```ruby
+user.referral_codes.create #=> randomly generated code
+user.referral_codes.create(code: "chris")
+```
+
+To customize the referral code generator:
+
+```ruby
+Refer.code_generator = ->(referrer) { [id, SecureRandom.alphanumeric(8).join("-") }
+#=> generates codes like "1-7frb5fUw"
+```
+
+By default, Refer will generate 8 character alphanumeric codes.
+
+##### Set a referral cookie
+
+To track users, we need to stash the referral code in a cookie when present. By default, Refer will look for `?ref=code` and save this in a cookie.
+
+```ruby
+class ApplicationController < ActionController::Base
+  before_action :set_refer_cookie
+end
+```
+
+You can customize the param name with:
+
+```ruby
+Refer.param_name = :ref
+```
+
+You can customize the cookie name with:
+
+```ruby
+Refer.cookie_name = :refer_code
+```
+
+##### Refer a user:
+
+To create a referral, you can run the following
+
+```ruby
+class RegistrationsController < ApplicationController
+  def create
+    @user = User.new(user_params)
+    if @user.save
+      refer @user #=> Looks up cookie and attempts referral
+      redirect_to root_path
+    else
+      render :new, status: :unprocessable_entity
+    end
+  end
+end
+```
+
+You can also do this manually:
+
+```ruby
+Refer.refer(code: "referral_code", referee: user)
+```
+
+Refer will make sure the user has not already been referred and create a Referral.
+
+##### Check if a user was referred already:
+
+```ruby
+Refer.referred?(user)
+#=> true/false
+```
+
+##### Accessing Referrals
+
+To access a user's referrals, you can use the `referrals` association:
+
+```ruby
+user.referrals #=> [Refer::Referral, Refer::Referral]
+```
+
+This returns a list of `Refer::Referral` objects.
+
+##### Accessing Referral
+
+To access a user's referral, you can use the `referral` association:
+
+```ruby
+user.referral #=> Refer::Referral
+```
+
+To access a user's referrer, you can use `referrer`:
+```ruby
+user.referrer #=> User that referred this User
+```
+
+## Providing Referral Rewards
+
+There are several common ways of handling rewards for successful referrals:
+
+* Immediate rewards
+When the referral is successfully created, you can immediately credit the referrer with their reward.
+
+* Reward after user actions
+You can check if a user was referred after they complete the action and provide a reward to the referrer.
+
+* Time-based rewards
+To provide a reward X days after a successful referral, you can use a schedule job to check for referrals X days ago and provide rewards to those referrers.
+
+We recommend keeping records for each reward given to a referral so you can limit rewards.
+
+## 🙏 Contributing
+If you have an issue you'd like to submit, please do so using the issue tracker in GitHub. In order for us to help you in the best way possible, please be as detailed as you can.
+
+## 📝 License
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/app/controllers/concerns/refer/controller.rb

@@ -0,0 +1,15 @@
+module Refer
+  module Controller
+    extend ActiveSupport::Concern
+
+    def set_refer_cookie
+      if (code = params[Refer.param_name])
+        cookies[Refer.cookie_name] = Refer.cookie(code)
+      end
+    end
+
+    def refer(referee)
+      Refer.refer(code: cookies[Refer.cookie_name], referee: referee)
+    end
+  end
+end

data/app/models/concerns/refer/has_referrals.rb

@@ -0,0 +1,11 @@
+module Refer
+  module HasReferrals
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def has_referrals
+        include Refer::Model
+      end
+    end
+  end
+end

data/app/models/concerns/refer/model.rb

@@ -0,0 +1,11 @@
+module Refer
+  module Model
+    extend ActiveSupport::Concern
+
+    included do
+      has_many :referrals, inverse_of: :referrer, class_name: "Refer::Referral"
+      has_one :referral, inverse_of: :referee, class_name: "Refer::Referral"
+      delegate :referrer, to: :referral
+    end
+  end
+end

data/app/models/refer/application_record.rb

@@ -0,0 +1,6 @@
+module Refer
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+    self.table_name_prefix = "refer_"
+  end
+end

data/app/models/refer/referral.rb

@@ -0,0 +1,11 @@
+module Refer
+  class Referral < ApplicationRecord
+    belongs_to :referrer, polymorphic: true
+    belongs_to :referee, polymorphic: true
+    belongs_to :referral_code, optional: true
+
+    before_validation do
+      self.referrer = referral_code&.referrer
+    end
+  end
+end

data/app/models/refer/referral_code.rb

@@ -0,0 +1,16 @@
+module Refer
+  class ReferralCode < ApplicationRecord
+    belongs_to :referrer, polymorphic: true
+    has_many :referrals
+
+    validates :code, presence: true, uniqueness: true
+
+    before_create if: -> { Refer.code_generator } do
+      Refer.code_generator.call(referrer)
+    end
+
+    def to_param
+      code
+    end
+  end
+end

data/db/migrate/20240611180738_create_refer_referrals.rb

@@ -0,0 +1,11 @@
+class CreateReferReferrals < ActiveRecord::Migration[7.2]
+  def change
+    create_table :refer_referrals do |t|
+      t.belongs_to :referrer, polymorphic: true, null: false
+      t.belongs_to :referee, polymorphic: true, null: false
+      t.belongs_to :referral_code
+
+      t.timestamps
+    end
+  end
+end

data/db/migrate/20240611183349_create_refer_referral_codes.rb

@@ -0,0 +1,10 @@
+class CreateReferReferralCodes < ActiveRecord::Migration[7.2]
+  def change
+    create_table :refer_referral_codes do |t|
+      t.belongs_to :referrer, polymorphic: true, null: false
+      t.string :code, null: false, index: { unique: true }
+
+      t.timestamps
+    end
+  end
+end

data/lib/generators/refer/model/USAGE

@@ -0,0 +1,8 @@
+Description:
+    Explain the generator
+
+Example:
+    bin/rails generate model Thing
+
+    This will create:
+        what/will/it/create

data/lib/generators/refer/model/model_generator.rb

@@ -0,0 +1,11 @@
+class Refer::ModelGenerator < Rails::Generators::NamedBase
+  source_root File.expand_path("templates", __dir__)
+
+  def migrations
+    rails_command "refer:install:migrations"
+  end
+
+  def add_refer
+    inject_into_class File.join("app", "models", "#{file_path}.rb"), class_name, "  has_referrals\n"
+  end
+end

data/lib/refer/engine.rb

@@ -1,4 +1,5 @@
 module Refer
   class Engine < ::Rails::Engine
+    isolate_namespace Refer
   end
 end

data/lib/refer/version.rb

@@ -1,3 +1,3 @@
 module Refer
-  VERSION = "0.0.1"
+  VERSION = "0.1.0"
 end

data/lib/refer.rb

@@ -1,6 +1,46 @@
 require "refer/version"
 require "refer/engine"
+require "securerandom"
 
 module Refer
-  # Your code goes here...
+  include ActiveSupport::Configurable
+
+  config_accessor :code_generator, default: ->(referrer) { SecureRandom.alphanumeric(8) }
+  config_accessor :cookie_length, default: 30.days
+  config_accessor :cookie_name, default: :refer_code
+  config_accessor :param_name, default: :ref
+
+  class Error < StandardError; end
+  class AlreadyReferred < Error; end
+
+  def self.referred?(referee)
+    Referral.where(referee: referee).exists?
+  end
+
+  def self.refer(code:, referee:)
+    return if referred?(referee)
+    ReferralCode.find_by(code: code)&.referrals&.create(referee: referee)
+  end
+
+  def self.refer!(code:, referee:)
+    raise AlreadyReferred, "#{referee} has already been referred" if referred?(referee)
+    ReferralCode.find_by!(code: code).referrals.create!(referee: referee)
+  end
+
+  def self.cookie(code)
+    {
+      value: code,
+      expires: Refer.cookie_length.from_now
+    }
+  end
 end
+
+ActiveSupport.on_load(:active_record) do
+  include Refer::HasReferrals
+end
+
+ActiveSupport.on_load(:action_controller) do
+  include Refer::Controller
+end
+
+ActiveSupport.run_load_hooks(:refer, Refer)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: refer
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Chris Oliver
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-06-11 00:00:00.000000000 Z
+date: 2024-06-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -24,7 +24,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 6.1.0
-description: Referral codes for Ruby on Rails applications
+description: Referral codes for Ruby on Rails apps
 email:
 - excid3@gmail.com
 executables: []
@@ -34,12 +34,21 @@ files:
 - MIT-LICENSE
 - README.md
 - Rakefile
-- app/assets/config/referral_codes_manifest.js
+- app/controllers/concerns/refer/controller.rb
+- app/models/concerns/refer/has_referrals.rb
+- app/models/concerns/refer/model.rb
+- app/models/refer/application_record.rb
+- app/models/refer/referral.rb
+- app/models/refer/referral_code.rb
 - config/routes.rb
+- db/migrate/20240611180738_create_refer_referrals.rb
+- db/migrate/20240611183349_create_refer_referral_codes.rb
+- lib/generators/refer/model/USAGE
+- lib/generators/refer/model/model_generator.rb
 - lib/refer.rb
 - lib/refer/engine.rb
 - lib/refer/version.rb
-- lib/tasks/referral_codes_tasks.rake
+- lib/tasks/refer_tasks.rake
 homepage: https://github.com/excid3/refer
 licenses:
 - MIT
@@ -65,5 +74,5 @@ requirements: []
 rubygems_version: 3.5.11
 signing_key:
 specification_version: 4
-summary: Referral codes for Ruby on Rails applications
+summary: Referral codes for Ruby on Rails apps
 test_files: []