shopify_api 9.5.1 → 13.1.0

data/docs/usage/rest.md

@@ -0,0 +1,144 @@
+# Make a REST API call
+
+Once OAuth is complete, we can use the `ShopifyAPI::Clients::Rest::Admin` client to make an API call to the Shopify Admin API. To do this, you can create an instance of `ShopifyAPI::Clients::Rest::Admin` using the current session to make requests to the Admin API.
+
+## Methods
+
+The Rest Admin client offers the 4 core request methods: `get`, `delete`, `post`, and `put`. These methods each take the parameters outlined in the table below. If the request is successful these methods will all return a `ShopifyAPI::Clients::HttpResponse` object, which has properties `code`, `headers`, and `body` otherwise an error will be raised describing what went wrong.
+
+| Parameter      | Type                                                     | Required in Methods | Default Value | Notes                                                                                                                                                                                                                                                                                  |
+| -------------- | -------------------------------------------------------- | :-----------------: | :-----------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `path`         | `String`                                                 |         all         |     none      | The requested API endpoint path. This can be one of two formats:<ul><li>The path starting after the `/admin/api/{version}/` prefix, such as `products`, which executes `/admin/api/{version}/products.json`</li><li>The full path, such as `/admin/oauth/access_scopes.json`</li></ul> |
+| `body`         | `Hash(any(Symbol, String), untyped)`                     |    `put`, `post`    |     none      | The body of the request                                                                                                                                                                                                                                                                |
+| `query`        | `Hash(any(Symbol, String), any(String, Integer, Float))` |        none         |     none      | An optional query object to be appended to the request url as a query string                                                                                                                                                                                                           |
+| `extraHeaders` | `Hash(any(Symbol, String), any(String, Integer, Float))` |        none         |     none      | Any additional headers you want to send with your request                                                                                                                                                                                                                              |
+| `tries`        | `Integer`                                                |        None         |      `1`      | The maximum number of times to try the request _(must be >= 0)_                                                                                                                                                                                                                        |
+
+**Note:** _These paramaters can still be used in all methods regardless of if they are required._
+
+## Usage Examples:
+
+### Perform a `GET` request:
+
+```ruby
+# Load the current session to get the `accessToken`.
+session = ShopifyAPI::Utils::SessionUtils.load_current_session(headers, cookies, is_online)
+
+# Create a new client.
+client = ShopifyAPI::Clients::Rest::Admin.new(session: session)
+
+# Use `client.get` to request the specified Shopify REST API endpoint, in this case `products`.
+response = client.get(path: "products")
+
+# Do something with the returned data
+some_function(response.body)
+```
+
+### Perform a `POST` request:
+
+```ruby
+# Load the current session to get the `accessToken`.
+session = ShopifyAPI::Utils::SessionUtils.load_current_session(headers, cookies, is_online)
+
+# Create a new client.
+client = ShopifyAPI::Clients::Rest::Admin.new(session: session)
+
+# Build your post request body.
+body = {
+  product: {
+    title: "Burton Custom Freestyle 151",
+    body_html: "\u003cstrong\u003eGood snowboard!\u003c\/strong\u003e",
+    vendor: "Burton",
+    product_type: "Snowboard",
+  }
+}
+
+# Use `client.post` to send your request to the specified Shopify Admin REST API endpoint.
+client.post({
+  path: "products",
+  body: body,
+});
+```
+
+_for more information on the `products` endpoint, [check out our API reference guide](https://shopify.dev/docs/api/admin-rest/unstable/resources/product)._
+
+### Override the `api_version`:
+
+```ruby
+# To experiment with prerelease features, pass the api_version "unstable".
+client = ShopifyAPI::Clients::Rest::Admin.new(session: session, api_version: "unstable")
+```
+
+## Pagination
+
+This library also supports cursor-based pagination for REST Admin API requests. [Learn more about REST request pagination](https://shopify.dev/docs/api/usage/pagination-rest).
+
+After making a request, the `next_page_info` and `prev_page_info` can be found on the response object and passed as the page_info query param in other requests.
+
+An example of this is shown below:
+
+```ruby
+session = ShopifyAPI::Utils::SessionUtils.load_current_session(headers, cookies, is_online)
+client = ShopifyAPI::Clients::Rest::Admin.new(session: session)
+
+response = client.get(path: "products", query: { limit: 10 })
+
+loop do
+  some_function(response.body)
+  break unless response.next_page_info
+  response =  client.get(path: "products", query: { limit: 10, page_info: response.next_page_info })
+end
+```
+
+Similarly, when using REST resources the `next_page_info` and `prev_page_info` can be found on the Resource class and passed as the page_info query param in other requests.
+
+An example of this is shown below:
+
+```ruby
+session = ShopifyAPI::Utils::SessionUtils.load_current_session(headers, cookies, is_online)
+
+products = ShopifyAPI::Product.all(session: session, limit: 10)
+
+loop do
+  some_function(products)
+  break unless ShopifyAPI::Product.next_page?
+  products = ShopifyAPI::Product.all(session: session, limit: 10, page_info: ShopifyAPI::Product.next_page_info)
+end
+```
+
+The next/previous page_info strings can also be retrieved from the response object and added to a request query to retrieve the next/previous pages.
+
+An example of this is shown below:
+
+```ruby
+session = ShopifyAPI::Utils::SessionUtils.load_current_session(headers, cookies, is_online)
+client = ShopifyAPI::Clients::Rest::Admin.new(session: session)
+
+response = client.get(path: "products", query: { limit: 10 })
+next_page_info = response.next_page_info
+
+if next_page_info
+  next_page_response =client.get(path: "products", query: { limit: 10, page_info: next_page_info })
+  some_function(next_page_response)
+end
+```
+
+### Error Messages
+
+You can rescue `ShopifyAPI::Errors::HttpResponseError` and output error messages with `errors.full_messages`
+
+See example:
+
+```ruby
+ fulfillment = ShopifyAPI::Fulfillment.new(session: @session)
+  fulfillment.order_id = 2776493818000
+  ...
+  fulfillment.tracking_company = "Jack Black's Pack, Stack and Track"
+  fulfillment.save()
+rescue ShopifyAPI::Errors::HttpResponseError => e
+  puts fulfillment.errors.full_messages
+  # {"base"=>["Line items are already fulfilled"]}
+  # If you report this error, please include this id: e712dde0-1270-4258-8cdb-d198792c917e.
+```
+
+[Back to guide index](../README.md)

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::Request.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,22 @@
+# typed: strict
+# frozen_string_literal: true
+
+module ShopifyAPI
+  module AdminVersions
+    SUPPORTED_ADMIN_VERSIONS = T.let([
+      "unstable",
+      "2023-07",
+      "2023-04",
+      "2023-01",
+      "2022-10",
+      "2022-07",
+      "2022-04",
+      "2022-01",
+    ], T::Array[String])
+
+    LATEST_SUPPORTED_ADMIN_VERSION = T.let("2023-07", 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/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