e_plat 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e9dbde4e59673eba0dc91580fd4f4f50bc138c380cfa00a78a2be1de12f1706c
-  data.tar.gz: 9998fa572e61d5e043fdbe2ec804c18cde16c65f2bb64534003a5f00e0034d38
+  metadata.gz: d10eb52dda105627cb32fb58161da4777a8a020f6ea70ba4111da4487441e743
+  data.tar.gz: 00ef52bdc6790981c6fcfb35615982c06b82152279d9a5f301ff3c84ad50747b
 SHA512:
-  metadata.gz: d855f8148b8df76db6202da298128a8e3c9f8ba1b1adebd7824182e80676ff6f242c59f3aa54cc791b6567f04e1741fefe7a643fe2c7e8523c93d0fb7cbc0236
-  data.tar.gz: 8c478644bf379156b98e80992edbec4a24baa95e854a8d9864abc92c0e8c73ea4e4d4d9980c3957926eb70164e3f547fbfaffd88373fbc3bc1859dd7e8c80101
+  metadata.gz: f5951156f87b275af28cefeed42eff062aeb85155454a8b498c54d795843be40acd5245d1f20b5e724912abef7ef43b0dc47c4e09f2084ad1ad1fbab8418aafa
+  data.tar.gz: 0af92dd3962135ec69c738eab60bc320e8add2de57832cc793ed11ab5118e1515a7a048623f75537e3c126ae1e78e9c109cab49685335d7a9860da655d611bdc

data/README.md

@@ -46,11 +46,34 @@ EPlat.config.bigcommerce_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
@@ -211,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         |
@@ -224,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>
@@ -584,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?           |  *                | *                 |        |
@@ -599,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'] 
+  })
 ```
  
 
@@ -805,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,13 +4,15 @@ 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
@@ -83,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
@@ -107,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
@@ -117,6 +134,10 @@ module EPlat
 			end
 		end
 
+		def shopify_graphql_version
+			"V202407"
+		end
+
 		def can_update_nested_resources?
 				case platform
 				when :shopify     then true
@@ -125,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/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
+	

data/lib/e_plat/mapping/shopify/v_2024_07/product/image.rb

@@ -0,0 +1,52 @@
+
+
+module EPlat
+	class Mapping
+		module Shopify
+			module V202407
+				class Product
+					class Image < EPlat::Mapping::Base
+												
+						def native_top_key
+							:itself
+						end
+						
+						def native_attributes
+							super.concat([
+								"id",
+								"alt_text", #would be altText before and after EPlat processes it
+								"width",
+								"height",
+								"url"
+							])
+						end
+						
+						def native_attribute_aliases
+							super.concat([
+								{
+									existing_entry: {native_key: "id", e_plat_key: "id",
+										custom_e_plat_getter: '-> { _1.try(:split, "/")&.last || _1 }',
+										custom_native_setter: '-> { "gid://shopify/ProductImage/#{_1}" }'
+									}
+								},
+								{
+									alias_attribute: {native_key: "alt_text", e_plat_key: "alt"}
+								},
+								{
+									existing_entry: {native_key: "width", e_plat_key: "width"}
+								},
+								{
+									existing_entry: {native_key: "height", e_plat_key: "height"}
+								},
+								{
+									alias_attribute: {native_key: "url", e_plat_key: "src"}
+								}
+							])
+						end
+						
+					end						
+				end
+			end
+		end
+	end
+end

data/lib/e_plat/mapping/shopify/v_2024_07/product/option.rb

@@ -0,0 +1,45 @@
+
+
+module EPlat
+	class Mapping
+		module Shopify
+			module V202407
+				class Product
+					class Option < EPlat::Mapping::Base
+						include_root_in_request_body true
+												
+						def native_top_key
+							:itself
+						end
+						
+						def native_attributes
+							super
+						end
+
+						def native_attribute_aliases
+							super.concat([
+								
+								{
+									existing_entry: {native_key: "id", e_plat_key: "id",
+										custom_e_plat_getter: '-> { _1&.split("/")&.last }',
+										custom_native_setter: '-> { "gid://shopify/ProductOption/#{_1}" }'
+									}
+								},
+								{
+									existing_entry: {native_key: "name", e_plat_key: "name"}
+								},
+								{
+									existing_entry: {native_key: "position", e_plat_key: "position"}
+								},
+								{
+									existing_entry: {native_key: "values", e_plat_key: "values"}
+								}
+							])
+						end
+						
+					end
+				end
+			end
+		end
+	end
+end

data/lib/e_plat/mapping/shopify/v_2024_07/product/variant/option_value.rb

@@ -0,0 +1,58 @@
+
+
+module EPlat
+	class Mapping
+		module Shopify
+			module V202407
+				class Product::Variant
+					class OptionValue < EPlat::Mapping::Base
+						include_root_in_request_body true
+												
+						def native_top_key
+							:itself
+						end
+						
+						def native_attributes
+							super.concat([
+							])
+						end
+
+
+						def native_attribute_aliases
+							super.concat([
+								# see virtual_collection @ EPlat::Mapping::VirtualCollection::Shopify::Product::Variant::OptionValue
+							])
+						end
+						
+					end
+				end
+			end
+		end
+	end
+end
+
+
+# bigcommerce
+#  option_values => [{
+# 	"id": 174,
+# 	"label": "Beige",
+# 	"option_id": 220,
+# 	"option_display_name": "Color"
+#   }]
+
+# shopify
+#  selected_options => [{
+	# "name"=>"Size",
+	# "value"=>"green",
+	# "option_value" => {
+	# 	"id"=>"gid://shopify/ProductOptionValue/657155129475", 
+	# 	"name"=>"green"
+	# }
+#  }]
+
+# target e_plat schema
+# option_values => [{
+# 	"id": 174,
+# 	"name": "Color",
+# 	"value": "Beige",
+# }]