shopify_api 9.0.0 → 12.4.0

data/docs/usage/session_storage.md

@@ -0,0 +1,46 @@
+
+# Create a Session Storage Implementation
+
+The implementation of session storage that you pass in `ShopifyAPI::Context.setup` is what the Shopify gem will use to store and load sessions. [Shopify::Auth::FileSessionStorage](../../lib/shopify_api/auth/file_session_storage.rb) can be used for testing purposes and as an example of how to make an implementation in your app. This is not recommended for production, we recommend you implement a solution that will store and load serialized sessions from a more ideal store such as a database like MySQL or MongoDB.
+
+## Create a New Session Storage Class
+
+You can create a session storage class that includes `ShopifyAPI::Auth::SessionStorage` and override the methods as shown in the table and example below:
+
+|       Method Name      |             Input Type            |           Return Type          |
+| ---------------------- | --------------------------------- | ------------------------------ |
+| `store_session`        | `ShopifyAPI::Auth::Session`       | `Boolean` (true if successful) |
+| `load_session`         | `String` (session id)             | `ShopifyAPI::Auth::Session`    |
+| `delete_session`       | `String` (session id)             | `Boolean` (true if successful) |
+
+
+```ruby
+class CustomSessionStorage
+  include ShopifyAPI::Auth::SessionStorage
+
+  def initialize
+    # Initialize as needed
+  end
+
+  def store_session(session)
+    # Implement a store function
+    some_store_function(id: session.id, session_data: session.serialize)
+  end
+
+  def load_session(id)
+    # Implement a fetch function
+    session_data = some_fetch_function(id)
+    ShopifyAPI::Auth::Session.deserialize(session_data)
+  end
+
+  def delete_session(id)
+    # Implement a delete function
+    some_delete_function(id)
+    true
+  end
+end
+```
+
+**Note:** We recommend utilizing the Session `serialize` and `deserialize` functions to make storing and loading sessions easier.
+
+Once this is complete you can pass an instance of this session storage class as `session_storage` in `ShopifyAPI::Context.setup`

data/docs/usage/webhooks.md

@@ -0,0 +1,98 @@
+# Webhooks
+
+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.
+
+## 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:
+
+```ruby
+module WebhookHandler 
+  include ShopifyAPI::Webhooks::Handler
+
+  class << self
+    def handle(topic:, shop:, body:)
+      puts "Received webhook! topic: #{topic} shop: #{shop} body: #{body}"
+    end
+  end
+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) 
+```
+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, 
+  fields: ["number","note"] # this can also be a single comma separated string
+) 
+```
+
+**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.
+
+### EventBridge and PubSub Webhooks
+
+You can also register webhooks for delivery to Amazon EventBridge or Google Cloud
+Pub/Sub. In this case the `path` argument to
+`Shopify.Webhooks.Registry.register` needs to be of a specific form.
+
+For EventBridge, the `path` must be the [ARN of the partner event
+source](https://docs.aws.amazon.com/eventbridge/latest/APIReference/API_EventSource.html).
+
+For Pub/Sub, the `path` must be of the form
+`pubsub://[PROJECT-ID]:[PUB-SUB-TOPIC-ID]`. For example, if you created a topic
+with id `red` in the project `blue`, then the value of `path` would be
+`pubsub://blue:red`.
+
+When registering for an EventBridge or PubSub Webhook you do not need to specify a handler as this is only used for handling Http webhooks.
+
+## Register a Webhook for a Shop
+At any point that you have a session for a shop you can register to receive webhooks for that shop. We recommend registering for webhooks immediately after [OAuth](./oauth.md).
+
+This can be done in one of two ways:
+
+If you would like to register to receive webhooks for all topics you have added to the registry for a specific shop you can simply call:
+```ruby
+ShopifyAPI::Webhooks::Registry.register_all(session: shop_session)
+```
+
+This will return an Array of `ShopifyAPI::Webhooks::RegisterResult`s that have fields `topic`, `success`, and `body` which can be used to see which webhooks were successfully registered.
+
+Or if you would like to register to receive webhooks for specific topics that have been added to the registry for a specific shop you can simply call `register` for any needed topics:
+```ruby
+ShopifyAPI::Webhooks::Registry.register(topic: "<specific-topic>", session: shop_session)
+```
+
+This will return a single `ShopifyAPI::Webhooks::RegisterResult`.
+
+## Unregister a Webhook 
+
+To unregister a topic from a shop you can simply call:
+```ruby
+ShopifyAPI::Webhooks::Registry.unregister(topic: "orders/create", session: shop_session)
+```
+
+## Process a Webhook
+
+To process an http webhook, you need to listen on the route(s) you provided during the Webhook registration process, then when the route is hit construct a `ShopifyAPI::Webhooks::Request` and call `ShopifyAPI::Webhooks::Registry.process`. This will verify the request did indeed come from Shopify and then call the specified handler for that webhook. An example in Rails is shown below:
+
+```ruby
+class WebhookController < ApplicationController
+  def webhook
+    ShopifyAPI::Webhooks::Registry.process(
+      ShopifyAPI::Webhooks::WebhookRequest.new(raw_body: request.raw_post, headers: request.headers.to_h)
+    )
+    render json: {success: true}.to_json
+  end
+end
+```

data/lib/shopify_api/admin_versions.rb

@@ -0,0 +1,20 @@
+# typed: strict
+# frozen_string_literal: true
+
+module ShopifyAPI
+  module AdminVersions
+    SUPPORTED_ADMIN_VERSIONS = T.let([
+      "unstable",
+      "2023-01",
+      "2022-10",
+      "2022-07",
+      "2022-04",
+      "2022-01",
+    ], T::Array[String])
+
+    LATEST_SUPPORTED_ADMIN_VERSION = T.let("2023-01", String)
+  end
+
+  SUPPORTED_ADMIN_VERSIONS = ShopifyAPI::AdminVersions::SUPPORTED_ADMIN_VERSIONS
+  LATEST_SUPPORTED_ADMIN_VERSION = ShopifyAPI::AdminVersions::LATEST_SUPPORTED_ADMIN_VERSION
+end

data/lib/shopify_api/auth/associated_user.rb

@@ -0,0 +1,36 @@
+# typed: strict
+# frozen_string_literal: true
+
+module ShopifyAPI
+  module Auth
+    class AssociatedUser < T::Struct
+      extend T::Sig
+
+      prop :id, Integer
+      prop :first_name, String
+      prop :last_name, String
+      prop :email, String
+      prop :email_verified, T::Boolean
+      prop :account_owner, T::Boolean
+      prop :locale, String
+      prop :collaborator, T::Boolean
+
+      alias_method :eql?, :==
+      sig { params(other: T.nilable(AssociatedUser)).returns(T::Boolean) }
+      def ==(other)
+        if other
+          id == other.id &&
+            first_name == other.first_name &&
+            last_name == other.last_name &&
+            email == other.email &&
+            email_verified == other.email_verified &&
+            account_owner == other.account_owner &&
+            locale == other.locale &&
+            collaborator == other.collaborator
+        else
+          false
+        end
+      end
+    end
+  end
+end

data/lib/shopify_api/auth/auth_scopes.rb

@@ -0,0 +1,75 @@
+# typed: strict
+# frozen_string_literal: true
+
+module ShopifyAPI
+  module Auth
+    class AuthScopes
+      extend T::Sig
+
+      SCOPE_DELIMITER = ","
+
+      sig { params(scope_names: T.any(String, T::Array[String])).void }
+      def initialize(scope_names = [])
+        @compressed_scopes = T.let([].to_set, T::Set[String])
+        @expanded_scopes = T.let([].to_set, T::Set[String])
+
+        if scope_names.is_a?(String)
+          scope_names = scope_names.to_s.split(SCOPE_DELIMITER)
+        end
+
+        store_scopes(scope_names)
+      end
+
+      sig { params(auth_scopes: AuthScopes).returns(T::Boolean) }
+      def covers?(auth_scopes)
+        auth_scopes.compressed_scopes <= expanded_scopes
+      end
+
+      sig { returns(String) }
+      def to_s
+        to_a.join(SCOPE_DELIMITER)
+      end
+
+      sig { returns(T::Array[String]) }
+      def to_a
+        compressed_scopes.to_a
+      end
+
+      sig { params(other: T.nilable(AuthScopes)).returns(T::Boolean) }
+      def ==(other)
+        !other.nil? &&
+          other.class == self.class &&
+          compressed_scopes == other.compressed_scopes
+      end
+
+      alias_method :eql?, :==
+
+      sig { returns(Integer) }
+      def hash
+        compressed_scopes.hash
+      end
+
+      protected
+
+      sig { returns(T::Set[String]) }
+      attr_reader :compressed_scopes, :expanded_scopes
+
+      private
+
+      sig { params(scope_names: T::Array[String]).void }
+      def store_scopes(scope_names)
+        scopes = scope_names.map(&:strip).reject(&:empty?).to_set
+        implied_scopes = scopes.map { |scope| implied_scope(scope) }.compact
+
+        @compressed_scopes = scopes - implied_scopes
+        @expanded_scopes = scopes + implied_scopes
+      end
+
+      sig { params(scope: String).returns(T.nilable(String)) }
+      def implied_scope(scope)
+        is_write_scope = scope =~ /\A(unauthenticated_)?write_(.*)\z/
+        "#{Regexp.last_match(1)}read_#{Regexp.last_match(2)}" if is_write_scope
+      end
+    end
+  end
+end

data/lib/shopify_api/auth/file_session_storage.rb

@@ -0,0 +1,72 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "fileutils"
+
+module ShopifyAPI
+  module Auth
+    class FileSessionStorage
+      extend T::Sig
+      extend T::Helpers
+      include ShopifyAPI::Auth::SessionStorage
+
+      sig { returns(String) }
+      attr_accessor :path
+
+      sig { params(path: String).void }
+      def initialize(path: "/tmp/shopify_api_sessions")
+        @path = path
+        FileUtils.mkdir_p(path) unless Dir.exist?(path)
+      end
+
+      sig do
+        override.params(session: Session)
+          .returns(T::Boolean)
+      end
+      def store_session(session)
+        File.write(session_file_path(session.id), session.serialize) > 0
+      end
+
+      sig do
+        override.params(id: String)
+          .returns(T.nilable(Session))
+      end
+      def load_session(id)
+        session_path = session_file_path(id)
+        if File.exist?(session_path)
+          ShopifyAPI::Auth::Session.deserialize(File.read(session_path))
+        end
+      end
+
+      sig do
+        override.params(id: String)
+          .returns(T::Boolean)
+      end
+      def delete_session(id)
+        session_path = session_file_path(id)
+        File.delete(session_path) if File.exist?(session_path)
+        true
+      end
+
+      alias_method :eql?, :==
+      sig { params(other: T.nilable(FileSessionStorage)).returns(T::Boolean) }
+      def ==(other)
+        if other
+          @path == other.path
+        else
+          false
+        end
+      end
+
+      private
+
+      sig do
+        params(id: String)
+          .returns(String)
+      end
+      def session_file_path(id)
+        "#{@path}/#{id}"
+      end
+    end
+  end
+end

data/lib/shopify_api/auth/jwt_payload.rb

@@ -0,0 +1,83 @@
+# typed: strict
+# frozen_string_literal: true
+
+module ShopifyAPI
+  module Auth
+    class JwtPayload
+      extend T::Sig
+
+      JWT_EXPIRATION_LEEWAY = 10
+
+      sig { returns(String) }
+      attr_reader :iss, :dest, :aud, :sub, :jti, :sid
+
+      sig { returns(Integer) }
+      attr_reader :exp, :nbf, :iat
+
+      sig { params(token: String).void }
+      def initialize(token)
+        payload_hash = begin
+          decode_token(token, Context.api_secret_key)
+        rescue ShopifyAPI::Errors::InvalidJwtTokenError
+          raise unless Context.old_api_secret_key
+
+          decode_token(token, T.must(Context.old_api_secret_key))
+        end
+
+        @iss = T.let(payload_hash["iss"], String)
+        @dest = T.let(payload_hash["dest"], String)
+        @aud = T.let(payload_hash["aud"], String)
+        @sub = T.let(payload_hash["sub"], String)
+        @exp = T.let(payload_hash["exp"], Integer)
+        @nbf = T.let(payload_hash["nbf"], Integer)
+        @iat = T.let(payload_hash["iat"], Integer)
+        @jti = T.let(payload_hash["jti"], String)
+        @sid = T.let(payload_hash["sid"], String)
+
+        raise ShopifyAPI::Errors::InvalidJwtTokenError,
+          "Session token had invalid API key" unless @aud == Context.api_key
+      end
+
+      sig { returns(String) }
+      def shop
+        @dest.gsub("https://", "")
+      end
+
+      # TODO: Remove before releasing v11
+      sig { params(shop: String).returns(T::Boolean) }
+      def validate_shop(shop)
+        Context.logger.warn(
+          "Deprecation notice: ShopifyAPI::Auth::JwtPayload.validate_shop no longer checks the given shop and always " \
+            "returns true. It will be removed in v11.",
+        )
+        true
+      end
+
+      alias_method :eql?, :==
+      sig { params(other: T.nilable(JwtPayload)).returns(T::Boolean) }
+      def ==(other)
+        return false unless other
+
+        iss == other.iss &&
+          dest == other.dest &&
+          aud == other.aud &&
+          sub == other.sub &&
+          exp == other.exp &&
+          nbf == other.nbf &&
+          iat == other.iat &&
+          jti == other.jti &&
+          sid == other.sid
+      end
+
+      private
+
+      sig { params(token: String, api_secret_key: String).returns(T::Hash[String, T.untyped]) }
+      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}'"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+# typed: strict
+# frozen_string_literal: true
+
+module ShopifyAPI
+  module Auth
+    module Oauth
+      class AuthQuery
+        extend T::Sig
+        include Utils::VerifiableQuery
+
+        sig { returns(String) }
+        attr_reader :code, :host, :hmac, :shop, :state, :timestamp
+
+        sig do
+          params(
+            code: String,
+            shop: String,
+            timestamp: String,
+            state: String,
+            host: String,
+            hmac: String,
+          ).void
+        end
+        def initialize(code:, shop:, timestamp:, state:, host:, hmac:)
+          @code = code
+          @shop = shop
+          @timestamp = timestamp
+          @state = state
+          @host = host
+          @hmac = hmac
+        end
+
+        sig { override.returns(String) }
+        def to_signable_string
+          params = {
+            code: code,
+            host: host,
+            shop: shop,
+            state: state,
+            timestamp: timestamp,
+          }
+          URI.encode_www_form(params)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# typed: strict
+# frozen_string_literal: true
+
+module ShopifyAPI
+  module Auth
+    module Oauth
+      class SessionCookie < T::Struct
+        extend T::Sig
+
+        SESSION_COOKIE_NAME = "shopify_app_session"
+
+        const :name, String, default: SESSION_COOKIE_NAME
+        const :value, String
+        const :expires, T.nilable(Time)
+
+        alias_method :eql?, :==
+        sig { params(other: T.nilable(SessionCookie)).returns(T::Boolean) }
+        def ==(other)
+          return false unless other
+
+          name == other.name &&
+            value == other.value &&
+            expires == other.expires
+        end
+      end
+    end
+  end
+end

data/lib/shopify_api/auth/oauth.rb

@@ -0,0 +1,135 @@
+# typed: strict
+# frozen_string_literal: true
+
+module ShopifyAPI
+  module Auth
+    module Oauth
+      extend T::Sig
+
+      NONCE_LENGTH = 15
+
+      class << self
+        extend T::Sig
+
+        sig do
+          params(
+            shop: String,
+            redirect_path: String,
+            is_online: T.nilable(T::Boolean),
+            scope_override: T.nilable(T.any(ShopifyAPI::Auth::AuthScopes, T::Array[String], String)),
+          ).returns(T::Hash[Symbol, T.any(String, SessionCookie)])
+        end
+        def begin_auth(shop:, redirect_path:, is_online: true, scope_override: nil)
+          scope = if scope_override.nil?
+            ShopifyAPI::Context.scope
+          elsif scope_override.is_a?(ShopifyAPI::Auth::AuthScopes)
+            scope_override
+          else
+            ShopifyAPI::Auth::AuthScopes.new(scope_override)
+          end
+
+          unless Context.setup?
+            raise Errors::ContextNotSetupError, "ShopifyAPI::Context not setup, please call ShopifyAPI::Context.setup"
+          end
+          raise Errors::UnsupportedOauthError, "Cannot perform OAuth for private apps." if Context.private?
+
+          state = SecureRandom.alphanumeric(NONCE_LENGTH)
+
+          cookie = SessionCookie.new(value: state, expires: Time.now + 60)
+
+          query = {
+            client_id: ShopifyAPI::Context.api_key,
+            scope: scope.to_s,
+            redirect_uri: "#{ShopifyAPI::Context.host}#{redirect_path}",
+            state: state,
+            "grant_options[]": is_online ? "per-user" : "",
+          }
+
+          query_string = URI.encode_www_form(query)
+
+          auth_route = "https://#{shop}/admin/oauth/authorize?#{query_string}"
+          { auth_route: auth_route, cookie: cookie }
+        end
+
+        sig do
+          params(
+            cookies: T::Hash[String, String],
+            auth_query: AuthQuery,
+          ).returns(T::Hash[Symbol, T.any(Session, SessionCookie)])
+        end
+        def validate_auth_callback(cookies:, auth_query:)
+          unless Context.setup?
+            raise Errors::ContextNotSetupError, "ShopifyAPI::Context not setup, please call ShopifyAPI::Context.setup"
+          end
+          raise Errors::InvalidOauthError, "Invalid OAuth callback." unless Utils::HmacValidator.validate(auth_query)
+          raise Errors::UnsupportedOauthError, "Cannot perform OAuth for private apps." if Context.private?
+
+          state = cookies[SessionCookie::SESSION_COOKIE_NAME]
+          raise Errors::NoSessionCookieError unless state
+
+          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
+          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?
+            raise Errors::RequestAccessTokenError,
+              "Cannot complete OAuth process. Received a #{response.code} error while requesting access token."
+          end
+          session_params = response.to_h
+
+          session = create_new_session(session_params, auth_query.shop)
+
+          cookie = if Context.embedded?
+            SessionCookie.new(
+              value: "",
+              expires: Time.now,
+            )
+          else
+            SessionCookie.new(
+              value: session.id,
+              expires: session.online? ? session.expires : nil,
+            )
+          end
+
+          Context.session_storage&.store_session(session)
+
+          { 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
+end