gecko-ruby 0.2.6 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 20b88c9b40a367779ee76883eb9c6311b9bddaf4520895d6385f4e2628413919
-  data.tar.gz: 1acf395ece0f1abbfd475f976667658894d0b56bdebd461371e25825e92e75b4
+  metadata.gz: df8f73db1e7b003d6bb6390cbf04bca52b59700ef2d9664e6015974c4306bccf
+  data.tar.gz: 74ac60ce61a2baf83ef5dbba6bdb813c8c117aa83729430e8da5be1befc0e94a
 SHA512:
-  metadata.gz: 27433416b6b19c2c2678da35bfc9c4ce0ed6f6f81866bf4e8993b26cb1430eb8691270810796014cd53558de573cbca59ebdd1bfea1291e82e1bfec8fc1794ec
-  data.tar.gz: 32f3d00580a3f09a288938a6675fd1c94580e5e15e00956bd861841103ac5842d56926e3867bd935e9cd2e0675b3537d916bcf0589ba589c780c1e98555f58b0
+  metadata.gz: f0e27ab4669777a3641565962b146f7fd71e6e74e3c46b6180708b79d0478893ced8fb2a37f6aed308244968cee4998195d503fe1f0847c68f5cfffe975a701c
+  data.tar.gz: d7bea6254cb350fd0a770346778cf97c999baecc8d18ac75c349e81423db88ee14c3e5f49919ba6d287f3c7f9e9cc600b518f8ac18f3dcf420342370ef91e876

data/.rubocop.yml

@@ -64,3 +64,6 @@ Layout/MultilineOperationIndentation:
 
 Style/ClassAndModuleChildren:
   EnforcedStyle: compact
+
+Style/DoubleNegation:
+  Enabled: false

data/.travis.yml

@@ -2,8 +2,9 @@ language: ruby
 before_install:
  - gem install bundler
 rvm:
-  - 1.9.3
-  - 2.0
   - 2.1
   - 2.2
   - 2.3
+  - 2.4
+  - 2.5
+  - ruby-head

data/CHANGELOG.md

@@ -1,5 +1,13 @@
-## 0.2.6 (2019-03-19)
-- [BACKPORT] Fix issue with find_many which manifested as a bug in has_many definitions with cached records being duplicated when more than 100 children existed.
+## 0.5.0 (2018-08-15)
+- [BREAKING CHANGE] has_many associations now return an enumerable
+  `CollectionProxy` where they used to return a plain array.
+- `has_many` associations now support `.build` which automatically assigns the parent
+  relation. `item = order.order_line_items.build(quantity: 123, variant_id: 123, price: 123)`
+  `item.order == order`.
+- Support for embedded serialization.
+  i.e `order.order_line_items.build(quantity: 123, price: 123, variant_id: 123); order.save`
+  will now save the Order and the order line items in a single API request.
+- Add minimum `oauth2` gem dependency
 
 ## 0.2.5 (2018-01-15)
 - Add `User#account_name`

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2014 TradeGecko Pte Ltd.
+Copyright (c) 2018 TradeGecko Pte Ltd.
 
 MIT License
 

data/README.md

@@ -5,7 +5,7 @@ The official TradeGecko API RubyGem
 
 This library provides a Ruby interface to publicly available (beta) API for TradeGecko.
 
-If you are unfamiliar with the TradeGecko API, you can read the documentation located at [http://developer.tradegecko.com](http://developer.tradegecko.com)
+If you are unfamiliar with the TradeGecko API, you can read the documentation located at [https://developer.tradegecko.com](https://developer.tradegecko.com)
 
 ## Installation
 
@@ -76,6 +76,8 @@ client.Product.where(ids: [123, 124])
 
 ## Building Records
 
+You can create new records by calling `build` on the appropriate adapter.
+
 ```ruby
 geckobot = client.Product.build(name: "Geckobot", product_type: "Robot")
 #=> <Gecko::Record::Product id=nil name="Geckobot" product_type: "Robot">
@@ -87,6 +89,8 @@ geckobot.persisted?
 
 #### Create Record
 
+You can persist new records by calling `save`.
+
 ```ruby
 geckobot = client.Product.build(name: "Geckobot", product_type: "Robot")
 #=> <Gecko::Record::Product id=nil name="Geckobot" product_type: "Robot">
@@ -98,6 +102,19 @@ geckobot
 #=> <Gecko::Record::Product id=124 name="Geckobot" product_type: "Robot">
 ```
 
+You can also create new records from inside a parent object.
+
+```ruby
+variant = product.variants.build(name: "Geckobot", sku: "ROBO")
+#=> <Gecko::Record::Variant id=nil product_id=123 name="Geckobot" sku: "ROBO">
+variant.persisted?
+#=> false
+variant.save #=> Persists to API
+#=> true
+variant
+#=> <Gecko::Record::Variant id=125 product_id=123 name="Geckobot" sku: "ROBO">
+```
+
 #### Update Record
 
 ```ruby
@@ -112,6 +129,39 @@ geckobot
 #=> <Gecko::Record::Product id=124 name="Geckobot" product_type: "Robo-boogie">
 ```
 
+#### Embedded Record Serialization
+
+Some records support being saved inside of their parents.
+A good example is creating a Sales Order and it's line items.
+
+```ruby
+order = client.Order.build(company_id: 123, shipping_address_id: 123)
+order.order_line_items.build(quantity: 1, variant_id: 123, price: 10.5)
+order.order_line_items.build(quantity: 2, variant_id: 124, price: 11.0)
+order.save # Persists to API
+#=> true
+order.order_line_items
+#=> [<Gecko::Record::OrderLineItem id=125 variant_id=123 quantity: 1 price: '10.5'>,
+     <Gecko::Record::OrderLineItem id=126 variant_id=124 quantity: 2 price: '11.0'>]
+```
+
+This also works when adding new items to an existing order.
+
+```ruby
+order = client.Order.find(123)
+order.order_line_items.build(quantity: 1, variant_id: 123, price: 10.5)
+order.order_line_items.build(quantity: 2, variant_id: 124, price: 11.0)
+order.save # Persists to API
+#=> true
+order.order_line_items
+#=> [<Gecko::Record::OrderLineItem id=125 variant_id=123 quantity: 1 price: '10.5'>,
+     <Gecko::Record::OrderLineItem id=126 variant_id=124 quantity: 2 price: '11.0'>]
+```
+
+N.B. Only creation of embedded objects works at this time.
+Updating/Deleting embedded items must still be done by calling `save/destroy`
+on each of the child objects themselves.
+
 #### Validations
 
 ```ruby
@@ -162,7 +212,7 @@ client.Product.last_response.headers['X-Rate-Limit-Reset']
 
 ## Contributing
 
-1. Fork it ( http://github.com/tradegecko/gecko/fork )
+1. Fork it ( https://github.com/tradegecko/gecko/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`)

data/gecko-ruby.gemspec

@@ -29,7 +29,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "thor"
   spec.add_development_dependency "pry"
 
-  spec.add_dependency "oauth2"
+  spec.add_dependency "oauth2", "> 1.1.0"
   spec.add_dependency "virtus"
   spec.add_dependency "activesupport"
 end

data/lib/gecko/helpers/association_helper.rb

@@ -2,67 +2,174 @@ module Gecko
   module Helpers
     # Helper for has_many/belongs_to relationships
     module AssociationHelper
-      # Set up a belongs_to relationship between two classes based on a
-      # JSON key of {class_name}_id.
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        # Set up a belongs_to relationship between two classes based on a
+        # JSON key of {class_name}_id.
+        #
+        # @example
+        #   class Gecko::Record::Variant
+        #     belongs_to :product
+        #   end
+        #
+        # @param [Symbol] model_name
+        # @param [#to_hash] options options for setting up the relationship
+        # @option options [String] :class_name Override the default class name
+        # @option options [String] :readonly (false) Whether to serialize
+        #   this attribute
+        #
+        # @return [undefined]
+        #
+        # @api public
+        def belongs_to(model_name, options={})
+          class_name  = options[:class_name] || model_name.to_s.classify
+          foreign_key = model_name.to_s.foreign_key.to_sym
+
+          define_method model_name do
+            if (id = attributes[foreign_key])
+              @client.adapter_for(class_name).find(id)
+            end
+          end
+          attribute foreign_key, Integer, readonly: options[:readonly]
+        end
+
+        # Set up a has_many relationship between two classes based on a
+        # JSON key of {class_name}_ids.
+        #
+        # @example
+        #   class Gecko::Record::Product
+        #     has_many :variants
+        #   end
+        #
+        # @param [Symbol] model_name
+        # @param [#to_hash] options options for setting up the relationship
+        # @option options [String] :class_name Override the default class name
+        # @option options [Boolean] :readonly (true) Whether to serialize this
+        #   attribute
+        # @option options [Boolean] :embedded (false) Whether this relation should
+        #   persisted inside it's parent record
+        #
+        # @return [undefined]
+        #
+        # @api public
+        def has_many(association_name, options={})
+          model_name = association_name.to_s.singularize
+          class_name = options[:class_name] || model_name.classify
+          foreign_key = model_name.foreign_key.pluralize.to_sym
+          readonly    = options.key?(:readonly) ? options[:readonly] : true
+
+          define_method association_name do
+            collection_proxies[association_name] ||= begin
+              ids = self.attributes[foreign_key]
+              if ids.any?
+                collection = @client.adapter_for(class_name).find_many(ids)
+              else
+                collection = []
+              end
+
+              build_collection_proxy(collection, {
+                embedded:         options[:embedded],
+                class_name:       class_name,
+                association_name: association_name
+              })
+            end
+          end
+          attribute foreign_key, Array[Integer], readonly: readonly
+        end
+      end
+
+    private
+
+      # Stores a reference to all of the child collection proxies on the model
       #
-      # @example
-      #   class Gecko::Record::Variant
-      #     belongs_to :product
-      #   end
+      # @return [Hash]
       #
-      # @param [Symbol] model_name
-      # @param [#to_hash] options options for setting up the relationship
-      # @option options [String] :class_name Override the default class name
-      # @option options [String] :readonly (false) Whether to serialize
-      #   this attribute
+      # @api private
+      def collection_proxies
+        @collection_proxies ||= {}
+      end
+
+      # Setup a child collection proxy on first instantation
       #
-      # @return [undefined]
+      # @return [Hash]
       #
-      # @api public
-      def belongs_to(model_name, options={})
-        class_name  = options[:class_name] || model_name.to_s.classify
-        foreign_key = model_name.to_s.foreign_key.to_sym
+      # @api private
+      def build_collection_proxy(target, association_name:, class_name:, embedded:)
+        CollectionProxy.new({
+          parent:           self,
+          target:           target,
+          embedded:         embedded,
+          class_name:       class_name,
+          association_name: association_name
+        })
+      end
+    end
 
-        define_method model_name do
-          if (id = attributes[foreign_key])
-            @client.adapter_for(class_name).find(id)
-          end
-        end
-        attribute foreign_key, Integer, readonly: options[:readonly]
+    # Provides a convenient wrapper for a collection of child records.
+    # Exposes both an Enumerable interface as well as the ability
+    # to create new child records
+    class CollectionProxy
+      include Enumerable
+      delegate :each, :empty?, to: :@target
+
+      attr_reader :association_name, :parent
+
+      # Setup the child collection proxy
+      #
+      # @return [Hash]
+      #
+      # @api private
+      def initialize(parent:, association_name:, class_name:, target:, embedded:)
+        @parent           = parent
+        @target           = target
+        @embedded         = embedded
+        @class_name       = class_name
+        @association_name = association_name
       end
 
-      # Set up a has_many relationship between two classes based on a
-      # JSON key of {class_name}_ids.
+      # Build a new child object inside the collection
       #
       # @example
-      #   class Gecko::Record::Product
-      #     has_many :variants
-      #   end
+      #   item = order.order_line_items.build(variant_id: 1234, quantiy: 12.5, price: 13.45)
+      #   order.order_line_items.include?(item) #=> true
       #
-      # @param [Symbol] model_name
-      # @param [#to_hash] options options for setting up the relationship
-      # @option options [String] :class_name Override the default class name
-      # @option options [String] :readonly (true) Whether to serialize this
-      #   attribute
+      # @param [#to_hash] attributes for the child record
       #
-      # @return [undefined]
+      # @return [Gecko::Record::Base]
       #
       # @api public
-      def has_many(association_name, options={})
-        model_name = association_name.to_s.singularize
-        class_name = options[:class_name] || model_name.classify
-        foreign_key = model_name.foreign_key.pluralize.to_sym
-        readonly    = options.key?(:readonly) ? options[:readonly] : true
-
-        define_method association_name do
-          ids = self.attributes[foreign_key]
-          if ids.any?
-            @client.adapter_for(class_name).find_many(ids)
-          else
-            []
-          end
+      def build(attributes)
+        if @parent.persisted?
+          parent_foreign_key = @parent.class.demodulized_name.foreign_key.to_sym
+          attributes[parent_foreign_key] = @parent.id
         end
-        attribute foreign_key, Array[Integer], readonly: readonly
+
+        record = client.adapter_for(@class_name).build(attributes)
+        @target << record
+        record
+      end
+
+      # Should this collection of records be serialized inside it's parent object
+      #
+      # @return [Boolean]
+      #
+      # @api private
+      def embed_records?
+        !!@embedded
+      end
+
+    private
+
+      # Access the Gecko Client object
+      #
+      # @return [Gecko::Client]
+      #
+      # @api private
+      def client
+        @parent.instance_variable_get(:@client)
       end
     end
   end

data/lib/gecko/helpers/serialization_helper.rb

@@ -30,6 +30,11 @@ module Gecko
           next unless writeable?(attribute)
           serialize_attribute(attribute_hash, attribute)
         end
+
+        embedded_collections_for_serialization.each do |collection|
+          serialize_new_records(attribute_hash, collection)
+        end
+
         attribute_hash
       end
 
@@ -96,6 +101,33 @@ module Gecko
       def root
         self.class.demodulized_name.underscore.to_sym
       end
+
+    private
+
+      # Returns embedded collections
+      #
+      # @return [Array<Gecko::Helpers::CollectionProxy>]
+      #
+      # @api private
+      def embedded_collections_for_serialization
+        collection_proxies.values.select(&:embed_records?)
+      end
+
+      # Serialize newly built embedded records into the payload
+      #
+      # @return [undefined]
+      #
+      # @api private
+      def serialize_new_records(serialized, collection_proxy)
+        new_records = collection_proxy.reject(&:persisted?)
+        return unless new_records.any?
+
+        parent_key = collection_proxy.parent.class.demodulized_name.foreign_key.to_sym
+
+        serialized[collection_proxy.association_name] = new_records.map do |record|
+          record.serializable_hash.except(parent_key)
+        end
+      end
     end
   end
 end

data/lib/gecko/record/base.rb

@@ -7,7 +7,7 @@ module Gecko
   module Record
     class Base
       include Virtus.model
-      extend  Gecko::Helpers::AssociationHelper
+      include  Gecko::Helpers::AssociationHelper
       include Gecko::Helpers::InspectionHelper
       include Gecko::Helpers::SerializationHelper
       include Gecko::Helpers::ValidationHelper

data/lib/gecko/record/base_adapter.rb

@@ -78,7 +78,7 @@ module Gecko
       def find_many(ids)
         existing, required = ids.partition { |id| has_record_for_id?(id) }
         if required.any?
-          where(ids: required) + existing.map { |id| record_for_id(id) }
+          where(ids: ids) + existing.map { |id| record_for_id(id) }
         else
           existing.map { |id| record_for_id(id) }
         end

data/lib/gecko/record/fulfillment.rb

@@ -9,7 +9,7 @@ module Gecko
       belongs_to :billing_address,  class_name: 'Address'
       belongs_to :stock_location,  class_name: 'Location'
 
-      has_many :fulfillment_line_items
+      has_many :fulfillment_line_items, embedded: true
 
       attribute :status,           String
       attribute :exchange_rate,    String

data/lib/gecko/record/invoice.rb

@@ -8,7 +8,7 @@ module Gecko
       belongs_to :billing_address
       belongs_to :payment_term
 
-      has_many :invoice_line_items
+      has_many :invoice_line_items, embedded: true
 
       attribute :invoice_number,  String
       attribute :invoiced_at,     Date

data/lib/gecko/record/order.rb

@@ -5,7 +5,7 @@ module Gecko
     class Order < Base
       has_many :fulfillments
       has_many :invoices
-      has_many :order_line_items
+      has_many :order_line_items, embedded: true
 
       belongs_to :company
       belongs_to :contact

data/lib/gecko/record/order_line_item.rb

@@ -24,9 +24,6 @@ module Gecko
       attribute :position,  Integer
 
       attribute :image_url, String,     readonly: true
-
-      # DEPRECATED
-      attribute :tax_rate,  BigDecimal
     end
 
     class OrderLineItemAdapter < BaseAdapter

data/lib/gecko/version.rb

@@ -1,3 +1,3 @@
 module Gecko
-  VERSION = '0.2.6'
+  VERSION = '0.5.0'
 end

data/test/helpers/association_helper_test.rb

@@ -33,7 +33,7 @@ class Gecko::Helpers::AssociationHelperTest < Minitest::Test
   def test_has_many_without_ids
     record = @klass.new(@client, {order_ids: []})
     @client.Order.expects(:find_many).never
-    assert_equal([], record.orders)
+    assert_empty(record.orders)
   end
 
   def test_belongs_to
@@ -53,4 +53,27 @@ class Gecko::Helpers::AssociationHelperTest < Minitest::Test
     @client.Order.expects(:find).with(56)
     record.small_order
   end
+
+  def test_building_a_new_embedded_item
+    record = @client.Order.build({})
+    embedded = record.order_line_items.build(quantity: 1, variant_id: 1)
+    assert_instance_of(Gecko::Record::OrderLineItem, embedded)
+    assert_nil(embedded.order_id)
+    assert_instance_of(Gecko::Record::OrderLineItem, embedded)
+    assert(!embedded.persisted?)
+    assert_includes(record.order_line_items, embedded)
+    skip("This hasn't been implemented for fresh records yet")
+    assert_equal(record, embedded.order)
+  end
+
+  def test_building_a_new_embedded_item_on_existing_record
+    record = @client.Order.instantiate_and_register_record(id: 123)
+    embedded = record.order_line_items.build(quantity: 1, variant_id: 1)
+    assert_instance_of(Gecko::Record::OrderLineItem, embedded)
+    assert_equal(123, embedded.order_id)
+    assert_instance_of(Gecko::Record::OrderLineItem, embedded)
+    assert(!embedded.persisted?)
+    assert_includes(record.order_line_items, embedded)
+    assert_equal(record, embedded.order)
+  end
 end

data/test/helpers/serialization_helper_test.rb

@@ -80,6 +80,22 @@ class Gecko::Helpers::SerializationHelperTest < Minitest::Test
     assert_equal(:order_line_item, record.root)
   end
 
+  def test_serializing_new_embedded_items
+    record = Gecko::Record::Order.new(@client, {})
+    record.order_line_items.build(quantity: 1, variant_id: 1)
+    serialized = record.serializable_hash
+    assert(1, serialized[:order_line_items].length)
+    assert_equal(1, serialized[:order_line_items][0][:variant_id])
+    assert_equal('1.0', serialized[:order_line_items][0][:quantity])
+    assert(!serialized[:order_line_items][0].key?(:order_id))
+  end
+
+  def test_doesnt_add_embedded_keys_unless_required
+    record = Gecko::Record::Order.new(@client, {})
+    serialized = record.serializable_hash
+    assert(!serialized.key?(:order_line_items))
+  end
+
 private
 
   def serialized_record

data/test/support/shared_sideloaded_data_parsing_examples.rb

@@ -8,7 +8,7 @@ module SharedSideloadedDataParsingExamples
         child_adapter = @client.adapter_for(child.singularize.classify)
 
         identity_map = child_adapter.instance_variable_get(:@identity_map)
-        child_collection = collection.flat_map { |record| record.send(child) }
+        child_collection = collection.flat_map { |record| record.send(child).to_a }
 
         assert_equal child_collection, identity_map.values
       end

data/test/test_helper.rb

@@ -1,7 +1,7 @@
 require 'gecko'
 require 'minitest/autorun'
 require 'minitest/pride'
-require 'mocha/mini_test'
+require 'mocha/minitest'
 require 'vcr'
 require 'webmock/minitest'
 require 'timecop'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gecko-ruby
 version: !ruby/object:Gem::Version
-  version: 0.2.6
+  version: 0.5.0
 platform: ruby
 authors:
 - Bradley Priest
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-03-19 00:00:00.000000000 Z
+date: 2018-08-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -154,16 +154,16 @@ dependencies:
   name: oauth2
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - ">"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - ">"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.1.0
 - !ruby/object:Gem::Dependency
   name: virtus
   requirement: !ruby/object:Gem::Requirement
@@ -356,7 +356,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubyforge_project: 
+rubygems_version: 2.7.6
 signing_key: 
 specification_version: 4
 summary: A Ruby interface to the TradeGecko API.