shopify_api 1.0.4 → 12.3.0

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,72 @@
+# 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
+          if @path.match?(%r{^https?://})
+            @path
+          elsif @path.match?(/^#{Context.host_name}/)
+            "#{Context.host_scheme}://#{@path}"
+          else
+            "#{Context.host}/#{@path}"
+          end
+        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,215 @@
+# 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

data/lib/shopify_api/webhooks/request.rb

@@ -0,0 +1,56 @@
+# typed: strict
+# frozen_string_literal: true
+
+module ShopifyAPI
+  module Webhooks
+    class Request
+      extend T::Sig
+      include Utils::VerifiableQuery
+
+      sig { override.returns(String) }
+      def hmac
+        Digest.hexencode(Base64.decode64(T.cast(@headers["x-shopify-hmac-sha256"], String)))
+      end
+
+      sig { returns(String) }
+      def topic
+        T.cast(@headers["x-shopify-topic"], String)
+      end
+
+      sig { returns(String) }
+      def shop
+        T.cast(@headers["x-shopify-shop-domain"], String)
+      end
+
+      sig { override.returns(String) }
+      def to_signable_string
+        @raw_body
+      end
+
+      sig { returns(T::Hash[String, T.untyped]) }
+      def parsed_body
+        JSON.parse(@raw_body)
+      end
+
+      sig { params(raw_body: String, headers: T::Hash[String, T.untyped]).void }
+      def initialize(raw_body:, headers:)
+        # normalize the headers by forcing lowercase, removing any prepended "http"s, and changing underscores to dashes
+        headers = headers.to_h { |k, v| [k.to_s.downcase.sub("http_", "").gsub("_", "-"), v] }
+
+        missing_headers = []
+        [
+          "x-shopify-topic",
+          "x-shopify-hmac-sha256",
+          "x-shopify-shop-domain",
+        ].each { |header| missing_headers << header unless headers.include?(header) }
+        unless missing_headers.empty?
+          raise Errors::InvalidWebhookError,
+            "Missing one or more of the required HTTP headers to process webhooks: #{missing_headers}"
+        end
+
+        @headers = headers
+        @raw_body = raw_body
+      end
+    end
+  end
+end