bill_forward 1.2014.296 → 1.2015.183

data/lib/bill_forward/entities/account.rb

@@ -1,19 +1,19 @@
-module BillForward
-  # This entity exposes the following child entities via method_missing:
-  # 
-  # Role[]           .roles
-  # PaymentMethod[]  .paymentMethods
-  # Profile          .profile
-  class Account < MutableEntity
-  	@resource_path = BillForward::ResourcePath.new("accounts", "account")
-
-  protected
-    def unserialize_all(hash)
-      super
-      unserialize_entity('profile', Profile, hash)
-
-      unserialize_array_of_entities('roles', Role, hash)
-      unserialize_array_of_entities('paymentMethods', PaymentMethod, hash)
-    end
-  end
+module BillForward
+  # This entity exposes the following child entities via method_missing:
+  # 
+  # Role[]           .roles
+  # PaymentMethod[]  .paymentMethods
+  # Profile          .profile
+  class Account < MutableEntity
+  	@resource_path = BillForward::ResourcePath.new("accounts", "account")
+
+  protected
+    def unserialize_all(hash)
+      super
+      unserialize_entity('profile', Profile, hash)
+
+      unserialize_array_of_entities('roles', Role, hash)
+      unserialize_array_of_entities('paymentMethods', PaymentMethod, hash)
+    end
+  end
 end

data/lib/bill_forward/entities/amendments/issue_invoice_amendment.rb

@@ -0,0 +1,10 @@
+module BillForward
+	class IssueInvoiceAmendment < Amendment
+		@resource_path = BillForward::ResourcePath.new("amendments", "amendment")
+		
+		def initialize(*args)
+			super
+			set_state_param('@type', 'IssueInvoiceAmendment')
+		end
+	end
+end

data/lib/bill_forward/entities/amendments/product_rate_plan_migration_amendment.rb

@@ -0,0 +1,18 @@
+module BillForward
+	# This entity exposes the following child entities via method_missing:
+	# 
+	# PricingComponentValueMigrationAmendmentMapping[]           .mappings
+	class ProductRatePlanMigrationAmendment < Amendment
+		@resource_path = BillForward::ResourcePath.new("amendments", "amendment")
+		
+		def initialize(*args)
+			super
+			set_state_param('@type', 'ProductRatePlanMigrationAmendment')
+		end
+	protected
+		def unserialize_all(hash)
+			super
+			unserialize_array_of_entities('mappings', PricingComponentValueMigrationAmendmentMapping, hash)
+		end
+	end
+end

data/lib/bill_forward/entities/api_configuration.rb

@@ -1,11 +1,23 @@
 module BillForward
   class APIConfiguration < MutableEntity
+  	@resource_path = BillForward::ResourcePath.new('configurations', 'APIConfiguration')
+
   	class << self
 		def create(entity = nil)
 	  		raise DenyMethod.new 'Create support is denied for this entity; '+
 		 	'at the time of writing, no API endpoint exists to support it. '+
 		 	'The entity can be created through cascade only (i.e. instantiated within another entity).'
 	  	end
+
+	  	def get_by_type(type, query_params = {}, custom_client = nil)
+			raise ArgumentError.new("type cannot be nil") if type.nil?
+
+			endpoint = sprintf('type/%s',
+				ERB::Util.url_encode(type)
+			)
+
+			self.request_many('get', endpoint, query_params, custom_client)
+		end
 	end
   end
 end

data/lib/bill_forward/entities/invoice.rb

@@ -1,9 +1,12 @@
 module BillForward
   # This entity exposes the following child entities via method_missing:
   # 
-  # InvoiceLine[]     .invoiceLines
-  # TaxLine[]         .taxLines
-  # InvoicePayment[]  .invoicePayments
+  # InvoiceLine[]         .invoiceLines
+  # TaxLine[]             .taxLines
+  # InvoicePayment[]      .invoicePayments
+  # Refund[]              .invoiceRefunds
+  # CreditNote[]          .invoiceCreditNotes
+  # SubscriptionCharge[]  .charges
   class Invoice < MutableEntity
   	@resource_path = BillForward::ResourcePath.new('invoices', 'invoice')
 
@@ -12,6 +15,26 @@ module BillForward
         raise DenyMethod.new 'Create support is denied for this entity; '+
           'Invoices are generated instead by the BillForward Engines.'
       end
+
+      def get_by_subscription_id(id, query_params = {}, custom_client = nil)
+        raise ArgumentError.new("id cannot be nil") if id.nil?
+
+        endpoint = sprintf('subscription/%s',
+          ERB::Util.url_encode(id)
+          )
+
+        self.request_many('get', endpoint, query_params, custom_client)
+      end
+
+      def get_by_account_id(id, query_params = {}, custom_client = nil)
+        raise ArgumentError.new("id cannot be nil") if id.nil?
+
+        endpoint = sprintf('account/%s',
+          ERB::Util.url_encode(id)
+          )
+
+        self.request_many('get', endpoint, query_params, custom_client)
+      end
     end
 
   protected
@@ -20,6 +43,9 @@ module BillForward
       unserialize_array_of_entities('invoiceLines', InvoiceLine, hash)
       unserialize_array_of_entities('taxLines', TaxLine, hash)
       unserialize_array_of_entities('invoicePayments', InvoicePayment, hash)
+      unserialize_array_of_entities('invoiceRefunds', Refund, hash)
+      unserialize_array_of_entities('invoiceCreditNotes', CreditNote, hash)
+      unserialize_array_of_entities('charges', SubscriptionCharge, hash)
     end
   end
 end

data/lib/bill_forward/entities/invoice_parts/taxation_link.rb

@@ -1,5 +1,5 @@
-module BillForward
-  class TaxationLink < MutableEntity
-    @resource_path = BillForward::ResourcePath.new("taxation-links", "TaxationLink")
-  end
-end
+module BillForward
+  class TaxationLink < MutableEntity
+    @resource_path = BillForward::ResourcePath.new("taxation-links", "TaxationLink")
+  end
+end

data/lib/bill_forward/entities/organisation.rb

@@ -1,37 +1,37 @@
-module BillForward
-  # This entity exposes the following child entities via method_missing:
-  # 
-  # APIConfiguration[]  .apiConfigurations
-  class Organisation < MutableEntity
-  	@resource_path = BillForward::ResourcePath.new("organizations", "organization")
-
-  	class << self
-  		def get_mine(options = {}, customClient = nil)
-			client = customClient
-			client = singleton_client if client.nil?
-
-  			route = resource_path.path
-			endpoint = 'mine'
-			url_full = "#{route}/#{endpoint}"
-
-			response = client.get(url_full)
-			results = response["results"]
-			
-			# maybe use build_entity_array here for consistency
-			entity_array = Array.new
-			# maybe it's an empty array, but that's okay too.
-			results.each do |value|
-				entity = self.new(value, client)
-				entity_array.push(entity)
-			end
-			entity_array
-  		end
-  	end
-
-  protected
-    def unserialize_all(hash)
-      super
-      unserialize_array_of_entities('apiConfigurations', APIConfiguration, hash)
-    end
-  end
+module BillForward
+  # This entity exposes the following child entities via method_missing:
+  # 
+  # APIConfiguration[]  .apiConfigurations
+  class Organisation < MutableEntity
+  	@resource_path = BillForward::ResourcePath.new("organizations", "organization")
+
+  	class << self
+  		def get_mine(options = {}, customClient = nil)
+			client = customClient
+			client = singleton_client if client.nil?
+
+  			route = resource_path.path
+			endpoint = 'mine'
+			url_full = "#{route}/#{endpoint}"
+
+			response = client.get(url_full)
+			results = response["results"]
+			
+			# maybe use build_entity_array here for consistency
+			entity_array = Array.new
+			# maybe it's an empty array, but that's okay too.
+			results.each do |value|
+				entity = self.new(value, client)
+				entity_array.push(entity)
+			end
+			entity_array
+  		end
+  	end
+
+  protected
+    def unserialize_all(hash)
+      super
+      unserialize_array_of_entities('apiConfigurations', APIConfiguration, hash)
+    end
+  end
 end

data/lib/bill_forward/entities/payment_method.rb

@@ -1,5 +1,5 @@
-module BillForward
-	class PaymentMethod < MutableEntity
-  		@resource_path = BillForward::ResourcePath.new("payment-methods", "paymentMethod")
-	end
+module BillForward
+	class PaymentMethod < MutableEntity
+  		@resource_path = BillForward::ResourcePath.new("payment-methods", "paymentMethod")
+	end
 end

data/lib/bill_forward/entities/payment_method_subscription_link.rb

@@ -1,5 +1,5 @@
-module BillForward
-  class PaymentMethodSubscriptionLink < MutableEntity
-    @resource_path = BillForward::ResourcePath.new("payment-method-subcription-links", "PaymentMethodSubscriptionLink")
-  end
-end
+module BillForward
+  class PaymentMethodSubscriptionLink < MutableEntity
+    @resource_path = BillForward::ResourcePath.new("payment-method-subcription-links", "PaymentMethodSubscriptionLink")
+  end
+end

data/lib/bill_forward/entities/pricing_component.rb

@@ -1,21 +1,21 @@
-module BillForward
-  # This entity exposes the following child entities via method_missing:
-  # 
-  # PricingComponentTier[]  .tiers
-  class PricingComponent < MutableEntity
-    @resource_path = BillForward::ResourcePath.new("pricing-components", "PricingComponent")
-
-    def self.get_all(options=nil, customClient=nil)
-      raise ArgumentError.new('Get All support is denied for this entity;
-        at the time of writing, no working API endpoint exists to support it.
-        The entity can be GETted through cascade (i.e. GET a related entity), or by ID only.'
-      )
-    end
-
-    protected
-      def unserialize_all(hash)
-        super
-        unserialize_array_of_entities('tiers', PricingComponentTier, hash)
-      end
-  end
-end
+module BillForward
+  # This entity exposes the following child entities via method_missing:
+  # 
+  # PricingComponentTier[]  .tiers
+  class PricingComponent < MutableEntity
+    @resource_path = BillForward::ResourcePath.new("pricing-components", "PricingComponent")
+
+    def self.get_all(options=nil, customClient=nil)
+      raise ArgumentError.new('Get All support is denied for this entity;
+        at the time of writing, no working API endpoint exists to support it.
+        The entity can be GETted through cascade (i.e. GET a related entity), or by ID only.'
+      )
+    end
+
+    protected
+      def unserialize_all(hash)
+        super
+        unserialize_array_of_entities('tiers', PricingComponentTier, hash)
+      end
+  end
+end

data/lib/bill_forward/entities/pricing_component_tier.rb

@@ -1,5 +1,5 @@
-module BillForward
-  class PricingComponentTier < MutableEntity
-    @resource_path = BillForward::ResourcePath.new("pricing-component-tiers", "pricingComponentTier")
-  end
-end
+module BillForward
+  class PricingComponentTier < MutableEntity
+    @resource_path = BillForward::ResourcePath.new("pricing-component-tiers", "pricingComponentTier")
+  end
+end

data/lib/bill_forward/entities/pricing_component_value.rb

@@ -1,5 +1,5 @@
-module BillForward
-  class PricingComponentValue < MutableEntity
-    @resource_path = BillForward::ResourcePath.new("pricing-component-values", "PricingComponentValue")
-  end
-end
+module BillForward
+  class PricingComponentValue < MutableEntity
+    @resource_path = BillForward::ResourcePath.new("pricing-component-values", "PricingComponentValue")
+  end
+end

data/lib/bill_forward/entities/pricing_component_value_migration_amendment_mapping.rb

@@ -0,0 +1,31 @@
+module BillForward
+  class PricingComponentValueMigrationAmendmentMapping < MutableEntity
+  	@resource_path = BillForward::ResourcePath.new('', 'PricingComponentValueMigrationAmendmentMapping')
+
+  	class << self
+  		def create(entity = nil)
+	  		raise DenyMethod.new 'Create support is denied for this entity; '+
+		 	'at the time of writing, no API endpoint exists to support it. '+
+		 	'The entity can be created through cascade only (i.e. instantiated within another entity).'
+	  	end
+  		
+	  	def get_by_id(id, query_params = {}, customClient = nil)
+	  		raise DenyMethod.new 'Get by ID support is denied for this entity; '+
+			 'at the time of writing, no API endpoint exists to support it.'+
+			 'The entity can be GETted through cascade only (i.e. GET a related entity).'
+	  	end
+
+	  	def get_all(query_params = {}, customClient = nil)
+	  		raise DenyMethod.new 'Get All support is denied for this entity; '+
+			 'at the time of writing, no API endpoint exists to support it.'+
+			 'The entity can be GETted through cascade only (i.e. GET a related entity).'
+	  	end
+	end
+
+  	def save()
+  		raise DenyMethod.new 'Save support is denied for this entity; '+
+		 'at the time of writing, the provided API endpoint is not functioning.'+
+		 'The entity can be saved through cascade only (i.e. save a related entity).'
+  	end
+  end
+end

data/lib/bill_forward/entities/product.rb

@@ -1,5 +1,5 @@
-module BillForward
-  class Product < MutableEntity
-    @resource_path = BillForward::ResourcePath.new("products", "product")
-  end
-end
+module BillForward
+  class Product < MutableEntity
+    @resource_path = BillForward::ResourcePath.new("products", "product")
+  end
+end

data/lib/bill_forward/entities/product_rate_plan.rb

@@ -1,19 +1,43 @@
-module BillForward
-  # This entity exposes the following child entities via method_missing:
-  # 
-  # Product             .product
-  # TaxationLink[]      .taxation
-  # PricingComponent[]  .pricingComponents
-  class ProductRatePlan < MutableEntity
-    @resource_path = BillForward::ResourcePath.new("product-rate-plans", "productRatePlan")
-
-    protected
-      def unserialize_all(hash)
-        super
-        unserialize_entity('product', Product, hash)
-
-        unserialize_array_of_entities('taxation', TaxationLink, hash)
-        unserialize_array_of_entities('pricingComponents', PricingComponent, hash)
-      end
-  end
-end
+module BillForward
+  # This entity exposes the following child entities via method_missing:
+  # 
+  # Product             .product
+  # TaxationLink[]      .taxation
+  # PricingComponent[]  .pricingComponents
+  class ProductRatePlan < MutableEntity
+    @resource_path = BillForward::ResourcePath.new("product-rate-plans", "productRatePlan")
+
+    class << self
+      def get_by_product_id(id, query_params = {}, custom_client = nil)
+        raise ArgumentError.new("id cannot be nil") if id.nil?
+
+        endpoint = sprintf('product/%s',
+          ERB::Util.url_encode(id)
+          )
+
+        self.request_many('get', endpoint, query_params, custom_client)
+      end
+
+      def get_by_product_and_plan_id(product_id, plan_id, query_params = {}, custom_client = nil)
+        raise ArgumentError.new("id cannot be nil") if product_id.nil?
+        raise ArgumentError.new("id cannot be nil") if plan_id.nil?
+
+        endpoint = sprintf('product/%s/rate-plan/%s',
+          ERB::Util.url_encode(product_id),
+          ERB::Util.url_encode(plan_id)
+          )
+
+        self.request_first('get', endpoint, query_params, custom_client)
+      end
+    end
+
+  protected
+    def unserialize_all(hash)
+      super
+      unserialize_entity('product', Product, hash)
+
+      unserialize_array_of_entities('taxation', TaxationLink, hash)
+      unserialize_array_of_entities('pricingComponents', PricingComponent, hash)
+    end
+  end
+end

data/lib/bill_forward/entities/profile.rb

@@ -1,15 +1,15 @@
-module BillForward
-	# This entity exposes the following child entities via method_missing:
-	# 
-	# Address[]      .addresses
-	class Profile < MutableEntity
-		@resource_path = BillForward::ResourcePath.new("profiles", "profile")
-
-	protected
-	    def unserialize_all(hash)
-	      super
-
-	      unserialize_array_of_entities('addresses', Address, hash)
-	    end
-	end
+module BillForward
+	# This entity exposes the following child entities via method_missing:
+	# 
+	# Address[]      .addresses
+	class Profile < MutableEntity
+		@resource_path = BillForward::ResourcePath.new("profiles", "profile")
+
+	protected
+	    def unserialize_all(hash)
+	      super
+
+	      unserialize_array_of_entities('addresses', Address, hash)
+	    end
+	end
 end

data/lib/bill_forward/entities/refund.rb

@@ -0,0 +1,5 @@
+module BillForward
+	class Refund < MutableEntity
+		@resource_path = BillForward::ResourcePath.new("refunds", "refund")
+	end
+end

data/lib/bill_forward/entities/role.rb

@@ -1,4 +1,4 @@
-module BillForward
-  class Role < InsertableEntity
-  end
+module BillForward
+  class Role < InsertableEntity
+  end
 end

data/lib/bill_forward/entities/stripe_ach_token.rb

@@ -0,0 +1,9 @@
+module BillForward
+	class StripeACHToken < MutableEntity
+		# WARNING: resource paths for StripeACHTokens do not follow the usual pattern;
+		# instead of posting to 'root' of a URL root reserved for AuthorizeNetTokens, 
+		# this routing is a bit less standard; for example we can't GET from the same
+		# place we POST to.
+  		@resource_path = BillForward::ResourcePath.new('vaulted-gateways/stripe-ACH', 'stripe_ach_token')
+	end
+end

data/lib/bill_forward/entities/subscription.rb

@@ -1,53 +1,83 @@
-module BillForward
-  # This entity exposes the following child entities via method_missing:
-  # 
-  # PricingComponentValue[]        .pricingComponentValues
-  # PricingComponentValueChange[]  .pricingComponentValueChanges
-  class Subscription < MutableEntity
-    @resource_path = BillForward::ResourcePath.new("subscriptions", "subscription")
-
-    class << self
-      def get_by_account_id(id, query_params = {}, customClient = nil)
-        client = customClient
-        client = singleton_client if client.nil?
-
-        raise ArgumentError.new("id cannot be nil") if id.nil?
-        TypeCheck.verifyObj(Hash, query_params, 'query_params')
-
-        route = resource_path.path
-        endpoint = 'account'
-        url_full = "#{route}/#{endpoint}/#{id}"
-
-        response = client.get(url_full, query_params)
-        results = response["results"]
-
-        # maybe use build_entity_array here for consistency
-        entity_array = Array.new
-        # maybe it's an empty array, but that's okay too.
-        results.each do |value|
-          entity = self.new(value, client)
-          entity_array.push(entity)
-        end
-        entity_array
-      end
-    end
-
-    def activate
-      set_state_param('state', 'AwaitingPayment')
-      response = save
-      response
-    end
-
-    protected
-      def unserialize_all(hash)
-        super
-        # always has these:
-        unserialize_array_of_entities('pricingComponentValues', PricingComponentValue, hash)
-        unserialize_array_of_entities('pricingComponentValueChanges', PricingComponentValueChange, hash)
-
-
-        # think about the other entities later..
-        # unserialize_array_of_entities('paymentMethodSubscriptionLinks', PaymentMethodSubscriptionLink, hash)
-      end
-  end
-end
+module BillForward
+  # This entity exposes the following child entities via method_missing:
+  # 
+  # PricingComponentValue[]        .pricingComponentValues
+  # PricingComponentValueChange[]  .pricingComponentValueChanges
+  class Subscription < MutableEntity
+    @resource_path = BillForward::ResourcePath.new("subscriptions", "subscription")
+
+    class << self
+      def get_by_account_id(id, query_params = {}, custom_client = nil)
+        raise ArgumentError.new("id cannot be nil") if id.nil?
+
+        endpoint = sprintf('account/%s',
+          ERB::Util.url_encode(id)
+          )
+
+        self.request_many('get', endpoint, query_params, custom_client)
+      end
+    end
+
+    def activate
+      set_state_param('state', 'AwaitingPayment')
+      response = save
+      response
+    end
+
+    #### MIGRATE PLAN VIA AMENDMENT
+
+
+
+    # Migrates subscription to new plan, with PricingComponentValue values corresponding to named PricingComponents.
+    # This works only for 'arrears' or 'in advance' pricing components.
+    #
+    # Note: pricing component mapping is not yet implemented, so currently the 'names_to_values' parameter is ignored.
+    #
+    # @param names_to_values [hash] The map of pricing component names to numerical values ('Bandwidth usage' => 102)
+    # @param new_plan_id [string] ID of the plan to migrate to.
+    # @param invoicing_type [ENUM{'Immediate', 'Aggregated'}] (Default: 'Aggregated') Subscription-charge invoicing type <Immediate>: Generate invoice straight away with this charge applied, <Aggregated>: Add this charge to next invoice
+    # @param new_plan [ProductRatePlan] (Alternative parameter to avoid extra API request) The plan to migrate to.
+    # 
+    # @return [self] The created Entity
+    def migrate_plan(names_to_values = Hash.new, new_plan_id = nil, invoicing_type = 'Aggregated', new_plan = nil)
+      # Until pricing component mapping is implemented, we don't to fetch the full plan
+      # if new_plan.nil? do
+      #   new_plan = BillForward::ProductRatePlan::get_by_id(new_plan_id)
+      # end
+
+      migrate_plan_simple(new_plan_id, invoicing_type)
+    end
+
+    protected
+      def unserialize_all(hash)
+        super
+        # always has these:
+        unserialize_array_of_entities('pricingComponentValues', PricingComponentValue, hash)
+        unserialize_array_of_entities('pricingComponentValueChanges', PricingComponentValueChange, hash)
+
+
+        # think about the other entities later..
+        # unserialize_array_of_entities('paymentMethodSubscriptionLinks', PaymentMethodSubscriptionLink, hash)
+      end
+
+      # Migrates subscription to new plan, with PricingComponentValue values corresponding to named PricingComponents.
+      #
+      # Note: this simple invocation will be deprecated when full support for mapping component values is introduced. The public 'migrate_plan' interface is not expected to change though.
+      #
+      # @param new_plan_id [string] ID of the plan to migrate to.
+      # @param invoicing_type [ENUM{'Immediate', 'Aggregated'}] (Default: 'Aggregated') Subscription-charge invoicing type <Immediate>: Generate invoice straight away with this charge applied, <Aggregated>: Add this charge to next invoice
+      # 
+      # @return [self] The created Entity
+      def migrate_plan_simple(new_plan_id, invoicing_type)
+        amendment = BillForward::ProductRatePlanMigrationAmendment.new({
+          'subscriptionID' => id,
+          'productRatePlanID' => new_plan_id,
+          'mappings' => Array.new,
+          'invoicingType' => invoicing_type
+          });
+
+        created_amendment = BillForward::ProductRatePlanMigrationAmendment.create(amendment)
+        created_amendment
+      end
+  end
+end

data/lib/bill_forward/entities/subscription_charge.rb

@@ -0,0 +1,14 @@
+module BillForward
+  # This entity exposes the following child entities via method_missing:
+  # 
+  # Invoice         .invoice
+  class SubscriptionCharge < MutableEntity
+  	@resource_path = BillForward::ResourcePath.new('charges', 'subscriptionCharge')
+
+  protected
+    def unserialize_all(hash)
+      super
+      unserialize_entity('invoice', Invoice, hash)
+    end
+  end
+end