promo 0.0.1

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,2 @@
+--colour
+--backtrace

data/Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in promo.gemspec
+gemspec
+
+gem 'pry'

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Pedro Ivo
+
+MIT License
+
+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,122 @@
+# Promo
+
+A gem to generate and use coupons and promocodes
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'promo'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install promo
+
+## Usage
+
+First you need to create the migrations needed in the gem:
+
+    # rails generate promo:install
+
+Objects must always be created through generate method instead using new.
+Here you may define some options:
+
+```ruby
+promo = Promo::Promocode.generate(options)
+
+options.multiple: false
+options.quantity: 1
+options.type: :percentage
+options.status: :valid
+options.expires: 4.weeks
+options.code: SecureRandom.hex(4)
+options.product: Some model with has_many :promocodes, as: :product
+```
+
+### Associated models
+
+#### Cart / Order
+While in a ecommerce, you might have a Cart and Order models (or any correspondency). thus you must associate these models in order to accept the promocodes associated.
+
+In a simple example, we might define a Cart model as:
+```ruby
+class Cart < ActiveRecord::Base
+  has_many :cart_items, dependent: :destroy
+  has_one :promo_history, :class_name => 'Promo::History'
+  has_one :promocode, through: :promo_history
+  ...
+end
+
+```
+
+And then, after the checkout that Cart model suppose to be transformed (or coppied) to a Order object, something like:
+
+```ruby
+class Order < ActiveRecord::Base
+  has_many :order_items, dependent: :destroy
+  has_one :promo_history, :class_name => 'Promo::History'
+  has_one :promocode, through: :promo_history
+  ...
+end
+
+```
+
+#### Products
+
+As a promocode may be associated with any kind of product, in the model you want allow it, you must define as
+
+```ruby
+class Product < ActiveRecord::Base
+  has_many :promocodes, as: :product
+
+  has_many :cart_item, as: :product
+  has_many :order_item, as: :product
+  
+  has_many :carts, through: :cart_item
+  has_many :orders, through: :order_item
+  ...
+end
+```
+
+### Then you can calculate the discount by
+
+```ruby
+class Cart < ActiveRecord::Base
+  def recalculate
+    self.update_attribute(:total_value, cart_items.map{ |i| i.product.value }.reduce(:+))
+    self.update_attribute(:discount_value, Promo::Usage.discount_for(promocode: self.promocode, product_list: product_list))
+    self.update_attribute(:final_value, self.total_value-self.discount_value)
+  end
+end
+```
+
+### Example application
+I've created a sample application with a basic product/cart/order model to test the gem, and also might be used as base for any simple ecommerce:
+
+http://github.com/x1s/promo-example-cart
+
+### Administration view
+
+```ruby
+# if you require 'sinatra' you get the DSL extended to Object
+gem 'sinatra', '>= 1.3.0', :require => nil
+```
+
+Add the following to your config/routes.rb:
+
+```ruby
+require 'promo/web'
+mount Promo::Web => '/promo'
+```
+
+## Contributing
+
+1. Fork it ( http://github.com/x1s/promo/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/config/locale/promo.en.yml

@@ -0,0 +1,8 @@
+promocode:
+  messages:
+    already_used: 'Promocode already used'
+    invalid: 'Invalid Promocode'
+    expired: 'This promocode has expired'
+    invalid_use: 'Invalid use of this promocode'
+    not_valid_for: 'This promocode is not valid for'
+    must_have_product: 'Product associated with this Promocode not found'

data/config/locale/promo.pt.yml

@@ -0,0 +1,8 @@
+promocode:
+  messages:
+    already_used: 'Promocode já utilizado'
+    invalid: 'Promocode inválido'
+    expired: 'Este promocode já expirou'
+    invalid_use: 'Uso invalido do cupão'
+    not_valid_for: 'Este cupão não é valido para este uso'
+    must_have_product: 'O produto associado ao promocode não foi encontrado'

data/lib/generators/promo/install/install_generator.rb

@@ -0,0 +1,20 @@
+# encoding: utf-8
+
+module Promo
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      desc 'Creates the models to the file'
+
+      def self.source_root
+        @_promo_source_root ||= File.expand_path("../templates", __FILE__)
+      end
+
+      def create_migration_files
+        time = Time.now.strftime("%Y%m%d%H%M%S").to_i
+        template '1_create_promo_promocode.rb', File.join('db', 'migrate', "#{time}_create_promo_promocode.rb")
+        template '2_create_promo_history.rb', File.join('db', 'migrate', "#{time+1}_create_promo_history.rb")
+      end
+
+    end
+  end
+end

data/lib/generators/promo/install/templates/1_create_promo_promocode.rb

@@ -0,0 +1,19 @@
+class CreatePromoPromocode < ActiveRecord::Migration
+  def change
+    create_table :promo_promocodes do |t|
+      t.references :product, polymorphic: true, index: true
+      t.references :cart, polymorphic: true, index: true
+      t.references :order, polymorphic: true, index: true
+      t.integer :value, default: 0
+      t.integer :promo_type, null: false
+      t.integer :status, default: 1
+      t.integer :quantity, default: 1
+      t.integer :used, default: 0
+      t.datetime :expires, null: false
+      t.string :code, null: false, index: true
+      t.datetime :used_at
+
+      t.timestamps
+    end
+  end
+end

data/lib/generators/promo/install/templates/2_create_promo_history.rb

@@ -0,0 +1,10 @@
+class CreatePromoHistory < ActiveRecord::Migration
+  def change
+    create_table :promo_histories do |t|
+      t.references :cart, polymorphic: true, index: true
+      t.references :order, polymorphic: true, index: true
+      t.references :promo_promocode, index: true
+      t.timestamps
+    end
+  end
+end

data/lib/promo.rb

@@ -0,0 +1,15 @@
+require "promo/version"
+
+require 'promo/promocode'
+require 'promo/history'
+require 'promo/usage'
+
+module Promo
+end
+
+class PromocodeException < StandardError; end
+class UsedPromocode < PromocodeException; end
+class ExpiredPromocode < PromocodeException; end
+class InvalidPromocode < PromocodeException; end
+class InvalidPromoProduct < PromocodeException; end
+

data/lib/promo/history.rb

@@ -0,0 +1,8 @@
+module Promo
+  class History < ActiveRecord::Base
+    self.table_name = 'promo_histories'
+    belongs_to :cart
+    belongs_to :order
+    belongs_to :promocode, :class_name => 'Promo::Promocode', :foreign_key => "promo_promocode_id"
+  end
+end

data/lib/promo/promocode.rb

@@ -0,0 +1,150 @@
+module Promo
+  class Promocode < ActiveRecord::Base
+    self.table_name = 'promo_promocodes'
+    # Forbide direct creation of objects
+    private_class_method :create
+
+    belongs_to :product, polymorphic: true
+
+    has_many :histories, :class_name => 'Promo::History', :foreign_key => "promo_promocode_id"
+    has_many :carts, through: :histories
+    has_many :orders, through: :histories
+
+    validates :code, uniqueness: true
+
+    STATUS = { valid: 0, expired: 1, invalid: 2, used: 3}
+    TYPE = { percentage: 1, fixed_value: 0 }
+
+    scope :last, -> { where(status: STATUS[:valid]).order(id: :desc).limit(10) }
+    scope :used, -> { where(status: STATUS[:used]).order(used_at: :desc) }
+    scope :invalid, -> { where(status: STATUS[:invalid]).order(used_at: :desc) }
+    scope :expired, -> { where("status = ? OR expires < ?", STATUS[:expired], Time.now).order(expires: :desc) }
+
+    # Objects must always be created through generate method instead using new.
+    # here you may define some options:
+    #  options.multiple: false
+    #  options.quantity: 1
+    #  options.type: :percentage
+    #  options.status: :valid
+    #  options.expires: 4.weeks
+    #  options.code: SecureRandom.hex(4)
+    #  options.product: Some model with has_many :promocodes, as: :product
+    #  options.product_type: Associate the promocode with a class of product (any product of that class)
+    def self.generate(options={})
+      options[:multiple] ||= false
+      options[:quantity] ||= 1
+      options[:quantity] = 1 if options[:quantity].to_i <= 0
+      options[:promo_type] ||= TYPE[:percentage]
+      options[:status] ||= STATUS[:valid]
+      options[:expires] ||= Time.now + 4.weeks
+
+      if options[:code].blank?
+        options[:code] = generate_code
+        generated_code = true
+      else
+        generated_code = false
+        options[:code] = generate_code(0,options[:code])
+      end
+
+      multiple = options[:multiple]
+      options.delete(:multiple)
+
+      if multiple
+        ret = []
+        many = options[:quantity].to_i
+        options[:quantity] = 1
+        many.times do |item|
+          opt = options.dup
+          opt[:code] = generate_code if generated_code
+          opt[:code] = generate_code(0,options[:code]+item.to_s) if !generated_code
+          ret << create!(opt)
+        end
+        return ret
+      end
+      create!(options)
+    end
+
+    #--------------------------
+
+    def use (options={})
+      is_valid? options
+
+      self.used += 1
+      self.status = STATUS[:used] if self.quantity == self.used
+      self.used_at = Time.now
+      save
+      self
+    end
+
+    def invalidate!
+      update_attributes(status: STATUS[:invalid], used_at: Time.now)
+    end
+
+    #--------------------------
+
+    def has_product?
+      !self.product.nil?
+    end
+
+    def is_percentage?
+      self.promo_type == TYPE[:percentage]
+    end
+
+    def is_fixed_value?
+      self.promo_type == TYPE[:fixed_value]
+    end
+
+    def is_expired?
+      return true if self.status == STATUS[:expired]
+      return false if self.expires > Time.now
+      update_attribute(:status, STATUS[:expired])
+      true
+    end
+
+
+    # Validates the use of this promocode
+    # Options:
+    #  product_list: Array with products, mandatory when the promocode is associated with
+    #                a specific product or a specific category of products
+    #    
+    def is_valid?(options={})
+      raise UsedPromocode.new 'promocode.messages.already_used' if self.status == STATUS[:used]
+      raise InvalidPromocode.new 'promocode.messages.invalid' if self.status != STATUS[:valid]
+      raise ExpiredPromocode.new 'promocode.messages.expired' if is_expired?
+
+      # Validating use with a specific product associated
+      if self.has_product?
+        logger.debug "#------------ Promocode associated with a product"
+        raise InvalidPromocode.new 'promocode.messages.invalid_use' if options[:product_list].nil?
+        if self.product && !options[:product_list].include?(self.product)
+          logger.debug "#--------------- Product associated not found on the list"
+          raise InvalidPromoProduct.new 'promocode.messages.not_valid_for'
+        end
+      end
+
+      # Validating use with when a class of product is associated with the promocode
+      # not a specific product (no product_id defined)
+      if self.product_id.nil? && !self.product_type.nil?
+        logger.debug "#------------ Promocode associated with a class"
+        raise InvalidPromocode.new 'promocode.messages.invalid_use' if options[:product_list].nil?
+        if options[:product_list].none? { |p| p.class.to_s == self.product_type }
+          logger.debug "#--------------- Class associated not found on the list"
+          raise InvalidPromoProduct.new 'promocode.messages.must_have_course'
+        end
+      end
+      # Returns the promocode if it's valid
+      self
+    end
+
+    # Generate random codes
+    def self.generate_code(size=4,code="")
+      code = SecureRandom.hex(size) if code.empty?
+      code = code+SecureRandom.hex(size) unless code.empty?
+      # Validates if the code is already created, then add something to the name
+      if Promo::Promocode.where(code: code).first
+        code = code+SecureRandom.hex(1)
+      end
+      code
+    end
+  end
+end

data/lib/promo/usage.rb

@@ -0,0 +1,52 @@
+module Promo
+  class Usage
+    class << self
+      # Validates the use of any promocode
+      # Options (Hash):
+      #  code: string with the code used
+      #  product_list: array with the products to be evaluated
+      def validate (options={})
+        promocode = Promo::Promocode.where(code: options[:code]).first
+        raise InvalidPromocode.new 'promocode.messages.invalid' if promocode.nil?
+        promocode.is_valid? options
+      end
+
+      # Calculates the discounts to any list of products
+      # Options (Hash):
+      #  promocode: Pomo::Promocode object
+      #  product_list: array with the products to be evaluated
+      def discount_for (options={})
+        return 0 if options[:promocode].nil?
+        promocode = options[:promocode]
+        product_list = options[:product_list]
+
+        return discount_for_product(promocode, product_list) if promocode.has_product?
+        if promocode.is_percentage?
+          calculate_percentage product_list.map(&:value).reduce(:+), promocode.value
+        else
+          promocode.value
+        end
+      end
+
+      # Calculates the dicount for a specific product in the list
+      # previously associated with the current promocode
+      # Parameters:
+      #  promocode: Pomo::Promocode object
+      #  product_list: array with the products to be evaluated
+      def discount_for_product promocode, product_list
+        product = promocode.product
+        return 0 unless product_list.include? product
+        if promocode.is_percentage?
+          calculate_percentage(product.value,promocode.value)
+        else
+          promocode.value
+        end
+      end
+
+      #calculates the percentage to a specific value
+      def calculate_percentage(value, percent)
+        (value * (percent.to_f/100)).to_i
+      end
+    end
+  end
+end

data/lib/promo/version.rb

@@ -0,0 +1,3 @@
+module Promo
+  VERSION = "0.0.1"
+end

data/promo.gemspec

@@ -0,0 +1,24 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'promo/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "promo"
+  spec.version       = Promo::VERSION
+  spec.authors       = ["Pedro Ivo"]
+  spec.email         = ["pedroivo@x1s.eti.br"]
+  spec.summary       = %q{Create coupons and promocodes}
+  spec.description   = %q{}
+  spec.homepage      = "http://github.com/x1s"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.5"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec"
+end

metadata

@@ -0,0 +1,121 @@
+--- !ruby/object:Gem::Specification
+name: promo
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Pedro Ivo
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-02-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: ''
+email:
+- pedroivo@x1s.eti.br
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- config/locale/promo.en.yml
+- config/locale/promo.pt.yml
+- lib/generators/promo/install/install_generator.rb
+- lib/generators/promo/install/templates/1_create_promo_promocode.rb
+- lib/generators/promo/install/templates/2_create_promo_history.rb
+- lib/promo.rb
+- lib/promo/history.rb
+- lib/promo/promocode.rb
+- lib/promo/usage.rb
+- lib/promo/version.rb
+- promo.gemspec
+- spec/lib/promo/history_spec.rb
+- spec/lib/promo/promocode_spec.rb
+- spec/lib/promo/usage_spec.rb
+- spec/lib/promo_spec.rb
+- spec/spec_helper.rb
+homepage: http://github.com/x1s
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: Create coupons and promocodes
+test_files:
+- spec/lib/promo/history_spec.rb
+- spec/lib/promo/promocode_spec.rb
+- spec/lib/promo/usage_spec.rb
+- spec/lib/promo_spec.rb
+- spec/spec_helper.rb