dear_inventory 0.7.5 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9fd73bb4ad365b44049b2329bc8124e68814c8c253d5bcf8c79c7e3f1ee6d445
-  data.tar.gz: 24787adfef1c7a1f059bec01f32a86034748ad57f2313d8cee10854b778181e0
+  metadata.gz: bbdd47a610c9e0211c3172dbefa7f7f01fd8b4f162d56a28278f918cdf5f410d
+  data.tar.gz: 35a216d5c1fef58b34cdeb5e270716b838bb150208c351c72b02efd51c0ddb19
 SHA512:
-  metadata.gz: bcbb7d9c3d0915ed5c9b4c824fd8f8f0b646807c8718eec81810e7022578b8566a4d6b156ca6220fa93192a7017581b68e104c9cd880c17fa9a9184cedcbaa3a
-  data.tar.gz: bb4dd0dc0e691e864d9f0a324e046f9f510ac194506a1c50812551b2f6bda15bd7a27bc0b37938ea4d9a61f3bafc7bdfa7ed9d7f71984358a9211d187074448b
+  metadata.gz: c367eb7bae39cc13c565b52276d11f108755648a07a975124a8781e104f7019966dbbddac9374bcdd4d06aada9a4ae123fac9202d026fdb7b7dc756108dc3e61
+  data.tar.gz: ab07f448af90b13057588b4cd5aaae384a731be266584c1382640c5666d45636581e867cc306d64b807199dad6d2e074f667e681f6febe6283fe3e9905f34f36

data/.rubocop.yml

@@ -30,6 +30,12 @@ Lint/AmbiguousBlockAssociation:
   Exclude:
     - spec/**/*
 
+Lint/RaiseException:
+  Enabled: true
+
+Lint/StructNewOverride:
+  Enabled: true
+
 Metrics/BlockLength:
   Exclude:
     - dear_inventory.gemspec
@@ -64,6 +70,15 @@ Style/Documentation:
 Style/GuardClause:
   Enabled: false
 
+Style/HashEachMethods:
+  Enabled: true
+
+Style/HashTransformKeys:
+  Enabled: true
+
+Style/HashTransformValues:
+  Enabled: true
+
 Style/LambdaCall:
   Enabled: false
 

data/README.md

@@ -1,8 +1,8 @@
 # DearInventory
 
-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/dear_inventory`. To experiment with that code, run `bin/console` for an interactive prompt.
+A Ruby API client for connecting to DEAR Inventory. At this point, I have only been implementing the GET requests based upon our business needs but, if you like the look of this gem but require a missing endpoint, it would be quite easy to bolt on POST/PUT/Delete endpoints.
 
-TODO: Delete this and the text above, and describe your gem
+Honestly, the DEAR API is a mess. Where possible, this gem attempts to hide the rampant inconsistencies and provide continuity but I'm afraid I'm no magician.
 
 ## Installation
 
@@ -22,10 +22,7 @@ Or install it yourself as:
 
 ## N.B for Ruby 2.7
 
-At time of writing, the Sorbet team has not yet accepted my pull request to fix
-deprecation warnings due to the use of the single splat operator. It can be
-quite frustrating to have your console flooded with warnings and so it may be
-worth your while specifying my fork of sorbet-runtime in your project's Gemfile:
+At time of writing, the Sorbet team has not yet accepted my pull request to fix deprecation warnings due to the use of the single splat operator. It can be quite frustrating to have your console flooded with warnings and so it may be worth your while specifying my fork of sorbet-runtime in your project's Gemfile:
 ```
 gem "sorbet-runtime",
     git: "https://github.com/HashNotAdam/sorbet.git",
@@ -33,10 +30,9 @@ gem "sorbet-runtime",
     glob: "gems/sorbet-runtime/sorbet-runtime.gemspec"
 ```
 
-## Usage
+## Configuration
 
-Before you begin, you will need to setup API credentials in DEAR Inventory at
-https://inventory.dearsystems.com/ExternalApi
+Before you begin, you will need to setup API credentials in DEAR Inventory at https://inventory.dearsystems.com/ExternalApi
 
 Next you need to supply your API credentials:
 ```ruby
@@ -48,18 +44,75 @@ DearInventory.configure do |config|
 end
 ```
 
+There is a default logger set to write to STDOUT which is also configurable
+
+```ruby
+DearInventory.configure do |config|
+  ...
+  config.logger = CustomLogger.new
+end
+```
+
+## Endpoints
+
+[Customer](https://github.com/HashNotAdam/dear_inventory-ruby/docs/resources/customer.md)
+[Product](https://github.com/HashNotAdam/dear_inventory-ruby/docs/resources/product.md)
+[Purchase](https://github.com/HashNotAdam/dear_inventory-ruby/docs/resources/purchase.md)
+[Advanced Purchase](https://github.com/HashNotAdam/dear_inventory-ruby/docs/resources/advanced_purchase.md)
+[Sale](https://github.com/HashNotAdam/dear_inventory-ruby/docs/resources/sale.md)
+
+## Managing pagination
+
+The response object for any endpoint that returns a paginated result set will include helper methods for retrieving the results.
+
+### each
+
+`each` iterates over all the records as if they were not paginated, automatically retrieving subsequent pages.
+
+```ruby
+DearInventory::Customer.().each do |record|
+	do_some_things(record)
+end
+```
+
+### next_page
+
+If you would like control over the pagination process, the paginated responses include a `next_page` method
+
+```ruby
+response = DearInventory::Customer.()
+
+loop do
+  do_some_things(response)
+  break unless response.next_page?
+  response = response.next_page
+end
+```
+
+## Exceptions
+
+Exceptions that occur while making a request to DEAR Inventory should be a subclass of DearInventory::RequestError. These errors include the DearInventory::Response instance which provides some flexibility in your error reporting.
+
+```ruby
+def find_a_sale
+  DearInventory::Sale.(id: "incorrect")
+rescue DearInventory::RequestError => e
+  message = [
+    e.message,
+    "URI: #{e.response.request.uri}",
+    "Params: #{e.response.request.params.to_h}"
+  ]
+  ErrorMonitoring.error(message.join("\n"))
+end
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push
-git commits and tags, and push the `.gem` file to
-[rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
-Since it is necessary to authenticate with DEAR Inventory to test API resources,
-credentials are required. The dotenv gem is loaded when tests are run and will
-look for a .env file in the root directory. A .env.example file has been
-supplied so you copy it to .env and replace the example values:
+Since it is necessary to authenticate with DEAR Inventory to test API resources, credentials are required. The dotenv gem is loaded when tests are run and will look for a .env file in the root directory. A .env.example file has been supplied so you copy it to .env and replace the example values:
 
 ```sh
 cp .env.example .env
@@ -67,8 +120,7 @@ cp .env.example .env
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/HashNotAdam/dear_inventory. This project is intended to be a safe, welcoming
-space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+Bug reports and pull requests are welcome on GitHub at https://github.com/HashNotAdam/dear_inventory. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
 ## License
 

data/dear_inventory.gemspec

@@ -32,8 +32,8 @@ Gem::Specification.new do |spec|
   spec.add_dependency "sorbet-runtime"
 
   spec.add_development_dependency "bundler", "~> 2.0"
+  spec.add_development_dependency "byebug"
   spec.add_development_dependency "dotenv"
-  spec.add_development_dependency "pry-byebug"
   spec.add_development_dependency "rake", ">= 12.3.3"
   spec.add_development_dependency "rspec", "~> 3.0"
   spec.add_development_dependency "rubocop", "~> 0.71"

data/docs/resources/advanced_purchase.md

@@ -0,0 +1,25 @@
+# AdvancedPurchase resource
+
+## Show GET
+
+```ruby
+DearInventory::AdvancedPurchase.show
+```
+
+### Parameters
+
+| Name | Type | Required |
+| --- | --- | --- |
+| id | String | true |
+| combine_additional_charges | Boolean | false |
+
+### Response
+
+To see what data is available in the response, you can call the `field` method:
+
+```ruby
+response = DearInventory::AdvancedPurchase.show(id: "abcdef01-2345-6789-abcd-ef0123456789")
+response.fields # [:id, :supplier_id, :supplier, :contact, :phone, :inventory_account, :blind_receipt, :approach, :billing_address, :shipping_address, :base_currency, :supplier_currency, :tax_rule, :tax_calculation, :terms, :required_by, :location, :note, :order_number, :order_date, :combined_receiving_status, :combined_invoice_status, :combined_payment_status, :type, :is_service_only, :status, :related_drop_ship_sale_task, :currency_rate, :last_updated_date, :order, :stock_received, :put_away, :invoice, :credit_note, :manual_journals, :additional_attributes, :attachments, :inventory_movements]
+id = response.id # abcdef01-2345-6789-abcd-ef0123456789
+```
+

data/docs/resources/customer.md

@@ -0,0 +1,31 @@
+# Customer resource
+
+## GET
+
+```ruby
+DearInventory::Customer.index
+DearInventory::Customer.()
+```
+
+### Parameters
+| Name | Type | Required |
+| --- | --- | --- |
+| id | String | false |
+| page | Integer | false |
+| limit | Integer | false |
+| name | String | false |
+| modified_since | DateTime | false |
+| include_deprecated | Boolean | false |
+
+### Response
+
+The index endpoint returns a paginated set of records.
+
+To see what data is available in the response, you can call the `field` method:
+
+```ruby
+response = DearInventory::Customer.()
+response.fields # [:records, :total, :page, :sale_list]
+records = response.records
+```
+

data/docs/resources/product.md

@@ -0,0 +1,37 @@
+# Product resource
+
+## GET
+
+```ruby
+DearInventory::Product.index
+DearInventory::Product.()
+```
+
+### Parameters
+| Name | Type | Required |
+| --- | --- | --- |
+| id | String | false |
+| page | Integer | false |
+| limit | Integer | false |
+| name | String | false |
+| sku | String | false |
+| modified_since | DateTime | false |
+| include_attachments | Boolean | false |
+| include_bom | Boolean | false |
+| include_deprecated | Boolean | false |
+| include_movements | Boolean | false |
+| include_reorder_levels | Boolean | false |
+| include_suppliers | Boolean | false |
+
+### Response
+
+The index endpoint returns a paginated set of records.
+
+To see what data is available in the response, you can call the `field` method:
+
+```ruby
+response = DearInventory::Product.()
+response.fields # [:records, :total, :page, :products]
+records = response.records
+```
+

data/docs/resources/purchase.md

@@ -0,0 +1,89 @@
+# Purchase resource
+
+## Index GET
+
+```ruby
+DearInventory::Purchase.index
+DearInventory::Purchase.()
+```
+
+### Parameters
+
+| Name                    | Type     | Required |
+| ----------------------- | -------- | -------- |
+| page                    | Integer  | false    |
+| limit                   | Integer  | false    |
+| search                  | String   | false    |
+| required_by             | DateTime | false    |
+| updated_since           | DateTime | false    |
+| order_status            | String   | false    |
+| restock_received_status | String   | false    |
+| invoice_status          | String   | false    |
+| credit_note_status      | String   | false    |
+| unstock_status          | String   | false    |
+| status                  | String   | false    |
+| drop_ship_task_id       | String   | false    |
+
+### Response
+
+The index endpoint returns a paginated set of purchase summary records. If you would like to load the full purchase, you can either use the helper method, `full_record`, or call the appropriate resource directly, keeping in mind that Simple and Advanced/Service purchases have different resources... because DEAR :shrug:
+
+```ruby
+DearInventory::Purchase.().records.each do |purchase_summary|
+  purchase = purchase_summary.full_record
+end
+```
+
+```ruby
+DearInventory::Purchase.().records.each do |purchase_summary|
+  purchase =
+    case purchase_summary.type
+    when "Advanced Purchase", "Service Purchase"
+      DearInventory::AdvancedPurchase.show(id: purchase_summary.id)
+    else
+      DearInventory::Purchase.show(id: purchase_summary.id)
+    end
+end
+```
+
+If you use the `each` helper method, it will automatically return the full record each time. Given it makes n+1 API requests, the time per iteration will be a lot slower than iterating over `records` directly, however, it's much nicer if you intend to load every record anway.
+
+```ruby
+DearInventory::Purchase.().each do |purchase|
+  so_stuff_with_the_full_purchase_record(purchase)
+end
+```
+
+To see what data is available in the response, you can call the `field` method:
+
+```ruby
+response = DearInventory::Purchase.()
+response.fields # [:records, :total, :page, :purchases]
+records = response.records
+```
+
+
+
+## Show GET
+
+```ruby
+DearInventory::Purchase.show
+```
+
+### Parameters
+
+| Name | Type | Required |
+| --- | --- | --- |
+| id | String | true |
+| combine_additional_charges | Boolean | false |
+
+### Response
+
+To see what data is available in the response, you can call the `field` method:
+
+```ruby
+response = DearInventory::Purchase.show(id: "abcdef01-2345-6789-abcd-ef0123456789")
+response.fields # [:id, :supplier_id, :supplier, :contact, :phone, :inventory_account, :blind_receipt, :approach, :billing_address, :shipping_address, :base_currency, :supplier_currency, :tax_rule, :tax_calculation, :terms, :required_by, :location, :note, :order_number, :order_date, :status, :related_drop_ship_sale_task, :currency_rate, :last_updated_date, :order, :stock_received, :invoice, :credit_note, :manual_journals, :additional_attributes, :attachments, :inventory_movements]
+id = response.id # abcdef01-2345-6789-abcd-ef0123456789
+```
+

data/docs/resources/sale.md

@@ -0,0 +1,89 @@
+# Sale resource
+
+## Index GET
+
+```ruby
+DearInventory::Sale.index
+DearInventory::Sale.()
+```
+
+### Parameters
+
+| Name                    | Type     | Required |
+| ----------------------- | -------- | -------- |
+| page                    | Integer  | false    |
+| limit                   | Integer  | false    |
+| search                  | String   | false    |
+| created_since           | DateTime | false    |
+| updated_since           | DateTime | false    |
+| ship_by                 | DateTime | false    |
+| quote_status            | String   | false    |
+| order_status            | String   | false    |
+| combined_invoice_status | String   | false    |
+| combined_pick_status    | String   | false    |
+| combined_pack_status    | String   | false    |
+| combined_shipp_status   | String   | false    |
+| credit_note_status      | String   | false    |
+| external_id             | String   | false    |
+| status                  | String   | false    |
+| ready_for_shipping      | Boolean  | false    |
+
+### Response
+
+The index endpoint returns a paginated set of sale summary records. If you would like to load the full purchase, you can either use the helper method, `full_record`, or call `DearInventory::Sale.show` resource.
+
+```ruby
+DearInventory::Sale.().records.each do |sale_summary|
+  sale = sale_summary.full_record
+end
+```
+
+```ruby
+DearInventory::Sale.().records.each do |sale_summary|
+  sale = DearInventory::Sale.show(id: sale_summary.id)
+end
+```
+
+If you use the `each` helper method, it will automatically return the full record each time. Given it makes n+1 API requests, the time per iteration will be a lot slower than iterating over `records` directly, however, it's much nicer if you intend to load every record anway.
+
+```ruby
+DearInventory::Sale.().each do |sale|
+  so_stuff_with_the_full_sale_record(sale)
+end
+```
+
+To see what data is available in the response, you can call the `field` method:
+
+```ruby
+response = DearInventory::Sale.()
+response.fields # [:records, :total, :page, :sales]
+records = response.records
+```
+
+
+
+## Show GET
+
+```ruby
+DearInventory::Sale.show
+```
+
+### Parameters
+
+| Name | Type | Required |
+| --- | --- | --- |
+| id | String | true |
+| combine_additional_charges | Boolean | false |
+| hide_inventory_movements | Boolean | false |
+| include_transactions | Boolean | false |
+
+### Response
+
+To see what data is available in the response, you can call the `field` method:
+
+```ruby
+response = DearInventory::Sale.show(id: "abcdef01-2345-6789-abcd-ef0123456789")
+response.fields # [:id, :customer, :customer_id, :contact, :phone, :email, :default_account, :skip_quote, :billing_address, :shipping_address, :base_currency, :customer_currency, :tax_rule, :tax_calculation, :terms, :price_tier, :ship_by, :location, :sale_order_date, :last_modified_on, :note, :customer_reference, :cogs_amount, :status, :combined_picking_status, :combined_packing_status, :combined_shipping_status, :fulfilment_status, :combined_invoice_status, :combined_payment_status, :combined_tracking_numbers, :carrier, :currency_rate, :sales_representative, :type, :source_channel, :external_id, :service_only, :quote, :order, :fulfilments, :invoices, :credit_notes, :manual_journals, :additional_attributes, :attachments, :inventory_movements, :transactions]
+id = response.id # abcdef01-2345-6789-abcd-ef0123456789
+```
+