shopify_api 13.0.0 → 14.0.0

data/docs/usage/webhooks.md

@@ -2,13 +2,43 @@
 
 The `shopify_api` gem provides webhook functionality to make it easy to both subscribe to and process webhooks. To implement in your app follow the steps outlined below.
 
+## Use with Rails
+If using in the Rails framework, we highly recommend you use the [shopify_app](https://github.com/Shopify/shopify_app) gem to interact with this gem. That gem handles [webhooks with a declarative configuration](https://github.com/Shopify/shopify_app/blob/main/docs/shopify_app/webhooks.md).
+
 ## Create a Webhook Handler
 
-If you want to register for an http webhook you need to implement a webhook handler which the `shopify_api` gem can use to determine how to process your webhook. You can make multiple implementations (one per topic) or you can make one implementation capable of handling all the topics you want to subscribe to. To do this simply make a module or class that includes or extends `ShopifyAPI::Webhooks::WebhookHandler` and implement the handle method which accepts the following named parameters: topic: `String`, shop: `String`, and body: `Hash[String, untyped]`. An example implementation is shown below:
+If you want to register for an http webhook you need to implement a webhook handler which the `shopify_api` gem can use to determine how to process your webhook. You can make multiple implementations (one per topic) or you can make one implementation capable of handling all the topics you want to subscribe to. To do this simply make a module or class that includes or extends `ShopifyAPI::Webhooks::WebhookHandler` and implement the `handle` method which accepts the following named parameters: data: `WebhookMetadata`. An example implementation is shown below:
+
+`data` will have the following keys
+- `topic`, `String` - The topic of the webhook
+- `shop`, `String` - The shop domain of the webhook
+- `body`, `T::Hash[String, T.untyped]`- The body of the webhook
+- `webhook_id`, `String` - The id of the webhook event to [avoid duplicates](https://shopify.dev/docs/apps/webhooks/best-practices#ignore-duplicates)
+- `api_version`, `String` - The api version of the webhook
 
 ```ruby
-module WebhookHandler 
-  include ShopifyAPI::Webhooks::Handler
+module WebhookHandler
+  extend ShopifyAPI::Webhooks::Handler
+
+  class << self
+    def handle_webhook(data)
+      puts "Received webhook! topic: #{data.topic} shop: #{data.shop} body: #{data.body} webhook_id: #{data.webhook_id} api_version: #{data.api_version"
+    end
+  end
+end
+```
+
+**Note:** As of version 13.5.0 the `ShopifyAPI::Webhooks::Handler` class is still available to be used but will be removed in a future version of the gem.
+
+### Best Practices
+It is recommended that in order to respond quickly to the Shopify webhook request that the handler not do any heavy logic or network calls, rather it should simply enqueue the work in some job queue in order to be executed later.
+
+### Webhook Handler for versions 13.4.0 and prior
+If you want to register for an http webhook you need to implement a webhook handler which the `shopify_api` gem can use to determine how to process your webhook. You can make multiple implementations (one per topic) or you can make one implementation capable of handling all the topics you want to subscribe to. To do this simply make a module or class that includes or extends `ShopifyAPI::Webhooks::Handler` and implement the handle method which accepts the following named parameters: topic: `String`, shop: `String`, and body: `Hash[String, untyped]`. An example implementation is shown below:
+
+```ruby
+module WebhookHandler
+  extend ShopifyAPI::Webhooks::Handler
 
   class << self
     def handle(topic:, shop:, body:)
@@ -18,24 +48,37 @@ module WebhookHandler
 end
 ```
 
-**Note:** It is recommended that in order to respond quickly to the Shopify webhook request that the handler not do any heavy logic or network calls, rather it should simply enqueue the work in some job queue in order to be executed later.
-
 ## Add to Webhook Registry
 
 The next step is to add all the webhooks you would like to subscribe to for any shop to the webhook registry. To do this you can call `ShopifyAPI::Webhooks::Registry.add_registration` for each webhook you would like to handle. `add_registration` accepts a topic string, a delivery_method symbol (currently supporting `:http`, `:event_bridge`, and `:pub_sub`), a webhook path (the relative path for an http webhook) and a handler. This only needs to be done once when the app is started and we recommend doing this at the same time that you setup `ShopifyAPI::Context`. An example is shown below to register an http webhook:
 
 ```ruby
-registration = ShopifyAPI::Webhooks::Registry.add_registration(topic: "orders/create", delivery_method: :http, handler: WebhookHandler) 
+registration = ShopifyAPI::Webhooks::Registry.add_registration(topic: "orders/create",
+                                                               delivery_method: :http,
+                                                               handler: WebhookHandler,
+                                                               path: 'callback/orders/create')
 ```
 If you are only interested in particular fields, you can optionally filter the data sent by Shopify by specifying the `fields` parameter. Note that you will still receive a webhook request from Shopify every time the resource is updated, but only the specified fields will be sent:
 
 ```ruby
 registration = ShopifyAPI::Webhooks::Registry.add_registration(
-  topic: "orders/create", 
-  delivery_method: :http, 
-  handler: WebhookHandler, 
+  topic: "orders/create",
+  delivery_method: :http,
+  handler: WebhookHandler,
+  path: 'callback/orders/create',
   fields: ["number","note"] # this can also be a single comma separated string
-) 
+)
+```
+
+If you are storing metafields on an object you are receiving webhooks for, you can specify them on registration to make sure that they are also sent through the `metafieldNamespaces` parameter. Note if you are also using the `fields` parameter you will need to add `metafields` into that as well.
+
+```ruby
+registration = ShopifyAPI::Webhooks::Registry.add_registration(
+  topic: "orders/create",
+  delivery_method: :http,
+  handler: WebhookHandler,
+  metafieldNamespaces: ["custom"]
+)
 ```
 
 **Note**: The webhooks you register with Shopify are saved in the Shopify platform, but the local `ShopifyAPI::Webhooks::Registry` needs to be reloaded whenever your server restarts.
@@ -75,7 +118,7 @@ ShopifyAPI::Webhooks::Registry.register(topic: "<specific-topic>", session: shop
 
 This will return a single `ShopifyAPI::Webhooks::RegisterResult`.
 
-## Unregister a Webhook 
+## Unregister a Webhook
 
 To unregister a topic from a shop you can simply call:
 ```ruby

data/lib/shopify_api/admin_versions.rb

@@ -5,6 +5,9 @@ module ShopifyAPI
   module AdminVersions
     SUPPORTED_ADMIN_VERSIONS = T.let([
       "unstable",
+      "2024-01",
+      "2023-10",
+      "2023-07",
       "2023-04",
       "2023-01",
       "2022-10",
@@ -13,7 +16,7 @@ module ShopifyAPI
       "2022-01",
     ], T::Array[String])
 
-    LATEST_SUPPORTED_ADMIN_VERSION = T.let("2023-04", String)
+    LATEST_SUPPORTED_ADMIN_VERSION = T.let("2024-01", String)
   end
 
   SUPPORTED_ADMIN_VERSIONS = ShopifyAPI::AdminVersions::SUPPORTED_ADMIN_VERSIONS

data/lib/shopify_api/auth/jwt_payload.rb

@@ -75,8 +75,8 @@ module ShopifyAPI
       def decode_token(token, api_secret_key)
         JWT.decode(token, api_secret_key, true,
           { exp_leeway: JWT_EXPIRATION_LEEWAY, algorithm: "HS256" })[0]
-      rescue
-        raise ShopifyAPI::Errors::InvalidJwtTokenError, "Failed to parse session token '#{token}'"
+      rescue JWT::DecodeError => err
+        raise ShopifyAPI::Errors::InvalidJwtTokenError, "Error decoding session token: #{err.message}"
       end
     end
   end

data/lib/shopify_api/auth/oauth/access_token_response.rb

@@ -0,0 +1,37 @@
+# typed: strict
+# frozen_string_literal: true
+
+module ShopifyAPI
+  module Auth
+    module Oauth
+      class AccessTokenResponse < T::Struct
+        extend T::Sig
+
+        const :access_token, String
+        const :scope, String
+        const :session, T.nilable(String)
+        const :expires_in, T.nilable(Integer)
+        const :associated_user, T.nilable(AssociatedUser)
+        const :associated_user_scope, T.nilable(String)
+
+        sig { returns(T::Boolean) }
+        def online_token?
+          !associated_user.nil?
+        end
+
+        alias_method :eql?, :==
+        sig { params(other: T.nilable(AccessTokenResponse)).returns(T::Boolean) }
+        def ==(other)
+          return false unless other
+
+          access_token == other.access_token &&
+            scope == other.scope &&
+            session == other.session &&
+            expires_in == other.expires_in &&
+            associated_user == other.associated_user &&
+            associated_user_scope == other.associated_user_scope
+        end
+      end
+    end
+  end
+end

data/lib/shopify_api/auth/oauth.rb

@@ -70,16 +70,27 @@ module ShopifyAPI
           raise Errors::InvalidOauthError,
             "Invalid state in OAuth callback." unless state == auth_query.state
 
-          # TODO: replace this call with the HTTP client once it is built
+          null_session = Auth::Session.new(shop: auth_query.shop)
           body = { client_id: Context.api_key, client_secret: Context.api_secret_key, code: auth_query.code }
-          response = HTTParty.post("https://#{auth_query.shop}/admin/oauth/access_token", body: body)
-          unless response.ok?
+
+          client = Clients::HttpClient.new(session: null_session, base_path: "/admin/oauth")
+          response = begin
+            client.request(
+              Clients::HttpRequest.new(
+                http_method: :post,
+                path: "access_token",
+                body: body,
+                body_type: "application/json",
+              ),
+            )
+          rescue ShopifyAPI::Errors::HttpResponseError => e
             raise Errors::RequestAccessTokenError,
-              "Cannot complete OAuth process. Received a #{response.code} error while requesting access token."
+              "Cannot complete OAuth process. Received a #{e.code} error while requesting access token."
           end
-          session_params = response.to_h
 
-          session = create_new_session(session_params, auth_query.shop)
+          session_params = T.cast(response.body, T::Hash[String, T.untyped]).to_h
+          session = Session.from(shop: auth_query.shop,
+            access_token_response: Oauth::AccessTokenResponse.from_hash(session_params))
 
           cookie = if Context.embedded?
             SessionCookie.new(
@@ -95,38 +106,6 @@ module ShopifyAPI
 
           { session: session, cookie: cookie }
         end
-
-        private
-
-        sig { params(session_params: T::Hash[String, T.untyped], shop: String).returns(Session) }
-        def create_new_session(session_params, shop)
-          session_params = session_params.to_h { |k, v| [k.to_sym, v] }
-
-          scope = session_params[:scope]
-
-          is_online = !session_params[:associated_user].nil?
-
-          if is_online
-            associated_user = AssociatedUser.new(session_params[:associated_user].to_h { |k, v| [k.to_sym, v] })
-            expires = Time.now + session_params[:expires_in].to_i
-            associated_user_scope = session_params[:associated_user_scope]
-            id = "#{shop}_#{associated_user.id}"
-          else
-            id = "offline_#{shop}"
-          end
-
-          Session.new(
-            id: id,
-            shop: shop,
-            access_token: session_params[:access_token],
-            scope: scope,
-            is_online: is_online,
-            associated_user_scope: associated_user_scope,
-            associated_user: associated_user,
-            expires: expires,
-            shopify_session_id: session_params[:session],
-          )
-        end
       end
     end
   end

data/lib/shopify_api/auth/session.rb

@@ -35,6 +35,11 @@ module ShopifyAPI
         @is_online
       end
 
+      sig { returns(T::Boolean) }
+      def expired?
+        @expires ? @expires < Time.now : false
+      end
+
       sig do
         params(
           shop: String,
@@ -84,6 +89,32 @@ module ShopifyAPI
           end
         end
 
+        sig { params(shop: String, access_token_response: Oauth::AccessTokenResponse).returns(Session) }
+        def from(shop:, access_token_response:)
+          is_online = access_token_response.online_token?
+
+          if is_online
+            associated_user = T.must(access_token_response.associated_user)
+            expires = Time.now + access_token_response.expires_in.to_i
+            associated_user_scope = access_token_response.associated_user_scope
+            id = "#{shop}_#{associated_user.id}"
+          else
+            id = "offline_#{shop}"
+          end
+
+          new(
+            id: id,
+            shop: shop,
+            access_token: access_token_response.access_token,
+            scope: access_token_response.scope,
+            is_online: is_online,
+            associated_user_scope: associated_user_scope,
+            associated_user: associated_user,
+            expires: expires,
+            shopify_session_id: access_token_response.session,
+          )
+        end
+
         sig { params(str: String).returns(Session) }
         def deserialize(str)
           Oj.load(str)

data/lib/shopify_api/auth/token_exchange.rb

@@ -0,0 +1,80 @@
+# typed: strict
+# frozen_string_literal: true
+
+module ShopifyAPI
+  module Auth
+    module TokenExchange
+      extend T::Sig
+
+      TOKEN_EXCHANGE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:token-exchange"
+      ID_TOKEN_TYPE = "urn:ietf:params:oauth:token-type:id_token"
+
+      class RequestedTokenType < T::Enum
+        enums do
+          ONLINE_ACCESS_TOKEN = new("urn:shopify:params:oauth:token-type:online-access-token")
+          OFFLINE_ACCESS_TOKEN = new("urn:shopify:params:oauth:token-type:offline-access-token")
+        end
+      end
+
+      class << self
+        extend T::Sig
+
+        sig do
+          params(
+            shop: String,
+            session_token: String,
+            requested_token_type: RequestedTokenType,
+          ).returns(ShopifyAPI::Auth::Session)
+        end
+        def exchange_token(shop:, session_token:, requested_token_type:)
+          unless ShopifyAPI::Context.setup?
+            raise ShopifyAPI::Errors::ContextNotSetupError,
+              "ShopifyAPI::Context not setup, please call ShopifyAPI::Context.setup"
+          end
+          raise ShopifyAPI::Errors::UnsupportedOauthError,
+            "Cannot perform OAuth Token Exchange for private apps." if ShopifyAPI::Context.private?
+          raise ShopifyAPI::Errors::UnsupportedOauthError,
+            "Cannot perform OAuth Token Exchange for non embedded apps." unless ShopifyAPI::Context.embedded?
+
+          # Validate the session token content
+          ShopifyAPI::Auth::JwtPayload.new(session_token)
+
+          shop_session = ShopifyAPI::Auth::Session.new(shop: shop)
+          body = {
+            client_id: ShopifyAPI::Context.api_key,
+            client_secret: ShopifyAPI::Context.api_secret_key,
+            grant_type: TOKEN_EXCHANGE_GRANT_TYPE,
+            subject_token: session_token,
+            subject_token_type: ID_TOKEN_TYPE,
+            requested_token_type: requested_token_type.serialize,
+          }
+
+          client = Clients::HttpClient.new(session: shop_session, base_path: "/admin/oauth")
+          response = begin
+            client.request(
+              Clients::HttpRequest.new(
+                http_method: :post,
+                path: "access_token",
+                body: body,
+                body_type: "application/json",
+              ),
+            )
+          rescue ShopifyAPI::Errors::HttpResponseError => error
+            if error.code == 400 && error.response.body["error"] == "invalid_subject_token"
+              raise ShopifyAPI::Errors::InvalidJwtTokenError, "Session token was rejected by token exchange"
+            end
+
+            raise error
+          end
+
+          session_params = T.cast(response.body, T::Hash[String, T.untyped]).to_h
+
+          Session.from(
+            shop: shop,
+            access_token_response: Oauth::AccessTokenResponse.from_hash(session_params),
+          )
+        end
+      end
+    end
+  end
+end

data/lib/shopify_api/clients/graphql/client.rb

@@ -42,6 +42,7 @@ module ShopifyAPI
               body_type: "application/json",
               tries: tries,
             ),
+            response_as_struct: Context.response_as_struct || false,
           )
         end
       end

data/lib/shopify_api/clients/http_client.rb

@@ -13,7 +13,9 @@ module ShopifyAPI
         session ||= Context.active_session
         raise Errors::NoActiveSessionError, "No passed or active session" unless session
 
-        @base_uri = T.let("https://#{session.shop}", String)
+        api_host = Context.api_host
+
+        @base_uri = T.let("https://#{api_host || session.shop}", String)
         @base_uri_and_path = T.let("#{@base_uri}#{base_path}", String)
 
         user_agent_prefix = Context.user_agent_prefix.nil? ? "" : "#{Context.user_agent_prefix} | "
@@ -23,13 +25,15 @@ module ShopifyAPI
           "Accept": "application/json",
         }, T::Hash[T.any(Symbol, String), T.untyped])
 
+        @headers["Host"] = session.shop unless api_host.nil?
+
         unless session.access_token.nil? || T.must(session.access_token).empty?
           @headers["X-Shopify-Access-Token"] = T.cast(session.access_token, String)
         end
       end
 
-      sig { params(request: HttpRequest).returns(HttpResponse) }
-      def request(request)
+      sig { params(request: HttpRequest, response_as_struct: T::Boolean).returns(HttpResponse) }
+      def request(request, response_as_struct: false)
         request.verify
 
         headers = @headers
@@ -56,6 +60,11 @@ module ShopifyAPI
             body = res.body
           end
 
+          if response_as_struct && body.is_a?(Hash)
+            json_body = body.to_json
+            body = JSON.parse(json_body, object_class: OpenStruct)
+          end
+
           response = HttpResponse.new(code: res.code.to_i, headers: res.headers.to_h, body: body)
 
           if response.headers["x-shopify-api-deprecated-reason"]

data/lib/shopify_api/clients/http_response.rb

@@ -12,17 +12,23 @@ module ShopifyAPI
       sig { returns(T::Hash[String, T::Array[String]]) }
       attr_reader :headers
 
-      sig { returns(T.any(T::Hash[String, T.untyped], String)) }
+      sig { returns(T.any(T::Hash[String, T.untyped], String, OpenStruct)) }
       attr_reader :body
 
       sig { returns(T.nilable(String)) }
       attr_reader :prev_page_info, :next_page_info
 
+      sig { returns(T.nilable(T::Hash[String, Integer])) }
+      attr_reader :api_call_limit
+
+      sig { returns(T.nilable(Float)) }
+      attr_reader :retry_request_after
+
       sig do
         params(
           code: Integer,
           headers: T::Hash[String, T::Array[String]],
-          body: T.any(T::Hash[String, T.untyped], String),
+          body: T.any(T::Hash[String, T.untyped], String, OpenStruct),
         ).void
       end
       def initialize(code:, headers:, body:)
@@ -33,6 +39,11 @@ module ShopifyAPI
         @prev_page_info = T.let(nil, T.nilable(String))
         @next_page_info = T.let(nil, T.nilable(String))
         @prev_page_info, @next_page_info = parse_link_header
+
+        @api_call_limit = T.let(nil, T.nilable(T::Hash[String, Integer]))
+        @retry_request_after = T.let(nil, T.nilable(Float))
+        @api_call_limit = parse_api_call_limit_header
+        @retry_request_after = parse_retry_header
       end
 
       sig { returns(T::Boolean) }
@@ -61,6 +72,22 @@ module ShopifyAPI
 
         [page_info["previous"], page_info["next"]]
       end
+
+      sig { returns(T.nilable(Float)) }
+      def parse_retry_header
+        return nil if @headers["retry-after"].nil?
+
+        T.must(@headers["retry-after"])[0].to_f
+      end
+
+      sig { returns(T.nilable(T::Hash[String, Integer])) }
+      def parse_api_call_limit_header
+        rate_limit_info = headers["x-shopify-shop-api-call-limit"]&.first
+        return if rate_limit_info.nil?
+
+        request_count, bucket_size = rate_limit_info.split("/").map(&:to_i)
+        { request_count: request_count, bucket_size: bucket_size }
+      end
     end
   end
 end

data/lib/shopify_api/context.rb

@@ -8,16 +8,20 @@ module ShopifyAPI
     @api_key = T.let("", String)
     @api_secret_key = T.let("", String)
     @api_version = T.let(LATEST_SUPPORTED_ADMIN_VERSION, String)
+    @api_host = T.let(nil, T.nilable(String))
     @scope = T.let(Auth::AuthScopes.new, Auth::AuthScopes)
     @is_private = T.let(false, T::Boolean)
     @private_shop = T.let(nil, T.nilable(String))
     @is_embedded = T.let(true, T::Boolean)
-    @logger = T.let(::Logger.new($stdout), ::Logger)
+    # Logger can either be a Logger or an ActiveSupport::BroadcastLogger, which is new in Rails 7.1.0. To avoid adding a
+    # dependency Active Support >= 7.1.0, we go with T.untyped
+    @logger = T.let(::Logger.new($stdout), T.untyped)
     @log_level = T.let(:info, Symbol)
     @notified_missing_resources_folder = T.let({}, T::Hash[String, T::Boolean])
     @active_session = T.let(Concurrent::ThreadLocalVar.new { nil }, T.nilable(Concurrent::ThreadLocalVar))
     @user_agent_prefix = T.let(nil, T.nilable(String))
     @old_api_secret_key = T.let(nil, T.nilable(String))
+    @response_as_struct = T.let(false, T.nilable(T::Boolean))
 
     @rest_resource_loader = T.let(nil, T.nilable(Zeitwerk::Loader))
 
@@ -33,12 +37,14 @@ module ShopifyAPI
           is_private: T::Boolean,
           is_embedded: T::Boolean,
           log_level: T.any(String, Symbol),
-          logger: ::Logger,
+          logger: T.untyped,
           host_name: T.nilable(String),
           host: T.nilable(String),
           private_shop: T.nilable(String),
           user_agent_prefix: T.nilable(String),
           old_api_secret_key: T.nilable(String),
+          api_host: T.nilable(String),
+          response_as_struct: T.nilable(T::Boolean),
         ).void
       end
       def setup(
@@ -54,7 +60,9 @@ module ShopifyAPI
         host: ENV["HOST"] || "https://#{host_name}",
         private_shop: nil,
         user_agent_prefix: nil,
-        old_api_secret_key: nil
+        old_api_secret_key: nil,
+        api_host: nil,
+        response_as_struct: false
       )
         unless ShopifyAPI::AdminVersions::SUPPORTED_ADMIN_VERSIONS.include?(api_version)
           raise Errors::UnsupportedVersionError,
@@ -64,6 +72,7 @@ module ShopifyAPI
         @api_key = api_key
         @api_secret_key = api_secret_key
         @api_version = api_version
+        @api_host = api_host
         @host = T.let(host, T.nilable(String))
         @is_private = is_private
         @scope = Auth::AuthScopes.new(scope)
@@ -72,6 +81,7 @@ module ShopifyAPI
         @private_shop = private_shop
         @user_agent_prefix = user_agent_prefix
         @old_api_secret_key = old_api_secret_key
+        @response_as_struct = response_as_struct
         @log_level = if valid_log_level?(log_level)
           log_level.to_sym
         else
@@ -84,6 +94,7 @@ module ShopifyAPI
       sig { params(api_version: String).void }
       def load_rest_resources(api_version:)
         # Unload any previous instances - mostly useful for tests where we need to reset the version
+        @rest_resource_loader&.setup
         @rest_resource_loader&.unload
 
         # No resources for the unstable version
@@ -115,19 +126,22 @@ module ShopifyAPI
       sig { returns(Auth::AuthScopes) }
       attr_reader :scope
 
-      sig { returns(::Logger) }
+      sig { returns(T.untyped) }
       attr_reader :logger
 
       sig { returns(Symbol) }
       attr_reader :log_level
 
+      sig { returns T.nilable(T::Boolean) }
+      attr_reader :response_as_struct
+
       sig { returns(T::Boolean) }
       def private?
         @is_private
       end
 
       sig { returns(T.nilable(String)) }
-      attr_reader :private_shop, :user_agent_prefix, :old_api_secret_key, :host
+      attr_reader :private_shop, :user_agent_prefix, :old_api_secret_key, :host, :api_host
 
       sig { returns(T::Boolean) }
       def embedded?

data/lib/shopify_api/logger.rb

@@ -75,7 +75,7 @@ module ShopifyAPI
       def valid_version(version)
         current_version = Gem::Version.create(ShopifyAPI::VERSION)
         deprecate_version = Gem::Version.create(version)
-        current_version < deprecate_version
+        T.must(current_version) < deprecate_version
       end
     end
   end