e_plat 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: afc8b814dc437fb360828f3452ce591e91450961c21d38d3d96e423ebbd6a85a
+  data.tar.gz: 7b851774151f4e8c00ac4cb3df57be9460fb77d70f54fc5d506686aaa18034c7
+SHA512:
+  metadata.gz: fd34b9a17e29ed2171428f889ee9ec88d8224b50438083b745d15ebf71f2311578a874e1aef051bd7cb2e5c6dca1ad6b929f77b8c161a29dd9642aa3794eb23b
+  data.tar.gz: a81bf741bef95ecf0b9296229ebea8bc0019a4416f1b718c88bdba14ac05848bfcc909398f4e05712527c249d5b67f6a13c1f011be8489a4808d2fe31eaa4a83

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2022 oliwoodsuk
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,339 @@
+# EPlat
+
+<strong>EPlat <small>(E-commerce Platform)</small> </br></strong>
+A single interface for interacting with E-commerce platform APIs.
+
+Goals are:
+<ul>
+	<li> 
+		Make it easy to use and request API resources from different platforms.
+	</li>
+	<li>
+		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. 
+	</li>
+	<li>
+		The e_plat alias interface mimics Shopify's API schema names and types.
+	</li>
+</ul>
+
+<p align="left">
+  <img src="mascot.png" width="350" title="hover text" alt="EPlat Platypus">
+</p>
+
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+	$ gem "e_plat"
+
+To your gemfile and then run
+
+	$ bundle
+
+
+## Config
+You can configure which platform APIs are used by updating the EPlat config: <br/>
+```ruby
+#initializers/e_plat.rb
+EPlat.config.shopify_api_version = "2022-10"
+EPlat.config.bigcommerce_api_version = "v3"
+EPlat.config.woocommerce_api_version = "v3"
+```
+
+## Relasing new version
+https://dev.to/doctolib/release-a-new-gem-version-je0
+
+
+## Usage
+
+1. Add `include EPlat::SessionState` to the top of your `ApplicationController` class.
+
+2. To make requests, first initialize a session like so:
+```ruby
+EPlat::Session.new(
+  platform: :shopify, 
+  store_url: "test-store.myshopify.com", 
+  api_token:  "123",
+  # store_hash: BigCommerce_specific
+)
+```
+
+3. You can then make requests to the platform via a singleton call on the class:
+```ruby
+EPlat::Product.find(id: 123)
+```
+
+4. Which will return an instance of:
+```ruby
+EPlat::Product
+```
+
+
+## Under The Hood
+
+<ol>
+	<li>
+		Request/Resources follow this format: <strong>EPlat::ResourceName</strong>. Requests are called on the class, which then return an instance.
+	</li>
+	<li>
+		EPlat resources will return their platform's native attributes, alongside a universal alias interface for viewing/editing via the EPlat schema. 
+	</li>
+		<ul>
+			<li>
+				EPlat aliases can always be safely called, but aren't always successfully mapped to underlying platform attributes.
+			</li>
+			<li>
+				Whilst the EPlat alias interface and methods often mean you can treat resources the same regardless of platform, you can also ignore this interface and interact with the platform native attributes like regular active resource/record object.
+			</li>
+			<li>
+				The EPlat alias interface is just a set of dynamically created getter/setter/predicate methods with types that control the native attributes of the resource.
+			</li>
+		</ul>
+</ol>
+
+
+
+
+## EPlat Alias Interface
+
+<details>
+  <summary>Shop</summary>
+
+  ### Mapped Aliases
+ 
+| Alas                            | Type      | Shopify | BigCommerce | WooCommerce |
+  | ------------------------------------ | --------- | ------- | -----------| ------------|
+  | id                                   | integer   | *       |  *         | nil         |
+  | name                                 | string    | *       |  *         | nil         |
+  | email                                | string    | *       |  *         | nil         |
+  | domain                               | string    | *       |  *         | nil         |
+  | province                             | string    | *       |  *         | nil         |
+  | country                              | string    | *       |  *         | nil         |
+  | address1                             | string    | *       | nil        | nil         |
+  | zip                                  | string    | *       | nil        | nil         |
+  | city                                 | string    | *       | nil        | nil         |
+  | source                               | string    | *       | nil        | nil         |
+  | phone                                | string    | *       | nil        | nil         |
+  | latitude                             | float     | *       | nil        | nil         |
+  | longitude                            | float     | *       | nil        | nil         |
+  | primary_locale                       | string    | *       | nil        | nil         |
+  | address2                             | string    | *       | nil        | nil         |
+  | created_at                           | datetime  | *       | nil        | nil         |
+  | updated_at                           | datetime  | *       | nil        | nil         |
+  | country_code                         | string    | *       |  *         | nil         |
+  | country_name                         | string    | *       | nil        | nil         |
+  | currency                             | string    | *       |  *         | nil         |
+  | customer_email                       | string    | *       | nil        | nil         |
+  | timezone                             | string    | *       | nil        | nil         |
+  | iana_timezone                        | string    | *       | nil        | nil         |
+  | shop_owner                           | string    | *       | nil        | nil         |
+  | money_format                         | string    | *       | nil        | nil         |
+  | money_with_currency_format           | string    | *       | nil        | nil         |
+  | weight_unit                          | string    | *       |  *         | nil         |
+  | province_code                        | string    | *       | nil        | nil         |
+  | taxes_included                       | boolean   | *       | nil        | nil         |
+  | auto_configure_tax_inclusivity       | boolean   | *       | nil        | nil         |
+  | tax_shipping                         | boolean   | *       | nil        | nil         |
+  | county_taxes                         | boolean   | *       | nil        | nil         |
+  | plan_display_name                    | string    | *       | nil        | nil         |
+  | plan_name                            | string    | *       |  *         | nil         |
+  | has_discounts                        | boolean   | *       | nil        | nil         |
+  | has_gift_cards                       | boolean   | *       | nil        | nil         |
+  | myshopify_domain                     | string    | *       | nil        | nil         |
+  | google_apps_domain                   | string    | *       | nil        | nil         |
+  | google_apps_login_enabled            | boolean   | *       | nil        | nil         |
+  | money_in_emails_format               | string    | *       | nil        | nil         |
+  | money_with_currency_in_emails_format| string    | *       | nil        | nil         |
+  | eligible_for_payments                | boolean   | *       | nil        | nil         |
+  | requires_extra_payments_agreement    | boolean   | *       | nil        | nil         |
+  | password_enabled                     | boolean   | *       | nil        | nil         |
+  | has_storefront                       | boolean   | *       | nil        | nil         |
+  | eligible_for_card_reader_giveaway    | boolean   | *       | nil        | nil         |
+  | finances                             | boolean   | *       | nil        | nil         |
+  | primary_location_id                  | integer   | *       | nil        | nil         |
+  | cookie_consent_level                 | string    | *       | nil        | nil         |
+  | visitor_tracking_consent_preference  | string    | *       | nil        | nil         |
+  | checkout_api_supported               | boolean   | *       | nil        | nil         |
+  | multi_location_enabled               | boolean   | *       | nil        | nil         |
+  | setup_required                       | boolean   | *       | nil        | nil         |
+  | pre_launch_enabled                   | boolean   | *       | nil        | nil         |
+  | enabled_presentment_currencies       | array     | *       | nil        | nil         |
+  | transactional_sms_disabled           | boolean   | *       | nil        | nil         |
+  | marketing_sms_consent_enabled_at_checkout | boolean | * | nil      | nil         |
+
+</details>
+</br>
+<details>
+  <summary>Product</summary>
+
+  ### Mapped Aliases
+  
+ | Alas                | Type     | Shopify | BigCommerce | WooCommerce |
+ | ------------------------| -------- | ------- | -----------| ------------|
+ | body_html                | string   | *       |  *         | nil         |
+ | created_at               | datetime | *       |  *         | nil         |
+ | handle                   | string   | *       |  *         | nil         |
+ | id                       | integer  | *       |  *         | nil         |
+ | images                   | array    | *       |  *         | nil         |
+ | options                  | array    | *       |  []        | nil         |
+ | product_type             | string   | *       |  *         | nil         |
+ | published_at             | datetime | *       | nil        | nil         |
+ | published_scope          | string   | *       | nil        | nil         |
+ | status                   | string   | *       | nil        | nil         |
+ | tags                     | string   | *       | nil        | nil         |
+ | admin_graphql_api_id     | string   | *       | nil        | nil         |
+ | template_suffix          | string   | *       | nil        | nil         |
+ | title                    | string   | *       |  *         | nil         |
+ | updated_at               | datetime | *       |  *         | nil         |
+ | variants                 | array    | *       |  *         | nil         |
+ | vendor                   | string   | *       | nil        | nil         |
+ 
+</details>
+</br>
+<details>
+  <summary>Product Variant</summary>
+
+  ### Mapped Aliases
+ 
+ | Alas             | Type     | Shopify | BigCommerce | WooCommerce |
+ | --------------------- | -------- | ------- | -----------| ------------|
+ | id                    | integer  | *       |  *         | nil         |
+ | product_id            | integer  | *       |  *         | nil         |
+ | title                 | string   | *       | nil        | nil         |
+ | price                 | string   | *       |  *         | nil         |
+ | sku                   | string   | *       |  *         | 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   | *       |  *         | nil         |
+ | option2               | string   | *       | nil        | nil         |
+ | option3               | string   | *       | nil        | nil         |
+ | created_at            | datetime | *       |  *         | nil         |
+ | updated_at            | datetime | *       |  *         | nil         |
+ | taxable               | boolean  | *       | nil        | nil         |
+ | barcode               | string   | *       | nil        | nil         |
+ | grams                 | integer  | *       | nil        | nil         |
+ | image_id              | integer  | *       | nil        | nil         |
+ | weight                | float    | *       |  *         | nil         |
+ | weight_unit           | string   | *       | nil        | nil         |
+ | inventory_item_id     | integer  | *       | nil        | nil         |
+ | inventory_quantity    | integer  | *       |  *         | 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         |
+ 
+</details>
+</br>
+<details>
+  <summary>Product Option</summary>
+
+  ### Mapped Aliases
+ 
+ | Alas | Type     | Shopify | BigCommerce | WooCommerce |
+ | --------- | -------- | ------- | -----------| ------------|
+ | id        | integer  | *       | nil        | nil         |
+ | product_id| integer  | *       | nil        | nil         |
+ | name      | string   | *       | nil        | nil         |
+ | position  | integer  | *       | nil        | nil         |
+ | values    | array    | *       | nil        | nil         |
+ 
+</details>
+</br>
+<details>
+  <summary>Product Image</summary>
+
+  ### Mapped Aliases
+ 
+ | Alas            | Type     | Shopify | BigCommerce | WooCommerce |
+ | -------------------- | -------- | ------- | -----------| ------------|
+ | id                   | integer  | *       |  *         | nil         |
+ | product_id           | integer  | *       |  *         | nil         |
+ | position             | integer  | *       | nil        | nil         |
+ | created_at           | datetime | *       |  *         | nil         |
+ | updated_at           | datetime | *       |  *         | nil         |
+ | alt                  | string   | *       | nil        | nil         |
+ | width                | integer  | *       | nil        | nil         |
+ | height               | integer  | *       | nil        | nil         |
+ | src                  | string   | *       |  *         | nil         |
+ | variant_ids          | array    | *       | nil        | nil         |
+ | admin_graphql_api_id | string   | *       | nil        | nil         |
+ 
+</details>
+
+<br>
+
+## Todos
+
+<ul>
+	<li>
+		Get BigCommerce request of shop working
+	</li>
+  <li>
+    find_by and where don't seem to work for big commerce 
+  </li>
+</ul>
+
+
+## Request Syntax
+
+```ruby
+### create new record
+product = EPlat::Product.new(:title => 't-shirt')
+product.save
+# or... 
+EPlat::Product.create(:title => 't-shirt')
+new_product = product.dup #duplicates entry without saving
+
+### delete record
+EPlat::Product.delete(params[:id])
+# or... 
+EPlat::Product.find(my_id).destroy
+
+### save record
+product = EPlat::Product.new(:title => 't-shirt')
+product.save
+
+### get records
+EPlat::Product.find(1) # => GET /product/1.json  (or EPlat::Product.first(args)) (or EPlat::Product.last(args))
+EPlat::Product.find(:all) # => GET /people.json
+EPlat::Product.find(:all, :params => { :title => "tshirt" }) # => GET /product.json?title=tshirt
+EPlat::Product.find(:one, :from => :leader) # => GET /product/leader.json
+EPlat::Product.find(:one, :from => "/product/1/specific_url.json") # => GET /product/1/specific_url.json
+
+
+#### options
+#prefix_options for nested URLs 
+EPlat::Product::Variant.collection_path(:variant_id => 5) # => /products/5/variants.json
+#returns a EPlat::Product::Variant instance
+
+# query_options to add to params ?x=y
+EPlat::Product.find(:all, query_options: {test: "is it?"})
+```
+
+
+## Resource Syntax
+
+```ruby
+#get clients shop
+shop = EPlat::Shop.current
+
+#to return all native platform attributes
+EPlat::Product.new({}).attributes 
+
+#see all of the successfully mapped aliases for a resource
+EPlat::Product.new({}).mapped_attributes.entries
+
+#check if a platforms resource is mapped to a specific EPlat alias
+EPlat::Product.new({}).mapped? "body_html"
+
+```
+
+

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"

data/config/routes.rb

@@ -0,0 +1,2 @@
+Rails.application.routes.draw do
+end

data/lib/active_resource/schema.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module ActiveResource # :nodoc:
+  class Schema # :nodoc:
+	# attributes can be known to be one of these types. They are easy to
+	# cast to/from.
+	KNOWN_ATTRIBUTE_TYPES = %w( string text integer float decimal datetime timestamp time date binary boolean array hash )
+
+	# An array of attribute definitions, representing the attributes that
+	# have been defined.
+	attr_accessor :attrs
+
+	# The internals of an Active Resource Schema are very simple -
+	# unlike an Active Record TableDefinition (on which it is based).
+	# It provides a set of convenience methods for people to define their
+	# schema using the syntax:
+	#  schema do
+	#    string :foo
+	#    integer :bar
+	#  end
+	#
+	#  The schema stores the name and type of each attribute. That is then
+	#  read out by the schema method to populate the schema of the actual
+	#  resource.
+	def initialize
+	  @attrs = {}
+	end
+
+	def attribute(name, type, options = {})
+	  raise ArgumentError, "Unknown Attribute type: #{type.inspect} for key: #{name.inspect}" unless type.nil? || Schema::KNOWN_ATTRIBUTE_TYPES.include?(type.to_s)
+
+	  the_type = type.to_s
+	  # TODO: add defaults
+	  # the_attr = [type.to_s]
+	  # the_attr << options[:default] if options.has_key? :default
+	  @attrs[name.to_s] = the_type
+	  self
+	end
+
+	# The following are the attribute types supported by Active Resource
+	# migrations.
+	KNOWN_ATTRIBUTE_TYPES.each do |attr_type|
+	  # def string(*args)
+	  #   options = args.extract_options!
+	  #   attr_names = args
+	  #
+	  #   attr_names.each { |name| attribute(name, 'string', options) }
+	  # end
+	  class_eval <<-EOV, __FILE__, __LINE__ + 1
+		# frozen_string_literal: true
+		def #{attr_type}(*args)
+		  options = args.extract_options!
+		  attr_names = args
+		  attr_names.each { |name| attribute(name, '#{attr_type}', options) }
+		end
+	  EOV
+	end
+  end
+end

data/lib/e_plat/client/default_request_args.rb

@@ -0,0 +1,33 @@
+
+module EPlat
+	class Client
+		module DefaultRequestArgs
+			extend ActiveSupport::Concern
+			
+			def product_default_find_args
+				case platform
+				when :shopify
+					{}
+				when :bigcommerce
+					{
+						"include" => ["variants", "images"]
+					}
+				when :woocommerce
+					{}
+				end
+			end
+			
+			def order_default_find_args
+				case platform
+				when :shopify
+					{}
+				when :bigcommerce
+					{}
+				when :woocommerce
+					{}
+				end
+			end
+			
+		end
+	end
+end

data/lib/e_plat/client/platform_convenience_methods.rb

@@ -0,0 +1,21 @@
+
+module EPlat
+	class Client
+		module PlatformConvenienceMethods
+			extend ActiveSupport::Concern
+			
+			def shopify?
+				platform == :shopify
+			end
+			
+			def bigcommerce?
+				platform == :bigcommerce
+			end
+			
+			def woocommerce?
+				platform == :woocommerce
+			end
+
+		end
+	end
+end

data/lib/e_plat/client.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module EPlat
+  class Client 
+    include Client::PlatformConvenienceMethods, Client::DefaultRequestArgs
+    
+    attr_accessor :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
+      get_api_version
+    end
+
+    def headers
+      platform_headers
+    end
+    
+    def inspect
+      "#<#{self.class} platform=#{platform.inspect} store_url=#{store_url.inspect} api_version=#{api_version.inspect}>"
+    end
+    
+    def inactive?
+      !valid?
+    end
+    
+    def active?
+      valid?
+    end
+
+    def valid?
+      platform.present? && store_url.present? && api_token.present? 
+    end
+    
+    def clear!
+      self.platform = nil
+    end
+    
+    def base_url 
+      case platform
+      when :shopify
+        "https://#{ store_url }"
+      when :bigcommerce
+        "https://api.bigcommerce.com"
+      when :woocommerce
+        "/"
+      end
+    end
+    
+    def url_prefix
+      case platform
+      when :shopify
+        "/admin/api/#{ api_version.dasherize }/"
+      when :bigcommerce
+        "/stores/#{ store_hash }/v#{ api_version }/catalog/"
+      when :woocommerce
+        "/"
+      end
+    end
+  
+    def platform_headers
+      case platform
+      when :shopify
+        {
+          "Content-Type" => "application/json",
+          "X-Shopify-Access-Token" => api_token
+        }
+      when :bigcommerce
+        {
+          "Content-Type" => "application/json",
+          "X-Auth-Token" => api_token,
+          "host" => "api.bigcommerce.com"
+        }
+      when :woocommerce
+        {
+          "Content-Type" => "application/json",
+          "Authorization" => "Bearer #{ api_token }"
+        }
+      end
+    end
+    
+    def get_api_version
+      self.api_version = 
+        case platform
+        when :shopify
+          EPlat.config.shopify_api_version
+        when :bigcommerce
+          EPlat.config.bigcommerce_api_version
+        when :woocommerce
+          EPlat.config.woocommerce_api_version
+        end
+    end
+
+      
+  end
+end

data/lib/e_plat/engine.rb

@@ -0,0 +1,4 @@
+module EPlat
+  class Engine < ::Rails::Engine
+  end
+end

data/lib/e_plat/errors/incorrect_type_error.rb

@@ -0,0 +1,8 @@
+
+module EPlat
+	class IncorrectTypeError < StandardError
+		def initialize(msg="Impossible to create type from argument")
+			super
+		end
+	end
+end

data/lib/e_plat/errors/missing_migration_key_error.rb

@@ -0,0 +1,9 @@
+
+module EPlat
+	class MissingMappingKeyError < StandardError
+		def initialize(msg="Missing hash key in the platform/e-plat's response. Check the mappings
+		")
+			super
+		end
+	end
+end

data/lib/e_plat/errors/missing_session_error.rb

@@ -0,0 +1,8 @@
+
+module EPlat
+	class MissingSessionError < StandardError
+		def initialize(msg="Missing session state, did you include EPlat::SessionState in your ApplicationController?")
+			super
+		end
+	end
+end

data/lib/e_plat/mapping/base.rb

@@ -0,0 +1,49 @@
+module EPlat
+	class Mapping
+		class Base
+			
+			def native_top_key
+				:itself # or top key of JSON response e.g. "data", "product", 
+			end
+			
+			def native_attributes
+				[]
+			end
+			
+			def native_attribute_aliases
+				[
+					# {
+					# 	alias_attribute: {native_key: "description",  e_plat_key: "body_html"}
+					# },
+					# {
+					# 	alias_attribute_with_custom_getter: {native_key:, e_plat_key:, via: }
+					# }
+				]
+			end
+			
+			def aliases
+				native_attribute_aliases.map do |alias_hash|
+					next unless alias_hash[:alias_attribute]
+					
+					keys = alias_hash[:alias_attribute].values[0..1]
+					Hash[*keys]
+				end.compact_blank.inject(&:merge) || {}
+			end
+			
+			def to_native_keys(attributes)
+				as = aliases.invert
+				attributes.transform_keys{|key| (as[key]) ? as[key] : key }
+			end
+			
+			def to_e_plat_keys(attributes)
+				as = aliases
+				attributes.transform_keys{|key| (as[key]) ? as[key] : key }
+			end
+			
+			def mappable_keys
+				native_attribute_aliases.map{|a| a.values.first[:e_plat_key]}.presence || :all
+			end
+
+		end
+	end
+end