chart_mogul 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: dacc8e1ab7ea648768a32a8e3cd7a0940d08ba83
-  data.tar.gz: d3591d6e6a8dea310da2f3d7b19244e44cd7fedf
+  metadata.gz: 7d2be0447fd155e52b53b2dec55b2a17cffa455c
+  data.tar.gz: df71a2c81fdb91fdab2b922e05887f856d7a35fb
 SHA512:
-  metadata.gz: 06209d073ba8e80b49191659e818078fdf5663992e31e986398245e4313e35f3cefeb67662028f4a5bac25e60b745a6da8555f3f2f4808140fb68a8610214082
-  data.tar.gz: f8dea0e870b94b7fe4c60883418aad0a3ff6b54659b0a01145811b94fa380fda7761e20ff2d9073299ad95f261bf9ad800bbc24c56cdb8a0ed39f7211c2e1c9c
+  metadata.gz: 4f03903826ba697eff43e9d1ea3692c03ef53399d0f3e7d3d01e4f0600c07240c284d1f0b6399a226d904d744dccf94f30be801fc8b8536c38d34aa66c3319f3
+  data.tar.gz: 5b9859eac58650c90ac7662743680bc9394448897cb466074542fbdf25e45d8b39a38308bec75aba99e14f36f6c8afe2310f6285d58b0fa25916f8953d458f86

data/.gitignore

@@ -7,3 +7,4 @@
 /pkg/
 /spec/reports/
 /tmp/
+*.gem

data/README.md

@@ -1,8 +1,6 @@
 # ChartMogul
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/chart_mogul`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
+This gem is designed to streamline interaction with the [ChartMogul](https://dev.chartmogul.com) API. The initial focus has been on support for the [Import API](link!!).
 
 ## Installation
 
@@ -22,7 +20,52 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+Credentials are provided in the Account / API area of the ChartMogul application and comprise an `account_token` and `secret_key`.
+
+This can be passed in when insantiating a `ChartMogul::Client` instance, eg:
+
+```ruby
+client = ChartMogul::Client.new(account_token: 'token value', secret_key: 'secret value')
+```
+
+If not passed to the constructor the values returned by the `CHART_MOGUL_ACCOUNT_TOKEN` and `CHART_MOGUL_SECRET_KEY` environment variables are used.
+
+Methods for access the API are exposed on the `client`.
+
+### Reading data
+
+Reading methods, `list_` prefix,  are either presented as simple methods that page through all responses from the API and present a fully populated Array of typed objects.
+
+```ruby
+client.list_customers  # => [ Import::Customer, Import::Customer ]
+```
+
+and as an iterative version, with an `_each` suffix, that expects a block. Useful for those situations where you're dealing with a lot of records and don't want them necessarily all in memory. This again handles the paging transparently.
+
+The block is yielded to with a typed object.
+
+```ruby
+client.list_customers_each do |customer|
+  # do something with the Import::Customer here
+end
+```
+
+### Importing data
+
+Data records are imported by passing a Hash of attributes to a `create_` prefixed method.
+
+```ruby
+client.create_plan({
+  data_source_uuid: "ds_2323232",
+  name: "Top Plan",
+  interval_count: 1,
+  interval_unit: :month
+})
+```
+
+Dates and times are expected as `Time` objects. The gem handles the formatting required by the ChartMogul API.
+
+Where possible pre request validation is also handled by the gem. `ArgumentErrors` with a description of the variable are raised in the event that pre submit validation fails.
 
 ## Development
 
@@ -32,7 +75,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/chart_mogul. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](contributor-covenant.org) code of conduct.
+Bug reports and pull requests are welcome on GitHub at https://github.com/adambird/chart_mogul. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](contributor-covenant.org) code of conduct.
 
 
 ## License

data/lib/chart_mogul/client.rb

@@ -30,6 +30,10 @@ module ChartMogul
                       end
     end
 
+    def credentials?
+      account_token && secret_key
+    end
+
     def ping?
       response = connection.get("/v1/ping")
       preprocess_response(response)[:data] == 'pong!'
@@ -37,7 +41,9 @@ module ChartMogul
 
     def paged_get(path, params, data_field)
       begin
-        result = preprocess_response(connection.get(path, params))
+        params[:page_number] = 1 unless params[:page_number]
+        response = connection.get(path, params)
+        result = preprocess_response(response)
         yield result[data_field]
         params[:page_number] = result[:current_page]
       end while params[:page_number] < result[:total_pages]
@@ -51,23 +57,33 @@ module ChartMogul
         raise UnauthorizedError.new
       when 422
         result = JSON.parse(response.body, symbolize_names: true)
-        raise ValidationError.new(result[:errors])
+        raise ValidationError.new(result)
       else
         puts response.inspect
         raise StandardError.new("#{response.status} #{response.body.slice(0,50)}")
       end
     end
 
+    def format_datetime(value)
+      value.strftime("%Y-%m-%d %H:%M:%S")
+    end
+
     class UnauthorizedError < StandardError
     end
 
     class ValidationError < StandardError
 
       attr_reader :errors
+      attr_reader :body
 
-      def initialize(errors)
-        @errors = errors
-        super("validation errors for #{errors.keys.join(', ')}")
+      def initialize(result)
+        @body = result
+        if result[:errors]
+          @errors = result[:errors]
+          super("validation errors for #{@errors.keys.join(', ')}")
+        else
+          super("validation errors #{@body}")
+        end
       end
 
     end

data/lib/chart_mogul/import/invoice.rb

@@ -0,0 +1,73 @@
+module ChartMogul
+  module Import
+    class Invoice
+
+      attr_reader :uuid
+      attr_reader :date
+      attr_reader :external_id
+      attr_reader :currency
+      attr_reader :due_date
+      attr_reader :line_items
+      attr_reader :transactions
+
+      class LineItem
+        attr_reader :uuid
+        attr_reader :external_id
+        attr_reader :type
+        attr_reader :subscription_uuid
+        attr_reader :plan_uuid
+        attr_reader :prorated
+        attr_reader :service_period_start
+        attr_reader :service_period_end
+        attr_reader :amount_in_cents
+        attr_reader :quantity
+        attr_reader :discount_code
+        attr_reader :discount_amount_in_cents
+        attr_reader :tax_amount_in_cents
+
+        def initialize(args)
+          %i{uuid external_id type subscription_uuid plan_uuid prorated amount_in_cents quantity discount_code discount_amount_in_cents tax_amount_in_cents}
+            .each do |key|
+              instance_variable_set("@#{key}", args[key])
+            end
+
+          %i{service_period_start service_period_end}
+            .each do |key|
+              instance_variable_set("@#{key}", Time.parse(args[key])) if args[key]
+            end
+        end
+
+      end
+
+
+      class Transaction
+        attr_reader :uuid
+        attr_reader :external_id
+        attr_reader :type
+        attr_reader :date
+        attr_reader :result
+
+        def initialize(args)
+          %i{uuid external_id type result}
+            .each do |key|
+              instance_variable_set("@#{key}", args[key])
+            end
+
+          instance_variable_set("@#{:date}", Time.parse(args[:date])) if args[:date]
+        end
+
+      end
+
+      def initialize(args)
+        @uuid = args[:uuid]
+        @external_id = args[:external_id]
+        @currency = args[:currency]
+        @date = Time.parse(args[:date]) if args[:date]
+        @due_date = Time.parse(args[:due_date]) if args[:due_date]
+
+        @line_items = args[:line_items].map { |li| LineItem.new(li) }
+        @transactions = args[:transactions].map { |li| Transaction.new(li) }
+      end
+    end
+  end
+end

data/lib/chart_mogul/import_api.rb

@@ -1,6 +1,7 @@
 require_relative 'import/customer'
 require_relative 'import/data_source'
 require_relative 'import/plan'
+require_relative 'import/invoice'
 
 module ChartMogul
   module ImportApi
@@ -70,7 +71,7 @@ module ChartMogul
     # Returns an Enumerable that will yield a ChartMogul::Import::Customer for
     # each record
     def list_customers_each(options={}, &block)
-      params = { page_number: 1 }
+      params = {}
       params[:data_source_uuid] = options[:data_source_uuid] if options[:data_source_uuid]
 
       paged_get("/v1/import/customers", params, :customers) do |customers|
@@ -80,13 +81,13 @@ module ChartMogul
       end
     end
 
-    # Public - create a Customer
+    # Public - import a Customer
     #
     # args   - Hash of params see https://dev.chartmogul.com/docs/customers
     #          Mandatory: :data_source_uuid, :external_id, :name
     #
     # Returns a ChartMogul::Import::Customer
-    def create_customer(args)
+    def import_customer(args)
       [:data_source_uuid, :external_id, :name].each do |attribute|
         refute_blank! args[attribute], attribute
       end
@@ -127,7 +128,7 @@ module ChartMogul
     # Returns an Enumerable that will yield a ChartMogul::Import::Plan for
     # each record
     def list_plans_each(options={}, &block)
-      params = { page_number: 1 }
+      params = {}
       params[:data_source_uuid] = options[:data_source_uuid] if options[:data_source_uuid]
 
       paged_get("/v1/import/plans", params, :plans) do |plans|
@@ -137,13 +138,13 @@ module ChartMogul
       end
     end
 
-    # Public - create a Plan
+    # Public - import a Plan
     #
     # args   - Hash of params see https://dev.chartmogul.com/docs/plans
     #          Mandatory: :data_source_uuid, :name, :interval_count, :interval_unit
     #
     # Returns a ChartMogul::Import::Plan
-    def create_plan(args)
+    def import_plan(args)
       [:data_source_uuid, :name, :interval_unit, :interval_count].each do |attribute|
         refute_blank! args[attribute], attribute
       end
@@ -158,5 +159,92 @@ module ChartMogul
 
       Import::Plan.new(preprocess_response(response))
     end
+
+    # Public      - import a single Invoice. Convenience method that
+    #               maps the output (and validation errors) to a single operation
+    #
+    # customer_id - ChartMogul id for the customer
+    # invoice     - Hash of params see https://dev.chartmogul.com/docs/invoices
+    #               See invoice_invoices for mandatory attributes
+    #
+    # Returns an Array of ChartMogul::Import::Invoice
+    def import_invoice(customer_id, invoice)
+      invoices = import_invoices(customer_id, [ invoice ])
+      invoices.first
+
+    rescue ChartMogul::Client::ValidationError => e
+      # restructure ValidationError to map the single invoice error that was returned
+      if e.body[:invoices]
+        raise ChartMogul::Client::ValidationError.new(e.body[:invoices].first)
+      else
+        raise
+      end
+    end
+
+    # Public      - import Invoices
+    #
+    # customer_id - ChartMogul id for the customer
+    # invoices    - Array of Hash of params see https://dev.chartmogul.com/docs/invoices
+    #               Mandatory: :external_id, :date, :currency, :line_items
+    #
+    # Returns an Array of ChartMogul::Import::Invoice
+    def import_invoices(customer_id, invoices)
+      refute_blank! customer_id, "customer_id"
+      refute! invoices.nil? && invoices.empty?, "invoices required"
+
+      args = { invoices: invoices }
+
+      args[:invoices].each do |invoice|
+        [:external_id, :date, :currency].each do |attribute|
+          refute_blank! invoice[attribute], attribute
+        end
+
+        invoice[:date] = format_datetime(invoice[:date])
+
+        assert! invoice[:line_items] && invoice[:line_items].any?, "line_items is required"
+
+        invoice[:line_items].each do |line_item|
+          line_item[:service_period_start] = format_datetime(line_item[:service_period_start]) if line_item[:service_period_start]
+          line_item[:service_period_end] = format_datetime(line_item[:service_period_end]) if line_item[:service_period_end]
+          assert! line_item[:quantity].nil? || line_item[:quantity] > 0, "line_item quantity must be greater than zero if specified"
+        end
+
+      end
+
+      response = connection.post do |request|
+        request.url "/v1/import/customers/#{customer_id}/invoices"
+        request.headers['Content-Type'] = "application/json"
+        request.body = args.to_json
+      end
+
+      preprocess_response(response)[:invoices].map { |i| Import::Invoice.new(i) }
+    end
+
+    # Public       - list of Customer invoices
+    # customer_id  - ChartMogul id for the customer
+    #
+    # Returns an Array of ChartMogul::Import::Invoice
+    def list_invoices(customer_id)
+      invoices = []
+      list_invoices_each(customer_id) { |i| invoices << i }
+      invoices
+    end
+
+    # Public    - iterate through all invoices
+    #
+    # customer_id  - ChartMogul id for the customer
+    #
+    # Returns an Enumerable that will yield a ChartMogul::Import::Invoice for
+    # each record
+    def list_invoices_each(customer_id, &block)
+      refute_blank! customer_id, "customer_id"
+
+      paged_get("/v1/import/customers/#{customer_id}/invoices", {}, :invoices) do |invoices|
+        invoices.each do |invoice|
+          yield Import::Invoice.new(invoice)
+        end
+      end
+    end
+
   end
 end

data/lib/chart_mogul/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: chart_mogul
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Adam Bird
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-03-25 00:00:00.000000000 Z
+date: 2016-04-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -103,6 +103,7 @@ files:
 - lib/chart_mogul/client.rb
 - lib/chart_mogul/import/customer.rb
 - lib/chart_mogul/import/data_source.rb
+- lib/chart_mogul/import/invoice.rb
 - lib/chart_mogul/import/plan.rb
 - lib/chart_mogul/import_api.rb
 - lib/chart_mogul/version.rb