shopify_api 8.1.0 → 9.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6b6467bc9d4c7e3180f0385a0b7c6f75921b391659e7d0566796fb34f5fe63d
-  data.tar.gz: 6bcd7084be9a692d3e960c5659b4ed4e25abd629e6f91f58faa9934f55f720a1
+  metadata.gz: 20f844e10d85c5f8069b9cfa56f081b5396e247e3a3ed9db28ebdb41dcf8ba54
+  data.tar.gz: fb4f49e89c1147b86674c98e02d4fb7b3338cc834cbb4f1e0dfe0953500db6a8
 SHA512:
-  metadata.gz: 4ab61dddb0c4fe44d89c9bced7e328c8e76932c9876803d2aeef6ea0a7c9eace8eaa728841f9445a2c59e53b555d8c16c40b4ed881b8630069f2e8343c2f3971
-  data.tar.gz: 5808669808de2b254c33d2a0d4f120f9b47a4868bb992575824f2a9348ecd74a1c54231b3ed821e694de1c2ed63ae6653c5138b6e86874d88c2a10fcee080965
+  metadata.gz: b2d726f0c5526c4800fe7b1fd260a27ac75f70251f879e179d10c093378aa6ebcce5dcf1a222a33c1f3dc27b5d547b3bb7269c25515c0000b6d311d3cccfd93b
+  data.tar.gz: 13c44be9e5ec956fd0f7d88b79d55460742cc0624f9c711fbf471de4907741f8d14ae7687307daca333e65988b0d0c84ffb0c49ced4ede0f56833f69da71e834

data/CHANGELOG.md

@@ -1,3 +1,28 @@
+== Version 9.0.0
+
+* Breaking change: Improved GraphQL client [#672](https://github.com/Shopify/shopify_api/pull/672). See the [client docs](docs/graphql.md) for usage and a migration guide.
+
+* Added options hash to create_permission_url and makes redirect_uri required [#670](https://github.com/Shopify/shopify_api/pull/670)
+
+* Release new Endpoint `fulfillment_order.locations_for_move` in 2020-01 REST API version [#669](https://github.com/Shopify/shopify_api/pull/669)
+
+* Release new Endpoints for `fulfillment` in 2020-01 REST API version [#639](https://github.com/Shopify/shopify_api/pull/639):
+  * `fulfillment.create` with `line_items_by_fulfillment_order`
+  * `fulfillment.update_tracking`
+  * `fulfillment.cancel`
+
+* Release new Endpoints for `fulfillment_order` in 2020-01 REST API version [#637](https://github.com/Shopify/shopify_api/pull/637):
+  * `fulfillment_order.fulfillment_request`
+  * `fulfillment_order.fulfillment_request.accept`
+  * `fulfillment_order.fulfillment_request.reject`
+  * `fulfillment_order.cancellation_request`
+  * `fulfillment_order.cancellation_request.accept`
+  * `fulfillment_order.cancellation_request.reject`
+
+* Release new Endpoints `fulfillment_order.move`, `fulfillment_order.cancel` and `fulfillment_order.close` in 2020-01 REST API version [#635](https://github.com/Shopify/shopify_api/pull/635)
+
+* Release new Endpoint `order.fulfillment_orders`, and active resources `AssignedFulfillmentOrder` and `FulfillmentOrder` in 2020-01 REST API version [#633](https://github.com/Shopify/shopify_api/pull/633)
+
 == Version 8.1.0
 
 * Release 2020-01 REST ADMIN API VERSION [#656](https://github.com/Shopify/shopify_api/pull/656)

data/README.md

@@ -192,17 +192,16 @@ ShopifyAPI uses ActiveResource to communicate with the REST web service. ActiveR
    shopify_session = ShopifyAPI::Session.new(domain: "SHOP_NAME.myshopify.com", api_version: api_version, token: nil)
    ```
 
-   Then call:
+   Then call `create_permission_url` with the redirect_uri you've registered for your application:
 
    ```ruby
-   scope = ["write_products"]
-   permission_url = shopify_session.create_permission_url(scope)
+   permission_url = shopify_session.create_permission_url(scope, "https://my_redirect_uri.com")
    ```
 
-   or if you want a custom redirect_uri:
+   You can also pass a state parameter in the options hash as a last argument:
 
    ```ruby
-   permission_url = shopify_session.create_permission_url(scope, "https://my_redirect_uri.com")
+   permission_url = shopify_session.create_permission_url(scope, "https://my_redirect_uri.com", { state: "My Nonce" })
    ```
 
 4. Once authorized, the shop redirects the owner to the return URL of your application with a parameter named 'code'. This is a temporary token that the app can exchange for a permanent access token.
@@ -347,15 +346,18 @@ gem install shopify_api_console
 
 ## GraphQL
 
-This library also supports Shopify's new [GraphQL API](https://help.shopify.com/api/graphql-admin-api)
-via a dependency on the [graphql-client](https://github.com/github/graphql-client) gem.
+Note: the GraphQL client has improved and changed in version 9.0. See the [client documentation](docs/graphql.md)
+for full usage details and a [migration guide](docs/graphql.md#migration-guide).
+
+This library also supports Shopify's [GraphQL Admin API](https://help.shopify.com/api/graphql-admin-api)
+via integration with the [graphql-client](https://github.com/github/graphql-client) gem.
 The authentication process (steps 1-5 under [Getting Started](#getting-started))
-is identical. Once your session is activated, simply construct a new graphql
-client and use `parse` and `query` as defined by
+is identical. Once your session is activated, simply access the GraphQL client
+and use `parse` and `query` as defined by
 [graphql-client](https://github.com/github/graphql-client#defining-queries).
 
 ```ruby
-client = ShopifyAPI::GraphQL.new
+client = ShopifyAPI::GraphQL.client
 
 SHOP_NAME_QUERY = client.parse <<-'GRAPHQL'
   {
@@ -369,6 +371,8 @@ result = client.query(SHOP_NAME_QUERY)
 result.data.shop.name
 ```
 
+[GraphQL client documentation](docs/graphql.md)
+
 ## Threadsafety
 
 ActiveResource is threadsafe as of version 4.1 (which works with Rails 4.x and above).
@@ -403,6 +407,14 @@ while products.next_page?
 end
 ```
 
+If you want cursor based pagination to work across page loads, or want to distribute workload across multiple background jobs, you can use #next_page_info or #previous_page_info methods that return strings:
+
+```
+  first_batch_products = ShopifyAPI::Product.find(:all, params: { limit: 50 })
+  second_batch_products = ShopifyAPI::Product.find(:all, params: { limit: 50, page_info: first_batch_products.next_page_info })
+  ...
+```
+
 Relative cursor pagination is currently available for all endpoints using the `2019-10` and later API versions.
 
 ## Using Development Version

data/docs/graphql.md

@@ -0,0 +1,191 @@
+# GraphQL client
+
+The `shopify_api` gem includes a full featured GraphQL client to interact with
+Shopify's [GraphQL Admin API](https://help.shopify.com/en/api/graphql-admin-api).
+GitHub's [graphql-client](https://github.com/github/graphql-client) is used as
+the underlying client and this library integrates it with our existing
+session, authentication, and API versioning features.
+
+## Example
+
+```ruby
+client = ShopifyAPI::GraphQL.client
+
+SHOP_NAME_QUERY = client.parse <<-'GRAPHQL'
+  {
+    shop {
+      name
+    }
+  }
+GRAPHQL
+
+result = client.query(SHOP_NAME_QUERY)
+result.data.shop.name
+```
+
+* [Getting started](#getting-started)
+* [Rails integration](#rails-integration)
+* [API versioning](#api-versioning)
+* [Initialization process](#initialization-process)
+* [Migration guide](#migration-guide)
+
+## Getting started
+
+1. [Dump the schema](#dump-the-schema)
+2. [Configure session/authencation](#sessions-and-authentication)
+3. [Make queries](#make-queries)
+
+### Dump the schema
+One of the main benefits of GraphQL is its [schema and type system](https://graphql.org/learn/schema/)
+which enables tools like graphql-client to ensure your queries are valid in development.
+
+So the first step in making GraphQL queries is having a local JSON file of Shopify's Admin schema.
+This gem provides a `shopify_api:graphql:dump` Rake task to make it as easy as possible:
+
+```bash
+$ rake shopify_api:graphql:dump SHOP_URL="https://API_KEY:PASSWORD@SHOP_NAME.myshopify.com" API_VERSION=2020-01
+```
+
+If successful `db/shopify_graphql_schemas/2020-01.json` will be created.
+
+You can either use private app authentication or an OAuth access token. Run `rake shopify_api:graphql:dump`
+to see full usage details.
+
+If you're using shopify_api in a Rails app, the default location for schema files is `db/shopify_graphql_schemas`.
+For non-Rails applications, the default is `shopify_graphql_schemas` in your project root.
+
+The schema path location can be changed via `ShopifyAPI::GraphQL.schema_location`:
+
+```ruby
+ShopifyAPI::GraphQL.schema_location = 'assets/schemas'
+```
+
+#### Updating schemas
+Each time you want to use a new API version, or update an existing one
+(such as the `unstable` version), simply run the Rake task again to overwrite the file.
+
+### Sessions and authentication
+The GraphQL client is designed to be integrated with the rest of shopify_api so
+all its features such as sessions, authentication, and API versioning work the
+exact same.
+
+If you've already been using the shopify_api gem in your application to make
+REST API calls then no other configuration is necessary.
+
+Steps 1-5 of our main [Getting started](https://github.com/Shopify/shopify_api#getting-started)
+section still apply for the GraphQL client as well.
+
+### Make queries
+Now that you've dumped a schema file and configured an authenticated session, you can make GraphQL API requests.
+graphql-client encourages all queries to be defined statically as constants:
+
+```ruby
+SHOP_NAME_QUERY = ShopifyAPI::GraphQL.client.parse <<-'GRAPHQL'
+  {
+    shop {
+      name
+    }
+  }
+GRAPHQL
+
+result = ShopifyAPI::GraphQL.client.query(SHOP_NAME_QUERY)
+result.data.shop.name
+```
+
+But we've also enabled its `allow_dynamic_queries` option if you prefer:
+
+```ruby
+query = ShopifyAPI::GraphQL.client.parse <<-'GRAPHQL'
+  {
+    shop {
+      name
+    }
+  }
+GRAPHQL
+
+result = ShopifyAPI::GraphQL.client.query(query)
+result.data.shop.name
+```
+
+See the [graphql-client documentation](https://github.com/github/graphql-client#defining-queries)
+for more details on defining and executing queries.
+
+## Rails integration
+`ShopifyAPI::GraphQL` integrates with Rails to automatically do the following:
+
+* load the `shopify_api:graphql:dump` Rake task
+* set the `schema_location` to be in the `db` directory in your Rails root
+* initialize clients in the Rails app initializer phase
+
+## API versioning
+`ShopifyAPI::GraphQL` is version aware and lets you easily make queries to multiple
+API versions through version specific clients if need be.
+
+If you have multiple clients and need to be explicit you can specify the version parameter:
+
+```ruby
+ShopifyAPI::GraphQL.client # defaults to the client using ShopifyAPI::Base.api_version
+ShopifyAPI::GraphQL.client('unstable')
+```
+
+## Initialization process
+`ShopifyAPI::GraphQL` is a thin integration layer which initializes `GraphQL::Client`s
+from local schema files.
+
+`ShopifyAPI::GraphQL.initialize_clients` scans `ShopifyAPI::GraphQL.schema_location`
+and creates a client for each version specific schema file found.
+
+This happens automatically in a Rails application due to our [integration](#rails-integration).
+For non-Rails applications, ensure you call `ShopifyAPI::GraphQL.initialize_clients`
+during your boot process.
+
+The goal is to have all clients created at boot so there's no schema loading,
+parsing, or client instantiation done during runtime when your app serves a request.
+
+## Migration guide
+Prior to shopify_api v9.0 the GraphQL client implementation was limited and almost
+unusable due to the client making dynamic introspection queries to Shopify's API.
+This was not only very slow but also led to unbounded memory growth.
+
+There are two steps to migrate to the new client:
+1. [Dump a local schema file](#dump-the-schema)
+2. [Migrate `client` usage](#migrate-usage)
+
+### Migrate usage
+
+Previously a client was initialized with `ShopifyAPI::GraphQL.new`:
+```ruby
+client = ShopifyAPI::GraphQL.new
+
+SHOP_NAME_QUERY = client.parse <<-'GRAPHQL'
+  {
+    shop {
+      name
+    }
+  }
+GRAPHQL
+
+result = client.query(SHOP_NAME_QUERY)
+result.data.shop.name
+```
+
+Now there's no need to initialize a client so all references to
+`ShopifyAPI::GraphQL.new` should be removed and instead the client is called
+via `ShopifyAPI::GraphQL.client`:
+
+```ruby
+client = ShopifyAPI::GraphQL.client
+
+SHOP_NAME_QUERY = client.parse <<-'GRAPHQL'
+  {
+    shop {
+      name
+    }
+  }
+GRAPHQL
+
+result = client.query(SHOP_NAME_QUERY)
+result.data.shop.name
+```
+
+See [making queries](#making-queries) for more usage details.

data/lib/shopify_api.rb

@@ -23,6 +23,8 @@ require 'shopify_api/session'
 require 'shopify_api/message_enricher'
 require 'shopify_api/connection'
 require 'shopify_api/pagination_link_headers'
+require 'shopify_api/graphql'
+require 'shopify_api/graphql/railtie' if defined?(Rails)
 
 if ShopifyAPI::Base.respond_to?(:connection_class)
   ShopifyAPI::Base.connection_class = ShopifyAPI::Connection

data/lib/shopify_api/api_version.rb

@@ -5,8 +5,8 @@ module ShopifyAPI
     class ApiVersionNotSetError < StandardError; end
     include Comparable
 
-    HANDLE_FORMAT = /^\d{4}-\d{2}$/.freeze
     UNSTABLE_HANDLE = 'unstable'
+    HANDLE_FORMAT = /((\d{4}-\d{2})|#{UNSTABLE_HANDLE})/.freeze
     UNSTABLE_AS_DATE = Time.utc(3000, 1, 1)
     API_PREFIX = '/admin/api/'
     LOOKUP_MODES = [:raise_on_unknown, :define_on_unknown].freeze

data/lib/shopify_api/graphql.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+require 'graphql/client'
+require 'shopify_api/graphql/http_client'
+
+module ShopifyAPI
+  module GraphQL
+    DEFAULT_SCHEMA_LOCATION_PATH = Pathname('shopify_graphql_schemas')
+
+    InvalidSchema = Class.new(StandardError)
+    InvalidClient = Class.new(StandardError)
+
+    class << self
+      delegate :parse, :query, to: :client
+
+      def client(api_version = ShopifyAPI::Base.api_version.handle)
+        initialize_client_cache
+        cached_client = @_client_cache[api_version]
+
+        if cached_client
+          cached_client
+        else
+          schema_file = schema_location.join("#{api_version}.json")
+
+          if !schema_file.exist?
+            raise InvalidClient, <<~MSG
+              Client for API version #{api_version} does not exist because no schema file exists at `#{schema_file}`.
+
+              To dump the schema file, use the `rake shopify_api:graphql:dump` task.
+            MSG
+          else
+            puts '[WARNING] Client was not pre-initialized. Ensure `ShopifyAPI::GraphQL.initialize_clients` is called during app initialization.'
+            initialize_clients
+            @_client_cache[api_version]
+          end
+        end
+      end
+
+      def clear_clients
+        @_client_cache = {}
+      end
+
+      def initialize_clients
+        initialize_client_cache
+
+        Dir.glob(schema_location.join("*.json")).each do |schema_file|
+          schema_file = Pathname(schema_file)
+          matches = schema_file.basename.to_s.match(/^#{ShopifyAPI::ApiVersion::HANDLE_FORMAT}\.json$/)
+
+          if matches
+            api_version = ShopifyAPI::ApiVersion.new(handle: matches[1])
+          else
+            raise InvalidSchema, "Invalid schema file name `#{schema_file}`. Does not match format of: `<version>.json`."
+          end
+
+          schema = ::GraphQL::Client.load_schema(schema_file.to_s)
+          client = ::GraphQL::Client.new(schema: schema, execute: HTTPClient.new(api_version)).tap do |c|
+            c.allow_dynamic_queries = true
+          end
+
+          @_client_cache[api_version.handle] = client
+        end
+      end
+
+      def schema_location
+        @schema_location || DEFAULT_SCHEMA_LOCATION_PATH
+      end
+
+      def schema_location=(path)
+        @schema_location = Pathname(path)
+      end
+
+      private
+
+      def initialize_client_cache
+        @_client_cache ||= {}
+      end
+    end
+  end
+end

data/lib/shopify_api/graphql/http_client.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+require 'graphql/client/http'
+
+module ShopifyAPI
+  module GraphQL
+    class HTTPClient < ::GraphQL::Client::HTTP
+      def initialize(api_version)
+        @api_version = api_version
+      end
+
+      def headers(_context)
+        ShopifyAPI::Base.headers
+      end
+
+      def uri
+        ShopifyAPI::Base.site.dup.tap do |uri|
+          uri.path = @api_version.construct_graphql_path
+        end
+      end
+    end
+  end
+end

data/lib/shopify_api/graphql/railtie.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+require 'rails/railtie'
+
+module ShopifyAPI
+  module GraphQL
+    class Railtie < Rails::Railtie
+      initializer 'shopify_api.initialize_graphql_clients' do |app|
+        ShopifyAPI::GraphQL.schema_location = app.root.join('db', ShopifyAPI::GraphQL.schema_location)
+        ShopifyAPI::GraphQL.initialize_clients
+      end
+
+      rake_tasks do
+        load 'shopify_api/graphql/task.rake'
+      end
+    end
+  end
+end