active_shopify_graphql 0.5.3 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e6fe91cae8b27f0c6154d8d43a42477e900dba59925b27421f5ea43278c8a786
-  data.tar.gz: 6480859442d7a8ff30dc17fa3c0a96c5ae383f0ce0465fbbb8a67ff26c46f6da
+  metadata.gz: 5fbed890ba698aa5134ff32bdd471ffa8944e56eaf5d6a8a6d28e8060983e519
+  data.tar.gz: 34d83bf513460e154f33369fe54e953c68a466e37d16effccb7cb92014f16824
 SHA512:
-  metadata.gz: e8572b7217ec7bb43172611d1d4059114b70de34342bb7c702265a90f3295004fd7de85b5449077054633ea199dd3f6606638f042cff3798dfc76d76dde24f4e
-  data.tar.gz: 975eca8ec8d7ab7e3f166884baa6e885d76596d130f4525281b85075b3acef960f5562a45ed8a7ae73ac14e1a2e179cc129dbcff6a5b0d5588ba21ccb6838893
+  metadata.gz: 4a1dad259585ae87c1afa68c18eb03f74b48b13068b452a41a7d42bfb576c244df4de5eab321559dc5c9a5f11e1f2964fb0cdef142058ae345a75cb29e9e5700
+  data.tar.gz: f847bdf0f63e10b67f866abd6fae9c0d24195977d078c6d7125e7eff083f2f6ba99e1b0c30ada1374f5ceb4f36f0e8a1d52506a2d7354c7e01020d7d1ab4bcf7

data/README.md

@@ -25,15 +25,21 @@ gem install active_shopify_graphql
 ```ruby
 # Configure in pure Ruby
 ActiveShopifyGraphQL.configure do |config|
-  config.admin_api_client = ShopifyGraphQL::Client
-  config.customer_account_client_class = Shopify::Account::Client
+  config.admin_api_executor = lambda do |query, **variables|
+    client = ShopifyAPI::Clients::Graphql::Admin.new(session: ShopifyAPI::Context.active_session)
+    response = client.query(query:, variables:)
+    response.body if response
+  end
 end
 
 # Or define a Rails initializer
 Rails.configuration.to_prepare do
   ActiveShopifyGraphQL.configure do |config|
-    config.admin_api_client = ShopifyGraphQL::Client
-    config.customer_account_client_class = Shopify::Account::Client
+    config.admin_api_executor = lambda do |query, **variables|
+      client = ShopifyAPI::Clients::Graphql::Admin.new(session: ShopifyAPI::Context.active_session)
+      response = client.query(query:, variables:)
+      response.body if response
+    end
   end
 end
 
@@ -90,7 +96,7 @@ orders = customer["orders"]["nodes"].map { |o| parse_order(o) }
 customer = Customer.includes(:orders).find(123456789)
 customer.email                # => "john@example.com"
 customer.created_at           # => #<DateTime>
-customer.orders.to_a          # Lazily loaded as a single query
+customer.orders               # Eagerly loaded as a single query
 ```
 
 **Benefits:**
@@ -138,11 +144,19 @@ Configure your Shopify GraphQL clients:
 # config/initializers/active_shopify_graphql.rb
 Rails.configuration.to_prepare do
   ActiveShopifyGraphQL.configure do |config|
-    # Admin API (must respond to #execute(query, **variables))
-    config.admin_api_client = ShopifyGraphQL::Client
-
-    # Customer Account API (must have .from_config(token) and #execute)
-    config.customer_account_client_class = Shopify::Account::Client
+    # Admin API (receives query, **variables as arguments)
+    config.admin_api_executor = lambda do |query, **variables|
+      client = ShopifyAPI::Clients::Graphql::Admin.new(session: ShopifyAPI::Context.active_session)
+      response = client.query(query:, variables:)
+      response.body if response
+    end
+
+    # Optional Customer Account API (receives query, customer_token, **variables as arguments)
+    config.customer_account_api_executor = lambda do |query, customer_token, **variables|
+      # This is a custom client example
+      client = Shopify::Account::Client.from_config(customer_token)
+      response = client.query(query, **variables)
+    end
   end
 end
 ```
@@ -309,7 +323,8 @@ Customer.where(email: "john@example.com")
 Customer.where(created_at: { gte: "2024-01-01", lt: "2024-02-01" })
 Customer.where(orders_count: { gte: 5 })
 
-# Wildcards (string query)
+# Wildcards are supported in string queries only
+# Use with caution as interpolation can lead to security issues
 Customer.where("email:*@example.com")
 
 # Parameter binding (safe)
@@ -319,6 +334,21 @@ Customer.where("email::email", email: "john@example.com")
 Customer.where(email: "@gmail.com").limit(100)
 ```
 
+#### Sorting
+
+```ruby
+# Sort by created_at ascending (default)
+Customer.where(email: "@example.com").order(sort_key: "CREATED_AT")
+
+# Sort by updated_at descending
+Customer.order(sort_key: "UPDATED_AT", reverse: true)
+
+# Combine with other chainable methods
+Customer.where(country: "Canada").order(sort_key: "CREATED_AT").limit(25)
+```
+
+**Note:** Sort keys are Shopify GraphQL enum values (e.g., `"CREATED_AT"`, `"UPDATED_AT"`, `"RELEVANCE"`). Available values depend on the specific Shopify API endpoint.
+
 #### Query Optimization
 
 ```ruby
@@ -349,7 +379,7 @@ ProductVariant.where("sku:FRZ*").in_pages(of: 10) do |page|
 end
 
 # Lazy enumeration
-scope = Customer.where(email: "*@example.com")
+scope = Customer.where(email: "@example.com")
 scope.each { |c| puts c.name }  # Executes query
 scope.first                      # Fetches just first
 ```

data/lib/active_shopify_graphql/configuration.rb

@@ -3,11 +3,11 @@
 module ActiveShopifyGraphQL
   # Configuration class for setting up external dependencies
   class Configuration
-    attr_accessor :admin_api_client, :customer_account_client_class, :logger, :log_queries, :max_objects_per_paginated_query
+    attr_accessor :admin_api_executor, :customer_account_api_executor, :logger, :log_queries, :max_objects_per_paginated_query
 
     def initialize
-      @admin_api_client = nil
-      @customer_account_client_class = nil
+      @admin_api_executor = nil
+      @customer_account_api_executor = nil
       @logger = nil
       @log_queries = false
       @max_objects_per_paginated_query = 250

data/lib/active_shopify_graphql/connections/connection_loader.rb

@@ -44,7 +44,7 @@ module ActiveShopifyGraphQL
         )
 
         parent_id = extract_gid(parent)
-        response_data = @loader_instance.perform_graphql_query(query, id: parent_id)
+        response_data = @loader_instance.execute_query(query, id: parent_id)
 
         return [] if response_data.nil?
 
@@ -76,7 +76,7 @@ module ActiveShopifyGraphQL
           singular: singular
         )
 
-        response_data = @loader_instance.perform_graphql_query(query)
+        response_data = @loader_instance.execute_query(query)
 
         return [] if response_data.nil?
 

data/lib/active_shopify_graphql/loader.rb

@@ -58,7 +58,7 @@ module ActiveShopifyGraphQL
 
     # Map the GraphQL response to model attributes
     def map_response_to_attributes(response_data, parent_instance: nil)
-      mapper = create_response_mapper
+      mapper = Response::ResponseMapper.new(context)
       attributes = mapper.map_response(response_data)
       cache_connections(mapper, response_data, target: attributes, parent_instance: parent_instance)
       attributes
@@ -74,7 +74,7 @@ module ActiveShopifyGraphQL
     # @return [Hash, nil] Attribute hash with connection cache, or nil if not found
     def load_attributes(id)
       query = Query::QueryBuilder.build_single_record_query(context)
-      response_data = execute_query(query, id: id)
+      response_data = perform_graphql_query(query, id: id)
       return nil if response_data.nil?
 
       map_response_to_attributes(response_data)
@@ -86,15 +86,19 @@ module ActiveShopifyGraphQL
     # @param per_page [Integer] Number of records per page
     # @param after [String, nil] Cursor to fetch records after
     # @param before [String, nil] Cursor to fetch records before
+    # @param sort_key [String, nil] The Shopify sort key (e.g., "CREATED_AT")
+    # @param reverse [Boolean, nil] Whether to reverse the sort order
     # @param query_scope [Query::Scope] The query scope for navigation
     # @return [PaginatedResult] A paginated result with attribute hashes and page info
-    def load_paginated_collection(conditions:, per_page:, query_scope:, after: nil, before: nil)
+    def load_paginated_collection(conditions:, per_page:, query_scope:, after: nil, before: nil, sort_key: nil, reverse: nil)
       collection_query_name = context.query_name.pluralize
       variables = build_collection_variables(
         conditions,
         per_page: per_page,
         after: after,
-        before: before
+        before: before,
+        sort_key: sort_key,
+        reverse: reverse
       )
 
       query = Query::QueryBuilder.build_paginated_collection_query(
@@ -113,6 +117,11 @@ module ActiveShopifyGraphQL
       connection_loader.load_records(query_name, variables, parent, connection_config)
     end
 
+    def execute_query(query, **variables)
+      log_query(self.class.name, query, variables)
+      perform_graphql_query(query, **variables)
+    end
+
     # Abstract method for executing GraphQL queries
     def perform_graphql_query(query, **variables)
       raise NotImplementedError, "#{self.class} must implement perform_graphql_query"
@@ -120,10 +129,6 @@ module ActiveShopifyGraphQL
 
     private
 
-    def create_response_mapper
-      Response::ResponseMapper.new(context)
-    end
-
     def should_log?
       ActiveShopifyGraphQL.configuration.log_queries && ActiveShopifyGraphQL.configuration.logger
     end
@@ -175,17 +180,13 @@ module ActiveShopifyGraphQL
       raise ArgumentError, "Shopify query validation failed: #{messages.join(', ')}"
     end
 
-    def execute_query(query, **variables)
-      perform_graphql_query(query, **variables)
-    end
-
     def execute_query_and_validate_search_response(query, **variables)
       response = execute_query(query, **variables)
       validate_search_query_response(response)
       response
     end
 
-    def build_collection_variables(conditions, per_page:, after: nil, before: nil)
+    def build_collection_variables(conditions, per_page:, after: nil, before: nil, sort_key: nil, reverse: nil)
       search_query = SearchQuery.new(conditions)
       variables = { query: search_query.to_s }
 
@@ -197,6 +198,9 @@ module ActiveShopifyGraphQL
         variables[:after] = after if after
       end
 
+      variables[:sort_key] = sort_key if sort_key
+      variables[:reverse] = reverse unless reverse.nil?
+
       variables.compact
     end
 

data/lib/active_shopify_graphql/loaders/admin_api_loader.rb

@@ -4,12 +4,10 @@ module ActiveShopifyGraphQL
   module Loaders
     class AdminApiLoader < Loader
       def perform_graphql_query(query, **variables)
-        log_query("Admin API", query, variables)
+        executor = ActiveShopifyGraphQL.configuration.admin_api_executor
+        raise Error, "Admin API executor not configured. Please configure it using ActiveShopifyGraphQL.configure" unless executor
 
-        client = ActiveShopifyGraphQL.configuration.admin_api_client
-        raise Error, "Admin API client not configured. Please configure it using ActiveShopifyGraphQL.configure" unless client
-
-        client.execute(query, **variables)
+        executor.call(query, **variables)
       end
     end
   end

data/lib/active_shopify_graphql/loaders/customer_account_api_loader.rb

@@ -23,16 +23,11 @@ module ActiveShopifyGraphQL
         map_response_to_attributes(response_data)
       end
 
-      def client
-        client_class = ActiveShopifyGraphQL.configuration.customer_account_client_class
-        raise Error, "Customer Account API client class not configured" unless client_class
-
-        @client ||= client_class.from_config(@token)
-      end
-
       def perform_graphql_query(query, **variables)
-        log_query("Customer Account API", query, variables)
-        client.query(query, variables)
+        executor = ActiveShopifyGraphQL.configuration.customer_account_api_executor
+        raise Error, "Customer Account API executor not configured. Please configure it using ActiveShopifyGraphQL.configure" unless executor
+
+        executor.call(query, @token, **variables)
       end
 
       def initialization_args

data/lib/active_shopify_graphql/model/connections.rb

@@ -102,7 +102,7 @@ module ActiveShopifyGraphQL::Model::Connections
           )
         else
           # Create a new proxy for custom options (don't cache these)
-          Connections::ConnectionProxy.new(
+          ActiveShopifyGraphQL::Connections::ConnectionProxy.new(
             parent: self,
             connection_name: name,
             connection_config: self.class.connections[name],

data/lib/active_shopify_graphql/model/finder_methods.rb

@@ -120,6 +120,18 @@ module ActiveShopifyGraphQL::Model::FinderMethods
       all.includes(*connection_names)
     end
 
+    # Set the sort order for the query
+    # @param sort_key [String] The Shopify sort key (e.g., "CREATED_AT", "UPDATED_AT")
+    # @param reverse [Boolean] Whether to reverse the sort order (optional)
+    # @return [Relation] A relation with order applied
+    #
+    # @example
+    #   Customer.order(sort_key: "CREATED_AT").where(country: "Canada")
+    #   Customer.where(status: "active").order(sort_key: "UPDATED_AT", reverse: true)
+    def order(sort_key:, reverse: nil)
+      all.order(sort_key: sort_key, reverse: reverse)
+    end
+
     private
 
     # Validates that selected attributes exist in the model

data/lib/active_shopify_graphql/query/relation.rb

@@ -23,7 +23,7 @@ module ActiveShopifyGraphQL
 
       DEFAULT_PER_PAGE = 250
 
-      attr_reader :model_class, :included_connections, :conditions, :total_limit, :per_page
+      attr_reader :model_class, :included_connections, :conditions, :total_limit, :per_page, :sort_key, :reverse
 
       def initialize(
         model_class,
@@ -33,7 +33,9 @@ module ActiveShopifyGraphQL
         total_limit: nil,
         per_page: DEFAULT_PER_PAGE,
         loader_class: nil,
-        loader_extra_args: []
+        loader_extra_args: [],
+        sort_key: nil,
+        reverse: nil
       )
         @model_class = model_class
         @conditions = conditions
@@ -43,6 +45,8 @@ module ActiveShopifyGraphQL
         @per_page = [per_page, ActiveShopifyGraphQL.configuration.max_objects_per_paginated_query].min
         @loader_class = loader_class
         @loader_extra_args = loader_extra_args
+        @sort_key = sort_key
+        @reverse = reverse
         @loaded = false
         @records = nil
       end
@@ -66,6 +70,22 @@ module ActiveShopifyGraphQL
         spawn(conditions: new_conditions)
       end
 
+      # Set the sort order for the query
+      # @param sort_key [String] The Shopify sort key (e.g., "CREATED_AT", "UPDATED_AT")
+      # @param reverse [Boolean] Whether to reverse the sort order (optional)
+      # @return [Relation] A new relation with order applied
+      # @raise [ArgumentError] If order is called on a relation that already has ordering
+      # @example
+      #   Customer.where(email: "*@example.com").order(sort_key: "CREATED_AT", reverse: true)
+      def order(sort_key:, reverse: nil)
+        if has_ordering?
+          raise ArgumentError, "Chaining multiple order clauses is not supported. " \
+                               "Combine ordering in a single order call instead."
+        end
+
+        spawn(sort_key: sort_key, reverse: reverse)
+      end
+
       # Find a single record by conditions
       # @param conditions [Hash] The conditions to match
       # @return [Object, nil] The first matching record or nil
@@ -302,6 +322,8 @@ module ActiveShopifyGraphQL
           per_page: effective_per_page,
           after: after,
           before: before,
+          sort_key: @sort_key,
+          reverse: @reverse,
           query_scope: build_query_scope_for_pagination
         )
       end
@@ -324,7 +346,9 @@ module ActiveShopifyGraphQL
           total_limit: changes.fetch(:total_limit, @total_limit),
           per_page: changes.fetch(:per_page, @per_page),
           loader_class: changes.fetch(:loader_class, @loader_class),
-          loader_extra_args: changes.fetch(:loader_extra_args, @loader_extra_args)
+          loader_extra_args: changes.fetch(:loader_extra_args, @loader_extra_args),
+          sort_key: changes.fetch(:sort_key, @sort_key),
+          reverse: changes.fetch(:reverse, @reverse)
         )
       end
 
@@ -341,6 +365,10 @@ module ActiveShopifyGraphQL
         end
       end
 
+      def has_ordering?
+        !@sort_key.nil?
+      end
+
       def build_loader
         klass = @loader_class || @model_class.send(:default_loader_class)
 

data/lib/active_shopify_graphql/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActiveShopifyGraphQL
-  VERSION = "0.5.3"
+  VERSION = "1.0.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: active_shopify_graphql
 version: !ruby/object:Gem::Version
-  version: 0.5.3
+  version: 1.0.0
 platform: ruby
 authors:
 - Nicolò Rebughini