shopify_api 9.5.1 → 10.0.0

data/lib/shopify_api/utils/session_utils.rb

@@ -0,0 +1,135 @@
+# typed: strict
+# frozen_string_literal: true
+
+module ShopifyAPI
+  module Utils
+    class SessionUtils
+      extend T::Sig
+
+      class << self
+        extend T::Sig
+
+        sig do
+          params(
+            auth_header: T.nilable(String),
+            cookies: T.nilable(T::Hash[String, String]),
+            is_online: T::Boolean
+          ).returns(T.nilable(Auth::Session))
+        end
+        def load_current_session(auth_header: nil, cookies: nil, is_online: false)
+          return load_private_session if Context.private?
+
+          session_id = current_session_id(auth_header, cookies, is_online)
+          return nil unless session_id
+
+          Context.session_storage.load_session(session_id)
+        end
+
+        sig do
+          params(
+            auth_header: T.nilable(String),
+            cookies: T.nilable(T::Hash[String, String]),
+            is_online: T::Boolean
+          ).returns(T::Boolean)
+        end
+        def delete_current_session(auth_header: nil, cookies: nil, is_online: false)
+          session_id = current_session_id(auth_header, cookies, is_online)
+          return false unless session_id
+
+          Context.session_storage.delete_session(session_id)
+        end
+
+        sig do
+          params(
+            shop: String,
+            include_expired: T::Boolean,
+          ).returns(T.nilable(Auth::Session))
+        end
+        def load_offline_session(shop:, include_expired: false)
+          session_id = offline_session_id(shop)
+          session = Context.session_storage.load_session(session_id)
+          return nil if session && !include_expired && session.expires && T.must(session.expires) < Time.now
+
+          session
+        end
+
+        sig do
+          params(
+            shop: String
+          ).returns(T::Boolean)
+        end
+        def delete_offline_session(shop:)
+          session_id = offline_session_id(shop)
+          Context.session_storage.delete_session(session_id)
+        end
+
+        private
+
+        sig { returns(Auth::Session) }
+        def load_private_session
+          unless Context.private_shop
+            raise Errors::SessionNotFoundError, "Could not load private shop, Context.private_shop is nil."
+          end
+
+          Auth::Session.new(
+            shop: T.must(Context.private_shop),
+            access_token: Context.api_secret_key,
+            scope: Context.scope.to_a
+          )
+        end
+
+        sig do
+          params(
+            auth_header: T.nilable(String),
+            cookies: T.nilable(T::Hash[String, String]),
+            online: T::Boolean
+          ).returns(T.nilable(String))
+        end
+        def current_session_id(auth_header, cookies, online)
+          if Context.embedded?
+            if auth_header
+              matches = auth_header.match(/^Bearer (.+)$/)
+              raise Errors::MissingJwtTokenError,
+                "Missing Bearer token in authorization header" unless matches
+
+              jwt_payload = Auth::JwtPayload.new(T.must(matches[1]))
+              shop = jwt_payload.shop
+
+              if online
+                jwt_session_id(shop, jwt_payload.sub)
+              else
+                offline_session_id(shop)
+              end
+            else
+              # falling back to session cookie
+              raise Errors::CookieNotFoundError, "JWT token or Session cookie not found for app" unless
+                cookies && cookies[Auth::Oauth::SessionCookie::SESSION_COOKIE_NAME]
+
+              cookie_session_id(cookies)
+            end
+          else
+            raise Errors::CookieNotFoundError, "Session cookie not found for app" unless
+              cookies && cookies[Auth::Oauth::SessionCookie::SESSION_COOKIE_NAME]
+
+            cookie_session_id(cookies)
+          end
+        end
+
+        sig { params(shop: String, user_id: String).returns(String) }
+        def jwt_session_id(shop, user_id)
+          "#{shop}_#{user_id}"
+        end
+
+        sig { params(shop: String).returns(String) }
+        def offline_session_id(shop)
+          "offline_#{shop}"
+        end
+
+        sig { params(cookies: T::Hash[String, String]).returns(T.nilable(String)) }
+        def cookie_session_id(cookies)
+          cookies[Auth::Oauth::SessionCookie::SESSION_COOKIE_NAME]
+        end
+      end
+    end
+  end
+end

data/lib/shopify_api/utils/verifiable_query.rb

@@ -0,0 +1,18 @@
+# typed: strict
+# frozen_string_literal: true
+
+module ShopifyAPI
+  module Utils
+    module VerifiableQuery
+      extend T::Sig
+      extend T::Helpers
+      interface!
+
+      sig { abstract.returns(T.nilable(String)) }
+      def hmac; end
+
+      sig { abstract.returns(String) }
+      def to_signable_string; end
+    end
+  end
+end

data/lib/shopify_api/version.rb

@@ -1,4 +1,6 @@
+# typed: strict
 # frozen_string_literal: true
+
 module ShopifyAPI
-  VERSION = "9.5.1"
+  VERSION = "10.0.0"
 end

data/lib/shopify_api/webhooks/handler.rb

@@ -0,0 +1,15 @@
+# typed: strict
+# frozen_string_literal: true
+
+module ShopifyAPI
+  module Webhooks
+    module Handler
+      extend T::Sig
+      extend T::Helpers
+      interface!
+
+      sig { abstract.params(topic: String, shop: String, body: T::Hash[String, T.untyped]).void }
+      def handle(topic:, shop:, body:); end
+    end
+  end
+end

data/lib/shopify_api/webhooks/register_result.rb

@@ -0,0 +1,14 @@
+# typed: strict
+# frozen_string_literal: true
+
+module ShopifyAPI
+  module Webhooks
+    class RegisterResult < T::Struct
+      extend T::Sig
+
+      const :topic, String
+      const :success, T::Boolean
+      const :body, T.nilable(T.any(T::Hash[String, T.untyped], String))
+    end
+  end
+end

data/lib/shopify_api/webhooks/registration.rb

@@ -0,0 +1,73 @@
+# typed: strict
+# frozen_string_literal: true
+
+module ShopifyAPI
+  module Webhooks
+    class Registration
+      extend T::Sig
+      extend T::Helpers
+      abstract!
+
+      FIELDS_DELIMITER = ","
+
+      sig { returns(String) }
+      attr_reader :topic
+
+      sig { returns(T.nilable(Handler)) }
+      attr_reader :handler
+
+      sig { returns(T.nilable(T::Array[String])) }
+      attr_reader :fields
+
+      sig do
+        params(topic: String, path: String, handler: T.nilable(Handler),
+          fields: T.nilable(T.any(String, T::Array[String]))).void
+      end
+      def initialize(topic:, path:, handler: nil, fields: nil)
+        @topic = T.let(topic.gsub("/", "_").upcase, String)
+        @path = path
+        @handler = handler
+        fields_array = fields.is_a?(String) ? fields.split(FIELDS_DELIMITER) : fields
+        @fields = T.let(fields_array&.map(&:strip)&.compact, T.nilable(T::Array[String]))
+      end
+
+      sig { abstract.returns(String) }
+      def callback_address; end
+
+      sig { abstract.returns(T::Hash[Symbol, String]) }
+      def subscription_args; end
+
+      sig { abstract.params(webhook_id: T.nilable(String)).returns(String) }
+      def mutation_name(webhook_id); end
+
+      sig { abstract.returns(String) }
+      def build_check_query; end
+
+      sig { abstract.params(body: T::Hash[String, T.untyped]).returns(T::Hash[Symbol, String]) }
+      def parse_check_result(body); end
+
+      sig { params(webhook_id: T.nilable(String)).returns(String) }
+      def build_register_query(webhook_id: nil)
+        identifier = webhook_id ? "id: \"#{webhook_id}\"" : "topic: #{@topic}"
+
+        subscription_args_string = subscription_args.map do |k, v|
+          "#{k}: #{k == :includeFields ? v : '"' + v + '"'}"
+        end.join(", ")
+
+        <<~QUERY
+          mutation webhookSubscription {
+            #{mutation_name(webhook_id)}(#{identifier}, webhookSubscription: {#{subscription_args_string}}) {
+              userErrors {
+                field
+                message
+              }
+              webhookSubscription {
+                id#{@fields.nil? ? "" : "\n      includeFields"}
+              }
+            }
+          }
+        QUERY
+      end
+    end
+  end
+end

data/lib/shopify_api/webhooks/registrations/event_bridge.rb

@@ -0,0 +1,61 @@
+# typed: strict
+# frozen_string_literal: true
+
+module ShopifyAPI
+  module Webhooks
+    module Registrations
+      class EventBridge < Registration
+        extend T::Sig
+
+        sig { override.returns(String) }
+        def callback_address
+          @path
+        end
+
+        sig { override.returns(T::Hash[Symbol, String]) }
+        def subscription_args
+          { arn: callback_address, includeFields: fields }.compact
+        end
+
+        sig { override.params(webhook_id: T.nilable(String)).returns(String) }
+        def mutation_name(webhook_id)
+          webhook_id ? "eventBridgeWebhookSubscriptionUpdate" : "eventBridgeWebhookSubscriptionCreate"
+        end
+
+        sig { override.returns(String) }
+        def build_check_query
+          <<~QUERY
+            {
+              webhookSubscriptions(first: 1, topics: #{@topic}) {
+                edges {
+                  node {
+                    id
+                    endpoint {
+                      __typename
+                      ... on WebhookEventBridgeEndpoint {
+                        arn
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          QUERY
+        end
+
+        sig { override.params(body: T::Hash[String, T.untyped]).returns(T::Hash[Symbol, String]) }
+        def parse_check_result(body)
+          edges = body.dig("data", "webhookSubscriptions", "edges") || {}
+          webhook_id = nil
+          current_address = nil
+          unless edges.empty?
+            node = edges[0]["node"]
+            webhook_id = node["id"].to_s
+            current_address = node["endpoint"]["arn"].to_s
+          end
+          { webhook_id: webhook_id, current_address: current_address }
+        end
+      end
+    end
+  end
+end

data/lib/shopify_api/webhooks/registrations/http.rb

@@ -0,0 +1,66 @@
+# typed: strict
+# frozen_string_literal: true
+
+module ShopifyAPI
+  module Webhooks
+    module Registrations
+      class Http < Registration
+        extend T::Sig
+
+        sig { override.returns(String) }
+        def callback_address
+          "https://#{Context.host_name}/#{@path}"
+        end
+
+        sig { override.returns(T::Hash[Symbol, String]) }
+        def subscription_args
+          { callbackUrl: callback_address, includeFields: fields }.compact
+        end
+
+        sig { override.params(webhook_id: T.nilable(String)).returns(String) }
+        def mutation_name(webhook_id)
+          webhook_id ? "webhookSubscriptionUpdate" : "webhookSubscriptionCreate"
+        end
+
+        sig { override.returns(String) }
+        def build_check_query
+          <<~QUERY
+            {
+              webhookSubscriptions(first: 1, topics: #{@topic}) {
+                edges {
+                  node {
+                    id
+                    endpoint {
+                      __typename
+                      ... on WebhookHttpEndpoint {
+                        callbackUrl
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          QUERY
+        end
+
+        sig { override.params(body: T::Hash[String, T.untyped]).returns(T::Hash[Symbol, String]) }
+        def parse_check_result(body)
+          edges = body.dig("data", "webhookSubscriptions", "edges") || {}
+          webhook_id = nil
+          current_address = nil
+          unless edges.empty?
+            node = edges[0]["node"]
+            webhook_id = node["id"].to_s
+            current_address =
+              if node.key?("endpoint")
+                node["endpoint"]["callbackUrl"].to_s
+              else
+                node["callbackUrl"].to_s
+              end
+          end
+          { webhook_id: webhook_id, current_address: current_address }
+        end
+      end
+    end
+  end
+end

data/lib/shopify_api/webhooks/registrations/pub_sub.rb

@@ -0,0 +1,65 @@
+# typed: strict
+# frozen_string_literal: true
+
+module ShopifyAPI
+  module Webhooks
+    module Registrations
+      class PubSub < Registration
+        extend T::Sig
+
+        sig { override.returns(String) }
+        def callback_address
+          @path
+        end
+
+        sig { override.returns(T::Hash[Symbol, String]) }
+        def subscription_args
+          project_topic_pair = callback_address.gsub(%r{^pubsub://}, "").split(":")
+          project = project_topic_pair[0]
+          topic = project_topic_pair[1]
+          { pubSubProject: project, pubSubTopic: topic, includeFields: fields }.compact
+        end
+
+        sig { override.params(webhook_id: T.nilable(String)).returns(String) }
+        def mutation_name(webhook_id)
+          webhook_id ? "pubSubWebhookSubscriptionUpdate" : "pubSubWebhookSubscriptionCreate"
+        end
+
+        sig { override.returns(String) }
+        def build_check_query
+          <<~QUERY
+            {
+              webhookSubscriptions(first: 1, topics: #{@topic}) {
+                edges {
+                  node {
+                    id
+                    endpoint {
+                      __typename
+                      ... on WebhookPubSubEndpoint {
+                        pubSubProject
+                        pubSubTopic
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          QUERY
+        end
+
+        sig { override.params(body: T::Hash[String, T.untyped]).returns(T::Hash[Symbol, String]) }
+        def parse_check_result(body)
+          edges = body.dig("data", "webhookSubscriptions", "edges") || {}
+          webhook_id = nil
+          current_address = nil
+          unless edges.empty?
+            node = edges[0]["node"]
+            webhook_id = node["id"].to_s
+            current_address = "pubsub://#{node["endpoint"]["pubSubProject"]}:#{node["endpoint"]["pubSubTopic"]}"
+          end
+          { webhook_id: webhook_id, current_address: current_address }
+        end
+      end
+    end
+  end
+end

data/lib/shopify_api/webhooks/registry.rb

@@ -0,0 +1,216 @@
+# typed: strict
+# frozen_string_literal: true
+
+module ShopifyAPI
+  module Webhooks
+    class Registry
+      @registry = T.let({}, T::Hash[String, Registration])
+
+      class << self
+        extend T::Sig
+        sig do
+          params(topic: String,
+            delivery_method: Symbol,
+            path: String,
+            handler: T.nilable(Handler),
+            fields: T.nilable(String)).void
+        end
+        def add_registration(topic:, delivery_method:, path:, handler: nil, fields: nil)
+          @registry[topic] = case delivery_method
+          when :pub_sub
+            Registrations::PubSub.new(topic: topic, path: path, fields: fields)
+          when :event_bridge
+            Registrations::EventBridge.new(topic: topic, path: path, fields: fields)
+          when :http
+            unless handler
+              raise Errors::InvalidWebhookRegistrationError, "Cannot create an Http registration without a handler."
+            end
+
+            Registrations::Http.new(topic: topic, path: path, handler: handler, fields: fields)
+          else
+            raise Errors::InvalidWebhookRegistrationError,
+              "Unsupported delivery method #{delivery_method}. Allowed values: {:http, :pub_sub, :event_bridge}."
+          end
+        end
+
+        sig { void }
+        def clear
+          @registry.clear
+        end
+
+        sig do
+          params(
+            topic: String,
+            session: Auth::Session
+          ).returns(RegisterResult)
+        end
+        def register(topic:, session:)
+          registration = @registry[topic]
+
+          unless registration
+            raise Errors::InvalidWebhookRegistrationError, "Webhook topic #{topic} has not been added to the registry."
+          end
+
+          client = Clients::Graphql::Admin.new(session: session)
+          register_check_result = webhook_registration_needed?(client, registration)
+
+          registered = true
+          register_body = nil
+
+          if register_check_result[:must_register]
+            register_body = send_register_request(
+              client,
+              registration,
+              register_check_result[:webhook_id]
+            )
+            registered = registration_sucessful?(
+              register_body,
+              registration.mutation_name(register_check_result[:webhook_id])
+            )
+          end
+
+          RegisterResult.new(topic: topic, success: registered, body: register_body)
+        end
+
+        sig do
+          params(
+            session: Auth::Session
+          ).returns(T::Array[RegisterResult])
+        end
+        def register_all(session:)
+          topics = @registry.keys
+          result = T.let([], T::Array[RegisterResult])
+          topics.each do |topic|
+            register_response = register(
+              topic: topic,
+              session: session
+            )
+            result.push(register_response)
+          end
+          result
+        end
+
+        sig do
+          params(
+            topic: String,
+            session: T.nilable(Auth::Session)
+          ).returns(T::Hash[String, T.untyped])
+        end
+        def unregister(topic:, session:)
+          client = Clients::Graphql::Admin.new(session: session)
+
+          webhook_id = get_webhook_id(topic: topic, client: client)
+          return {} if webhook_id.nil?
+
+          delete_mutation = <<~MUTATION
+            mutation webhookSubscription {
+              webhookSubscriptionDelete(id: "#{webhook_id}") {
+                userErrors {
+                  field
+                  message
+                }
+                deletedWebhookSubscriptionId
+              }
+            }
+          MUTATION
+
+          delete_response = client.query(query: delete_mutation)
+          raise Errors::WebhookRegistrationError,
+            "Failed to delete webhook from Shopify" unless delete_response.ok?
+          result = T.cast(delete_response.body, T::Hash[String, T.untyped])
+          errors = result["errors"] || {}
+          raise Errors::WebhookRegistrationError,
+            "Failed to delete webhook from Shopify: #{errors[0]["message"]}" unless errors.empty?
+          user_errors = result.dig("data", "webhookSubscriptionDelete", "userErrors") || {}
+          raise Errors::WebhookRegistrationError,
+            "Failed to delete webhook from Shopify: #{user_errors[0]["message"]}" unless user_errors.empty?
+          result
+        end
+
+        sig do
+          params(
+            topic: String,
+            client: Clients::Graphql::Admin
+          ).returns(T.nilable(String))
+        end
+        def get_webhook_id(topic:, client:)
+          fetch_id_query = <<~QUERY
+            {
+              webhookSubscriptions(first: 1, topics: #{topic.gsub("/", "_").upcase}) {
+                edges {
+                  node {
+                    id
+                    }
+                  }
+                }
+              }
+            }
+          QUERY
+
+          fetch_id_response = client.query(query: fetch_id_query)
+          raise Errors::WebhookRegistrationError,
+            "Failed to fetch webhook from Shopify" unless fetch_id_response.ok?
+          body = T.cast(fetch_id_response.body, T::Hash[String, T.untyped])
+          errors = body["errors"] || {}
+          raise Errors::WebhookRegistrationError,
+            "Failed to fetch webhook from Shopify: #{errors[0]["message"]}" unless errors.empty?
+
+          edges = body.dig("data", "webhookSubscriptions", "edges") || {}
+          return nil if edges.empty?
+
+          edges[0]["node"]["id"].to_s
+        end
+        sig { params(request: Request).void }
+        def process(request)
+          raise Errors::InvalidWebhookError, "Invalid webhook HMAC." unless Utils::HmacValidator.validate(request)
+
+          handler = @registry[request.topic]&.handler
+
+          unless handler
+            raise Errors::NoWebhookHandler, "No webhook handler found for topic: #{request.topic}."
+          end
+
+          handler.handle(topic: request.topic, shop: request.shop, body: request.parsed_body)
+        end
+
+        private
+
+        sig do
+          params(
+            client: Clients::Graphql::Admin,
+            registration: Registration,
+          ).returns(T::Hash[Symbol, T.untyped])
+        end
+        def webhook_registration_needed?(client, registration)
+          check_response = client.query(query: registration.build_check_query)
+          raise Errors::WebhookRegistrationError,
+            "Failed to check if webhook was already registered" unless check_response.ok?
+          parsed_check_result = registration.parse_check_result(T.cast(check_response.body, T::Hash[String, T.untyped]))
+          must_register = parsed_check_result[:current_address] != registration.callback_address
+
+          { webhook_id: parsed_check_result[:webhook_id], must_register: must_register }
+        end
+
+        sig do
+          params(
+            client: Clients::Graphql::Admin,
+            registration: Registration,
+            webhook_id: T.nilable(String)
+          ).returns(T::Hash[String, T.untyped])
+        end
+        def send_register_request(client, registration, webhook_id)
+          register_response = client.query(query: registration.build_register_query(webhook_id: webhook_id))
+
+          raise Errors::WebhookRegistrationError, "Failed to register webhook with Shopify" unless register_response.ok?
+
+          T.cast(register_response.body, T::Hash[String, T.untyped])
+        end
+
+        sig { params(body: T::Hash[String, T.untyped], mutation_name: String).returns(T::Boolean) }
+        def registration_sucessful?(body, mutation_name)
+          !body.dig("data", mutation_name, "webhookSubscription").nil?
+        end
+      end
+    end
+  end
+end