rspreedly 0.0.1

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,5 @@
+*.sw?
+.DS_Store
+coverage
+rdoc
+pkg

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Richard Livsey
+
+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.rdoc

@@ -0,0 +1,78 @@
+= RSpreedly
+
+Ruby library to access the Spreedly API (all of it).
+
+== Why another one?
+
+There are a few of these knocking about, but I couldn't find one particular to my needs:
+
+ * Well covered with specs (aiming for 100%)
+ * Covers the entire API, not just parts of it
+ * Rubyish/ActiveRecord style access
+
+== Usage
+
+Configure your API key and site name for your account:
+
+    RSpreedly::Config.setup do |config|
+      config.api_key        = "your-api-key"
+      config.site_name      = "your-site-name"
+    end
+
+List subscribers
+
+    RSpreedly::Subscriber.find(:all).each do |subscriber|
+      # do something
+    end
+
+CRUD access to subscribers
+
+    sub = RSpreedly::Subscriber.new(:customer_id => 42, :email => "somewhere@example.com")
+    sub.token => nil
+    sub.save 
+    sub.token => "6af9994a57e420345897b1abb4c27a9db27fa4d0"
+        
+    sub = RSpreedly::Subscriber.find(42)
+    sub.email = "new-email@example.com"
+    sub.save
+    
+    sub = RSpreedly::Subscriber.find(69)
+    sub.destroy
+
+Comp subscriptions
+
+    comp = RSpreedly::ComplimentarySubscription.new(:duration_quantity => 3, :duration_units => "months", :feature_level => "Pro")      
+    sub = RSpreedly::Subscriber.find(69)
+    sub.comp_subscription(comp)
+
+View all plans
+
+    plans = RSpreedly::SubscriptionPlan.find(:all)
+    
+Raise an invoice, and pay it
+
+    invoice = Invoice.new(:subscription_plan_id => 5, :subscriber => sub)
+    invoice.save
+    
+    payment = RSpreedly::PaymentMethod::CreditCard(:card_type => 'visa', :number => '123456', ...)
+    invoice.pay(payment)
+
+See the specs and API docs at Spreedly for more details and the rest of the things it can do.
+
+https://www.spreedly.com/manual/integration-reference/url-reference/
+
+== Todo
+
+ * Better specs for data we send to Spreedly.
+ * Better docs.
+
+== Thanks
+
+I studied the other Spreedly APIs and there may well be a line or three this library has in common with:
+
+ * http://github.com/terralien/spreedly-gem
+ * http://github.com/erbmicha/spreedly/
+
+== Copyright
+
+Copyright (c) 2009 Richard Livsey. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,48 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "rspreedly"
+    gem.summary = %Q{Ruby library for the Spreedly API}
+    gem.email = "richard@livsey.org"
+    gem.homepage = "http://github.com/rlivsey/rspreedly"
+    gem.authors = ["Richard Livsey"]
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION.yml')
+    config = YAML.load(File.read('VERSION.yml'))
+    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "RSpreedly #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+

data/VERSION

@@ -0,0 +1 @@
+0.0.1

data/lib/rspreedly/base.rb

@@ -0,0 +1,76 @@
+module RSpreedly
+
+  class Base
+    include HTTParty
+    format :xml
+    base_uri "https://spreedly.com/api/v4"
+
+    def self.api_request(type, path, options={})
+      path = "#{RSpreedly::Config.site_name}#{path}"
+      options.merge!({
+        :basic_auth => {:username => RSpreedly::Config.api_key, :password => 'X'},
+        :headers    => {"Content-Type" => 'application/xml'}
+      })
+      self.do_request(type, path, options)
+    end
+
+    def self.do_request(type, path, options)
+      response  = self.send(type.to_s, path, options)      
+      message   = "#{response.code}: #{response.body}"
+      
+      case response.code.to_i
+      when 403
+        raise(RSpreedly::Error::Forbidden.new, message)
+      when 422
+        raise(RSpreedly::Error::BadRequest.new, message)
+      when 404
+        raise(RSpreedly::Error::NotFound.new, message)        
+      end      
+
+      response
+    end
+
+    def initialize(attrs={})
+      self.attributes = attrs
+    end
+    
+    def attributes=(attrs)
+      attrs.each do |k, v|
+        self.send("#{k}=", v)
+      end      
+    end
+    
+    def api_request(type, path, options={})
+      self.class.api_request(type, path, options)
+    end
+
+    # TODO - do this nicer
+    # rather eew at the moment and hand made XML is not nice
+    def to_xml(opts={})
+      exclude = opts[:exclude] || []
+      
+      tag     = opts[:tag] || RSpreedly.underscore(self.class.to_s)
+      inner   = opts[:inner]
+      outer   = opts[:outer]      
+      no_tag  = opts[:no_tag]
+      
+      xml = ""
+      xml << "<#{outer}>" if outer
+      xml << "<#{tag}>" unless no_tag
+      xml << "<#{inner}>" if inner
+      self.instance_variables.each do |var|
+        name = var.gsub('@', '')
+        next if exclude.include?(name.to_sym)
+        value = self.instance_variable_get(var)
+        if value.respond_to?(:to_xml)
+          value = value.to_xml(:no_tag => (RSpreedly.underscore(value.class.to_s) == name)) 
+        end
+        xml << "<#{name}>#{value}</#{name}>"
+      end
+      xml << "</#{inner}>" if inner      
+      xml << "</#{tag}>" unless no_tag
+      xml << "</#{outer}>" if outer      
+      xml
+    end
+  end
+end

data/lib/rspreedly/complimentary_subscription.rb

@@ -0,0 +1,5 @@
+module RSpreedly
+  class ComplimentarySubscription < Base
+    attr_accessor :duration_quantity, :duration_units, :feature_level
+  end
+end

data/lib/rspreedly/complimentary_time_extension.rb

@@ -0,0 +1,5 @@
+module RSpreedly
+  class ComplimentaryTimeExtension < Base
+    attr_accessor :duration_quantity, :duration_units
+  end
+end

data/lib/rspreedly/config.rb

@@ -0,0 +1,84 @@
+module RSpreedly
+  module Config    
+    class << self
+      
+      # the configuration hash itself
+      def configuration
+        @configuration ||= defaults
+      end
+      
+      def defaults
+        {
+          :logger     => defined?(RAILS_DEFAULT_LOGGER) ? RAILS_DEFAULT_LOGGER : Logger.new(STDOUT),
+          :debug      => false,
+          :site_name  => nil,   # your site name
+          :key        => nil    # your API key
+        }
+      end
+      
+      def [](key)
+        configuration[key]
+      end
+      
+      def []=(key, val)
+        configuration[key] = val
+      end
+
+      # remove an item from the configuration
+      def delete(key)
+        configuration.delete(key)
+      end
+      
+      # Return the value of the key, or the default if doesn't exist
+      # 
+      # ==== Examples
+      # 
+      # RSpreedly::Config.fetch(:monkey, false)
+      # => false
+      # 
+      def fetch(key, default)
+        configuration.fetch(key, default)
+      end
+
+      def to_hash
+        configuration
+      end      
+
+      # Yields the configuration.
+      # 
+      # ==== Examples
+      #   RSpreedly::Config.use do |config|
+      #     config[:debug]    = true
+      #     config.something  = false
+      #   end
+      # 
+      def setup
+        yield self
+        nil
+      end      
+
+      def clear
+        @configuration = {}
+      end
+      
+      def reset
+        @configuration = defaults
+      end
+      
+      # allow getting and setting properties via RSpreedly::Config.xxx
+      # 
+      # ==== Examples
+      # RSpreedly::Config.debug
+      # RSpreedly::Config.debug = false
+      # 
+      def method_missing(method, *args)
+        if method.to_s[-1,1] == '='
+          configuration[method.to_s.tr('=','').to_sym] = *args
+        else
+          configuration[method]
+        end
+      end      
+      
+    end 
+  end
+end

data/lib/rspreedly/error.rb

@@ -0,0 +1,9 @@
+module RSpreedly
+  module Error
+    class Base            < StandardError;  end
+    class Forbidden       < Base;             end # 403 errors
+    class BadRequest      < Base;             end # 422 errors
+    class NotFound        < Base;             end # 404 errors
+    class GatewayTimeout  < Base;             end # 504 errors  
+  end  
+end

data/lib/rspreedly/invoice.rb

@@ -0,0 +1,61 @@
+module RSpreedly
+
+  class Invoice < Base
+
+    attr_accessor :subscription_plan_id, 
+                  :subscriber,
+                  :closed,
+                  :created_at,
+                  :token,
+                  :updated_at,
+                  :price,
+                  :amount,
+                  :currency_code,
+                  :line_items
+
+    # Create an Invoice (more)
+    # POST /api/v4/[short site name]/invoices.xml
+    def create
+      begin
+        create!
+      rescue RSpreedly::Error::Base
+        # gulp those errors down
+        # TODO - set self.errors or something?
+      end      
+    end
+
+    def create!
+      result = api_request(:post, "/invoices.xml", :body => self.to_xml)
+      self.attributes = result["invoice"]
+      true      
+    end
+
+    alias_method :save,   :create
+    alias_method :save!,  :create!
+
+    def subscriber=(data)
+      if data.is_a? Hash
+        data = RSpreedly::Subscriber.new(data)
+      end
+      @subscriber = data
+    end
+    
+    def line_items=(data)
+      @line_items = []
+      data.each do |item|
+        if item.is_a? Hash
+          item = RSpreedly::LineItem.new(item)
+        end
+        @line_items << item
+      end
+    end
+
+    # Pay an Invoice (more)
+    # PUT /api/v4/[short site name]/invoices/[invoice token]/pay.xml
+    def pay(payment)
+      result = api_request(:put, "/invoices/#{self.token}/pay.xml", :body => payment.to_xml(:outer => 'payment'))
+      self.attributes = result["invoice"]
+      true
+    end
+  end
+end

data/lib/rspreedly/line_item.rb

@@ -0,0 +1,5 @@
+module RSpreedly
+  class LineItem < Base
+    attr_accessor :price, :notes, :amount, :description, :currency_code
+  end
+end

data/lib/rspreedly/payment_method.rb

@@ -0,0 +1,7 @@
+module RSpreedly
+  module PaymentMethod
+    class CreditCard < Base
+      attr_accessor :number, :verification_value, :month, :year, :first_name, :last_name, :card_type
+    end
+  end
+end

data/lib/rspreedly/subscriber.rb

@@ -0,0 +1,153 @@
+module RSpreedly
+
+  class Subscriber < Base
+
+    attr_accessor :active,
+                  :active_until,
+                  :billing_first_name,
+                  :billing_last_name,
+                  :card_expires_before_next_auto_renew,
+                  :created_at,
+                  :customer_id,
+                  :eligible_for_free_trial,
+                  :email,
+                  :feature_level,
+                  :grace_until,
+                  :in_grace_period,
+                  :lifetime_subscription,
+                  :new_customer_id,
+                  :on_trial,
+                  :payment_method,
+                  :ready_to_renew,
+                  :recurring,
+                  :screen_name,
+                  :store_credit,
+                  :store_credit_currency_code,
+                  :subscription_plan_name,
+                  :token,
+                  :updated_at
+
+    class << self
+
+      # Get a subscriber’s details
+      # GET /api/v4/[short site name]/subscribers/[subscriber id].xml    
+      def find(id)      
+        return all if id == :all
+
+        begin
+          data = api_request(:get, "/subscribers/#{id}.xml")
+          Subscriber.new(data["subscriber"])
+        rescue RSpreedly::Error::NotFound
+          nil
+        end
+      end
+
+      # Get a list of all subscribers (more)
+      # GET /api/v4/[short site name]/subscribers.xml    
+      def all
+        response = api_request(:get, "/subscribers.xml")
+        return [] unless response.has_key?("subscribers")
+        response["subscribers"].collect{|data| Subscriber.new(data)}
+      end
+
+      # Clear all subscribers from a *test* site (more)
+      # DELETE /api/v4/[short site name]/subscribers.xml
+      def delete_all
+        !! api_request(:delete, "/subscribers.xml")      
+      end
+
+      alias_method :destroy_all, :delete_all
+
+    end
+
+    def new_record?
+      !self.token
+    end
+
+    def save
+      self.new_record? ? self.create : self.update
+    end
+
+    # Create a subscriber (more)
+    # POST /api/v4/[short site name]/subscribers.xml    
+    def create!
+      result = api_request(:post, "/subscribers.xml", :body => self.to_xml)
+      self.attributes = result["subscriber"]
+      true
+    end
+
+    def create
+      begin
+        create!
+      rescue RSpreedly::Error::Base
+        # gulp those errors down
+        # TODO - set self.errors or something?
+      end
+    end
+
+    # Update a Subscriber (more)
+    # PUT /api/v4/[short site name]/subscribers/[subscriber id].xml    
+    def update!
+      !! api_request(:put, "/subscribers/#{self.customer_id}.xml", :body => self.to_xml(:exclude => [:customer_id]))
+    end
+
+    def update
+      begin
+        update!
+      rescue RSpreedly::Error::Base
+        # gulp those errors down
+        # TODO - set self.errors or something?
+      end      
+    end
+
+    # Delete one subscriber from a *test* site (more)
+    # DELETE /api/v4/[short site name]/subscribers/[subscriber id].xml    
+    def destroy
+      begin
+        !! api_request(:delete, "/subscribers/#{self.customer_id}.xml")
+      rescue RSpreedly::Error::NotFound
+        nil
+      end      
+    end
+    alias_method :delete, :destroy
+
+    # Give a subscriber a complimentary subscription (more)
+    # POST /api/v4/[short site name]/subscribers/[subscriber id]/complimentary_subscriptions.xml    
+    def comp_subscription(subscription)
+      result = api_request(:post, "/subscribers/#{self.customer_id}/complimentary_subscriptions.xml", :body => subscription.to_xml)
+      self.attributes = result["subscriber"]
+      true
+    end
+
+    # Give a subscriber a complimentary time extension (more)
+    # POST /api/v4/[short site name]/subscribers/[subscriber id]/complimentary_time_extension.xml
+    def comp_time_extension(extension)
+      result = api_request(:post, "/subscribers/#{self.customer_id}/complimentary_time_extensions.xml", :body => extension.to_xml)
+      self.attributes = result["subscriber"]
+      true      
+    end
+
+    # Programatically Stopping Auto Renew of a Subscriber (more)
+    # POST /api/v4/[short site name]/subscribers/[subscriber id]/stop_auto_renew.xml
+    def stop_auto_renew
+      !! api_request(:post, "/subscribers/#{self.customer_id}/stop_auto_renew.xml")
+    end
+
+    # Programatically Subscribe a Subscriber to a Free Trial Plan (more)
+    # POST /api/v4/[short site name]/subscribers/[subscriber id]/subscribe_to_free_trial.xml
+    def subscribe_to_free_trial(plan)
+      result = api_request(:post, "/subscribers/#{self.customer_id}/subscribe_to_free_trial.xml", :body => plan.to_xml)
+      self.attributes = result["subscriber"]
+      true      
+    end
+
+    # Programatically Allow Another Free Trial (more)
+    # POST /api/v4/[short site name]/subscribers/[subscriber id]/allow_free_trial.xml
+    def allow_free_trial
+      result = api_request(:post, "/subscribers/#{self.customer_id}/allow_free_trial.xml")
+      self.attributes = result["subscriber"]
+      true            
+    end
+
+  end
+end

data/lib/rspreedly/subscription_plan.rb

@@ -0,0 +1,40 @@
+module RSpreedly
+    
+  class SubscriptionPlan < Base
+    
+    attr_accessor :amount,
+                  :charge_after_first_period,
+                  :charge_later_duration_quantity,
+                  :charge_later_duration_units,
+                  :created_at,
+                  :currency_code,
+                  :description,
+                  :duration_quantity,
+                  :duration_units,
+                  :enabled,
+                  :feature_level,
+                  :force_recurring,
+                  :id,
+                  :name,
+                  :needs_to_be_renewed,
+                  :plan_type,
+                  :price,
+                  :return_url,
+                  :terms,
+                  :updated_at
+    
+    # there's no API method for just getting one plan, so we fake it!
+    def self.find(id)
+      return all if id == :all
+      all.find{|plan| plan.id == id}
+    end
+    
+    # Get a list of all subscription plans (more)
+    # GET /api/v4/[short site name]/subscription_plans.xml
+    def self.all
+      response = api_request(:get, "/subscription_plans.xml")
+      return [] unless response.has_key?("subscription_plans")
+      response["subscription_plans"].collect{|data| SubscriptionPlan.new(data)}
+    end
+  end
+end

data/lib/rspreedly.rb

@@ -0,0 +1,29 @@
+require 'logger'
+require 'httparty'
+
+require 'rspreedly/error'
+require 'rspreedly/config'
+require 'rspreedly/base'
+require 'rspreedly/invoice'
+require 'rspreedly/line_item'
+require 'rspreedly/subscriber'
+require 'rspreedly/subscription_plan'
+require 'rspreedly/payment_method'
+require 'rspreedly/complimentary_subscription'
+require 'rspreedly/complimentary_time_extension'
+
+
+module RSpreedly
+
+  # a few utility methods
+
+  # pretty much stolen from Rails
+  def self.underscore(camel_cased_word)
+    camel_cased_word.to_s.gsub(/\w+::/, '').
+    gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+    gsub(/([a-z\d])([A-Z])/,'\1_\2').
+    tr("-", "_").
+    downcase
+  end
+
+end