e_plat 0.5.5 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 85b0fb58fb552bdd494649429de66feb12612b53ee0cf49bda4b1a87e14e81b7
-  data.tar.gz: e5702192f1057e1f65736e20c88d7c35a4d6490db785d0dc4ef95381015cc6b2
+  metadata.gz: d10eb52dda105627cb32fb58161da4777a8a020f6ea70ba4111da4487441e743
+  data.tar.gz: 00ef52bdc6790981c6fcfb35615982c06b82152279d9a5f301ff3c84ad50747b
 SHA512:
-  metadata.gz: ac493807a5ffc4e61a7eb7d5fa4b28777697a9aa5c50a8cb145e8d1327bef821f8efcdacc672e6652778fb3b3c5c5961d76d5844d4a874a2f2bdacdf3b7896e8
-  data.tar.gz: c69b4fb8c31be9eecaaf6e587bbdd964a4a7ff046a844f0e3c81063d95a156fffe5667d9273a40e3e25fed5460e780bf02b2a5f29b7eb215d55c7806b15d718d
+  metadata.gz: f5951156f87b275af28cefeed42eff062aeb85155454a8b498c54d795843be40acd5245d1f20b5e724912abef7ef43b0dc47c4e09f2084ad1ad1fbab8418aafa
+  data.tar.gz: 0af92dd3962135ec69c738eab60bc320e8add2de57832cc793ed11ab5118e1515a7a048623f75537e3c126ae1e78e9c109cab49685335d7a9860da655d611bdc

data/README.md

@@ -3,7 +3,7 @@
 <strong>EPlat <small>(E-commerce Platform)</small> </br></strong>
 A single interface for interacting with E-commerce platform APIs.
 
-Goals are:
+Goals:
 <ul>
 	<li> 
 		Make it easy to use and request API resources from different platforms.
@@ -12,7 +12,7 @@ Goals are:
 		Offer a universal alias interface for interacting with common natured attributes. e.g. Shopify's product.body_html and BigCommerce's product.description.
 	</li>
 	<li>
-		Have a simple, easy-to-understand, lightweight project structure. 
+		Have a simple, easy-to-understand project structure. 
 	</li>
 	<li>
 		The e_plat alias interface mimics Shopify's API schema names and types.
@@ -43,15 +43,37 @@ You can configure which platform APIs are used by updating the EPlat config: <br
 #initializers/e_plat.rb
 EPlat.config.shopify_api_version = "2024-01"
 EPlat.config.bigcommerce_api_version = "v3"
-EPlat.config.woocommerce_api_version = "v3"
 
 # EPlat.api_display_name.shopify #=> "2024-01" # presents as the platform would display in URL paths
 # EPlat.config.shopify_api_version #=> "2024_01" # coerced interally for creating constants
+# EPlat.config.print_graphql_requests #=> false # prints out Shopify graphql queries/mutations to the console
 ```
 <br>
 
-## Relasing new version
+## Testing
+
+To run the test for the default versions of all supported platforms:
+```
+  bundle exec rails test
+```
+
+To run with specific api versions, you can set globals inline
+```
+  EPLAT_SHOPIFY_API_VERSION=2024_07 EPLAT_BIGCOMMERCE_API_VERSION=v3 rails test
+```
+
+To print out Shopify GraphQL queries/mutations
+```
+EPLAT_PRINT_GRAPHQL_REQUESTS=true rails test
+```
+
+<br>
+
+## Releasing a new version
 https://dev.to/doctolib/release-a-new-gem-version-je0
+
+<br>
+
 <br>
 
 ## Usage
@@ -62,7 +84,7 @@ EPlat::Session.new(
   platform: :shopify, 
   store_url: "test-store.myshopify.com", 
   api_token:  "123",
-  # store_hash: optional BigCommerce store hash
+  # store_hash: "optional BigCommerce store hash"
 )
 ```
 
@@ -71,7 +93,7 @@ EPlat::Session.new(
 EPlat::Product.find(id: 123)
 ```
 
-3. Which will return an instance of:
+3. Which will return a platform resource instance that inherits from:
 ```ruby
 EPlat::Product
 ```
@@ -212,10 +234,8 @@ EPlat is designed to let you mostly use it's universal interface, but then easil
  | options                  | array    | *       | *            | nil         |
  | product_type             | string   | *       | type         | nil         |
  | published_at             | datetime | *       | nil          | nil         |
- | published_scope          | string   | *       | nil          | nil         |
  | status                   | string   | *       | availability | nil         |
  | tags                     | string   | *       | nil          | nil         |
- | admin_graphql_api_id     | string   | *       | nil          | nil         |
  | template_suffix          | string   | *       | nil          | nil         |
  | title                    | string   | *       | name         | nil         |
  | updated_at               | datetime | *       | date_modified| nil         |
@@ -225,68 +245,62 @@ EPlat is designed to let you mostly use it's universal interface, but then easil
 
 ### EPlat::Product::Variant
 
- 
- | Alias                  | Type     | Shopify | BigCommerce           | Etc |
- | --------------------- | -------- | ------- | ----------------------| ------------|
- | id                    | integer  | *       | id                    | nil         |
- | product_id            | integer  | *       | product_id            | nil         |
- | title                 | string   | *       | option_values&.map(&:label)&.join(' ') | nil         |
- | price                 | string   | *       | price                 | nil         |
- | sku                   | string   | *       | sku                   | nil         |
- | position              | integer  | *       | nil                   | nil         |
- | inventory_policy      | string   | *       | nil                   | nil         |
- | compare_at_price      | string   | *       | nil                   | nil         |
- | fulfillment_service   | string   | *       | nil                   | nil         |
- | inventory_management  | string   | *       | nil                   | nil         |
- | option1               | string   | *       | option_values[0].label| nil         |
- | option2               | string   | *       | nil                   | nil         |
- | option3               | string   | *       | nil                   | nil         |
- | created_at            | datetime | *       | nil                   | nil         |
- | updated_at            | datetime | *       | nil                   | nil         |
- | taxable               | boolean  | *       | nil                   | nil         |
- | barcode               | string   | *       | nil                   | nil         |
- | grams                 | integer  | *       | nil                   | nil         |
- | image_id              | integer  | *       | nil                   | nil         |
- | weight                | float    | *       | weight                | nil         |
- | weight_unit           | string   | *       | nil                   | nil         |
- | inventory_item_id     | integer  | *       | nil                   | nil         |
- | inventory_quantity    | integer  | *       | inventory_level       | nil         |
- | old_inventory_quantity| integer  | *       | nil                   | nil         |
- | presentment_prices    | array    | *       | nil                   | nil         |
- | tax_code              | string   | *       | nil                   | nil         |
- | requires_shipping     | boolean  | *       | nil                   | nil         |
- | admin_graphql_api_id  | string   | *       | nil                   | nil         |
- 
+
+| Alias                 | Type     | Shopify | BigCommerce                          | Etc |
+|-----------------------|----------|---------|--------------------------------------|-----|
+| id                    | integer  | *       | id                                   | nil |
+| title                 | string   | *       | option_values&.map(&:label)&.join(' ') | nil |
+| price                 | string   | *       | price                                | nil |
+| sku                   | string   | *       | sku                                  | nil |
+| position              | integer  | *       | nil                                  | nil |
+| inventory_policy      | string   | *       | nil                                  | nil |
+| compare_at_price      | string   | *       | nil                                  | nil |
+| inventory_management  | boolean  | inventoryItem[tracked] | nil                        | nil |
+| created_at            | datetime | *       | nil                                  | nil |
+| updated_at            | datetime | *       | nil                                  | nil |
+| taxable               | boolean  | *       | nil                                  | nil |
+| barcode               | string   | *       | nil                                  | nil |
+| grams                 | integer  | getter only: converted node.inventoryItem[measurement][weight][value] | nil                                  | nil |
+| weight                | float    | getter only: node.inventoryItem[measurement][weight][value]      | weight |
+| weight_unit           | string   | getter only: node.inventoryItem[measurement][weight][unit]       | nil  |
+| inventory_item_id     | integer  | getter only: node.inventoryItem[id]| nil                            | nil |
+| inventory_quantity    | integer  | getter only: node.inventoryQuantity     | inventory_level                      | nil |
+| tax_code              | string   | *       | nil                                  | nil |
+| requires_shipping     | boolean  | InventoryItem[requiresShipping] | nil              | nil |
  *Bigcommerce variant.title= setter is not supported
  
  
  ### EPlat::Product::Option
  
- | Alias      | Type     | Shopify | BigCommerce| Etc |
- | --------- | -------- | ------- | -----------| ------------|
- | id        | integer  | *       | nil        | nil         |
- | product_id| integer  | *       | nil        | nil         |
- | name      | string   | *       | nil        | nil         |
- | position  | integer  | *       | nil        | nil         |
- | values    | array    | *       | nil        | nil         |
- 
+ | Alias      | Type     | Shopify | BigCommerce                  | Etc |
+ | ---------- | -------- | ------- | ---------------------------- | --- |
+ | id         | integer  | *       | id                           | nil |
+ | name       | string   | *       | display_name                 | nil |
+ | position   | integer  | *       | sort_order                   | nil |
+ | values     | array    | *       | option_values[i][label]      | nil |
+
 
   ### EPlat::Product::Image
  
  | Alias            | Type     | Shopify | BigCommerce | Etc |
  | -------------------- | -------- | ------- | -----------  | ------------|
  | id                   | integer  | *       | id           | nil         |
- | product_id           | integer  | *       | product_id   | nil         |
  | position             | integer  | *       | nil          | nil         |
- | created_at           | datetime | *       | date_created | nil         |
- | updated_at           | datetime | *       | date_modified| nil         |
  | alt                  | string   | *       | nil          | nil         |
  | width                | integer  | *       | nil          | nil         |
  | height               | integer  | *       | nil          | nil         |
  | src                  | string   | *       | url_standard | nil         |
  | variant_ids          | array    | *       | nil          | nil         |
- | admin_graphql_api_id | string   | *       | nil          | nil         |
 
+
+ ### EPlat::Product::Variant::OptionValue 
+ (not supported for Shopify API v2024_01)
+
+ | Alias                | Type     | Shopify                                    | BigCommerce        | Etc |
+ | -------------------- | -------- | ------------------------------------------ | ------------------ | --- |
+ | id                   | integer  | [selected_options][option_value][id]       | id                 | nil |
+ | name                 | string   | [selected_options][name]                   | option_display_name| nil |
+ | value                | string   | [selected_options][value]                  | label              | nil |
 </details>
 
 <details>
@@ -412,6 +426,26 @@ EPlat is designed to let you mostly use it's universal interface, but then easil
 | longitude     | float   | *       | nil         | nil         |
 
 
+### EPlat::Order::BillingAddress
+
+| Alias         | Type    | Shopify | BigCommerce | Etc |
+|---------------|---------|---------|-------------|-------------|
+| address1      | string  | *       | street_1    | nil         |
+| address2      | string  | *       | street_2    | nil         |
+| city          | string  | *       | city        | nil         |
+| company       | string  | *       | company     | nil         |
+| country       | string  | *       | country     | nil         |
+| first_name    | string  | *       | first_name  | nil         |
+| last_name     | string  | *       | last_name   | nil         |
+| phone         | string  | *       | phone       | nil         |
+| province      | string  | *       | state       | nil         |
+| zip           | string  | *       | zip         | nil         |
+| country_code  | string  | *       | country_iso2| nil         |
+| province_code | string  | *       | nil         | nil         |
+| latitude      | float   | *       | nil         | nil         |
+| longitude     | float   | *       | nil         | nil         |
+
+
 ### EPlat::Order::LineItem
 
 | Attribute                     | Type    | Shopify | BigCommerce | Etc  |
@@ -565,11 +599,12 @@ Unfortunately it's in a Time Integer format. Haven't yet got dynamic conversion
  | ::Product.find_by(attr: '')   |  *                | *                 |        |
  | ::Product.create(attr:)       |  *                | *                 |        |
  | ::Product.save                |  *                | *                 |        |
- | .save saves nested resources  |  *                |                   |        |
+ | .save saves nested resources  |  only variants    |                   |        |
  | ::Product.delete(id)          |  *                | *                 |        |
  | ::Product.count               |  *                | *                 |        |
  | product.dup                   |  *                | *                 |        |
  | product.variants              |  *                | *                 |        |
+ | product.load_all_variants     |  *                | *                 |        |
  | product.find_variant(id)      |  *                | *                 |        |
  | product.images                |  *                | *                 |        |
  | products.next_page?           |  *                | *                 |        |
@@ -580,11 +615,23 @@ Unfortunately it's in a Time Integer format. Haven't yet got dynamic conversion
  | products.next_page_info       |  *                | *                 |        |
 
  ```ruby
-  #  How you might safely handle pagination via user input
-  # <%= link_to "previous products", "/", page_info: products.previous_page_info %>
-  # <%= link_to "Next products",     "/", page_info: products.next_page_info %>
-
-  EPlat::Product.find(:all, params: {limit: 2, EPlat::Current.e_plat_session.pagination_param => params['page_info'] })
+  # The 2024 increased Shopify variants limit
+  @product.load_all_variants #returns all variants. In Shopify's case it will keep on requesting in batches until it has the full amount (capped at 10x requests of 200 currently i.e. 2,000 variants)
+
+  ### Pagination
+  # ...How you might handle pagination.
+
+  # Add pagination cursors to your link's params. This is available on any EPlat::Collection instance
+  <%= link_to "previous products", "/", forward_page_info:  products.previous_page_info %>
+  <%= link_to "Next products",     "/", backward_page_info: products.next_page_info %>
+
+  # Then on the server, let EPlat handle the correct platform specific arguments to request with.
+  EPlat::Product.find(:all, params: {
+    EPlat::Current.e_plat_session.pagination_param(:forward) => params['forward_page_info'] 
+  })
+  EPlat::Product.find(:all, params: {
+    EPlat::Current.e_plat_session.pagination_param(:backward) => params['backward_page_info'] 
+  })
 ```
  
 
@@ -749,7 +796,7 @@ Unfortunately it's in a Time Integer format. Haven't yet got dynamic conversion
       (although should be kept track of locally)
     </li>
     <li>
-      <strong>GraphQL</strong>. EPlat just handles REST
+      <strong>GraphQL</strong>. EPlat just handles REST (for now, although we plan to change the internals for Shopify product to use Graphql under the hood)
   <ul>
 </details>
 
@@ -786,12 +833,14 @@ EPlat::Product.find(my_id).destroy
 
 ### save record
 product = EPlat::Product.new(title: 't-shirt')
-product.save
+product.save # true or false
+product.errors # active record like errors if .save returned false
 
 product.full_response # <Net::HTTPOK>
 product.headers # { "date"=>"Fri, 17 Nov 2023 14:25:53 GMT", ...}
 JSON.parse(product.full_response.body) # "{...}"
 
+
 ### get records
 EPlat::Product.find(101) # GET EPlat::Product.first(args)) (or EPlat::Product.last(args))
 EPlat::Product.all 

data/lib/e_plat/client/default_request_args.rb

@@ -10,7 +10,7 @@ module EPlat
 					{}
 				when :bigcommerce
 					{
-						"include" => "variants,images"
+						"include" => "variants,images,options"
 					}
 				when :woocommerce
 					{}

data/lib/e_plat/client.rb

@@ -4,18 +4,34 @@ module EPlat
 	class Client 
 		include Client::PlatformConvenienceMethods, Client::DefaultRequestArgs
 
-		SHOPIFY_PAGINATION_PARAM 	 = "page_info"
-		BIGCOMMERCE_PAGINATION_PARAM = "page"
+		SHOPIFY_REST_PAGINATION_PARAM 	 		  = "page_info"
+		SHOPIFY_GRAPHQL_FORWARD_PAGINATION_PARAM  = "after"
+		SHOPIFY_GRAPHQL_BACKWARD_PAGINATION_PARAM = "before"
+		BIGCOMMERCE_PAGINATION_PARAM  	 	 	  = "page"
 		
 		attr_reader :platform, :store_url, :api_token, :api_version, :store_hash
 
-		def initialize(platform: nil, store_url: nil, api_token: nil, store_hash: nil)      
-			@platform, @store_url, @api_token, @store_hash = platform&.to_sym, store_url, api_token, store_hash
+		def initialize(platform: nil, store_url: nil, api_token: nil, store_hash: nil, api_version: nil)      
+			@platform, @store_url, @api_token, @store_hash, @api_version = platform&.to_sym, store_url, api_token, store_hash, api_version
 		end
 
 		def headers
 			platform_headers
 		end
+
+		# Dynamically determines the class based on the platform
+		# needs to return nil if there isn't a more specific class than the klass passed in
+		def platform_klass(klass)
+			return if klass.to_s.include? "EPlat::#{platform.capitalize}"
+			platform_specific_class_name = klass.to_s.gsub("EPlat::", "EPlat::#{platform.capitalize}::")
+
+			platform_specific_class = platform_specific_class_name.safe_constantize
+			if platform_specific_class_name != klass.to_s && platform_specific_class
+				platform_specific_class
+			else
+				nil
+			end
+		end
 		
 		def inspect
 			"#<#{self.class} platform=#{platform.inspect} store_url=#{store_url.inspect} api_version=#{api_version.inspect}>"
@@ -42,8 +58,14 @@ module EPlat
 		
 		def url_prefix(klass: nil)
 			# for nested resources like "/products/:product/variants/:id"
+			klass_without_platform_scoping = nil
+			EPlat::SUPPORTED_PLATFORMS.each do |platform|
+				klass_without_platform_scoping = klass.to_s.gsub!("#{ platform.capitalize }::", "") if klass.to_s.include?("#{ platform.capitalize }::")
+			end
+			klass = klass_without_platform_scoping&.safe_constantize || klass
+
 			collection_path = 
-				if klass.to_s.scan("::").length == 2
+				if klass.to_s.scan("::").length > 1
 					parent_klass = klass.to_s.split("::")[1].underscore
 					"#{ parent_klass.pluralize }/:#{ parent_klass }/"
 				else
@@ -63,6 +85,19 @@ module EPlat
 				"/" # not yet supported
 			end
 		end
+
+		def graphql_request_url
+			case platform
+			when :shopify
+				"https://#{ store_url }/admin/api/#{ api_version.dasherize }/graphql.json"
+			else
+				raise EPlat::Error, "GraphQL is not supported for #{ platform }"
+			end
+		end
+
+		def uses_graphql_for_products?
+			platform == :shopify && api_version != "2024_01"
+		end
 	
 		def platform_headers
 			case platform
@@ -87,6 +122,8 @@ module EPlat
 		end
 		
 		def api_version
+			return @api_version if @api_version.present?
+			
 			case platform
 			when :shopify
 				EPlat.config.shopify_api_version
@@ -97,6 +134,10 @@ module EPlat
 			end
 		end
 
+		def shopify_graphql_version
+			"V202407"
+		end
+
 		def can_update_nested_resources?
 				case platform
 				when :shopify     then true
@@ -105,11 +146,16 @@ module EPlat
 				end
 		end
 
-		def pagination_param
+		def pagination_param(direction=:forward)
 			case platform
-			when :shopify     then SHOPIFY_PAGINATION_PARAM
-			when :bigcommerce then BIGCOMMERCE_PAGINATION_PARAM
-			when :woocommerce then nil
+			when :shopify
+				if uses_graphql_for_products? 
+					direction == :backward ? SHOPIFY_GRAPHQL_BACKWARD_PAGINATION_PARAM : SHOPIFY_GRAPHQL_FORWARD_PAGINATION_PARAM
+				else 
+					SHOPIFY_REST_PAGINATION_PARAM
+				end
+			when :bigcommerce 
+				BIGCOMMERCE_PAGINATION_PARAM
 			end
 		end
 

data/lib/e_plat/initializer.rb

@@ -0,0 +1,26 @@
+module EPlat
+	class Initializer
+		class << self
+			
+			REQUIRED_CLASSES = EPlat::SUPPORTED_RESOURCES.map do |resource|
+				[
+					"EPlat::#{ resource.classify }",
+					EPlat::SUPPORTED_PLATFORMS.map do |platform|
+						"EPlat::#{ platform.classify }::#{ resource.classify }"
+					end
+				]
+			end.flatten.freeze
+
+			def check_required_classes!
+				REQUIRED_CLASSES.each do |klass|
+					unless Object.const_defined?(klass)
+						raise EPlat::Error, "Required class #{klass} not defined"
+					end
+				end
+			end
+
+		end
+	end
+end
+
+	  

data/lib/e_plat/mapping/bigcommerce/v_3/product/option.rb

@@ -0,0 +1,58 @@
+
+
+module EPlat
+	class Mapping
+		module Bigcommerce
+			module V3
+				class Product
+					class Option < EPlat::Mapping::Base
+
+						def native_top_key
+							"data"
+						end
+						
+						def native_attributes
+							super.concat([
+								"id",
+								"product_id",
+								"display_name",
+								"type",
+								"config",
+								"sort_order",
+								"option_values",
+								"modifiers",
+								"option_set_id",
+								"option_set_display",
+								"variants"
+							])
+						end
+						
+						def native_attribute_aliases
+							super.concat([
+								{
+									existing_entry: {native_key:   "id", 	e_plat_key: "id"}
+								},
+								{
+									alias_attribute: {native_key:   "display_name", e_plat_key: "name"}
+								},
+								{
+									alias_attribute: {native_key:   "sort_order", e_plat_key: "position"}
+								},
+								{
+									alias_attribute: {native_key: "option_values", e_plat_key: "values",
+										custom_e_plat_getter: '-> (option_values) {
+											option_values.map{|val| val.label}
+										}',
+										custom_native_setter: '-> (option) { raise EPlat::Error.new "EPlat does not yet support native setting back to .option_values[i][:label]" }'
+									}
+								}
+
+							])
+						end
+						
+					end
+				end
+			end
+		end
+	end
+end

data/lib/e_plat/mapping/bigcommerce/v_3/product/variant/option_value.rb

@@ -0,0 +1,42 @@
+
+
+module EPlat
+	class Mapping
+		module Bigcommerce
+			module V3
+				class Product::Variant
+					class OptionValue < EPlat::Mapping::Base
+
+						def native_top_key
+							"data"
+						end
+						
+						def native_attributes
+							super.concat([
+								"id",
+								"label",
+								"option_id",
+								"option_display_name"
+							])
+						end
+						
+						def native_attribute_aliases
+							super.concat([
+								{
+									existing_entry: {native_key: "id", e_plat_key: "id"}
+								},
+								{
+									alias_attribute: {native_key: "option_display_name", e_plat_key: "name"}
+								},
+								{
+									alias_attribute: {native_key: "label", e_plat_key: "value"}
+								}
+							])
+						end
+						
+					end
+				end
+			end
+		end
+	end
+end

data/lib/e_plat/mapping/shopify/v_2024_07/metafield.rb

@@ -0,0 +1,26 @@
+module EPlat
+	class Mapping
+		module Shopify
+			module V202407 #< :module
+				class Metafield < EPlat::Mapping::Base
+					
+					def native_top_key
+						"metafield"
+					end
+					
+					def native_attributes
+						super.concat([
+						])
+					end
+					
+					def native_attribute_aliases
+						super.concat([
+						])
+					end
+						
+				end
+			end
+		end
+	end
+end
+	

data/lib/e_plat/mapping/shopify/v_2024_07/order/billing_address.rb

@@ -0,0 +1,14 @@
+
+
+module EPlat
+	class Mapping
+		module Shopify
+			module V202407
+				class Order
+					class BillingAddress < ShippingAddress; end
+				end
+			end
+		end
+	end
+end
+

data/lib/e_plat/mapping/shopify/v_2024_07/order/shipping_address.rb

@@ -0,0 +1,30 @@
+
+
+module EPlat
+	class Mapping
+		module Shopify
+			module V202407
+				class Order
+					class ShippingAddress < EPlat::Mapping::Base
+												
+						def native_top_key
+							:itself
+						end
+						
+						def native_attributes
+							super.concat([
+							])
+						end
+						
+						def native_attribute_aliases
+							super.concat([
+							])
+						end
+						
+					end
+				end
+			end
+		end
+	end
+end
+

data/lib/e_plat/mapping/shopify/v_2024_07/order.rb

@@ -0,0 +1,26 @@
+module EPlat
+		class Mapping
+			module Shopify
+				module V202407 #< :module
+					class Order < EPlat::Mapping::Base
+						
+						def native_top_key
+							"order"
+						end
+						
+						def native_attributes
+							super.concat([
+							])
+						end
+						
+						def native_attribute_aliases
+							super.concat([
+							])
+						end
+							
+					end
+				end
+			end
+		end
+end
+