EPT-2986 Add comments (#79)

* Add comments

* Update documentation

Author: k4th

lib/beyond_api/services/authentication/signer.rb

@@ -2,15 +2,41 @@
 
 module BeyondApi
   module Authentication
+    # @example How to instantiate a client
+    #   @client = BeyondApi::Authentication::Signer.new(api_url: 'https://example.com/api', access_token: 'your_token')
     class Signer < BaseService
-      def all(params = {})
-        get('signers', params)
+      # List all signers.
+      #
+      # @see https://developer.epages.com/beyond-docs/#list_signers
+      #
+      # @return [Hash]
+      #      #
+      # @example
+      #   @client.all
+      def all
+        get('signers')
       end
 
+      # Create a signer.
+      #
+      # @see https://developer.epages.com/beyond-docs/#create_signer
+      #
+      # @return [Hash]
+      #
+      # @example
+      #   @client.create
       def create
         post('signers')
       end
 
+      # Delete a signer. If at least one signer has been created, you cannot delete the last signer.
+      #
+      # @see https://developer.epages.com/beyond-docs/#delete_signer
+      #
+      # @return [Hash]
+      #
+      # @example
+      #   @client.delete('aa859c3c-702c-4310-9b23-638fbc468f33')
       def delete(id)
         super("signers/#{id}") # Concerns::Connection delete method
       end

lib/beyond_api/services/authentication/token.rb

@@ -2,24 +2,47 @@
 
 module BeyondApi
   module Authentication
+    # @example How to instantiate a client
+    #   @client = BeyondApi::Authentication::Token.new(api_url: 'https://example.com/api')
     class Token < BaseService
-      include Concerns::Connection # @session, @authorization
-
       def initialize(**params)
         super
-
         @authorization = :basic
         @camelize_keys = false
       end
 
+      # Create a JsonWebToken from a refresh token.
+      #
+      # @see https://developer.epages.com/beyond-docs/#create_a_jsonwebtoken_from_refresh_token
+      #
+      # @return [Hash]
+      #
+      # @example
+      #   @client.refresh_token('your_refresh_token')
       def refresh(refresh_token)
         post('oauth/token', {}, { grant_type: 'refresh_token', refresh_token: })
       end
 
+      # Create a JsonWebToken from a refresh token.
+      #
+      # @see https://developer.epages.com/beyond-docs/#create_a_jsonwebtoken_from_refresh_token
+      #
+      # @return [Hash]
+      #
+      # @example
+      #   @client.get('GY_GTp')
       def get(code)
         post('oauth/token', {}, { grant_type: 'authorization_code', code: })
       end
 
+      # Create a a JsonWebToken using the client_credentials grant type.
+      #
+      # @see https://developer.epages.com/beyond-docs/#create_a_jsonwebtoken_from_client_credentials
+      #
+      # @return [Hash]
+      #
+      # @example
+      #   @client.client_credentials
       def client_credentials
         post('oauth/token', {}, { grant_type: 'client_credentials' })
       end

lib/beyond_api/services/checkout/shipping_zone.rb

@@ -2,9 +2,23 @@
 
 module BeyondApi
   module Checkout
+    # @example How to instantiate a client
+    #   @client = BeyondApi::Checkout::ShippingZone.new(api_url: 'https://example.com/api', access_token: 'your_token')
     class ShippingZone < BaseService
-      def all
-        get('shipping-zones')
+      # List all shipping zones in a paged way.
+      #
+      # @see https://developer.epages.com/beyond-docs/#list_shipping_zones
+      #
+      # @option params [Boolean] :paginated
+      # @option params [Integer] :size the page size
+      # @option params [Integer] :page the page number
+      #
+      # @return [Hash]
+      #
+      # @example
+      #   @client.all(size: 100, page: 0)
+      def all(params = {})
+        fetch_all_pages('shipping-zones', params)
       end
     end
   end

lib/beyond_api/services/product_management/category.rb

@@ -2,23 +2,77 @@
 
 module BeyondApi
   module ProductManagement
+    # @example How to instantiate a client
+    #   @client = BeyondApi::ProductManagement::Category.new(api_url: 'https://example.com/api', access_token: 'your_token')
     class Category < BaseService
+      # Retrieve the details of a category.
+      #
+      # @see https://developer.epages.com/beyond-docs/#show_category_details
+      #
+      # @param id [String] the category UUID
+      #
+      # @return [Hash]
+      #
+      # @example
+      #   @client.find('e97226a6-9412-481f-b1d7-e64fc58df88e')
       def find(id)
         get("categories/#{id}")
       end
 
+      # List all available categories in a paged manner.
+      #
+      # @see https://developer.epages.com/beyond-docs/#list_categories
+      #
+      # @option params [Boolean] :paginated
+      # @option params [Integer] :size the page size
+      # @option params [Integer] :page the page number
+      #
+      # @return [Hash]
+      #
+      # @example
+      #   @client.all(size: 100, page: 0)
       def all(params = {})
         fetch_all_pages('categories', params)
       end
 
+      # Create a product category.
+      #
+      # @see https://developer.epages.com/beyond-docs/#create_category
+      #
+      # @param body [Hash] the request body
+      #
+      # @return [Hash]
+      #
+      # @example
+      #   @client.create(name: 'Power Bars', type: 'SMART', default_sort: 'NEWEST_FIRST')
       def create(body)
         post('categories', body)
       end
 
+      # Update all product category properties.
+      #
+      # @see https://developer.epages.com/beyond-docs/#update_all_category_properties
+      #
+      # @param body [Hash] the request body
+      #
+      # @return [Hash]
+      #
+      # @example
+      #   @client.update(name: 'High Protein Power Bars', type: 'SMART', default_sort: 'NEWEST_FIRST')
       def update(id, body)
         put("categories/#{id}", body)
       end
 
+      # Delete a product category.
+      #
+      # @see https://developer.epages.com/beyond-docs/#list_categories
+      #
+      # @param id [String] the category UUID
+      #
+      # @return [Hash] an empty hash
+      #
+      # @example
+      #   @client.delete('c8cc52ec-fe57-4d4d-a2e3-f1756e767724')
       def delete(id)
         super("categories/#{id}") # Concerns::Connection delete method
       end

lib/beyond_api/services/product_management/image.rb

@@ -2,7 +2,20 @@
 
 module BeyondApi
   module ProductManagement
+    # @example How to instantiate a client
+    #   @client = BeyondApi::ProductManagement::Image.new(api_url: 'https://example.com/api', access_token: 'your_token')
     class Image < BaseService
+      # Retrieve the images of a product.
+      #
+      # @see https://developer.epages.com/beyond-docs/#list_product_images
+      #
+      # @option params [Integer] :size the page size
+      # @option params [Integer] :page the page number
+      #
+      # @return [Hash]
+      #
+      # @example
+      #   @client.all(size: 100, page: 0)
       def all(id, params = {})
         get("products/#{id}/images", params)
       end

lib/beyond_api/services/product_management/product.rb

@@ -2,15 +2,117 @@
 
 module BeyondApi
   module ProductManagement
+    # @example How to instantiate a client
+    #   @client = BeyondApi::ProductManagement::Product.new(api_url: 'https://example.com/api', access_token: 'your_token')
     class Product < BaseService
+      # List all products in a paged manner.
+      #
+      # @see https://developer.epages.com/beyond-docs/#list_products
+      #
+      # @option params [Boolean] :paginated
+      # @option params [Integer] :size the page size
+      # @option params [Integer] :page the page number
+      #
+      # @return [Hash]
+      #
+      # @example
+      #   @client.all(size: 100, page: 0)
       def all(params = {})
         fetch_all_pages('products', params)
       end
 
+      # Create a product.
+      #
+      # @see https://developer.epages.com/beyond-docs/#create_product
+      #
+      # @param body [Hash] the request body
+      #
+      # @return [Hash]
+      #
+      # @example
+      #   product_data = {
+      #     sku: '123456789-001',
+      #     name: 'Rioja Castillo de Puerto (2013)',
+      #     description: 'Spain\nRioja Tempranillo',
+      #     manufacturer: 'Grape Vineyard',
+      #     essential_features: 'Dry. 12% alcohol. Best vine variety.',
+      #     tags: ['Bestseller', 'Red Wine', 'Sale'],
+      #     product_identifiers: [
+      #       {
+      #         type: 'EAN',
+      #         value: '9780134308135'
+      #       }
+      #     ],
+      #     sales_price: {
+      #       tax_model: 'GROSS',
+      #       amount: 8.7,
+      #       currency: 'EUR'
+      #     },
+      #     list_price: {
+      #       tax_model: 'GROSS',
+      #       amount: 10.95,
+      #       currency: 'EUR'
+      #     },
+      #     manufacturer_price: {
+      #       tax_model: 'GROSS',
+      #       amount: 11.95,
+      #       currency: 'EUR'
+      #     },
+      #     visible: true,
+      #     tax_class: 'REGULAR',
+      #     shipping_weight: {
+      #       value: 1175.0,
+      #       display_unit: 'GRAMS'
+      #     },
+      #     max_order_quantity: 6,
+      #     shipping_dimension: {
+      #       length: 1500,
+      #       width: 1000,
+      #       height: 2000
+      #     },
+      #     ref_price: {
+      #       ref_quantity: 1,
+      #       unit: 'LITER',
+      #       quantity: 0.75,
+      #       price: {
+      #         tax_model: 'GROSS',
+      #         amount: 11.6,
+      #         currency: 'EUR'
+      #       }
+      #     },
+      #     shipping_period: {
+      #       min: 2,
+      #       max: 4,
+      #       display_unit: 'WEEKS'
+      #     },
+      #     pickup_period: {
+      #       min: 1,
+      #       max: 2,
+      #       display_unit: 'WEEKS'
+      #     },
+      #     product_labels: [
+      #       {
+      #         type: 'NEW',
+      #         active_from: '2024-08-19T13:04:55.897122293',
+      #         active_until: '2024-09-16T13:04:55.897122293'
+      #       }
+      #     ]
+      #   }
+      #   @client.create(product_data)
       def create(body)
         post('products', body)
       end
 
+      # Retrieve the details of a product.
+      #
+      # @see https://developer.epages.com/beyond-docs/#show_product_details
+      #
+      # @param id [String] the product UUID
+      #
+      # @return [Hash]
+      #
+      # @example
+      #   @client.find('985efde9-577c-4752-9556-af5ed8a81b1b')
       def find(id)
         get("products/#{id}")
       end

lib/beyond_api/services/product_management/variation.rb

@@ -2,7 +2,22 @@
 
 module BeyondApi
   module ProductManagement
+    # @example How to instantiate a client
+    #   @client = BeyondApi::ProductManagement::Variation.new(api_url: 'https://example.com/api', access_token: 'your_token')
     class Variation < BaseService
+      # Retrieve the variations of a variation product in a paged manner.
+      #
+      # @see https://developer.epages.com/beyond-docs/#list_variations
+      #
+      # @param id [String] the product UUID
+      # @option params [Boolean] :paginated
+      # @option params [Integer] :size the page size
+      # @option params [Integer] :page the page number
+      #
+      # @return [Hash]
+      #
+      # @example
+      #   @client.all(size: 100, page: 0)
       def all(id, params = {})
         get("products/#{id}/variations", params)
       end

lib/beyond_api/services/product_management/variation_image.rb

@@ -2,7 +2,23 @@
 
 module BeyondApi
   module ProductManagement
+    # @example How to instantiate a client
+    #   @client = BeyondApi::ProductManagement::VariationImage.new(api_url: 'https://example.com/api', access_token: 'your_token')
     class VariationImage < BaseService
+      # Retrieve the images of a single variation of a variation product in a paged manner.
+      #
+      # @see https://developer.epages.com/beyond-docs/#list_variation_images
+      #
+      # @param product_id [String] the product UUID
+      # @param variation_id [String] the variation UUID
+      # @option params [Boolean] :paginated
+      # @option params [Integer] :size the page size
+      # @option params [Integer] :page the page number
+      #
+      # @return [Hash]
+      #
+      # @example
+      #   @client.all(size: 100, page: 0)
       def all(product_id, variation_id, _params = {})
         get("products/#{product_id}/variations/#{variation_id}/images")
       end