shopify_api 13.4.0 → 14.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d837a507476d9d344892dc7667fed5cf1fcc20ac37c5bc5488e4a2583b3dab5c
-  data.tar.gz: b385d9e275df49f00fd8aac9bba99c6df69a9f111afd92285e12e2b411d734e5
+  metadata.gz: 0eceb8b083a02fd062ebc545e6d4a60b1b4c11fec77bead21bef052f1c184b0a
+  data.tar.gz: 6d47eb134e26c9536db9ee6225abf3edf00a07c15060aa6cae6d490b49347151
 SHA512:
-  metadata.gz: 0f1de95b3fd22f3f7494914d74647cb51607e5302c3bbf23c7d29e159f1a90f21509d2c7ade5606287dd698ce67e7ec018bf0fa0a099f4034eefdac363d0f20f
-  data.tar.gz: 58e4c9c8c67bed4996f056e0219d45c38d589feb2e04e3902302afb71e3f282b2138f85b813d394a953c7c323cfd2f42c71464931fdd7f83327c145921b18d96
+  metadata.gz: 38fb4a844e00437ff2d2e93cc6c931c13ace7511aec1dcbf49585a6ea22a0f4db59cc472d46b257424645b20de2740600d8e429ed21435cf64448df6aea5f3e4
+  data.tar.gz: d3d4102189174b84791a7f0065bf633b548b4034fcff31305b7d350de3a3d07fdc7b6fe1a21dd8e7286583656d1bec7517ed4662aa429c17d00fcfdc9176eba2

data/.github/ISSUE_TEMPLATE/BUG_REPORT.md

@@ -6,35 +6,41 @@ labels: "Type: Bug 🐛"
 
 # Issue summary
 
-<!--
-
-Write a short description of the issue here. Please provide any details or logs that
-can help us debug it.
+Before opening this issue, I have:
+
+- [ ] Upgraded to the latest version of the package
+  - `shopify_api` version:
+  - Ruby version:
+  - Operating system:
+- [ ] Set `log_level: :debug` [in my configuration](https://github.com/Shopify/shopify-api-ruby#setup-shopify-context), if applicable
+- [ ] Found a reliable way to reproduce the problem that indicates it's a problem with the package
+- [ ] Looked for similar issues in this repository
+- [ ] Checked that this isn't an issue with a Shopify API
+  - If it is, please create a post in the [Shopify community forums](https://community.shopify.com/c/partners-and-developers/ct-p/appdev) or report it to [Shopify Partner Support](https://help.shopify.com/en/support/partners/org-select)
 
-Increase the logs as described in the README by setting log_level to :debug, and paste the relevant portion here.
-
-Learn more: https://github.com/Shopify/shopify-api-ruby#setup-shopify-context
+<!--
+Write a short description of the issue here.
 
+We can only fix issues for which there is a clear reproduction scenario.
+The more context you can provide, the easier it becomes for us to investigate and fix the issue.
 -->
 
-- `shopify_api` version:
-- Ruby version:
-- Operating system:
-
-```
-// Paste any relevant logs here
-```
-
 ## Expected behavior
 
-<!-- What do you think should happen? -->
+What do you think should happen?
 
 ## Actual behavior
 
-<!-- What actually happens? -->
+What actually happens?
 
 ## Steps to reproduce the problem
 
 1.
 1.
 1.
+
+## Debug logs
+
+```
+// Paste any relevant logs here
+```

data/.github/workflows/build.yml

@@ -11,7 +11,6 @@ jobs:
     strategy:
       matrix:
         version:
-          - 2.7
           - 3.0
           - 3.1
     steps:

data/CHANGELOG.md

@@ -4,6 +4,17 @@ Note: For changes to the API, see https://shopify.dev/changelog?filter=api
 
 ## Unreleased
 
+## 14.0.1
+- [#1288](https://github.com/Shopify/shopify-api-ruby/pull/1288) Fix FeatureDeprecatedError being raised without a message.
+- [1290](https://github.com/Shopify/shopify-api-ruby/pull/1290) Move deprecation of `ShopifyAPI::Webhooks::Handler#handle` to version 15.0.0
+
+## 14.0.0
+- [#1274](https://github.com/Shopify/shopify-api-ruby/pull/1274) ⚠️ [Breaking] Update sorbet and rbi dependencies. Remove support for ruby 2.7. Minimum required Ruby version is 3.0
+- [#1282](https://github.com/Shopify/shopify-api-ruby/pull/1282) Fixes a bug where diffing attributes to update not take into account of Array changes and required ids.
+- [#1254](https://github.com/Shopify/shopify-api-ruby/pull/1254) Introduce token exchange API for fetching access tokens. This feature is currently unstable and cannot be used yet.
+- [#1268](https://github.com/Shopify/shopify-api-ruby/pull/1268) Add [new webhook handler interface](https://github.com/Shopify/shopify-api-ruby/blob/main/docs/usage/webhooks.md#create-a-webhook-handler) to provide `webhook_id ` and `api_version` information to webhook handlers.
+- [#1275](https://github.com/Shopify/shopify-api-ruby/pull/1275) Allow adding custom headers in REST Resource HTTP calls.
+
 ## 13.4.0
 - [#1210](https://github.com/Shopify/shopify-api-ruby/pull/1246) Add context option `response_as_struct` to allow GraphQL API responses to be accessed via dot notation.
 - [#1257](https://github.com/Shopify/shopify-api-ruby/pull/1257) Add `api_call_limit` and `retry_request_after` to REST resources to expose rate limit information.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,46 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, and in the interest of
+fostering an open and welcoming community, we pledge to respect all
+people who contribute through reporting issues, posting feature
+requests, updating documentation, submitting pull requests or patches,
+and other activities.
+
+We are committed to making participation in this project a
+harassment-free experience for everyone, regardless of level of
+experience, gender, gender identity and expression, sexual orientation,
+disability, personal appearance, body size, race, ethnicity, age,
+religion, or nationality.
+
+Examples of unacceptable behavior by participants include:
+
+- The use of sexualized language or imagery
+- Personal attacks
+- Trolling or insulting/derogatory comments
+- Public or private harassment
+- Publishing other's private information, such as physical or electronic
+  addresses, without explicit permission
+- Other unethical or unprofessional conduct
+
+Project maintainers have the right and responsibility to remove, edit,
+or reject comments, commits, code, wiki edits, issues, and other
+contributions that are not aligned to this Code of Conduct, or to ban
+temporarily or permanently any contributor for other behaviors that they
+deem inappropriate, threatening, offensive, or harmful.
+
+By adopting this Code of Conduct, project maintainers commit themselves
+to fairly and consistently applying these principles to every aspect of
+managing this project. Project maintainers who do not follow or enforce
+the Code of Conduct may be permanently removed from the project team.
+
+This Code of Conduct applies both within project spaces and in public
+spaces when an individual is representing the project or its community.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may
+be reported by contacting a project maintainer at <opensource@shopify.com>.
+All complaints will be reviewed and investigated and will result in a response
+that is deemed necessary and appropriate to the circumstances. Maintainers are
+obligated to maintain confidentiality with regard to the reporter of an incident.
+
+This Code of Conduct is adapted from the Contributor Covenant, version
+1.3.0, available from http://contributor-covenant.org/version/1/3/0/

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    shopify_api (13.4.0)
+    shopify_api (14.0.1)
       activesupport
       concurrent-ruby
       hash_diff
@@ -16,7 +16,7 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (7.1.2)
+    activesupport (7.1.3.2)
       base64
       bigdecimal
       concurrent-ruby (~> 1.0, >= 1.0.2)
@@ -30,26 +30,26 @@ GEM
       public_suffix (>= 2.0.2, < 5.0)
     ast (2.4.2)
     base64 (0.2.0)
-    bigdecimal (3.1.5)
+    bigdecimal (3.1.6)
     byebug (11.1.3)
     coderay (1.1.3)
-    concurrent-ruby (1.2.2)
+    concurrent-ruby (1.2.3)
     connection_pool (2.4.1)
     crack (0.4.5)
       rexml
-    diff-lcs (1.5.0)
-    drb (2.2.0)
-      ruby2_keywords
+    drb (2.2.1)
+    erubi (1.12.0)
     fakefs (1.4.1)
     hash_diff (1.1.1)
     hashdiff (1.0.1)
     httparty (0.21.0)
       mini_mime (>= 1.0.0)
       multi_xml (>= 0.5.2)
-    i18n (1.14.1)
+    i18n (1.14.4)
       concurrent-ruby (~> 1.0)
     json (2.6.2)
-    jwt (2.7.1)
+    jwt (2.8.1)
+      base64
     method_source (1.0.0)
     mini_mime (1.1.5)
     minitest (5.15.0)
@@ -60,25 +60,25 @@ GEM
     oj (3.16.3)
       bigdecimal (>= 3.0)
     openssl (3.2.0)
-    parallel (1.22.1)
-    parser (3.2.2.4)
+    parallel (1.24.0)
+    parser (3.3.0.5)
       ast (~> 2.4.1)
       racc
-    pry (0.14.1)
+    prettier_print (1.2.1)
+    prism (0.21.0)
+    pry (0.14.2)
       coderay (~> 1.1)
       method_source (~> 1.0)
     pry-byebug (3.10.1)
       byebug (~> 11.0)
       pry (>= 0.13, < 0.15)
     public_suffix (4.0.6)
-    racc (1.7.1)
+    racc (1.7.3)
     rainbow (3.1.1)
     rake (13.0.6)
-    rbi (0.0.15)
-      ast
-      parser (>= 2.6.4.0)
+    rbi (0.1.8)
+      prism (>= 0.18.0, < 0.22)
       sorbet-runtime (>= 0.5.9204)
-      unparser
     regexp_parser (2.5.0)
     rexml (3.2.5)
     rubocop (1.36.0)
@@ -98,49 +98,44 @@ GEM
     rubocop-sorbet (0.6.11)
       rubocop (>= 0.90.0)
     ruby-progressbar (1.11.0)
-    ruby2_keywords (0.0.5)
     securerandom (0.3.1)
-    sorbet (0.5.10438)
-      sorbet-static (= 0.5.10438)
-    sorbet-runtime (0.5.10438)
-    sorbet-static (0.5.10438-universal-darwin-21)
-    sorbet-static (0.5.10438-universal-darwin-22)
-    sorbet-static (0.5.10438-x86_64-linux)
-    sorbet-static-and-runtime (0.5.10438)
-      sorbet (= 0.5.10438)
-      sorbet-runtime (= 0.5.10438)
-    spoom (1.1.11)
-      sorbet (>= 0.5.9204)
-      sorbet-runtime (>= 0.5.9204)
+    sorbet (0.5.11230)
+      sorbet-static (= 0.5.11230)
+    sorbet-runtime (0.5.11230)
+    sorbet-static (0.5.11230-universal-darwin)
+    sorbet-static (0.5.11230-x86_64-linux)
+    sorbet-static-and-runtime (0.5.11230)
+      sorbet (= 0.5.11230)
+      sorbet-runtime (= 0.5.11230)
+    spoom (1.2.4)
+      erubi (>= 1.10.0)
+      sorbet-static-and-runtime (>= 0.5.10187)
+      syntax_tree (>= 6.1.1)
       thor (>= 0.19.2)
-    tapioca (0.10.2)
-      bundler (>= 1.17.3)
+    syntax_tree (6.2.0)
+      prettier_print (>= 1.2.0)
+    tapioca (0.12.0)
+      bundler (>= 2.2.25)
       netrc (>= 0.11.0)
       parallel (>= 1.21.0)
-      pry (>= 0.12.2)
-      rbi (~> 0.0.0, >= 0.0.14)
-      sorbet-static-and-runtime (>= 0.5.9204)
-      spoom (~> 1.1.0, >= 1.1.11)
+      rbi (>= 0.1.4, < 0.2)
+      sorbet-static-and-runtime (>= 0.5.10820)
+      spoom (~> 1.2.0, >= 1.2.0)
       thor (>= 1.2.0)
       yard-sorbet
-    thor (1.2.1)
+    thor (1.3.0)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
     unicode-display_width (2.3.0)
-    unparser (0.6.5)
-      diff-lcs (~> 1.3)
-      parser (>= 3.1.0)
     webmock (3.14.0)
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
-    webrick (1.7.0)
-    yard (0.9.28)
-      webrick (~> 1.7.0)
-    yard-sorbet (0.7.0)
+    yard (0.9.34)
+    yard-sorbet (0.8.1)
       sorbet-runtime (>= 0.5)
       yard (>= 0.9)
-    zeitwerk (2.6.12)
+    zeitwerk (2.6.13)
 
 PLATFORMS
   arm64-darwin-21

data/dev.yml

@@ -3,8 +3,9 @@ name: shopify-api
 type: ruby
 
 up:
-  - ruby: 3.0.3
-  - bundler
+  - ruby: 3.0.6
+  - bundler:
+      gemfile: Gemfile
 
 commands:
   console:

data/docs/usage/rest.md

@@ -69,18 +69,18 @@ Typical methods provided for each resources are:
 Full list of methods can be found on each of the resource class.
 - Path:
   - https://github.com/Shopify/shopify-api-ruby/blob/main/lib/shopify_api/rest/resources/#{version}/#{resource}.rb
-- Example for `Order` resource on `2023-04` version:
-  - https://github.com/Shopify/shopify-api-ruby/blob/main/lib/shopify_api/rest/resources/2023_04/order.rb
+- Example for `Order` resource on `2024-01` version:
+  - https://github.com/Shopify/shopify-api-ruby/blob/main/lib/shopify_api/rest/resources/2024_01/order.rb
 
-### Usage Examples
-⚠️ Reference documentation on [shopify.dev](https://shopify.dev/docs/api/admin-rest) contains more examples on how to use each REST Resources.
+### The `save` method
 
-```Ruby
-# Find and update a customer email
-customer = ShopifyAPI::Customer.find(id: customer_id)
-customer.email = "steve-lastnameson@example.com"
-customer.save!
+The `save` or `save!` method on a resource allows you to `create` or `update` that resource.
+
+#### Create a new resource
 
+To create a new resource using the `save` or `save!` method, you can initialize the resource with a hash of values or simply assigning them manually. For example:
+
+```Ruby
 # Create a new product from hash
 product_properties = {
   title: "My awesome product"
@@ -88,10 +88,63 @@ product_properties = {
 product = ShopifyAPI::Product.new(from_hash: product_properties)
 product.save!
 
-# Create a product manually
+# Create a new product manually
 product = ShopifyAPI::Product.new
 product.title = "Another one"
 product.save!
+```
+
+#### Update an existing resource
+
+To update an existing resource using the `save` or `save!` method, you'll need to fetch the resource from Shopify first. Then, you can manually assign new values to the resource before calling `save` or `save!`. For example:
+
+```Ruby
+# Update a product's title
+product = ShopifyAPI::Product.find(id: product_id)
+product.title = "My new title"
+product.save!
+
+# Remove a line item from a draft order
+draft_order = ShopifyAPI::DraftOrder.find(id: draft_order_id)
+
+new_line_items = draft_order.line_items.reject { |line_item| line_item["id"] == 12345 }
+draft_order.line_items = new_line_items
+
+draft_order.save!
+```
+
+> [!IMPORTANT]
+> If you need to unset an existing value,
+> please explicitly set that attribute to `nil` or empty values such as `[]` or `{}`. For example:
+>
+> ```Ruby
+>   # Removes shipping address from draft_order
+>   draft_order.shipping_address = {}
+>   draft_order.save!
+> ```
+>
+> This is because only modified values are sent to the API, so if `shipping_address` is not "modified" to `{}`. It won't be part of the PUT request payload
+
+When updating a resource, only the modified attributes, the resource's primary key, and required parameters are sent to the API. The primary key is usually the `id` attribute of the resource, but it can vary if the `primary_key` method is overwritten in the resource's class. The required parameters are identified using the path parameters of the `PUT` endpoint of the resource.
+
+### Headers
+You can add custom headers to the HTTP calls made by methods like `find`, `delete`, `all`, `count`
+by setting the `headers` attribute on the `ShopifyAPI::Rest::Base` class in an initializer, like so:
+
+```ruby
+ShopifyAPI::Rest::Base.headers = { "X-Custom-Header" => "Custom Value" }
+# `find` will call the API endpoint with the custom header
+ShopifyAPI::Customer.find(id: customer_id)
+```
+
+### Usage Examples
+⚠️ The [API reference documentation](https://shopify.dev/docs/api/admin-rest) contains more examples on how to use each REST Resources.
+
+```Ruby
+# Find and update a customer email
+customer = ShopifyAPI::Customer.find(id: customer_id)
+customer.email = "steve-lastnameson@example.com"
+customer.save!
 
 # Get all orders
 orders = ShopifyAPI::Orders.all

data/docs/usage/webhooks.md

@@ -7,10 +7,37 @@ If using in the Rails framework, we highly recommend you use the [shopify_app](h
 
 ## 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
+  extend ShopifyAPI::Webhooks::WebhookHandler
+
+  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 
+module WebhookHandler
   extend ShopifyAPI::Webhooks::Handler
 
   class << self
@@ -21,25 +48,23 @@ 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", 
+registration = ShopifyAPI::Webhooks::Registry.add_registration(topic: "orders/create",
                                                                delivery_method: :http,
                                                                handler: WebhookHandler,
-                                                               path: 'callback/orders/create') 
+                                                               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
 )

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

@@ -89,7 +89,8 @@ module ShopifyAPI
           end
 
           session_params = T.cast(response.body, T::Hash[String, T.untyped]).to_h
-          session = create_new_session(session_params, auth_query.shop)
+          session = Session.from(shop: auth_query.shop,
+            access_token_response: Oauth::AccessTokenResponse.from_hash(session_params))
 
           cookie = if Context.embedded?
             SessionCookie.new(
@@ -105,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

@@ -89,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/logger.rb

@@ -33,7 +33,7 @@ module ShopifyAPI
       def deprecated(message, version)
         return unless enabled_for_log_level?(:warn)
 
-        raise Errors::FeatureDeprecatedError unless valid_version(version)
+        raise Errors::FeatureDeprecatedError, message unless valid_version(version)
 
         send_to_logger(:warn, message)
       end
@@ -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

data/lib/shopify_api/rest/base.rb

@@ -2,7 +2,6 @@
 # frozen_string_literal: true
 
 require "active_support/inflector"
-require "hash_diff"
 
 module ShopifyAPI
   module Rest
@@ -11,8 +10,9 @@ module ShopifyAPI
       extend T::Helpers
       abstract!
 
-      @has_one = T.let({}, T::Hash[Symbol, Class])
-      @has_many = T.let({}, T::Hash[Symbol, Class])
+      @headers = T.let(nil, T.nilable(T::Hash[T.any(Symbol, String), String]))
+      @has_one = T.let({}, T::Hash[Symbol, T::Class[T.anything]])
+      @has_many = T.let({}, T::Hash[Symbol, T::Class[T.anything]])
       @paths = T.let([], T::Array[T::Hash[Symbol, T.any(T::Array[Symbol], String, Symbol)]])
       @custom_prefix = T.let(nil, T.nilable(String))
       @read_only_attributes = T.let([], T.nilable(T::Array[Symbol]))
@@ -55,12 +55,24 @@ module ShopifyAPI
         sig { returns(T.nilable(String)) }
         attr_reader :custom_prefix
 
-        sig { returns(T::Hash[Symbol, Class]) }
+        sig { returns(T::Hash[Symbol, T::Class[T.anything]]) }
         attr_reader :has_many
 
-        sig { returns(T::Hash[Symbol, Class]) }
+        sig { returns(T::Hash[Symbol, T::Class[T.anything]]) }
         attr_reader :has_one
 
+        sig { returns(T.nilable(T::Hash[T.any(Symbol, String), String])) }
+        attr_accessor :headers
+
+        sig { params(subclass: T::Class[T.anything]).returns(T.untyped) }
+        def inherited(subclass)
+          super
+
+          subclass.define_singleton_method(:headers) do
+            ShopifyAPI::Rest::Base.headers
+          end
+        end
+
         sig do
           params(
             session: T.nilable(Auth::Session),
@@ -74,7 +86,7 @@ module ShopifyAPI
           client = ShopifyAPI::Clients::Rest::Admin.new(session: session)
 
           path = T.must(get_path(http_method: :get, operation: :get, ids: ids))
-          response = client.get(path: path, query: params.compact)
+          response = client.get(path: path, query: params.compact, headers: headers)
 
           instance_variable_get(:"@prev_page_info").value = response.prev_page_info
           instance_variable_get(:"@next_page_info").value = response.next_page_info
@@ -187,6 +199,21 @@ module ShopifyAPI
           custom_prefix ? "#{T.must(custom_prefix).sub(%r{\A/}, "")}/#{match}" : match
         end
 
+        sig do
+          params(
+            http_method: Symbol,
+            operation: Symbol,
+          ).returns(T.nilable(T::Array[Symbol]))
+        end
+        def get_path_ids(http_method:, operation:)
+          found_path = @paths.find do |path|
+            http_method == path[:http_method] && operation == path[:operation]
+          end
+          return nil if found_path.nil?
+
+          T.cast(found_path[:ids], T::Array[Symbol])
+        end
+
         sig do
           params(
             http_method: Symbol,
@@ -205,13 +232,13 @@ module ShopifyAPI
 
           case http_method
           when :get
-            client.get(path: T.must(path), query: params.compact)
+            client.get(path: T.must(path), query: params.compact, headers: headers)
           when :post
-            client.post(path: T.must(path), query: params.compact, body: body || {})
+            client.post(path: T.must(path), query: params.compact, body: body || {}, headers: headers)
           when :put
-            client.put(path: T.must(path), query: params.compact, body: body || {})
+            client.put(path: T.must(path), query: params.compact, body: body || {}, headers: headers)
           when :delete
-            client.delete(path: T.must(path), query: params.compact)
+            client.delete(path: T.must(path), query: params.compact, headers: headers)
           else
             raise Errors::InvalidHttpRequestError, "Invalid HTTP method: #{http_method}"
           end
@@ -341,6 +368,7 @@ module ShopifyAPI
         @client.delete(
           path: T.must(self.class.get_path(http_method: :delete, operation: :delete, entity: self)),
           query: params.compact,
+          headers: self.class.headers,
         )
       rescue ShopifyAPI::Errors::HttpResponseError => e
         @errors.errors << e
@@ -355,10 +383,16 @@ module ShopifyAPI
       sig { params(update_object: T::Boolean).void }
       def save(update_object: false)
         method = deduce_write_verb
+
+        body = {
+          self.class.json_body_name => attributes_to_update.merge(build_required_attributes(http_method: method)),
+        }
+
         response = @client.public_send(
           method,
-          body: { self.class.json_body_name => attributes_to_update },
+          body: body,
           path: deduce_write_path(method),
+          headers: self.class.headers,
         )
 
         if update_object
@@ -374,22 +408,34 @@ module ShopifyAPI
 
       sig { returns(T::Hash[String, String]) }
       def attributes_to_update
-        original_state_for_update = original_state.reject do |attribute, _|
+        updatable_attributes = original_state.reject do |attribute, _|
           self.class.read_only_attributes&.include?("@#{attribute}".to_sym)
         end
 
-        diff = HashDiff::Comparison.new(
-          deep_stringify_keys(original_state_for_update),
-          deep_stringify_keys(to_hash(true)),
-        ).left_diff
+        stringified_updatable_attributes = deep_stringify_keys(updatable_attributes)
+        stringified_new_attributes = deep_stringify_keys(to_hash(true))
+        ShopifyAPI::Utils::AttributesComparator.compare(
+          stringified_updatable_attributes,
+          stringified_new_attributes,
+        )
+      end
 
-        diff.each do |attribute, value|
-          if value.is_a?(Hash) && value[0] == HashDiff::NO_VALUE
-            diff[attribute] = send(attribute)
-          end
+      sig { params(http_method: Symbol).returns(T::Hash[String, T.untyped]) }
+      def build_required_attributes(http_method:)
+        required_attributes = {}
+
+        primary_key_value = send(self.class.primary_key)
+        unless primary_key_value.nil?
+          required_attributes[self.class.primary_key] = primary_key_value
+        end
+
+        path_ids = deduce_path_ids(http_method)
+        path_ids&.each do |path_id|
+          path_id_value = send(path_id)
+          required_attributes[path_id.to_s] = path_id_value unless path_id_value.nil?
         end
 
-        diff
+        required_attributes
       end
 
       sig { returns(Symbol) }
@@ -409,6 +455,18 @@ module ShopifyAPI
         path
       end
 
+      sig { params(method: Symbol).returns(T.nilable(T::Array[Symbol])) }
+      def deduce_path_ids(method)
+        path_ids = self.class.get_path_ids(http_method: method, operation: method)
+
+        if path_ids.nil?
+          method = method == :post ? :put : :post
+          path_ids = self.class.get_path_ids(http_method: method, operation: method)
+        end
+
+        path_ids
+      end
+
       sig { params(hash: T::Hash[T.any(String, Symbol), T.untyped]).returns(T::Hash[String, String]) }
       def deep_stringify_keys(hash)
         hash.each_with_object({}) do |(key, value), result|
@@ -440,7 +498,7 @@ module ShopifyAPI
       sig do
         params(
           element: T.nilable(T.any(T::Hash[String, T.untyped], ShopifyAPI::Rest::Base)),
-          attribute_class: Class,
+          attribute_class: T::Class[T.anything],
           saving: T::Boolean,
         ).returns(T.nilable(T::Hash[String, T.untyped]))
       end

data/lib/shopify_api/utils/attributes_comparator.rb

@@ -0,0 +1,85 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "hash_diff"
+
+module ShopifyAPI
+  module Utils
+    module AttributesComparator
+      class << self
+        extend T::Sig
+
+        sig do
+          params(
+            original_attributes: T::Hash[String, T.untyped],
+            updated_attributes: T::Hash[String, T.untyped],
+          ).returns(T::Hash[String, T.untyped])
+        end
+        def compare(original_attributes, updated_attributes)
+          attributes_diff = HashDiff::Comparison.new(
+            original_attributes,
+            updated_attributes,
+          ).left_diff
+
+          update_value = build_update_value(
+            attributes_diff,
+            reference_values: updated_attributes,
+          )
+
+          update_value
+        end
+
+        sig do
+          params(
+            diff: T::Hash[String, T.untyped],
+            path: T::Array[String],
+            reference_values: T::Hash[String, T.untyped],
+          ).returns(T::Hash[String, T.untyped])
+        end
+        def build_update_value(diff, path: [], reference_values: {})
+          new_hash = {}
+
+          diff.each do |key, value|
+            current_path = path + [key.to_s]
+
+            if value.is_a?(Hash)
+              has_numbered_key = value.keys.any? { |k| k.is_a?(Integer) }
+              ref_value = T.unsafe(reference_values).dig(*current_path)
+
+              if has_numbered_key && ref_value.is_a?(Array)
+                new_hash[key] = ref_value
+              else
+                new_value = build_update_value(value, path: current_path, reference_values: reference_values)
+
+                # Only add to new_hash if the user intentionally updates
+                # to empty value like `{}` or `[]`. For example:
+                #
+                # original = { "a" => { "foo" => 1 } }
+                # updated = { "a" => {} }
+                # diff = { "a" => { "foo" => HashDiff::NO_VALUE } }
+                # key = "a", new_value = {}, ref_value = {}
+                # new_hash = { "a" => {} }
+                #
+                # In addition, we omit cases where after removing `HashDiff::NO_VALUE`
+                # we only have `{}` left. For example:
+                #
+                # original = { "a" => { "foo" => 1, "bar" => 2} }
+                # updated = { "a" => { "foo" => 1 } }
+                # diff = { "a" => { "bar" => HashDiff::NO_VALUE } }
+                # key = "a", new_value = {}, ref_value = { "foo" => 1 }
+                # new_hash = {}
+                #
+                # new_hash is empty because nothing changes
+                new_hash[key] = new_value if !new_value.empty? || ref_value.empty?
+              end
+            elsif value != HashDiff::NO_VALUE
+              new_hash[key] = value
+            end
+          end
+
+          new_hash
+        end
+      end
+    end
+  end
+end

data/lib/shopify_api/utils/hmac_validator.rb

@@ -27,7 +27,7 @@ module ShopifyAPI
         def validate_signature(verifiable_query, secret)
           received_signature = verifiable_query.hmac
           computed_signature = compute_signature(verifiable_query.to_signable_string, secret)
-          OpenSSL.secure_compare(computed_signature, received_signature)
+          OpenSSL.secure_compare(computed_signature, T.must(received_signature))
         end
 
         sig { params(signable_string: String, secret: String).returns(String) }

data/lib/shopify_api/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module ShopifyAPI
-  VERSION = "13.4.0"
+  VERSION = "14.0.1"
 end

data/lib/shopify_api/webhooks/handler.rb

@@ -3,13 +3,36 @@
 
 module ShopifyAPI
   module Webhooks
+    class WebhookMetadata < T::Struct
+      const :topic, String
+      const :shop, String
+      const :body, T::Hash[String, T.untyped]
+      const :api_version, String
+      const :webhook_id, String
+    end
+
     module Handler
+      include Kernel
       extend T::Sig
       extend T::Helpers
       interface!
 
-      sig { abstract.params(topic: String, shop: String, body: T::Hash[String, T.untyped]).void }
+      sig do
+        abstract.params(topic: String, shop: String, body: T::Hash[String, T.untyped]).void
+      end
       def handle(topic:, shop:, body:); end
     end
+
+    module WebhookHandler
+      include Kernel
+      extend T::Sig
+      extend T::Helpers
+      interface!
+
+      sig do
+        abstract.params(data: WebhookMetadata).void
+      end
+      def handle(data:); end
+    end
   end
 end

data/lib/shopify_api/webhooks/registration.rb

@@ -13,7 +13,7 @@ module ShopifyAPI
       sig { returns(String) }
       attr_reader :topic
 
-      sig { returns(T.nilable(Handler)) }
+      sig { returns(T.nilable(T.any(Handler, WebhookHandler))) }
       attr_reader :handler
 
       sig { returns(T.nilable(T::Array[String])) }
@@ -23,7 +23,7 @@ module ShopifyAPI
       attr_reader :metafield_namespaces
 
       sig do
-        params(topic: String, path: String, handler: T.nilable(Handler),
+        params(topic: String, path: String, handler: T.nilable(T.any(Handler, WebhookHandler)),
           fields: T.nilable(T.any(String, T::Array[String])),
           metafield_namespaces: T.nilable(T::Array[String])).void
       end

data/lib/shopify_api/webhooks/registry.rb

@@ -17,7 +17,7 @@ module ShopifyAPI
           params(topic: String,
             delivery_method: Symbol,
             path: String,
-            handler: T.nilable(Handler),
+            handler: T.nilable(T.any(Handler, WebhookHandler)),
             fields: T.nilable(T.any(String, T::Array[String])),
             metafield_namespaces: T.nilable(T::Array[String])).void
         end
@@ -193,7 +193,18 @@ module ShopifyAPI
             raise Errors::NoWebhookHandler, "No webhook handler found for topic: #{request.topic}."
           end
 
-          handler.handle(topic: request.topic, shop: request.shop, body: request.parsed_body)
+          if handler.is_a?(WebhookHandler)
+            handler.handle(data: WebhookMetadata.new(topic: request.topic, shop: request.shop,
+              body: request.parsed_body, api_version: request.api_version, webhook_id: request.webhook_id))
+          else
+            handler.handle(topic: request.topic, shop: request.shop, body: request.parsed_body)
+            warning = <<~WARNING
+              DEPRECATED: Use ShopifyAPI::Webhooks::WebhookHandler#handle instead of
+              ShopifyAPI::Webhooks::Handler#handle.
+              https://github.com/Shopify/shopify-api-ruby/blob/main/docs/usage/webhooks.md#create-a-webhook-handler
+            WARNING
+            ShopifyAPI::Logger.deprecated(warning, "15.0.0")
+          end
         end
 
         private

data/lib/shopify_api/webhooks/request.rb

@@ -22,6 +22,16 @@ module ShopifyAPI
         T.cast(@headers["x-shopify-shop-domain"], String)
       end
 
+      sig { returns(String) }
+      def api_version
+        T.cast(@headers["x-shopify-api-version"], String)
+      end
+
+      sig { returns(String) }
+      def webhook_id
+        T.cast(@headers["x-shopify-webhook-id"], String)
+      end
+
       sig { override.returns(String) }
       def to_signable_string
         @raw_body

data/lib/shopify_api.rb

@@ -16,6 +16,7 @@ require "concurrent"
 
 require_relative "shopify_api/inflector"
 require_relative "shopify_api/admin_versions"
+require_relative "shopify_api/webhooks/handler"
 
 loader = Zeitwerk::Loader.for_gem
 loader.inflector = ShopifyAPI::Inflector.new(__FILE__)

data/shopify_api.gemspec

@@ -30,7 +30,7 @@ Gem::Specification.new do |s|
 
   s.license = "MIT"
 
-  s.required_ruby_version = ">= 2.6"
+  s.required_ruby_version = ">= 3.0"
 
   s.add_runtime_dependency("activesupport")
   s.add_runtime_dependency("concurrent-ruby")

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: shopify_api
 version: !ruby/object:Gem::Version
-  version: 13.4.0
+  version: 14.0.1
 platform: ruby
 authors:
 - Shopify
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-01-15 00:00:00.000000000 Z
+date: 2024-03-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -276,6 +276,7 @@ files:
 - BREAKING_CHANGES_FOR_OLDER_VERSIONS.md
 - BREAKING_CHANGES_FOR_V10.md
 - CHANGELOG.md
+- CODE_OF_CONDUCT.md
 - CONTRIBUTING.md
 - Gemfile
 - Gemfile.lock
@@ -302,9 +303,11 @@ files:
 - lib/shopify_api/auth/auth_scopes.rb
 - lib/shopify_api/auth/jwt_payload.rb
 - lib/shopify_api/auth/oauth.rb
+- lib/shopify_api/auth/oauth/access_token_response.rb
 - lib/shopify_api/auth/oauth/auth_query.rb
 - lib/shopify_api/auth/oauth/session_cookie.rb
 - lib/shopify_api/auth/session.rb
+- lib/shopify_api/auth/token_exchange.rb
 - lib/shopify_api/clients/graphql/admin.rb
 - lib/shopify_api/clients/graphql/client.rb
 - lib/shopify_api/clients/graphql/storefront.rb
@@ -938,6 +941,7 @@ files:
 - lib/shopify_api/rest/resources/2024_01/user.rb
 - lib/shopify_api/rest/resources/2024_01/variant.rb
 - lib/shopify_api/rest/resources/2024_01/webhook.rb
+- lib/shopify_api/utils/attributes_comparator.rb
 - lib/shopify_api/utils/graphql_proxy.rb
 - lib/shopify_api/utils/hmac_validator.rb
 - lib/shopify_api/utils/http_utils.rb
@@ -1022,14 +1026,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.6'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.4
+rubygems_version: 3.5.6
 signing_key: 
 specification_version: 4
 summary: The gem for accessing the Shopify API