Support using the Storefront private access token

This allows for using [the Storefront private access token][1] with the
library's Storefront GraphQL client. Since this client is probably going
to be running on a server where the token can be secured, using the
private access token should be preferred. This commit doesn't make using
the private token the default to avoid an immediate breaking change. We
want to give clients time to see the deprecation and update their
scripts.

Closes #1293

[1]: https://shopify.dev/docs/api/usage/authentication#getting-started-with-private-access

Author: bfad

CHANGELOG.md

@@ -7,6 +7,8 @@ Note: For changes to the API, see https://shopify.dev/changelog?filter=api
 - [#1071](https://github.com/Shopify/shopify-api-ruby/issues/1071) Fix FulfillmentEvent class types
 - Fix: InventoryItem class `harmonized_system_code` attribute type which can be either integer, string or nil
 - Fix: Variant class `inventory_quantity` attribute type which can be either integer, string or nil
+- [1293](https://github.com/Shopify/shopify-api-ruby/issues/1293) Add support for using Storefront private access tokens. 
+- Deprecated passing the public Storefront access token as a positional parameter to the Storefront GraphQL client in favor of using the named parameter. (You probably want to use the private access token for this client anyway.)
 
 ## 14.0.1
 - [#1288](https://github.com/Shopify/shopify-api-ruby/pull/1288) Fix FeatureDeprecatedError being raised without a message.

Gemfile.lock

@@ -139,6 +139,7 @@ GEM
 
 PLATFORMS
   arm64-darwin-21
+  arm64-darwin-23
   universal-darwin-22
   x86_64-linux
 

docs/usage/graphql_storefront.md

@@ -1,19 +1,21 @@
 # Make a Storefront API call
 
-The library also allows you to send GraphQL requests to the [Shopify Storefront API](https://shopify.dev/docs/api/storefront). To do that, you can use `ShopifyAPI::Clients::Graphql::Storefront` with the current session and a `storefrontAccessToken`.
+The library also allows you to send GraphQL requests to the [Shopify Storefront API](https://shopify.dev/docs/api/storefront). To do that, you can use `ShopifyAPI::Clients::Graphql::Storefront` with either a [private or public Storefront access token](https://shopify.dev/docs/api/usage/authentication#access-tokens-for-the-storefront-api).
 
 You can obtain Storefront API access tokens for both private apps and sales channels. Please read [our documentation](https://shopify.dev/docs/custom-storefronts/building-with-the-storefront-api/getting-started) to learn more about Storefront Access Tokens.
 
 Below is an example of how you may query the Storefront API:
 
 ```ruby
 # Load the access token as per instructions above
-storefront_access_token = ''
+storefront_private_access_token = ''
 # your shop domain
 shop_url = 'shop.myshopify.com'
 
-# initialize the client with session and storefront access token
-client = ShopifyAPI::Clients::Graphql::Storefront.new(shop_url, storefront_access_token)
+# initialize the client with session and a private Storefront access token
+client = ShopifyAPI::Clients::Graphql::Storefront.new(shop_url, private_token: storefront_private_access_token)
+# or, alternatively with a public Storefront access token:
+# client = ShopifyAPI::Clients::Graphql::Storefront.new(shop_url, public_token: storefront_public_access_token)
 
 query = <<~QUERY
   {
@@ -35,14 +37,19 @@ query = <<~QUERY
   }
 QUERY
 
-response = client.query(query: query)
+# You may not need the "Shopify-Storefront-Buyer-IP" header, see its documentation: 
+# https://shopify.dev/docs/api/usage/authentication#making-server-side-requests
+response = client.query(query: query, headers: { "Shopify-Storefront-Buyer-IP": request.ip })
 # do something with the returned data
 ```
 
 By default, the client uses the API version configured in `ShopifyAPI`.  To use a different API version, set the optional `api_version` parameter.  To experiment with prerelease API features, use `"unstable"` for the API version.
 
 ```ruby
-client = ShopifyAPI::Clients::Graphql::Storefront.new(shop_url, storefront_access_token, api_version: "unstable")
+client = ShopifyAPI::Clients::Graphql::Storefront.new(shop_url,
+  private_token: storefront_private_access_token,
+  api_version: "unstable"
+)
 ```
 
 Want to make calls to the Admin API? Click [here](graphql.md)

lib/shopify_api/clients/graphql/storefront.rb

@@ -5,16 +5,38 @@ module ShopifyAPI
   module Clients
     module Graphql
       class Storefront < Client
-        sig { params(shop: String, storefront_access_token: String, api_version: T.nilable(String)).void }
-        def initialize(shop, storefront_access_token, api_version: nil)
+        sig do
+          params(
+            shop: String,
+            storefront_access_token: T.nilable(String),
+            private_token: T.nilable(String),
+            public_token: T.nilable(String),
+            api_version: T.nilable(String),
+          ).void
+        end
+        def initialize(shop, storefront_access_token = nil, private_token: nil, public_token: nil, api_version: nil)
+          unless storefront_access_token.nil?
+            warning = <<~WARNING
+              DEPRECATED: Use the named parameters for the Storefront token instead of passing
+              the public token as the second argument. Also, you may want to look into using
+              the Storefront private access token instead:
+              https://shopify.dev/docs/api/usage/authentication#getting-started-with-private-access
+            WARNING
+            ShopifyAPI::Logger.deprecated(warning, "15.0.0")
+          end
+
           session = Auth::Session.new(
             id: shop,
             shop: shop,
             access_token: "",
             is_online: false,
           )
           super(session: session, base_path: "/api", api_version: api_version)
-          @storefront_access_token = storefront_access_token
+          @storefront_access_token = T.let(T.must(private_token || public_token || storefront_access_token), String)
+          @storefront_auth_header = T.let(
+            private_token.nil? ? "X-Shopify-Storefront-Access-Token" : "Shopify-Storefront-Private-Token",
+            String,
+          )
         end
 
         sig do
@@ -26,7 +48,7 @@ def initialize(shop, storefront_access_token, api_version: nil)
           ).returns(HttpResponse)
         end
         def query(query:, variables: nil, headers: {}, tries: 1)
-          T.must(headers).merge!({ "X-Shopify-Storefront-Access-Token": @storefront_access_token })
+          T.must(headers).merge!({ @storefront_auth_header => @storefront_access_token })
           super(query: query, variables: variables, headers: headers, tries: tries)
         end
       end

test/clients/graphql/storefront_test.rb

@@ -27,6 +27,62 @@ def build_client
             ShopifyAPI::Clients::Graphql::Storefront.new(@shop, @storefront_access_token, api_version: @api_version)
           end
         end
+
+        def test_can_query_using_private_token
+          query = <<~QUERY
+            {
+              shop {
+                name
+              }
+            }
+          QUERY
+          extra_headers = { extra: "header" }
+          body = { query: query, variables: nil }
+          success_body = { "success" => true }
+          response_headers = { "content-type" => "application/json" }
+
+          @client = ShopifyAPI::Clients::Graphql::Storefront.new(@shop, private_token: "private_token")
+          @expected_headers = TestHelpers::Constants::DEFAULT_CLIENT_HEADERS.merge({
+            "Shopify-Storefront-Private-Token": "private_token",
+          }).merge(extra_headers)
+
+          stub_request(:post, "https://test-shop.myshopify.com/#{@path}/#{ShopifyAPI::Context.api_version}/graphql.json")
+            .with(body: body, headers: @expected_headers)
+            .to_return(body: success_body.to_json, headers: response_headers)
+
+          response = @client.query(query: query, headers: extra_headers)
+          assert_equal(success_body, response.body)
+        end
+
+        def test_can_query_using_public_token
+          query = <<~QUERY
+            {
+              shop {
+                name
+              }
+            }
+          QUERY
+          extra_headers = { extra: "header" }
+          body = { query: query, variables: nil }
+          success_body = { "success" => true }
+          response_headers = { "content-type" => "application/json" }
+
+          @client = ShopifyAPI::Clients::Graphql::Storefront.new(@shop, public_token: "public_token")
+          @expected_headers = TestHelpers::Constants::DEFAULT_CLIENT_HEADERS.merge({
+            "X-Shopify-Storefront-Access-Token": "public_token",
+          }).merge(extra_headers)
+
+          stub_request(:post, "https://test-shop.myshopify.com/#{@path}/#{ShopifyAPI::Context.api_version}/graphql.json")
+            .with(body: body, headers: @expected_headers)
+            .to_return(body: success_body.to_json, headers: response_headers)
+
+          response = @client.query(query: query, headers: extra_headers)
+          assert_equal(success_body, response.body)
+        end
+
+        def test_error_raised_when_no_token_provided
+          assert_raises(TypeError) { ShopifyAPI::Clients::Graphql::Storefront.new(@shop) }
+        end
       end
     end
   end