referable 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 9918f1d6a54a3de5cb02eea2f3390206feb3ab39
+  data.tar.gz: e54e727bd83f1dfcc10803c51841c7524a50ceb8
+SHA512:
+  metadata.gz: edf925ff93ca80029d7812650d9c04150f54425468bf9a36edb458b2839548ad3a57771b4e2488e4573c8176457395c1745f6127955cb13ecdda0b23b3f052d4
+  data.tar.gz: 50ba1849b82a66e6593219374baf429f783ca3c833192ba64fc8f6880b1c105e048f9791e61cd729c72b0dbf0bbf5103f87b69177d00602f513aee1b1e52e757

data/.gitignore

@@ -0,0 +1,12 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.4.0
+before_install: gem install bundler -v 1.15.4

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting hello@eola.co.uk. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in referable.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Eola Ltd.
+
+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,119 @@
+# Referable
+
+Referable provides you with a generator that happily creates a multi-tenant referral
+system for your app with rewards, in just two steps.
+
+1.
+```bash
+rails g referable user && rails db:migrate
+```
+
+2.
+```ruby
+ReferableReward.create! reward: 'A new car',
+                         referrals_required: 10,
+                         acquireable_by: 'user'
+```
+
+aaand... you're done!
+
+```ruby
+user = User.first
+
+user.recruits
+#=> #<ActiveRecord::Associations::CollectionProxy [...]>
+
+user.recruits << User.create(name: 'Dan')
+#=> #<ActiveRecord::Associations::CollectionProxy [...]>
+
+user.referrals.count
+#=> 1
+
+user.distance_to_next_reward
+#=> 9
+
+user.percent_to_next_reward
+#=> 10.0
+
+user.last_acquired_reward.name
+#=> 'nothing'
+```
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'referable'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself:
+```bash
+gem install referable
+```
+
+## Usage
+
+The generator modifies an existing Rails model to allow referral functionality. The model
+does not need to have any other dependencies.
+
+To enable referrals for a specific model, run
+```bash
+rails generate referable name_of_model
+```
+
+This will create the necessary migration(s). Next, check the contents of the migrations.
+Notably, the _add_referral_fields_to_XXX_ migration, as this updates each record for your
+model with a referral slug.
+
+Then,
+```bash
+rails db:migrate
+```
+
+This can be added for any number of models in your application.
+
+### Creating rewards
+
+Rewards are set for each model type individually. IE a President will have a different set
+of rewards to a PrimeMinister.
+
+Creating rewards is as simple as:
+```ruby
+ReferableReward.create! reward: 'A new car',
+                        referrals_required: 10,
+                        acquireable_by: 'user'
+```
+
+### Callback when model reaches a reward
+
+Want to notify someone or do something when a user acquires a new reward?
+Just hook in to `Referable#acquired_reward!`
+
+### Adding a recruit in devise
+
+At [eola](https://eola.co.uk), we hook in to the `Devise::RegistrationsController#post`
+action, checking for the referral slug in the params. If it exists, the user is given
+the new recruit.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/referable. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Referable project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/referable/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "referable"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/generators/referable/USAGE

@@ -0,0 +1,10 @@
+Description:
+    Creates a multi-tenant referral system, with rewards
+
+Example:
+    rails generate referable user
+
+    This will create:
+        - A model and migration for rewards.
+        - A migration for the relevant model.
+        - A Concern that you can customise

data/lib/generators/referable/migrations.rb

@@ -0,0 +1,15 @@
+module Migrations
+  require_relative './migrations/model_migrator'
+  require_relative './migrations/reward_migrator'
+
+  include ModelMigrator
+  include RewardMigrator
+
+  def migration_created?(migration_name)
+    /#{migration_name}/ =~ last_migration
+  end
+
+  def last_migration
+    Dir['db/migrate/*'].last
+  end
+end

data/lib/generators/referable/migrations/model_migrator.rb

@@ -0,0 +1,48 @@
+module Migrations
+  module ModelMigrator
+    def create_model_migration
+      generate 'migration',
+               "add_referral_fields_to_#{file_name} \
+               last_reward_acquired_id:integer \
+               referral_slug \
+               referrals_count:integer"
+      add_model_migration_details
+    end
+
+    private
+
+    def add_model_migration_details
+      return unless migration_created?("_add_referral_fields_to_#{file_name}")
+      constrain_count
+      write_slug_data
+      constrain_slug
+    end
+
+    def constrain_count
+      inject_into_file(last_migration, after: '_count, :integer') do
+        ', default: 0, null: false'
+      end
+    end
+
+    def write_slug_data
+      inject_into_file(last_migration, after: 'null: false') do
+        <<~TEXT
+        \n
+            # Update each record with a slug
+            #{class_name}.find_each do |#{file_name}|
+              #{file_name}.valid?
+              #{file_name}.update_attribute(:slug, #{file_name}.slug)
+            end
+
+            # Add constraint
+        TEXT
+      end
+    end
+
+    def constrain_slug
+      inject_into_file(last_migration, after: 'Add constraint') do
+        "\n    change_column_null :#{plural_name}, :referral_slug, false"
+      end
+    end
+  end
+end

data/lib/generators/referable/migrations/referral_migration.rb

@@ -0,0 +1,28 @@
+module Migrations
+  module ReferralMigrator
+
+    def create_reward_migration
+      generate 'migration', "create_referrals"
+      add_referral_migration_details
+    end
+
+    private
+
+    def add_referral_migration_details
+      return unless migration_created?('create_referrals')
+      inject_into_file(last_migration, after: 'do |t|') do
+        <<~TEXT
+        \n
+            t.integer "recruit_id"
+            t.datetime "created_at", null: false
+            t.datetime "updated_at", null: false
+            t.string "referrer_type"
+            t.bigint "referrer_id"
+            t.string "recruit_type"
+            t.index ["recruit_type", "recruit_id"], name: "index_referrals_on_recruit_type_and_recruit_id"
+            t.index ["referrer_type", "referrer_id"], name: "index_referrals_on_referrer_type_and_referrer_id"
+        TEXT
+      end
+    end
+  end
+end

data/lib/generators/referable/migrations/reward_migrator.rb

@@ -0,0 +1,24 @@
+module Migrations
+  module RewardMigrator
+
+    def create_reward_migration
+      generate 'migration', "create_referable_rewards"
+      add_reward_migration_details
+    end
+
+    private
+
+    def add_reward_migration_details
+      return unless migration_created?('create_referable_rewards')
+      inject_into_file(last_migration, after: 'do |t|') do
+        <<~TEXT
+        \n
+              t.string "reward", null: false
+              t.integer "referrals_required", null: false
+              t.integer "acquireable_by", null: false
+              t.timestamps
+        TEXT
+      end
+    end
+  end
+end

data/lib/generators/referable/referable_generator.rb

@@ -0,0 +1,41 @@
+require 'rails/generators/base'
+
+class ReferableGenerator < Rails::Generators::NamedBase
+  require_relative './migrations'
+
+  include Migrations
+
+  source_root File.expand_path('../templates', __FILE__)
+
+  def copy_referral
+    copy_file "model/referal.rb", "app/models/referral.rb"
+  end
+
+  def copy_referable_concern
+    copy_file "concerns/referable.rb", "app/models/concerns/referable.rb"
+    copy_file "model/referable_reward.rb", "app/models/referable_reward.rb"
+  end
+
+  def setup_migrations
+    create_model_migration
+    create_reward_migration
+  end
+
+  def include_concern_in_class
+    inject_into_file "app/models/#{file_name}.rb", after: 'User < ApplicationRecord' do
+      "\n  include Referable"
+    end
+  end
+
+  def add_class_to_referable_reward
+    symbol_in_array = acquireable_by_empty? ? ":#{file_name}" : ", :#{file_name}"
+    inject_into_file('app/models/referable_reward.rb',
+                     before: '], _prefix: :acquireable_by') { symbol_in_array }
+  end
+
+  private
+
+  def acquireable_by_empty?
+    File.read('app/models/referable_reward.rb').include? 'acquireable_by: []'
+  end
+end

data/lib/generators/referable/templates/concerns/referable.rb

@@ -0,0 +1,55 @@
+module Referable
+  extend ActiveSupport::Concern
+
+  included do
+    has_many   :referrals, as: :referrer
+    has_many   :recruits, through: :referrals, source_type: name
+    belongs_to :last_reward_acquired,
+               class_name: 'ReferableReward',
+               default: -> { ReferableReward.zeroth_tier(self.class.name.downcase) }
+
+    before_save :add_referral_slug
+  end
+
+  def percent_to_next_reward
+    last_tier_count = last_reward_acquired.referrals_required
+    next_tier_count = last_reward_acquired
+                        .next_reward(above: referrals.size)
+                        .referrals_required - last_tier_count
+    current_count = referrals.size - last_tier_count
+    (current_count.to_f / next_tier_count) * 100
+  end
+
+  def distance_to_next_reward
+    last_reward_acquired
+      .next_reward(above: referrals.size)
+      .referrals_required - referrals.size
+  end
+
+  def acquired_reward!
+    update!(last_reward_acquired: last_reward_acquired.next_reward(above: referrals.size))
+  end
+
+  def increment!(attribute, by = 1)
+    super
+    check_for_new_reward
+  end
+
+  private
+
+  def check_for_new_reward
+    count = referrals.size
+    if count >= last_reward_acquired.next_reward(above: count).referrals_required
+      acquired_reward!
+    end
+  end
+
+  def add_referral_slug
+    self.referral_slug = create_referral_slug unless referral_slug
+  end
+
+  def create_referral_slug
+    slug = Utilities.generate_friendly_chars(3)
+    self.class.exists?(referral_slug: slug) ? create_referral_slug : slug
+  end
+end

data/lib/generators/referable/templates/model/referable_reward.rb

@@ -0,0 +1,39 @@
+class ReferableReward < ApplicationRecord
+
+  enum acquireable_by: [], _prefix: :acquireable_by
+
+  validates :referrals_required, uniqueness: {
+    scope: :acquireable_by, message: 'Target aleady present for this kind of reward'
+  }
+
+  def self.best_reward(acquireable_by)
+    where(acquireable_by: acquireable_by).order(referrals_required: :desc).first
+  end
+
+  def self.zeroth_tier(acquireable_by)
+    zeroth = find_by(referrals_required: 0, acquireable_by: acquireable_by)
+    return zeroth if zeroth
+    create!(reward: 'none', referrals_required: 0, acquireable_by: acquireable_by)
+  end
+
+  def next_reward(above: 0)
+    query = self.class
+                .where(acquireable_by: acquireable_by)
+                .where('referrals_required > ?', referrals_required)
+                .where('referrals_required >= ?', above)
+                .order(referrals_required: :asc)
+                .limit(1)
+    query.any? ? query.first : self
+  end
+
+  def previous_reward(below: 10e5)
+    query = self.class
+                .where(acquireable_by: acquireable_by)
+                .where('referrals_required < ?', referrals_required)
+                .where('referrals_required <= ?', below)
+                .order(referrals_required: :desc)
+                .limit(1)
+    query.any? ? query.first : self
+  end
+
+end

data/lib/generators/referable/templates/model/referral.rb

@@ -0,0 +1,6 @@
+class Referral < ApplicationRecord
+
+  belongs_to :referrer, polymorphic: true, counter_cache: true
+  belongs_to :recruit, polymorphic: true
+
+end

data/lib/referable.rb

@@ -0,0 +1,4 @@
+require 'referable/version'
+
+module Referable
+end

data/lib/referable/version.rb

@@ -0,0 +1,3 @@
+module Referable
+  VERSION = '0.2.0'
+end

data/referable.gemspec

@@ -0,0 +1,27 @@
+# coding: utf-8
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "referable/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = 'referable'
+  spec.version       = Referable::VERSION
+  spec.authors       = ['Daniel Steele']
+  spec.email         = ['danielsteele@hotmail.co.uk']
+
+  spec.summary       = 'Add a multi-tenant referral system to your app'
+  spec.description   = 'Add a multi-tenant referral and rewards system to your app'
+  spec.homepage      = 'https://github.com/eola/referable'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', '~> 1.15'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+end

metadata

@@ -0,0 +1,108 @@
+--- !ruby/object:Gem::Specification
+name: referable
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Daniel Steele
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2017-10-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Add a multi-tenant referral and rewards system to your app
+email:
+- danielsteele@hotmail.co.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- CODE_OF_CONDUCT.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/generators/referable/USAGE
+- lib/generators/referable/migrations.rb
+- lib/generators/referable/migrations/model_migrator.rb
+- lib/generators/referable/migrations/referral_migration.rb
+- lib/generators/referable/migrations/reward_migrator.rb
+- lib/generators/referable/referable_generator.rb
+- lib/generators/referable/templates/concerns/referable.rb
+- lib/generators/referable/templates/model/referable_reward.rb
+- lib/generators/referable/templates/model/referral.rb
+- lib/referable.rb
+- lib/referable/version.rb
+- referable.gemspec
+homepage: https://github.com/eola/referable
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.11
+signing_key: 
+specification_version: 4
+summary: Add a multi-tenant referral system to your app
+test_files: []