shopify_api 13.1.0 → 13.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 330b033c35e9b3b421a89e937cd50f80cd9439cdfc344c9809ef16746971a6e0
-  data.tar.gz: 522ce45ee19bc4208b3ee29eb95f620cfc473757507075da9fcb679ba63946a8
+  metadata.gz: d837a507476d9d344892dc7667fed5cf1fcc20ac37c5bc5488e4a2583b3dab5c
+  data.tar.gz: b385d9e275df49f00fd8aac9bba99c6df69a9f111afd92285e12e2b411d734e5
 SHA512:
-  metadata.gz: 884e25968587509d4c7643e128939832613dfc3c335936b517c574b5d4ad2f83e0a7ddb19af55214a04b27a72a4eb9fa1e23e7bf992031120e5c4bb96e67f934
-  data.tar.gz: b163f2f6290fdf41ca6a5f10c3b4732f1e9f9404d56d560a83db657f70b55f39edc2916660ce0ddf4e24bb8faf4049b6ce55b93dc651ef7fe6f2842483482c2a
+  metadata.gz: 0f1de95b3fd22f3f7494914d74647cb51607e5302c3bbf23c7d29e159f1a90f21509d2c7ade5606287dd698ce67e7ec018bf0fa0a099f4034eefdac363d0f20f
+  data.tar.gz: 58e4c9c8c67bed4996f056e0219d45c38d589feb2e04e3902302afb71e3f282b2138f85b813d394a953c7c323cfd2f42c71464931fdd7f83327c145921b18d96

data/.github/CODEOWNERS

@@ -1 +1 @@
-*       @shopify/learn-libs-superteam
+*       @Shopify/client-libraries-app-templates

data/.github/workflows/build.yml

@@ -20,6 +20,10 @@ jobs:
         uses: ruby/setup-ruby@v1
         with:
           ruby-version: ${{ matrix.version }}
+      - name: Install OpenSSL
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libssl-dev
       - name: Run Bundle Commands
         run: |
           bundle config set --with docs

data/.rubocop.yml

@@ -57,6 +57,8 @@ Layout/EmptyLineAfterGuardClause:
   Enabled: true
 Style/GlobalStdStream:
   Enabled: true
+Style/OpenStructUse:
+  Enabled: false
 Layout/LineLength:
   Exclude:
     - "test/clients/*"

data/BREAKING_CHANGES_FOR_V10.md

@@ -0,0 +1,231 @@
+# Breaking change notice for version 10.0.0
+
+We've rewritten this library for v10, so that it provides all essential features for a Shopify app without depending on the [Active Resource](https://github.com/rails/activeresource) or [graphql-client](https://github.com/github/graphql-client) libraries.
+
+#### Table of Contents
+- [New Features](#new-features)
+- [Upgrade Guide](#upgrade-guide)
+  - [1. Configuration Changes](#1-configuration-changes)
+  - [2. Session Changes](#2-session-changes)
+    - [ShopifyAPI::Auth::Session](#shopifyapiauthsession)
+  - [3. API Client Changes](#3-api-client-changes)
+    - [GraphQL](#graphql)
+    - [Rest](#rest)
+      - [Using Rest Resources](#using-rest-resources)
+      - [Using Rest Admin Client](#using-rest-admin-client)
+    - [Generic HTTP Client](#generic-http-client)
+- [Useful References](#useful-references)
+
+## New Features
+Here are the main features version 10 provides:
+
+- OAuth support, both with online and offline tokens.
+- Full, transparent support for JWT sessions for embedded apps and cookies for non-embedded ones.
+  - Removal of support for 3rd party cookies which are increasingly more difficult to use with modern browsers.
+- Admin API support
+  - Auto-generated, version-specific REST resources which are similar to `ActiveResource` (though not identical), that provide methods for all endpoints defined in our [REST API reference](https://shopify.dev/docs/api/admin-rest), as well as direct definition of known attributes.
+  - A GraphQL client that doesn't rely on the ActiveResource implementation for REST.
+- Webhook management, with features for adding handlers and registering them with Shopify.
+- Storefront GraphQL API support
+
+Please refer to the [Getting Started](docs/getting_started.md) guide in this repository for instructions on how to use each of these components.
+
+### Reasoning
+- Browsers stopped allowing 3rd party cookies, even after jumping through several [ITP](https://webkit.org/tracking-prevention-policy/) hoops, which made the code
+even more more complex and error prone.
+    - Session tokens and `authenticatedFetch` were introduced to make it possible for apps to authenticate requests without depending on cookies.
+    - The gem was too closely tied to rails on how it sets up sessions (which worked for cookies), so we had to detach the library from rails
+  in order to be able to work with both cookies and session tokens.
+- We previously relied on an `omniauth-oauth2` strategy that worked fine when cookies were the only option. But it became increasingly
+awkward when we moved towards session tokens, which meant re-writing the OAuth process in the gem as a whole.
+  - Introducing a DB stored session persistence rather than cookie stored.
+- Most feedback we got previously was due to the `ActiveResource` classes failing out of sync with the API because:
+  1. We have some endpoints that didn't 100% follow REST convention;
+  2. We had a single class for each resource and manually maintained custom methods that didn't work across API versions.
+
+- To solve the REST problems:
+    - We were adding support for auto-generated, version-specific resources for other languages, we decided to add them for Ruby too.
+  But those same instances where the API doesn't follow convention would become problematic. Thus we opted for the most explicit option where **every** method was "custom" rather than just some, so that the resources were always consistent.
+
+## Upgrade Guide
+With this, a lot changed in how apps access the library. Here are the updates you should make when migrating to v10:
+
+### 1. Configuration Changes
+#### Removed ShopifyAPI::Base
+`ShopifyAPI::Base` class has been removed. Previous versions of this gem used this class to configure API request setting like:
+  - **API request version**
+    - **Previously**: Set by `ShopifyAPI::Base.api_version = "xxxx"`
+    - **Change**: Configured `api_version` in [ShopifyAPI::Context.setup](#shopifyapicontextsetup)
+  - **Set `User-Agent` on API request header**
+    - **Previously**: Set by `ShopifyAPI::Base.header["User-Agent"] = "xxxxx"`
+    - **Change**: Configured `user_agent_prefix` in [ShopifyAPI::Context.setup](#shopifyapicontextsetup)
+  - **Set custom headers on API requests**
+    - **Previously**: Set by `ShopifyAPI::Base.header["User-Agent"] = "xxxxx"`
+    - **Change**: Custom headers can be added to requests when you use [`ShopifyAPI::Clients::HttpRequest`](https://github.com/Shopify/shopify-api-ruby/blob/main/lib/shopify_api/clients/http_request.rb#L14)
+
+#### ShopifyAPI::Context.setup
+Initializing the `ShopifyAPI::Context` with the parameters of your app by calling `ShopifyAPI::Context.setup` (example below) when your app starts (e.g `application.rb` in a Rails app).
+This class holds global configurations for your app and defines how the library behaves.
+
+```ruby
+ShopifyAPI::Context.setup(
+  api_key: "<api-key>",
+  api_secret_key: "<api-secret-key>",
+  host_name: "<application-host-name>",
+  scope: "read_orders,read_products,etc",
+  is_embedded: true, # Set to true if you are building an embedded app
+  is_private: false, # Set to true if you are building a private app
+  api_version: "2021-01" # The version of the API you would like to use
+  user_agent_prefix: "<user_agent_prefix>" # Set a custom prefix for "User-Agent" header when making API requests
+  ###
+)
+```
+
+See other fields accepted during `ShopifyAPI::Context` setup in [context.rb](https://github.com/Shopify/shopify-api-ruby/blob/main/lib/shopify_api/context.rb).
+
+### 2. Session Changes
+`ShopifyAPI::Base` class has been removed, you can no longer activate session using `ShopifyAPI::Base.activate_session`. Instead, you can use
+`ShopifyAPI::Context.activate_session` to set the active session ([`ShopifyAPI::Auth::Session`](#shopifyapiauthsesion)).
+If you're using the [ShopifyApp](https://github.com/Shopify/shopify_app) gem in a Rails app, you don't have to manually set the active session if you use the included `ActiveSupport` concerns. See [Session Docs](https://github.com/Shopify/shopify_app/blob/main/docs/shopify_app/sessions.md) from ShopifyApp gem.
+
+You can also manually specify the session to use without setting the active session by passing in the session object ([`ShopifyAPI::Auth::Session`](#shopifyapiauthsesion)) when instantiating new `ShopifyAPI::Clients` objects.
+If session is `nil`, it'll default to use active session from `ShopifyAPI::Context.active_session`.
+
+```ruby
+# Manually specifying a session (ShopifyAPI::Auth::Session) in API clients.
+
+# GraphQL Client
+graphql_client = ShopifyAPI::Clients::Graphql::Admin.new(session: session)
+
+# REST Client
+rest_client = ShopifyAPI::Clients::Rest::Admin.new(session: session)
+
+# Using REST Resources
+rest_resource = ShopifyAPI::Shop.new(session: session)
+```
+
+##### ShopifyAPI::Auth::Session
+If you're building a Rails app, it is highly recommended for you to use the [`ShopifyApp` gem to perform OAuth and session storage](https://github.com/Shopify/shopify_app/blob/main/docs/shopify_app/sessions.md).
+
+If you're not using Rails, please see the [Performing OAuth](./docs/usage/oauth.md) guide on how to perform OAuth to retrieve and store sessions.
+
+### 3. API Client Changes
+
+#### GraphQL
+- We deprecated the dependency of [graphql-client](https://rubygems.org/gems/graphql-client) gem. You must refactor your existing query and response parsing to use our new GraphQL HTTP Client classes.
+  - [Admin API Client](https://github.com/Shopify/shopify-api-ruby/blob/main/lib/shopify_api/clients/graphql/admin.rb)
+  - [Storefront API Client](https://github.com/Shopify/shopify-api-ruby/blob/main/lib/shopify_api/clients/graphql/storefront.rb)
+- There is no need to dump the schema to a local JSON file before using it anymore.
+- The api version used to be set on `ShopifyAPI::Base.api_version`, however that's now deprecated.
+You may specify a specific version when initializing your client, or it'll infer to `ShopifyAPI::Context.api_version` as default.
+
+⚠️ See other Admin API usage in ["Make a GraphQL API call" documentation](https://github.com/Shopify/shopify-api-ruby/blob/main/docs/usage/graphql.md).
+
+⚠️ See Storefront API client usage in ["Make a Storefront API call" documentation](https://github.com/Shopify/shopify-api-ruby/blob/main/docs/usage/graphql.md).
+
+###### Example refactor
+ShopifyAPI Client v9
+```ruby
+ShopifyAPI::Base.api_version = "2023-04"
+client = ShopifyAPI::GraphQL.client
+
+SHOP_NAME_QUERY = client.parse <<-'GRAPHQL'
+  {
+    shop {
+      name
+    }
+  }
+GRAPHQL
+
+result = client.query(SHOP_NAME_QUERY)
+shop_name = result.data.shop.name
+```
+
+ShopifyAPI Client v10+
+```ruby
+client = ShopifyAPI::Clients::Graphql::Admin.new(session: session, api_version: "2023-04")
+# session must be an instance of ShopifyAPI::Auth::Session, see Section - [2. Session Changes]
+
+SHOP_NAME_QUERY =<<~QUERY
+  {
+    shop {
+      name
+    }
+  }
+QUERY
+
+response = client.query(query: query)
+shop_name = response.body["data"]["shop"]["name"]
+```
+
+#### REST
+##### Using REST Resources
+- The use of `ActiveResource` has been deprecated, REST API requests must now be refactored to use the new format that better represents our REST API schema.
+- Previously the api_version is specified in `ShopifyAPI::Base.api_version`, that has been deprecated. It's now configured in [`ShopifyAPI::Context.setup`](#shopifyapicontextsetup).
+
+###### Example refactor
+⚠️ You can find detailed examples on how each of the resource endpoints work in our [REST reference documentation](https://shopify.dev/docs/api/admin-rest).
+
+Please see below a (non-exhaustive) list of common replacements to guide you in your updates, using the `Order` resource as an example.
+For more detail, see [`order` reference documentation's](https://shopify.dev/docs/api/admin-rest/2023-07/resources/order#top) ruby example.
+
+|Usage | Before| After |
+| -----| --- | --- |
+|Find partially paid orders| `Order.find(:all, params: {financial_status: "partially_paid"})`| `Order.all(financial_status: "partially_paid")` |
+|Find order by ID `<id>` | `Order.find(<id>)` | `Order.find(id: <id>)` |
+|Update an order's fulfillment status|`order = Order.find<id>`<br/>`order.fulfillment_status = "fulfilled"`<br/>`order.note = "Fulfilled on September 6, 2023"`<br/>`order.save`|`order = Order.find(id: <id>)`<br/>`order.fulfillment_status = "fulfilled"`<br/>`order.note = "Fulfilled on September 6, 2023"`<br/>`order.save!`|
+|Close an order| `order = Order.new(<id>)`<br/>`order.post(:close)` | `order = Order.find(id: <id>)`<br/>`order.close` |
+|Delete an order| `order = Order.new(<id>)`<br/>`order.delete`       | `Order.delete(id: <id>)` |
+
+###### Note on resource connections
+Previously we added helper methods to load related resource connections like [`orders.transactions`](https://github.com/Shopify/shopify-api-ruby/blob/97eec35fb76afbce1d948cee2963791457e934da/lib/shopify_api/resources/order.rb#L20).
+After the upgrade, only connected properties listed in the REST API will be supported.
+
+For example:
+- `order.transactions` is not supported because `transactions` is not a property of the `Order` resource.
+- `order.customer` is supported because `customer` is a property of the `Order` resource.
+
+[See the full list of `Order` properties here.](https://shopify.dev/docs/api/admin-rest/2023-07/resources/order#resource-object)
+
+##### Using REST Admin Client
+If you do not want to use the REST resource classes, you can use our REST Admin client directly to make HTTP requests.
+
+⚠️ See other REST client usage in ["Make a REST API call" documentation](https://github.com/Shopify/shopify-api-ruby/blob/main/docs/usage/rest.md).
+
+Example:
+```ruby
+# Create a new client.
+client = ShopifyAPI::Clients::Rest::Admin.new(session: session)
+
+# Update title for product with ID <id>
+body = {
+  product: {
+    title: "My cool product"
+  }
+}
+
+# Use `client.put` to send your request to the specified Shopify Admin REST API endpoint.
+client.put(path: "products/<id>.json", body: body)
+```
+
+#### Generic HTTP Client
+We added a new generic [HttpClient](https://github.com/Shopify/shopify-api-ruby/blob/main/lib/shopify_api/clients/http_client.rb) wrapper to make requests and handle Shopify specific errors. All of the REST and GraphQL Clients use this HTTP Client in its foundation.
+You can use this to make direct HTTP API calls easily.
+See how the GraphQL Client makes a request with this HttpClient class in its [implementation here](https://github.com/Shopify/shopify-api-ruby/blob/main/lib/shopify_api/clients/graphql/client.rb#L33-L45).
+
+## Useful references
+
+ShopifyAPI:
+- [Performing OAuth](https://github.com/Shopify/shopify-api-ruby/blob/main/docs/usage/oauth.md)
+- [Make a GraphQL API Call](https://github.com/Shopify/shopify-api-ruby/blob/main/docs/usage/graphql.md)
+- [Make a Storefront API Call (GraphQL)](https://github.com/Shopify/shopify-api-ruby/blob/main/docs/usage/graphql_storefront.md)
+- [Make a REST API Call](https://github.com/Shopify/shopify-api-ruby/blob/main/docs/usage/rest.md)
+- [Webhooks](https://github.com/Shopify/shopify-api-ruby/blob/main/docs/usage/webhooks.md)
+
+ShopifyApp Gem (Rails):
+- [Authentication](https://github.com/Shopify/shopify_app/blob/main/docs/shopify_app/authentication.md)
+- [Sessions](https://github.com/Shopify/shopify_app/blob/main/docs/shopify_app/sessions.md)
+
+Shopify API:
+- [Admin GraphQL Reference](https://shopify.dev/docs/api/admin-graphql)
+- [Admin REST Reference](https://shopify.dev/docs/api/admin-rest)

data/CHANGELOG.md

@@ -4,6 +4,30 @@ Note: For changes to the API, see https://shopify.dev/changelog?filter=api
 
 ## Unreleased
 
+## 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.
+- [#1257](https://github.com/Shopify/shopify-api-ruby/pull/1257) Added support for the 2024-01 API version. This also includes a fix for the `for_hash` option when creating resources.
+
+## 13.3.1
+
+- [#1244](https://github.com/Shopify/shopify-api-ruby/pull/1244) Add `expired?` to `ShopifyAPI::Auth::Session` to check if the session is expired (mainly for user sessions)
+- [#1249](https://github.com/Shopify/shopify-api-ruby/pull/1249) Fix bug where mandatory webhooks could not be processed
+- [#1250](https://github.com/Shopify/shopify-api-ruby/pull/1250) Remove rails methods .empty? .present? that were breaking CI
+
+## 13.3.0
+
+- [#1241](https://github.com/Shopify/shopify-api-ruby/pull/1241) Add `api_host` to `ShopifyAPI::Context.setup`, allowing the API host to be overridden in `ShopifyAPI::Clients::HttpClient`. This context option is intended for internal Shopify use only.
+- [#1237](https://github.com/Shopify/shopify-api-ruby/pull/1237) Skip mandatory webhook topic registration/unregistrations
+- [#1239](https://github.com/Shopify/shopify-api-ruby/pull/1239) Update `OAuth.validate_auth_callback` to use `ShopifyApi::Clients::HttpClient`.
+
+## 13.2.0
+
+- [#1183](https://github.com/Shopify/shopify-api-ruby/pull/1189) Added string array support for fields parameter in Webhook::Registry
+- [1208](https://github.com/Shopify/shopify-api-ruby/pull/1208) Fix CustomerAddress and FulfillmentRequest methods
+- [1225](https://github.com/Shopify/shopify-api-ruby/pull/1225) Support for 2023_10 API version
+- [#1186](https://github.com/Shopify/shopify-api-ruby/pull/1186) Extend webhook registration to support metafield_namespaces
+
 ## 13.1.0
 
 - [#1183](https://github.com/Shopify/shopify-api-ruby/pull/1183) Added support for API version 2023-07
@@ -14,7 +38,7 @@ Note: For changes to the API, see https://shopify.dev/changelog?filter=api
 
 - [#1140](https://github.com/Shopify/shopify-api-ruby/pull/1140) ⚠️ [Breaking] Reformat Http error messages to be JSON parsable.
 - [#1142](https://github.com/Shopify/shopify-api-ruby/issues/1142) Restore API version 2022-04, in alignment with [this](https://shopify.dev/changelog/action-required-support-for-api-version-2022-04-extended-to-june-30-2023) changelog notice.
-- [#1155](https://github.com/Shopify/shopify-api-ruby/pull/1155) ⚠️ [Breaking] Remove session storage that was deprecated with [#1055](https://github.com/Shopify/shopify-api-ruby/pull/1055). ⚠️ [Breaking] GraphQL Proxy now requires `session` to be passed as an argument.
+- [#1155](https://github.com/Shopify/shopify-api-ruby/pull/1155) ⚠️ [Breaking] Remove session storage that was deprecated with [#1055](https://github.com/Shopify/shopify-api-ruby/pull/1055). To upgrade, remove `session_storage` from your API context block. ⚠️ [Breaking] GraphQL Proxy now requires `session` to be passed as an argument.
 - [#1150](https://github.com/Shopify/shopify-api-ruby/pull/1150) [Patch] Add support for Event topic names.
 
 ## 12.5.0

data/CONTRIBUTING.md

@@ -1,9 +1,34 @@
 
 Submitting Issues
 -----------------
+Submitting Issues
 
 Please open an issue here if you encounter a specific bug with this API client library or if something is documented here https://shopify.dev/docs/apps but is missing from this package.
 
 General questions about the Shopify API and usage of this package (not necessarily a bug) should be posted on the [Shopify forums](https://community.shopify.com/c/partners-and-developers/ct-p/appdev).
 
 When in doubt, post on the forum first. You'll likely have your questions answered more quickly if you post there; more people monitor the forum than Github.
+
+In order for us to best triage the issue, please include steps to reproduce the issue as well as the impacted feature.
+
+## Roadmap
+
+The focus of development efforts by maintainers of this project a roadmap will be proposed via PR and accessible at any point in the ROADMAP.md file.
+
+Working with a pull request modify the [ROADMAP.md](https://github.com/Shopify/shopify-api-ruby/blob/aa0b7f9a5a9095ca11f3f93f9aecc72e8daa6bce/ROADMAP.md) allows us to invite community feedback on the direction while not adding another communication avenue. While there are certainly better tools for the job than a markdown file for this, we are aiming to keep a minimal toolset to help us better manage the communication channels that we have open.
+
+If there are concerns with the direction and priorities of the maintainers, this roadmap PR is the appropriate place to share your concerns.
+
+## Submitting Pull Requests
+
+We welcome pull requests and help from the community! PRs fixing bugs will take priority to triaging proposed net new functionality. If you do want to add a feature, we recommend opening an issue first exploring the appetite of the community / maintainers to ensure there is alignment on direction before you spend time on the PR.
+
+## Gem Architecture
+Understanding how all the components of the Shopify App development stack work together will help best understand what level of abstraction a feature is meant to be applied. Please consider this architecture before introducing new functionally to ensure it is in the right place:
+
+| Gem Name | Job |
+|---|---|
+| Shopify API (this gem) | Obtain a session, clients for APIs (REST, GraphQL), error handling, webhook management |
+| REST Resources | Interfaces to the APIs. Response casting into defined objects with attributes/methods |
+| Shopify App | Build Shopify app using Rails conventions. Oauth, webhook processing, persistence, etc |
+| App Template | Template demonstrating how to use all these components in one starting boilerplate application |

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    shopify_api (13.1.0)
+    shopify_api (13.4.0)
       activesupport
       concurrent-ruby
       hash_diff
@@ -16,20 +16,30 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (7.0.6)
+    activesupport (7.1.2)
+      base64
+      bigdecimal
       concurrent-ruby (~> 1.0, >= 1.0.2)
+      connection_pool (>= 2.2.5)
+      drb
       i18n (>= 1.6, < 2)
       minitest (>= 5.1)
+      mutex_m
       tzinfo (~> 2.0)
     addressable (2.8.0)
       public_suffix (>= 2.0.2, < 5.0)
     ast (2.4.2)
+    base64 (0.2.0)
+    bigdecimal (3.1.5)
     byebug (11.1.3)
     coderay (1.1.3)
     concurrent-ruby (1.2.2)
+    connection_pool (2.4.1)
     crack (0.4.5)
       rexml
     diff-lcs (1.5.0)
+    drb (2.2.0)
+      ruby2_keywords
     fakefs (1.4.1)
     hash_diff (1.1.1)
     hashdiff (1.0.1)
@@ -40,19 +50,20 @@ GEM
       concurrent-ruby (~> 1.0)
     json (2.6.2)
     jwt (2.7.1)
-    language_server-protocol (3.17.0.1)
     method_source (1.0.0)
-    mini_mime (1.1.2)
+    mini_mime (1.1.5)
     minitest (5.15.0)
     mocha (1.13.0)
     multi_xml (0.6.0)
+    mutex_m (0.2.0)
     netrc (0.11.0)
-    oj (3.15.0)
-    openssl (3.1.0)
+    oj (3.16.3)
+      bigdecimal (>= 3.0)
+    openssl (3.2.0)
     parallel (1.22.1)
-    parser (3.1.2.1)
+    parser (3.2.2.4)
       ast (~> 2.4.1)
-    prettier_print (0.1.0)
+      racc
     pry (0.14.1)
       coderay (~> 1.1)
       method_source (~> 1.0)
@@ -60,6 +71,7 @@ GEM
       byebug (~> 11.0)
       pry (>= 0.13, < 0.15)
     public_suffix (4.0.6)
+    racc (1.7.1)
     rainbow (3.1.1)
     rake (13.0.6)
     rbi (0.0.15)
@@ -85,12 +97,9 @@ GEM
       rubocop (~> 1.35)
     rubocop-sorbet (0.6.11)
       rubocop (>= 0.90.0)
-    ruby-lsp (0.3.2)
-      language_server-protocol (~> 3.17.0)
-      sorbet-runtime
-      syntax_tree (>= 3.4)
     ruby-progressbar (1.11.0)
-    securerandom (0.2.2)
+    ruby2_keywords (0.0.5)
+    securerandom (0.3.1)
     sorbet (0.5.10438)
       sorbet-static (= 0.5.10438)
     sorbet-runtime (0.5.10438)
@@ -104,8 +113,6 @@ GEM
       sorbet (>= 0.5.9204)
       sorbet-runtime (>= 0.5.9204)
       thor (>= 0.19.2)
-    syntax_tree (3.6.1)
-      prettier_print
     tapioca (0.10.2)
       bundler (>= 1.17.3)
       netrc (>= 0.11.0)
@@ -133,7 +140,7 @@ GEM
     yard-sorbet (0.7.0)
       sorbet-runtime (>= 0.5)
       yard (>= 0.9)
-    zeitwerk (2.6.8)
+    zeitwerk (2.6.12)
 
 PLATFORMS
   arm64-darwin-21
@@ -149,7 +156,6 @@ DEPENDENCIES
   rubocop
   rubocop-shopify
   rubocop-sorbet
-  ruby-lsp
   shopify_api!
   sorbet
   tapioca

data/README.md

@@ -17,6 +17,9 @@ You can use this library in any application that has a Ruby backend, since it do
 
 **Note**: These instructions apply to v10 or later of this package. If you're running v9 in your app, you can find the documentation [in this branch](https://github.com/Shopify/shopify-api-ruby/tree/v9).
 
+## Use with Rails
+If using in the Rails framework, we highly recommend you use the [shopify_app](https://github.com/Shopify/shopify_app) gem to interact with this gem. Authentication, session storage, webhook registration, and other frequently implemented paths are managed in that gem with easy to use configurations.
+
 ## Requirements
 
 To follow these usage guides, you will need to:
@@ -67,46 +70,19 @@ The Shopify API gem tries to make this easy by providing functions to begin and
 
 If you intend to use webhooks in your application follow the steps in the [Webhooks doc](docs/usage/webhooks.md) for instructions on registering and handling webhooks.
 
-### Start Making Authenticated Shopify Requests
+### Start Making Authenticated Shopify API Requests
 
-Once your app can perform OAuth, it can now make authenticated Shopify API calls using the Admin [REST](docs/usage/rest.md) or [GraphQL](docs/usage/graphql.md) Clients, or the [Storefront API GraphQL Client](docs/usage/graphql_storefront.md).
+Once your app can perform OAuth, it can now make authenticated Shopify API calls, see docs for:
+* Making [Admin REST API](docs/usage/rest.md) requests
+* Making [Admin GraphQL API](docs/usage/graphql.md) requests
+* Making [Storefront GraphQL API](docs/usage/graphql_storefront.md) requests
 
 ## Breaking Change Notices
 
 ### Breaking change notice for version 10.0.0
+See [BREAKING_CHANGES_FOR_V10](BREAKING_CHANGES_FOR_V10.md)
 
-We've rewritten this library for v10, so that it provides all essential features for a Shopify app without depending on the [Active Resource](https://github.com/rails/activeresource) or [graphql-client](https://github.com/github/graphql-client) libraries.
-
-Here are the main features it provides:
-
-- OAuth support, both with online and offline tokens.
-- Full, transparent support for JWT sessions for embedded apps and cookies for non-embedded ones.
-  - Removal of support for 3rd party cookies which are increasingly more difficult to use with modern browsers.
-- Admin API support
-  - Auto-generated, version-specific REST resources which are similar to `ActiveResource` (though not identical), that provide methods for all endpoints defined in our [REST API reference](https://shopify.dev/docs/api/admin-rest), as well as direct definition of known attributes.
-  - A GraphQL client that doesn't rely on the ActiveResource implementation for REST.
-- Webhook management, with features for adding handlers and registering them with Shopify.
-- Storefront GraphQL API support
-
-Please refer to [the documentation](docs/getting_started.md) in this repository for instructions on how to use each of these components.
-
-With this, a lot changed in how apps access the library. Here are the updates you should make when migrating to v10:
-
-- Call `ShopifyAPI::Context.setup` when setting up your app. This class holds global configurations for your app and defines how the library behaves.
-- If not using the `shopify_app` gem, your app needs to provide an implementation of `ShopifyAPI::Auth::SessionStorage` for production. Read more about this [in our documentation](docs/usage/session_storage.md).
-- To change the `User-Agent` header, use `user_agent_prefix` in `ShopifyAPI::Context.setup`.
-- Usages of the `ActiveResource` classes for REST API requests need to be refactored into the new format. You can find detailed examples on how each of the endpoints work in our [reference documentation](https://shopify.dev/docs/api/admin-rest).
-
-    Please see below a (non-exhaustive) list of common replacements to guide you in your updates, using the `Order` resource as an example.
-
-    | Before                                             | After |
-    | ---                                                | --- |
-    | `Order.find(:all, params: {param1: value1})`       | `Order.all(param1: value1)` |
-    | `Order.find(<id>)`                                 | `Order.find(id: <id>)` |
-    | `order = Order.new(<id>)`<br/>`order.post(:close)` | `order = Order.new`<br/>`order.close` |
-    | `order = Order.new(<id>)`<br/>`order.delete`       | `Order.delete(id: <id>)` |
-
-## Breaking changes for older versions
+### Breaking changes for older versions
 
 See [BREAKING_CHANGES_FOR_OLDER_VERSIONS](BREAKING_CHANGES_FOR_OLDER_VERSIONS.md)
 

data/ROADMAP.md

@@ -0,0 +1,10 @@
+# Roadmap
+
+|Priority|Description|Delivery Time frame|
+|---|---|---|
+|P0|Respond timely to open issues/Pull Requests|Ongoing|
+|P1|Minor API release with support for 10-23 API version|Oct 6 - 13|
+|P2|Restore dot notation access to GraphQL responses|Oct 26 - Dec 7|
+|P2|Restrospection GQL queries to define types for GQL resources|October 26- Dec 7|
+|P2|New token exchange authentication via optional feature flag|October 26- Dec 7|
+|P3|[Extract REST resources into their own gem](https://github.com/Shopify/shopify-api-ruby/issues/1194)|Oct 26 - Dec 7|

data/docs/README.md

@@ -10,4 +10,3 @@ You can follow our getting started guide to learn how to use this library.
 - [Make a GraphQL API call](usage/graphql.md)
 - [Make a Storefront API call](usage/graphql_storefront.md)
 - [Webhooks](usage/webhooks.md)
-- [Known issues and caveats](issues.md)

data/docs/getting_started.md

@@ -37,10 +37,27 @@ ShopifyAPI::Context.setup(
 Next, unless you are making a private app, you need to go through OAuth as described [here](https://shopify.dev/docs/apps/auth/oauth) to create sessions for shops using your app.
 The Shopify API gem tries to make this easy by providing functions to begin and complete the OAuth process. See the [Oauth doc](usage/oauth.md) for instructions on how to use these.
 
-### Register Webhooks and a Webhook Handler
+### Sessions
 
-If you intend to use webhooks in your application follow the steps in the [Webhooks doc](usage/webhooks.md) for instructions on registering and handling webhooks.
+Sessions are required to make requests with the REST or GraphQL clients. This Library provides helpers for creating sessions via OAuth. Helpers are provided to retrieve session ID from a HTTP request from an embedded Shopify app or cookies from non-embedded apps.
+
+Session persistence is handled by the [ShopifyApp](https://github.com/Shopify/shopify_app) gem and is recommended for use in the Rails context. See that gem for documentation on how to use it.
+
+#### Cookie
+Cookie based authentication is not supported for embedded apps due to browsers dropping support for third party cookies due to security concerns. Non-embedded apps are able to use cookies for session storage/retrieval.
+
+For *non-embedded* apps, you can pass the cookies into `ShopifyAPI::Utils::SessionUtils.current_session_id(nil, cookies, true)` for online (user) sessions or `ShopifyAPI::Utils::SessionUtils.current_session_id(nil, cookies, false)` for offline (store) sessions.
+
+#### Getting Session ID From Embedded Requests
+For *embedded* apps, you can pass the auth header into `ShopifyAPI::Utils::SessionUtils.current_session_id(auth_header, nil, true)` for online (user) sessions or `ShopifyAPI::Utils::SessionUtils.current_session_id(auth_header, nil, false)` for offline (store) sessions. This function needs an `auth_header` which is the `HTTP_AUTHORIZATION` header.
 
-### Start Making Authenticated Shopify Requests
+If your app uses client side rendering instead of server side rendering, you will need to use App Bridge's [authenticatedFetch](https://shopify.dev/docs/apps/auth/oauth/session-tokens/getting-started) to make authenticated API requests from the client.
+
+#### Start Making Authenticated Shopify Requests
 
 You can now start making authenticated Shopify API calls using the Admin [REST](usage/rest.md) or [GraphQL](usage/graphql.md) Clients or the [Storefront GraphQL Client](usage/graphql_storefront.md).
+
+### Register Webhooks and a Webhook Handler
+
+If you intend to use webhooks in your application follow the steps in the [Webhooks doc](usage/webhooks.md) for instructions on registering and handling webhooks.
+

data/docs/usage/custom_apps.md

@@ -0,0 +1,75 @@
+# Custom Apps
+
+If you have followed instructions on creating [custom apps](https://help.shopify.com/current/manual/apps/app-types/custom-apps), you should be able to access your API token without having to go through the OAuth flow.
+
+You can follow instructions for [initializing the session object](#initializing-the-session-object) to construct the session object to be used in authenticated API calls to your store.  There are 2 methods to use the session object to make API calls:
+1. [Passing `session` object into each client request](#passing-session-object-into-each-client-request)
+2. [Setting `active_session` in `ShopifyAPI::Context`](#setting-active-session-in-shopifyapicontext)
+
+## Initializing the Session object
+Following is a basic example to construct a simple Session object. You can see full list of parameters for this object in the [class definition](https://github.com/Shopify/shopify-api-ruby/blob/main/lib/shopify_api/auth/session.rb)
+```ruby
+session = ShopifyAPI::Auth::Session.new(
+  shop: "#{your_shop_name}.myshopify.com"
+  access_token: "the_token_for_your_custom_app_found_in_admin"
+)
+
+```
+## Using `Session` to make API calls
+
+### Passing `session` object into each client request
+Example:
+```ruby
+def make_api_request(shop)
+  # 1. create session object
+    session = ShopifyAPI::Auth::Session.new(
+      shop: "#{your_shop_name}.myshopify.com"
+      access_token: "the_token_for_your_custom_app_found_in_admin"
+    )
+
+  # 2a. Create API client with the session information
+  # session must be type `ShopifyAPI::Auth::Session`
+  graphql_client = ShopifyAPI::Clients::Graphql::Admin.new(session: session)
+  response = graphql_client.query(query: MY_API_QUERY)
+
+  # 2b. REST example
+  product_count = ShopifyAPI::Product.count(session: session)
+
+  ...
+end
+```
+
+### Setting `active_session` in `ShopifyAPI::Context`
+Alternatively, if you don't want to keep having to create/retrieve a Session object for a shop, you may set [`ShopifyAPI::Context.active_session`](https://github.com/Shopify/shopify-api-ruby/blob/main/lib/shopify_api/context.rb#L144).
+All of the API client classes will [use the `active_session`](https://github.com/Shopify/shopify-api-ruby/blob/c3bb9d8f8b6053756149a4cf9299e059ec337544/lib/shopify_api/clients/http_client.rb#L13) if the `session` passed in is `nil`.
+
+Example:
+```ruby
+#### Configuration
+def configure_app
+  # This method is called before making authenticated API calls
+  session = ShopifyAPI::Auth::Session.new(
+      shop: "#{your_shop_name}.myshopify.com"
+      access_token: "the_token_for_your_custom_app_found_in_admin"
+    )
+
+  # Activate session to be used in all API calls
+  # session must be type `ShopifyAPI::Auth::Session`
+  ShopifyAPI::Context.activate_session(session)
+end
+
+#### Using clients to make authenticated API calls
+def make_api_request
+  # 1. Create API client without session information
+  # The graphql_client will use `ShopifyAPI::Context.active_session` when making API calls
+  graphql_client = ShopifyAPI::Clients::Graphql::Admin.new
+
+  # 2. Use API client to make queries
+  ...
+end
+
+```
+
+⚠️ See following docs on how to use the API clients:
+- [Make a GraphQL API call](https://github.com/Shopify/shopify-api-ruby/blob/main/docs/usage/graphql.md)
+- [Make a REST API call](https://github.com/Shopify/shopify-api-ruby/blob/main/docs/usage/rest.md)