recurly 0.4.16 → 2.0.0

data/README.markdown

@@ -0,0 +1,118 @@
+# Recurly
+
+<http://github.com/recurly/recurly-ruby-client>
+
+[Recurly](http://recurly.com/)'s Ruby client library is an interface to its
+[REST API](http://docs.recurly.com/api/basics).
+
+
+## Installation
+
+Recurly is packaged as a Ruby gem. We recommend you install it with
+[Bundler](http://gembundler.com/) by adding the following line to your Gemfile:
+
+``` ruby
+gem 'recurly', '~> 2.0.0'
+```
+
+Recurly will automatically use [Nokogiri](http://nokogiri.org/) (for a nice
+speed boost) if it's available and loaded in your app's environment.
+
+
+## Configuration
+
+If you're using Rails, you can generate an initializer with the following
+command:
+
+``` bash
+$ rails g recurly:config
+```
+
+If you're not using Rails, use the following template:
+
+``` ruby
+Recurly.api_key        = ENV['RECURLY_API_KEY']
+Recurly.js.private_key = ENV['RECURLY_JS_PRIVATE_KEY']
+```
+
+Configure the client library with the credentials you find at
+`https://{subdomain}.recurly.com/developer/api_access` (replace `{subdomain}`
+with your Recurly subdomain).
+
+
+## Usage
+
+Instructions and examples are available on
+[Recurly's documentation site](http://docs.recurly.com/api/basics).
+
+Recurly's gem API is available [here](http://rdoc.info/gems/recurly).
+
+
+## Contributing
+
+Developing for the Recurly gem is easy with [Bundler](http://gembundler.com/).
+
+Fork and clone the repository, `cd` into the directory, and, with a Ruby of
+your choice (1.8.7 is supported, but we suggest 1.9.2 or greater), set up your
+environment.
+
+If you don't have Bundler installed, install it with the following command:
+
+``` bash
+$ [sudo] gem install bundler
+```
+
+And bundle:
+
+``` bash
+$ bundle --path=vendor/bundle
+```
+
+You should now be able to run the test suite with Rake:
+
+``` bash
+$ bundle exec rake
+```
+
+To run the suite using Nokogiri:
+
+``` bash
+$ XML=nokogiri bundle exec rake
+```
+
+Or, if [Guard](https://github.com/guard/guard) is more your speed:
+
+``` bash
+$ bundle exec guard
+```
+
+If you plan on submitting a patch, please write tests for it (we use
+[MiniTest::Spec](http://bfts.rubyforge.org/minitest/MiniTest/Expectations.html)).
+
+If everything looks good, submit a pull request on GitHub and we'll bring in
+your changes.
+
+
+## License
+
+(The MIT License.)
+
+© 2011 Recurly Inc.
+
+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/bin/recurly

@@ -0,0 +1,78 @@
+#!/usr/bin/env ruby
+$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
+
+module CLI
+  def version
+    require 'recurly/version'
+    "Recurly v#{Recurly::Version::VERSION}"
+  end
+
+  def clear
+    print `clear`
+  end
+end
+include CLI
+
+require 'optparse'
+options = {}
+OptionParser.new do |opts|
+  opts.banner = 'Usage: recurly [options] -- [irb options]'
+
+  opts.on '-k', '--api-key [api key]', 'Your API key' do |api_key|
+    options[:api_key] = api_key
+  end
+
+  opts.on '-v', '--verbose', 'Show full request/response log' do |verbose|
+    options[:verbose] = verbose
+  end
+
+  opts.on(
+    '-e', '--exec [code]', 'Execute a line of code before the session'
+  ) do |line|
+    options[:exec] = line
+  end
+
+  opts.separator nil
+
+  opts.on '-h', '--help', 'Display this screen' do
+    puts opts
+    exit
+  end
+
+  opts.on '--version', 'The current version' do
+    puts version
+    exit
+  end
+end.parse!
+
+require 'recurly'
+Recurly.api_key = options[:api_key] || ENV['RECURLY_API_KEY']
+include Recurly
+
+require 'logger'
+Recurly.logger = Logger.new(
+  STDOUT, options[:verbose] ? Logger::DEBUG : Logger::INFO
+)
+
+require 'irb'
+require 'irb/completion'
+
+class << IRB
+  alias old_setup setup
+  def setup ap_path
+    old_setup ap_path
+    conf[:PROMPT][:RECURLY] = {
+      :PROMPT_N => 'recurly> ',
+      :PROMPT_I => 'recurly> ',
+      :PROMPT_S => nil,
+      :PROMPT_C => ' ?> ',
+      :RETURN => " => %s\n"
+    }
+    conf[:PROMPT_MODE] = :RECURLY
+  end
+end
+
+puts version
+eval options[:exec] if options[:exec]
+IRB.start $0
+exit!

data/lib/rails/generators/recurly/config_generator.rb

@@ -0,0 +1,16 @@
+module Recurly
+  class ConfigGenerator < Rails::Generators::Base
+    desc "Creates a configuration file at config/initializers/recurly.rb"
+
+    # Creates a configuration file at <tt>config/initializers/recurly.rb</tt>
+    # when running <tt>rails g recurly:config</tt>.
+    def create_recurly_file
+      create_file 'config/initializers/recurly.rb', <<EOF
+Recurly.api_key          = ENV['RECURLY_API_KEY']
+Recurly.js.private_key   = ENV['RECURLY_JS_PRIVATE_KEY']
+
+# Recurly.default_currency = 'USD'
+EOF
+    end
+  end
+end

data/lib/rails/recurly.rb

@@ -0,0 +1,13 @@
+module Recurly
+  class Railtie < Rails::Railtie
+    initializer :recurly_set_logger do
+      Recurly.logger = Rails.logger
+    end
+
+    initializer :recurly_set_accept_language do
+      ActionController::Base.prepend_before_filter do
+        Recurly::API.accept_language = request.env['HTTP_ACCEPT_LANGUAGE']
+      end
+    end
+  end
+end

data/lib/recurly.rb

@@ -1,154 +1,79 @@
-require 'active_resource'
-require 'active_support/deprecation'
-require 'cgi'
-require 'openssl'
-require 'addressable/uri'
-
-# load ActiveResource patches
-if ::ActiveResource::VERSION::MAJOR == 3
-  if ::ActiveResource::VERSION::MINOR == 0 &&
-     ::ActiveResource::VERSION::TINY < 20
-    require 'patches/rails3/active_model/serializers/xml'
-  end
-  require 'patches/rails3/active_resource/connection'
-elsif ::ActiveResource::VERSION::MAJOR == 2
-  require 'patches/rails2/active_resource/connection'
-end
-
-if ::ActiveResource::VERSION::MAJOR == 2 ||
-    (::ActiveResource::VERSION::MAJOR == 3 &&
-     ::ActiveResource::VERSION::MINOR == 0)
-  require 'patches/rails2/active_resource/base'
-end
-
-require 'recurly/version'
-require 'recurly/exceptions'
-require 'recurly/formats/xml_with_pagination'
-require 'recurly/formats/xml_with_errors'
-require 'recurly/config_parser'
-require 'recurly/rails3/railtie' if defined?(::Rails::Railtie)
-require 'recurly/base'
-
-# load rails2 fixes
-if ::ActiveResource::VERSION::MAJOR == 2
-  require 'recurly/rails2/compatibility'
-end
-
-# configuration
+# Recurly is a Ruby client for Recurly's REST API.
 module Recurly
-
-  autoload :Account,        'recurly/account'
-  autoload :AccountBase,    'recurly/account_base'
-  autoload :BillingInfo,    'recurly/billing_info'
-  autoload :Charge,         'recurly/charge'
-  autoload :Coupon,         'recurly/coupon'
-  autoload :Credit,         'recurly/credit'
-  autoload :Invoice,        'recurly/invoice'
-  autoload :Plan,           'recurly/plan'
-  autoload :Subscription,   'recurly/subscription'
-  autoload :Transaction,    'recurly/transaction'
-  autoload :Transparent,    'recurly/transparent'
-  autoload :Verification,   'recurly/verification'
-
-  class << self
-    attr_accessor :api_key, :environment, :subdomain, :private_key
-
-    # default Recurly.settings_path to config/recurly.yml
-    unless respond_to?(:settings_path)
-      def settings_path
-        @settings_path || "config/recurly.yml"
-      end
-
-      def settings_path=(new_settings_path)
-        @settings_path = new_settings_path
-      end
-    end
-
-    def configured?
-      Base.user && Base.site
+  autoload :Account,      'recurly/account'
+  autoload :AddOn,        'recurly/add_on'
+  autoload :Adjustment,   'recurly/adjustment'
+  autoload :API,          'recurly/api'
+  autoload :BillingInfo,  'recurly/billing_info'
+  autoload :Coupon,       'recurly/coupon'
+  autoload :Helper,       'recurly/helper'
+  autoload :Invoice,      'recurly/invoice'
+  autoload :JS,           'recurly/js'
+  autoload :Money,        'recurly/money'
+  autoload :Plan,         'recurly/plan'
+  autoload :Redemption,   'recurly/redemption'
+  autoload :Resource,     'recurly/resource'
+  autoload :Subscription, 'recurly/subscription'
+  autoload :Transaction,  'recurly/transaction'
+  autoload :Version,      'recurly/version'
+  autoload :XML,          'recurly/xml'
+
+  # The exception class from which all Recurly exceptions inherit.
+  class Error < StandardError
+    def set_message message
+      @message = message
     end
 
-    # Alias password to api_key
-    def password
-      self.api_key
-    end
-    def password=(password)
-      self.api_key = password
+    # @return [String]
+    def to_s
+      defined? @message and @message or super
     end
+  end
 
-    # Ignore username
-    def username
-      nil
-    end
-    def username=(_)
-    end
-
-    def configure
-      if block_given?
-        yield self
-
-        Base.user = api_key
-        Base.site = site_for_environment(environment)
-
-        return true
-      else
-        if ENV["RECURLY_CONFIG"]
-          Recurly.configure_from_json(ENV["RECURLY_CONFIG"])
-        else
-          Recurly.configure_from_yaml
-        end
-      end
-    end
-
-    def site_for_environment(environment)
-      if environment == :development
-        "http://api.lvh.me:3000"
-      else
-        "https://api.recurly.com"
-      end
-    end
-
-
-    # allows configuration from a yml file that contains the fields:
-    # api_key,site,private_key
-    def configure_from_yaml(path = nil)
-      configure do |c|
-        # parse configuration from yml
-        recurly_config = ConfigParser.parse(path)
-
-        if recurly_config.present?
-
-          # check for environment specific config
-          recurly_env = Rails.env if defined?(Rails) and Rails.respond_to?(:env)
-          recurly_env ||= ENV["RAILS_ENV"] || ENV["RACK_ENV"] || "development"
-          recurly_config = recurly_config[recurly_env] if recurly_config.has_key?(recurly_env)
+  # This exception is raised if Recurly has not been configured.
+  class ConfigurationError < Error
+  end
 
-          c.api_key = recurly_config["api_key"] || recurly_config["password"]
-          c.subdomain = recurly_config["subdomain"]
-          c.private_key = recurly_config["private_key"]
-          c.environment = recurly_config["environment"]
-        end
-      end
+  class << self
+    # @return [String] An API key.
+    # @raise [ConfigurationError] If not configured.
+    def api_key
+      defined? @api_key and @api_key or raise(
+        ConfigurationError, "Recurly.api_key not configured"
+      )
     end
+    attr_writer :api_key
 
-    # allows configuration from a json string that contains the fields:
-    # api_key,site,private_key
-    def configure_from_json(json_string)
-      config_data = ActiveSupport::JSON.decode(json_string)
-      configure do |c|
-        c.api_key = config_data['api_key'] || config_data['password']
-        c.subdomain = config_data['subdomain']
-        c.private_key = config_data['private_key']
-        c.environment = config_data['environment']
-      end
+    # @return [String, nil] A default currency.
+    def default_currency
+      return @default_currency if defined? @default_currency
+      @default_currency = 'USD'
     end
+    attr_writer :default_currency
 
-    def current_accept_language
-      Thread.current[:recurly_accept_language]
+    # @return [JS] The Recurly.js module.
+    def js
+      JS
     end
 
-    def current_accept_language=(accept_language)
-      Thread.current[:recurly_accept_language] = accept_language
+    # Assigns a logger to log requests/responses and more.
+    #
+    # @return [Logger, nil]
+    # @example
+    #   require 'logger'
+    #   Recurly.logger = Logger.new STDOUT
+    # @example Rails applications automatically log to the Rails log:
+    #   Recurly.logger = Rails.logger
+    # @example Turn off logging entirely:
+    #   Recurly.logger = nil # Or Recurly.logger = Logger.new nil
+    attr_accessor :logger
+
+    # Convenience logging method includes a Logger#progname dynamically.
+    # @return [true, nil]
+    def log level, message
+      logger and logger.send(level, name) { message }
     end
   end
 end
+
+require 'rails/recurly' if defined? Rails::Railtie

data/lib/recurly/account.rb

@@ -1,114 +1,55 @@
 module Recurly
-  class Account < Base
-    self.element_name = "account"
-    self.primary_key = :account_code
-
-    # known attributes for a recurly account
-    def self.known_attributes
-      [
-        "account_code",
-        "username",
-        "first_name",
-        "last_name",
-        "email",
-        "company_name",
-        "hosted_login_token",
-        "accept_language"
-      ]
-    end
-
-    # initialize associations
-    def initialize(attributes = {}, persisted = false)
-      attributes = attributes.with_indifferent_access
-      attributes[:billing_info] ||= {}
-      super
-    end
-
-    attr_accessor :account_code_was
-    def account_code=(new_account_code)
-      self.account_code_was = self.account_code
-      super
-    end
-
-    def to_param
-      account_code_was || account_code
-    end
-
-    def encode(options={})
-      attributes[:accept_language] ||= Recurly.current_accept_language
-      super
-    end
-
-    # Maps the
-    SHOW_PARAMS = {
-      :active => "active_subscribers",
-      :pastdue => "pastdue_subscribers",
-      :free => "non_subscribers"
-    }
-
-    # Lists all accounts (with optional filter)
-    # This method also accepts a Hash that allows you to specify a page number, etc.
-    #
-    # examples:
-    #   Account.list(:all) #=> returns all accounts
-    #   Account.list(:active) #=> returns active accounts
-    #   Account.list(:pastdue) #=> returns pastdue accounts
-    #   Account.list(:free) #=> returns the free accounts
-    #   Account.list(:active, {:page => 3}) #=> returns the 3rd page of active accounts
-    #
-    def self.list(status = :all, params = {})
-      opts = {:params => params}
-
-      if status && status != :all
-        params[:show] = SHOW_PARAMS[status] || status
-      end
-      find(:all, opts)
-    end
-
-    def close_account
-      destroy
-    end
-
-    def charges(status = :all)
-      Charge.list(account_code, status)
+  class Account < Resource
+    # @macro [attach] scope
+    #   @scope class
+    #   @return [Pager<Account>] A pager that yields +$1+ accounts.
+    scope :active,         :state => :active
+    scope :closed,         :state => :closed
+    scope :subscriber,     :state => :subscriber
+    scope :non_subscriber, :state => :non_subscriber
+    scope :past_due,       :state => :past_due
+
+    # @macro [attach] has_many
+    #   @return [Pager<Resource>, Array] A pager that yields $1 for persisted
+    #     accounts; an empty array otherwise.
+    has_many :adjustments
+    has_many :invoices
+    has_many :subscriptions
+    has_many :transactions
+
+    # @return [BillingInfo, nil]
+    has_one :billing_info, :readonly => false
+
+    # @return [Redemption, nil]
+    has_one :redemption
+
+    define_attribute_methods %w(
+      account_code
+      state
+      username
+      email
+      first_name
+      last_name
+      company_name
+      accept_language
+      created_at
+    )
+    alias to_param account_code
+
+    # @return [Invoice] A newly-created invoice.
+    # @raise [Invalid] Raised if the account cannot be invoiced.
+    def invoice!
+      Invoice.from_response API.post(invoices.uri)
+    rescue Recurly::API::UnprocessableEntity => e
+      raise Invalid, e.message
+    end
+
+    private
+
+    def xml_keys
+      keys = super
+      keys << 'account_code' if account_code? && !account_code_changed?
+      keys.sort
     end
-    memoize :charges
-
-    def lookup_charge(id)
-      Charge.lookup(account_code, id)
-    end
-
-    def credits
-      Credit.list(account_code)
-    end
-    memoize :credits
-
-    def lookup_credit(id)
-      Credit.lookup(account_code, id)
-    end
-
-    def transactions(status)
-      Transaction.list_for_account(account_code, status)
-    end
-    memoize :transactions
-
-    def lookup_transaction(id)
-      Transaction.lookup(account_code, id)
-    end
-
-    def invoices
-      Invoice.list(account_code)
-    end
-    memoize :invoices
-
-    def lookup_invoice(id)
-      Invoice.lookup(account_code, id)
-    end
-
-    def coupon
-      Coupon.find(account_code)
-    end
-    memoize :coupon
-
   end
-end
+end