fulfil_api 0.0.3 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c2f9290d460010359822ca7683de870fea5a0e694fb49c3d4b7eb752377a47dc
-  data.tar.gz: 11b8066943e9e9559e37fd5aa33dfff5d36aa8ad0af4110e2e5e34afc2c2da1a
+  metadata.gz: 2a26b32a0feab8bd7e697b27db519ac3945fefcd00159aa714742c40ac5abffe
+  data.tar.gz: e8e5c494d57360d1cacbbea096c6c4cac3d70d504d04f4478a5f5508db658a63
 SHA512:
-  metadata.gz: ec1dea5391c0951596e70baab45118e143f43e0e98f254a773114a62db8635fdfb545ff8fe7bf5ffe37041f57aa14b69f54c72e93b60c5afae1bcdc1d92a3147
-  data.tar.gz: 035f253caee934a63c349e1bb206d100347cc7537836e9a04f34e7baa15a6bd1c03fe5dfccb3b7218df02ae0ff133d075c216e77e689fbdfb2b0915a2b3ff638
+  metadata.gz: 1d4b7f5ca1a4bc4e8449cc3b235fd9f3b467e7977d76feaa52fa11dac18a6a34ba1ab6b4a8280183e798e45f4ddfda00e0e2d27534ca467110a3cdec203adc49
+  data.tar.gz: 63ce6d7793de383098af74f7ca3c81ef8730351d7483390f8256f2dcd5cecc5cb3385ff46e9046fe7ed51f62e66f183b3b4abbf7b11f92a8322abe1ef44eeec9

data/README.md

@@ -68,28 +68,28 @@ The gem uses an `ActiveRecord` like query interface to query the Fulfil API.
 
 ```ruby
 # Find one specific resource
-sales_order = FulfilApi::Resource.set(name: "sale.sale").find_by(["id", "=", 100])
+sales_order = FulfilApi::Resource.set(model_name: "sale.sale").find_by(["id", "=", 100])
 p sales_order["id"] # => 100
 
 # Find a list of resources
-sales_orders = FulfilApi::Resource.set(name: "sale.sale").where(["channel", "=", 4])
+sales_orders = FulfilApi::Resource.set(model_name: "sale.sale").where(["channel", "=", 4])
 p sales_orders.size # => 500 (standard number of resources returned by Fulfil)
 p sales_orders.first["id"] # => 10 (an example of an ID returned by Fulfil)
 
 # Find a limited list of resources
-sales_orders = FulfilApi::Resource.set(name: "sale.sale").where(["channel", "=", 4]).limit(50)
+sales_orders = FulfilApi::Resource.set(model_name: "sale.sale").where(["channel", "=", 4]).limit(50)
 p sales_orders.size # => 50
 
 # Include more resource details than the ID only
-sales_orders = FulfilApi::Resource.set(name: "sale.sale").select("reference").where(["channel", "=", 4])
+sales_orders = FulfilApi::Resource.set(model_name: "sale.sale").select("reference").where(["channel", "=", 4])
 p sales_orders.first["reference"] # => SO1234
 
 # Fetch nested data from a relation
-line_items = FulfilApi::Resource.set(name: "sale.line").select("sale.reference")
+line_items = FulfilApi::Resource.set(model_name: "sale.line").select("sale.reference")
 p line_items.first["sale"]["reference"] # => SO1234
 
 # Query nested data from a relation
-line_items = FulfilApi::Resource.set(name: "sale.line").where(["sale.reference", "=", "SO1234"])
+line_items = FulfilApi::Resource.set(model_name: "sale.line").where(["sale.reference", "=", "SO1234"])
 p line_items.first["id"] # => 10
 ```
 
@@ -100,14 +100,14 @@ p line_items.first["id"] # => 10
 Any data returned through the `FulfilApi` gem returns a list or a single `FulfilApi::Resource`. The data of the API resource is accessible through a `Hash`-like method.
 
 ```ruby
-sales_order = FulfilApi::Resource.set(name: "sale.sale").find_by(["id", "=", 100])
+sales_order = FulfilApi::Resource.set(model_name: "sale.sale").find_by(["id", "=", 100])
 p sales_order["id"] # => 100
 ```
 
 When you're requesting relational data for an API resource, you can access it in a similar manner.
 
 ```ruby
-sales_order = FulfilApi::Resource.set(name: "sale.sale").select("channel.name").find_by(["id", "=", 100])
+sales_order = FulfilApi::Resource.set(model_name: "sale.sale").select("channel.name").find_by(["id", "=", 100])
 p sales_order["channel"]["name"] # => Shopify
 ```
 
@@ -115,14 +115,14 @@ p sales_order["channel"]["name"] # => Shopify
 
 ```ruby
 # You can't do this
-FulfilApi::Resource.set(name: "sale.sale").select("lines.reference").find_by(["id", "=", 100])
+FulfilApi::Resource.set(model_name: "sale.sale").select("lines.reference").find_by(["id", "=", 100])
 
 # You can do this (BUT it's not recommended)
-sales_order = FulfilApi::Resource.set(name: "sale.sale").select("lines").find_by(["id", "=", 100])
-line_items = FulfilApi::Resource.set(name: "sale.line").where(["id", "in", sales_order["lines"]])
+sales_order = FulfilApi::Resource.set(model_name: "sale.sale").select("lines").find_by(["id", "=", 100])
+line_items = FulfilApi::Resource.set(model_name: "sale.line").where(["id", "in", sales_order["lines"]])
 
 # You can do this (recommended)
-line_items = FulfilApi::Resource.set(name: "sale.line").find_by(["sale.id", "=", 100])
+line_items = FulfilApi::Resource.set(model_name: "sale.line").find_by(["sale.id", "=", 100])
 ```
 
 ## Development

data/lib/fulfil_api/customer_shipment.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module FulfilApi
+  # The {FulfilApi::CustomerShipment} represents a single StockShipmentOut resource returned
+  #   by the API endpoints of Fulfil.
+  class CustomerShipment < Resource
+    MODEL_NAME = "stock.shipment.out"
+
+    class << self
+      # Sets the fulfillment status of the customer shipment on hold
+      #
+      # @param id_or_ids [String, Integer, Array[String], Array[Integer]] The ID(s) of the customer shipment(s) to hold.
+      # @param note [String] A note to define the reason for holding. (Optional)
+      # @param hold_reason [String] An hold reason ID. (Optional)
+      # @return [Boolean] Returns true if hold successfully.
+      # @raise [FulfilApi::Error] If an error occurs during holding the customer shipment.
+      #
+      # @example Hold a customer shipment
+      #   FulfilApi::CustomerShipment.hold(123, note: "Double booking", hold_reason: hold_reason_id)
+      #
+      # @example Hold multipe customer shipments
+      #   FulfilApi::CustomerShipment.hold([123, 456], note: "Double booking", hold_reason: hold_reason_id)
+      def hold!(id_or_ids, note: nil, hold_reason: nil)
+        FulfilApi.client.put("/model/#{MODEL_NAME}/hold",
+                             body: [[*id_or_ids].flatten, { note: note, hold_reason: hold_reason }.compact_blank])
+
+        true
+      end
+
+      # Unholds the fulfillment status of the customer shipment
+      #
+      # @param id_or_ids [String, Integer, Array[String], Array[Integer]]
+      #   The ID(s) of the customer shipment(s) to unhold.
+      # @param note [String] A note to define the reason for unholding.
+      # @return [Boolean] Returns true if hold successfully.
+      # @raise [FulfilApi::Error] If an error occurs during holding the customer shipment.
+      #
+      # @example Unhold a customer shipment
+      #   FulfilApi::CustomerShipment.unhold(123, note: "All clear")
+      #
+      # @example Unhold a customer shipment
+      #   FulfilApi::CustomerShipment.unhold([123, 456], note: "All clear")
+      def unhold!(id_or_ids, note: nil)
+        FulfilApi.client.put("/model/#{MODEL_NAME}/unhold", body: [[*id_or_ids].flatten, { note: note }.compact_blank])
+
+        true
+      end
+    end
+
+    # Sets the current customer shipment on hold, rescuing any errors that occur and handling them based on error type.
+    #
+    # @param note [String] A note to define the reason for holding. (Optional)
+    # @param hold_reason [String] An hold reason ID. (Optional)
+    # @return [Boolean] Returns true if hold successfully, otherwise false.
+    #
+    # @example Holds a customer_shipment
+    #   customer_shipment.hold(note: "Double booking", hold_reason: hold_reason_id)
+    def hold(note: nil, hold_reason: nil)
+      self.class.hold!(id, note: note, hold_reason: hold_reason)
+    rescue FulfilApi::Error => e
+      handle_error(e)
+      false
+    end
+
+    # Unholds the current customer shipment, rescuing any errors that occur and handling them based on error type.
+    #
+    # @param note [String] A note to define the reason for unholding.
+    # @return [Boolean] Returns true if unhold successfully, otherwise false.
+    #
+    # @example Unholds a customer_shipment
+    #   customer_shipment.unhold(note: "Double booking")
+    def unhold(note: nil)
+      self.class.unhold!(id, note: note)
+    rescue FulfilApi::Error => e
+      handle_error(e)
+      false
+    end
+
+    private
+
+    def handle_error(err)
+      errors.add(code: err.details[:response_status], type: :system, message: err.details[:response_body])
+    end
+  end
+end

data/lib/fulfil_api/resource/attribute_type.rb

@@ -25,7 +25,7 @@ module FulfilApi
 
       # @param value [Any]
       def initialize(value)
-        @type = extended?(value) ? value.fetch("__class__") : nil
+        @type = extended?(value) ? value.fetch("__class__").downcase : nil
         @value = value
       end
 

data/lib/fulfil_api/resource/errors.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module FulfilApi
+  class Resource
+    # The Errors class provides a structure to track and manage errors related to a API resource.
+    class Errors
+      include Enumerable
+
+      delegate_missing_to :@errors
+
+      # @param resource_klass [FulfilApi::Resource] The resource class that this Errors instance is associated with.
+      def initialize(resource_klass)
+        @errors = []
+        @resource_klass = resource_klass
+      end
+
+      # Adds a new error to the collection, unless the same error already exists.
+      #
+      # @param code [String, Symbol] The error code.
+      # @param message [String] A description of the error.
+      # @param type [String, Symbol] The type of the error (e.g. user, authorization).
+      # @return [Array<Hash>] The updated list of errors.
+      #
+      # @example Adding an error
+      #   errors.add(code: "invalid_field", message: "Field is required", type: "validation")
+      def add(code:, message:, type:)
+        @errors << { code: code.to_s, type: type.to_sym, message: message } unless added?(code: code, type: type)
+        @errors
+      end
+
+      # Checks if an error with the specified code and type has already been added.
+      #
+      # @param code [String, Symbol] The error code to check.
+      # @param type [String, Symbol] The error type to check.
+      # @return [Boolean] True if the error has already been added, false otherwise.
+      #
+      # @example Checking if an error exists
+      #   errors.added?(code: "invalid_field", type: "validation")
+      def added?(code:, type:)
+        @errors.any? do |error|
+          error[:code] == code.to_s && error[:type] == type.to_sym
+        end
+      end
+
+      # Clears all errors from the collection.
+      #
+      # @return [Array] The cleared list of errors
+      #
+      # @example Clearing all errors
+      #   errors.clear
+      def clear
+        @errors = []
+        @errors
+      end
+
+      # Returns an array of the full error messages (just the message field).
+      #
+      # @return [Array<String>] The list of error messages.
+      #
+      # @example Retrieving full error messages
+      #   errors.full_messages
+      def full_messages
+        @errors.pluck(:message)
+      end
+
+      # Returns the collection of error messages as an array of hashes.
+      #
+      # @return [Array<Hash>] The array of error hashes.
+      #
+      # @example Retrieving all error messages
+      #   errors.messages
+      def messages
+        @errors
+      end
+    end
+  end
+end

data/lib/fulfil_api/resource/persistable.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module FulfilApi
+  class Resource
+    # The Persistable module provides methods for saving and updating resources
+    #   in the Fulfil API. It defines both instance and class methods for persisting
+    #   changes to resources.
+    #
+    # This module handles common actions like saving and updating a resource,
+    #   including error handling for different types of API errors.
+    module Persistable
+      extend ActiveSupport::Concern
+
+      class_methods do
+        # Updates a resource by its ID and model name.
+        #
+        # @param id [String, Integer] The ID of the resource to update.
+        # @param model_name [String] The name of the model to which the resource belongs.
+        # @param attributes [Hash] The attributes to update on the resource.
+        # @return [FulfilApi::Resource] The updated resource.
+        #
+        # @example Updating a resource
+        #   FulfilApi::Resource.update(id: 123, model_name: "sale.sale", reference: "MK123")
+        def update(id:, model_name:, **attributes)
+          resource = new(id: id, model_name: model_name)
+          resource.update(attributes)
+        end
+
+        # Updates a resource by its ID and model name, raising an error if the update fails.
+        #
+        # @param id [String, Integer] The ID of the resource to update.
+        # @param model_name [String] The name of the model to which the resource belongs.
+        # @param attributes [Hash] The attributes to update on the resource.
+        # @return [FulfilApi::Resource] The updated resource.
+        # @raise [FulfilApi::Error] If the update fails.
+        #
+        # @example Updating a resource with error raising
+        #   FulfilApi::Resource.update!(id: 123, model_name: "sale.sale", reference: "MK123")
+        def update!(id:, model_name:, **attributes)
+          resource = new(id: id, model_name: model_name)
+          resource.update!(attributes)
+        end
+      end
+
+      # Saves the current resource, rescuing any errors that occur and handling them based on error type.
+      #
+      # @return [FulfilApi::Resource, nil] Returns the resource if saved successfully, otherwise nil.
+      # @raise [FulfilApi::Error] If an error occurs during saving.
+      #
+      # @example Saving a resource
+      #   resource.save
+      def save
+        save!
+      rescue FulfilApi::Error => e
+        case (error = JSON.parse(e.details[:response_body]).deep_symbolize_keys!)
+        in { type: "UserError" }
+          errors.add(code: error[:code], type: :user, message: error[:message])
+        in { code: Integer, name: String, description: String }
+          errors.add(code: error[:code], type: :authorization, message: error[:description])
+        end
+
+        self
+      end
+
+      # Saves the current resource, raising an error if it cannot be saved.
+      #
+      # @return [FulfilApi::Resource] The saved resource.
+      # @raise [FulfilApi::Error] If an error occurs during saving.
+      #
+      # @example Saving a resource with error raising
+      #   resource.save!
+      def save!
+        errors.clear
+
+        if id.present?
+          FulfilApi.client.put("/model/#{model_name}/#{id}", body: to_h)
+        else # rubocop:disable Style/EmptyElse
+          # TODO: Implement the {#create} and {#create!} methods to save a new resource
+        end
+
+        self
+      end
+
+      # Updates the resource with the given attributes and saves it.
+      #
+      # @param attributes [Hash] The attributes to assign to the resource.
+      # @return [FulfilApi::Resource] The updated resource.
+      #
+      # @example Updating a resource
+      #   resource.update(reference: "MK123")
+      def update(attributes)
+        assign_attributes(attributes)
+        save
+      end
+
+      # Updates the resource with the given attributes and saves it, raising an error if saving fails.
+      #
+      # @param attributes [Hash] The attributes to assign to the resource.
+      # @return [FulfilApi::Resource] The updated resource.
+      # @raise [FulfilApi::Error] If an error occurs during the update.
+      #
+      # @example Updating a resource with error raising
+      #   resource.update!(reference: "MK123")
+      def update!(attributes)
+        assign_attributes(attributes)
+        save!
+      end
+    end
+  end
+end

data/lib/fulfil_api/resource/relation/loadable.rb

@@ -14,22 +14,25 @@ module FulfilApi
         # Loads resources from Fulfil's API based on the current filters, fields, and limits
         #   if they haven't been loaded yet.
         #
-        # Requires that {#name} is set; raises an exception if it's not.
+        # Requires that {#model_name} is set; raises an exception if it's not.
         #
         # @return [true, false] True if the resources were loaded successfully.
-        def load
+        def load # rubocop:disable Metrics/MethodLength
           return true if loaded?
 
-          if name.nil?
+          if model_name.nil?
             raise FulfilApi::Resource::Relation::ModelNameMissing, "The model name is missing. Use #set to define it."
           end
 
           response = FulfilApi.client.put(
-            "/model/#{name}/search_read",
+            "/model/#{model_name}/search_read",
             body: { filters: conditions, fields: fields, limit: request_limit }.compact_blank
           )
 
-          @resources = response.map { |resource| @resource_klass.new(resource) }
+          @resources = response.map do |attributes|
+            @resource_klass.new(attributes.merge(model_name: model_name))
+          end
+
           @loaded = true
         end
 

data/lib/fulfil_api/resource/relation/naming.rb

@@ -19,11 +19,11 @@ module FulfilApi
         #
         # @todo In the future, derive the {#name} from the @resource_klass automatically.
         #
-        # @param name [String] The name of the resource model in Fulfil.
+        # @param model_name [String] The name of the resource model in Fulfil.
         # @return [FulfilApi::Resource::Relation] A new {Relation} instance with the model name set.
-        def set(name:)
+        def set(model_name:)
           clone.tap do |relation|
-            relation.name = name
+            relation.model_name = model_name
           end
         end
       end

data/lib/fulfil_api/resource/relation/query_methods.rb

@@ -41,10 +41,10 @@ module FulfilApi
         #   depending on the API's limitations.
         #
         # @example Requesting nested data fields
-        #   FulfilApi::Resource.set(name: "sale.line").select("sale.reference").find_by(["id", "=", 10])
+        #   FulfilApi::Resource.set(model_name: "sale.line").select("sale.reference").find_by(["id", "=", 10])
         #
         # @example Requesting additional fields
-        #   FulfilApi::Resource.set(name: "sale.sale").select(:reference).find_by(["id", "=", 10])
+        #   FulfilApi::Resource.set(model_name: "sale.sale").select(:reference).find_by(["id", "=", 10])
         #
         # @param fields [Array<Symbol, String>] The fields to include in the response.
         # @return [FulfilApi::Resource::Relation] A new {Relation} instance with the selected fields.
@@ -59,7 +59,7 @@ module FulfilApi
         #   as arrays according to the Fulfil API documentation.
         #
         # @example Simple querying with conditions
-        #   FulfilApi::Resource.set(name: "sale.line").where(["sale.reference", "=", "ORDER-123"])
+        #   FulfilApi::Resource.set(model_name: "sale.line").where(["sale.reference", "=", "ORDER-123"])
         #
         # @todo Enhance the {#where} method to allow more natural and flexible queries.
         #

data/lib/fulfil_api/resource/relation.rb

@@ -13,7 +13,7 @@ module FulfilApi
       include Naming
       include QueryMethods
 
-      attr_accessor :conditions, :fields, :name, :request_limit
+      attr_accessor :conditions, :fields, :model_name, :request_limit
 
       delegate_missing_to :all
 

data/lib/fulfil_api/resource.rb

@@ -5,9 +5,17 @@ module FulfilApi
   #   endpoints of Fulfil.
   class Resource
     include AttributeAssignable
+    include Persistable
+
+    class ModelNameMissing < Error; end
 
     def initialize(attributes = {})
+      attributes.deep_stringify_keys!
+
       @attributes = {}.with_indifferent_access
+      @model_name = attributes.delete("model_name").presence ||
+                    raise(ModelNameMissing, "The model name is missing. Use the :model_name attribute to define it.")
+
       assign_attributes(attributes)
     end
 
@@ -23,7 +31,7 @@ module FulfilApi
       #   forwarded to the {FulfilApi::Resource.relation}.
       #
       # @example forwarding of the .where class method
-      #   FulfilApi::Resource.set(name: "sale.sale").find_by(["id", "=", 100])
+      #   FulfilApi::Resource.set(model_name: "sale.sale").find_by(["id", "=", 100])
       #
       # @return [FulfilApi::Resource::Relation]
       def relation
@@ -39,11 +47,30 @@ module FulfilApi
       @attributes[attribute_name]
     end
 
+    # Builds a structure for keeping track of any errors when trying to use the
+    #   persistance methods for the API resource.
+    #
+    # @return [FulfilApi::Resource::Errors]
+    def errors
+      @errors ||= Errors.new(self)
+    end
+
+    # The {#id} is a shorthand to easily grab the ID of an API resource.
+    #
+    # @return [Integer, nil]
+    def id
+      @attributes["id"]
+    end
+
     # Returns all currently assigned attributes for a {FulfilApi::Resource}.
     #
     # @return [Hash]
     def to_h
       @attributes
     end
+
+    private
+
+    attr_reader :model_name
   end
 end

data/lib/fulfil_api/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FulfilApi
-  VERSION = "0.0.3"
+  VERSION = "0.1.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fulfil_api
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.1.0
 platform: ruby
 authors:
 - Stefan Vermaas
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-09-06 00:00:00.000000000 Z
+date: 2024-09-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -84,10 +84,13 @@ files:
 - lib/fulfil_api/access_token.rb
 - lib/fulfil_api/client.rb
 - lib/fulfil_api/configuration.rb
+- lib/fulfil_api/customer_shipment.rb
 - lib/fulfil_api/error.rb
 - lib/fulfil_api/resource.rb
 - lib/fulfil_api/resource/attribute_assignable.rb
 - lib/fulfil_api/resource/attribute_type.rb
+- lib/fulfil_api/resource/errors.rb
+- lib/fulfil_api/resource/persistable.rb
 - lib/fulfil_api/resource/relation.rb
 - lib/fulfil_api/resource/relation/loadable.rb
 - lib/fulfil_api/resource/relation/naming.rb