@shopify/shopify-api 6.0.0-rc4 → 6.0.0-rc6

package/docs/usage/billing.md

@@ -0,0 +1,169 @@
+# Billing for your app
+
+Some partners might wish to charge merchants for using their app.
+The Admin API provides endpoints that enable apps to trigger purchases in the Shopify platform, so that merchants can pay for apps as part of their Shopify payments.
+
+This library provides support for billing apps by:
+
+1. Checking if the store has already paid for the app
+1. Triggering a charge for the merchant if the store has not paid
+
+**Note**: this package uses the GraphQL Admin API to look for / request payment, which means an app must go through OAuth before it can charge merchants.
+
+Learn more about [how billing works](https://shopify.dev/apps/billing).
+
+## Setting up for billing
+
+To trigger the billing behaviour, you'll need to set the `billing` value when calling `shopifyApi()`. For example:
+
+```ts
+import {
+  shopifyApi,
+  BillingInterval,
+  BillingReplacementBehavior,
+} from '@shopify/shopify-api';
+
+const shopify = shopifyApi({
+  apiKey: ...,
+  apiSecretKey: ...,
+  :
+  :
+  billing: {
+    'My billing plan': {
+      amount: 1,
+      currencyCode: 'USD',
+      interval: BillingInterval.Every30Days,
+      replacementBehavior: BillingReplacementBehavior.ApplyImmediately,
+    },
+  },
+});
+```
+
+This setting is a collection of billing plans. Each billing plan allows the following properties:
+
+| Parameter             | Type                         | Required? | Default Value | Notes                                                                                                                                                                                            |
+| --------------------- | ---------------------------- | :-------: | :-----------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `amount`              | `number`                     |    Yes    |       -       | The amount to charge                                                                                                                                                                             |
+| `currencyCode`        | `string`                     |    Yes    |       -       | The currency to charge, currently only `"USD"` is accepted                                                                                                                                       |
+| `interval`            | `BillingInterval`            |    Yes    |       -       | `BillingInterval` value                                                                                                                                                                          |
+| `trialDays`           | `number`                     |    No     |       -       | Give merchants this many days before charging. _Not available for `OneTime` plans_                                                                                                               |
+| `replacementBehavior` | `BillingReplacementBehavior` |    No     |       -       | `BillingReplacementBehavior` value, see [the reference](https://shopify.dev/api/admin-graphql/2022-07/mutations/appSubscriptionCreate) for more information. _Not available for `OneTime` plans_ |
+
+## Checking for payment
+
+Once the app has an access token, you can call `shopify.billing.check` to look for an existing payment.
+
+Here's a typical example of how apps might do that:
+
+```ts
+// This can happen at any point after the merchant goes through the OAuth process, as long as there is a session object
+// The session can come from either shopify.session.getCurrent or shopify.session.getOffline
+function billingMiddleware(req, res, next) {
+  const session = shopify.session.getCurrent({
+    isOnline: true,
+    rawRequest: req,
+    rawResponse: res,
+  });
+
+  const hasPayment = await shopify.billing.check({
+    session,
+    plans: ['My billing plan'],
+    isTest: true,
+  });
+
+  if (hasPayment) {
+    next();
+  } else {
+    // Either request payment now or redirect to plan selection page
+  }
+}
+
+app.use('/requires-payment/*', billingMiddleware);
+```
+
+**Note**: the `check` method will always query Shopify's API because merchants can cancel subscriptions at any point. Depending on the number of requests your app handles, you might want to cache a merchant's payment status, but you should periodically call this method to ensure you're blocking unpaid access.
+
+The `check` method accepts the following parameters:
+
+| Parameter | Type                 | Required? | Default Value | Notes                                   |
+| --------- | -------------------- | :-------: | :-----------: | --------------------------------------- |
+| `session` | `Session`            |    Yes    |       -       | The `Session` for the current request   |
+| `plans`   | `string \| string[]` |    Yes    |       -       | Which plans to look for                 |
+| `isTest`  | `boolean`            |    No     |    `true`     | Whether to look for test purchases only |
+
+It returns `true` if there is a payment for any of the given plans, and `false` otherwise.
+
+## Requesting payment
+
+When you want create a new charge for the merchant, you can call `shopify.billing.request` to instruct Shopify to create a charge.
+Here are some typical examples of how apps might do that:
+
+<div>Example single-plan setup - charge after OAuth completes
+
+```ts
+app.get('/auth/callback', async () => {
+  const callback = await shopify.auth.callback({
+    isOnline: false,
+    rawRequest: req,
+    rawResponse: res,
+  });
+
+  // Check if we require payment ... see example above
+
+  const confirmationUrl = await shopify.billing.request({
+    session: callback.session,
+    plan: 'My billing plan',
+    isTest: true,
+  });
+
+  res.redirect(confirmationUrl);
+});
+```
+
+</div><div>Example multi-plan setup - charge based on user selection
+
+```ts
+app.post('/api/select-plan', async (req, res) => {
+  const session = shopify.session.getCurrent({
+    isOnline: true,
+    rawRequest: req,
+    rawResponse: res,
+  });
+
+  const confirmationUrl = await shopify.billing.request({
+    session,
+    // Receive the selected plan from the frontend
+    plan: req.body.selectedPlan,
+    isTest: true,
+  });
+
+  res.redirect(confirmationUrl);
+});
+```
+
+The `request` method accepts the following parameters:
+
+| Parameter | Type      | Required? | Default Value | Notes                                                |
+| --------- | --------- | :-------: | :-----------: | ---------------------------------------------------- |
+| `session` | `Session` |    Yes    |       -       | The `Session` for the current request                |
+| `plan`    | `string`  |    Yes    |       -       | Which plan to create a charge for                    |
+| `isTest`  | `boolean` |    No     |    `true`     | If `true`, Shopify will not charge for this purchase |
+
+It will return a `string` containing a URL - we don't redirect right away to make it possible for apps to run their own code after it creates the payment request.
+
+The app **must** redirect the merchant to this URL so that they can confirm the charge before Shopify applies it.
+The merchant will be sent back to your app's main page after the process is complete.
+
+## When should the app check for payment?
+
+As mentioned above, billing requires a session to access the API, which means that the app must actually be installed before it can request payment.
+
+With the `check` method, your app can block access to specific endpoints, or to the app as a whole.
+If you're gating access to the entire app, you should check for billing:
+
+1. After OAuth completes, you'll get the session back from `shopify.auth.callback`. You can use the session to ensure billing takes place as part of the authentication flow.
+1. When validating requests from the frontend. Since the check requires API access, you can only run it in requests that work with `shopify.session.getCurrent`.
+
+**Note**: the merchant may refuse payment when prompted or cancel subscriptions later on, but the app will already be installed at that point. We recommend using [billing webhooks](https://shopify.dev/apps/billing#webhooks-for-billing) to revoke access for merchants when they cancel / decline payment.
+
+[Back to guide index](../../README.md#features)

package/docs/usage/customsessions.md

@@ -0,0 +1,154 @@
+# Create a `CustomSessionStorage` solution
+
+This library comes with various session management options, see our [documentation on session storage strategies](../../session-storage/README.md) for more details.
+
+If you wish to use an alternative session storage solution for production, you'll need to set up a `CustomSessionStorage`, which you can then use in initializing your `config`. The `CustomSessionStorage` class expects to be initialized with the following three mandatory callbacks that link to your chosen storage solution and map to the `storeSession`, `loadSession`, and `deleteSession` methods on the class.
+
+## Callback methods
+
+All of the callbacks used to create a new instance of `CustomSessionStorage` should be `async` functions and return a `Promise` that resolves to a specified type, as outlined below.
+
+| Method           | Arg type           | Return type                                                          | Notes                                                                                                                                                                                                               |
+| ---------------- | ------------------ | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `storeCallback`  | `SessionInterface` | `Promise<boolean>`                                                   | Takes in the `Session` to be stored or updated, returns a `boolean` (`true` if stored successfully). <br/> This callback is used both to save new a `Session` and to **update an existing `Session`**.              |
+| `loadCallback`   | `string`           | `Promise<SessionInterface \| Record<string, unknown> \| undefined> ` | Takes in the id of the `Session` to load (as a `string`) and returns either an instance of a `Session`, an object to be used to instantiate a `Session`, or `undefined` if no record is found for the specified id. |
+| `deleteCallback` | `string`           | `Promise<boolean>`                                                   | Takes in the id of the `Session` to load (as a `string`) and returns a `boolean` (`true` if deleted successfully).                                                                                                  |
+
+There are two optional callbacks methods that can also be passed in during initialization. They're not used internally in the library but can be useful to have in your app if you call `shopify.config.sessionStorage.deleteSessions` or `findSessionsByShop`.
+
+| Optional Method              | Arg type   | Return type                    | Notes                                                                                                                                  |
+| ---------------------------- | ---------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `deleteSessionsCallback`     | `string[]` | `Promise<boolean>`             | Takes in an array of ids of `Session`'s to be deleted (as an array of `string`), returns a `boolean` (`true` if deleted successfully). |
+| `findSessionsByShopCallback` | `string`   | `Promise<SessionInterface[]> ` | Takes in the shop domain (as a `string`) and returns an array of the sessions of that shop, or an empty array (`[]`) if none found.    |
+
+## Example usage
+
+This is an example implementation of a `CustomSessionStorage` solution, using `redis` for storage (mandatory callbacks only).
+
+Before starting this tutorial, make sure to [set up your app](../../README.md).
+
+### Install `redis` dependencies
+
+First, make sure you have Redis installed on your machine. You can follow their [Quick Start guide](https://redis.io/topics/quickstart) to get up and running, and then come back here to continue with this example.
+
+**Note**: Mac users should be able to just run `brew install redis` to install redis using homebrew
+
+Once you have Redis installed globally, you will need to add the `redis` client to your project by running:
+
+```shell
+$ npm install redis@4
+```
+
+### Create a RedisStore class
+
+Then, create a new class for our `redis` solution in `redis-store.ts`:
+
+```ts
+/* redis-store.ts */
+
+// Import the Node redis package
+import {createClient} from 'redis';
+
+class RedisStore {
+  constructor() {
+    // Create a new redis client and connect to the server
+    this.client = createClient({
+      url: 'redis://localhost:6379',
+    });
+    this.client.on('error', (err) => console.log('Redis Client Error', err));
+    this.client.connect();
+  }
+
+  /*
+    The storeCallback takes in the Session, and sets a stringified version of it on the redis store
+    This callback is used for BOTH saving new Sessions and updating existing Sessions.
+    If the session can be stored, return true
+    Otherwise, return false
+  */
+  async storeCallback(session) {
+    try {
+      // Inside our try, we use the `setAsync` method to save our session.
+      // This method returns a boolean (true if successful, false if not)
+      return await this.client.set(session.id, JSON.stringify(session));
+    } catch (err) {
+      // throw errors, and handle them gracefully in your application
+      throw new Error(err);
+    }
+  }
+
+  /*
+    The loadCallback takes in the id, and uses the getAsync method to access the session data
+     If a stored session exists, it's parsed and returned
+     Otherwise, return undefined
+  */
+  async loadCallback(id) {
+    try {
+      // Inside our try, we use `getAsync` to access the method by id
+      // If we receive data back, we parse and return it
+      // If not, we return `undefined`
+      let reply = await this.client.get(id);
+      if (reply) {
+        return JSON.parse(reply);
+      } else {
+        return undefined;
+      }
+    } catch (err) {
+      throw new Error(err);
+    }
+  }
+
+  /*
+    The deleteCallback takes in the id, and uses the redis `del` method to delete it from the store
+    If the session can be deleted, return true
+    Otherwise, return false
+  */
+  async deleteCallback(id) {
+    try {
+      // Inside our try, we use the `delAsync` method to delete our session.
+      // This method returns a boolean (true if successful, false if not)
+      return await this.client.del(id);
+    } catch (err) {
+      throw new Error(err);
+    }
+  }
+}
+
+// Export the class
+export default RedisStore;
+```
+
+### Create a new `CustomSessionStorage` to use in `config`
+
+Now we can import our custom storage class into our `index.ts` and use it to setup our storage solution in `config`.
+
+```ts
+/* index.ts */
+
+import {shopifyApi, LATEST_API_VERSION} from '@shopify/shopify-api';
+import {CustomSessionStorage} from '@shopify/shopify-api/session-storage/custom';
+
+// Import our custom storage class
+import RedisStore from './redis-store';
+
+// Create a new instance of the custom storage class
+const redisStore = new RedisStore();
+
+// Setup config with CustomSessionStorage
+const shopify = shopifyApi({
+  ...
+  // Pass the sessionStorage methods to pass into a new instance of `CustomSessionStorage`
+  sessionStorage: new CustomSessionStorage(
+    redisStore.storeCallback.bind(redisStore),
+    redisStore.loadCallback.bind(redisStore),
+    redisStore.deleteCallback.bind(redisStore),
+  ),
+});
+
+// Your app will now use your new storage solution to access and manage Sessions
+```
+
+At this point, you should have a working `CustomSessionStorage` solution that will work seamlessly with this library in your Shopify application.
+
+**Note:** This is only one possible `CustomSessionStorage` solution. As long as your callback methods fit the requirements for argument types and return types, you can use any storage solution or database you're comfortable and/or familiar with.
+
+[Back to guide index](../../README.md#features)

package/docs/usage/graphql.md

@@ -0,0 +1,132 @@
+# GraphQL Admin API client
+
+Once OAuth is complete, we can use this library to interact with the Admin GraphQL API.
+To do that, create an instance of `shopify.clients.Graphql` using the current shop URL and session `accessToken` in your app's endpoint.
+
+To create a client, you'll need a session, for example:
+
+```ts
+// Requests to /my-endpoint must be made with authenticatedFetch from App Bridge for embedded apps
+app.get('/my-endpoint', async () => {
+  const session = await shopify.session.getCurrent({
+    isOnline: true,
+    rawRequest: req,
+    rawResponse: res,
+  });
+
+  const client = new shopify.clients.Graphql({
+    domain: session.shop,
+    accessToken: session.accessToken,
+  });
+});
+```
+
+Once you construct a client, you can use the `query` method to run GraphQL queries or mutations on the API.
+
+<div>Using a string:
+
+```ts
+const response = await client.query({
+  data: `{
+    products (first: 10) {
+      edges {
+        node {
+          id
+          title
+          descriptionHtml
+        }
+      }
+    }
+  }`,
+});
+console.log(response.headers, response.body);
+```
+
+</div><div>Or using variables:
+
+```ts
+const response = await client.query({
+  data: {
+    query: `query GetProducts($first: Int!) {
+      products (first: $first) {
+        edges {
+          node {
+            id
+            title
+            descriptionHtml
+          }
+        }
+      }
+    }`,
+    variables: {
+      first: 10,
+    },
+  },
+});
+console.log(response.headers, response.body);
+```
+
+</div>
+
+**Note**: we recommend using the [Shopify Admin API GraphiQL explorer](https://shopify.dev/apps/tools/graphiql-admin-api) to help build your queries.
+
+If you're using TypeScript, you can pass in a type argument for the response body:
+
+```ts
+// If using TypeScript, you can type the response body
+interface MyResponseBodyType {
+  data: {
+    //...
+  };
+}
+
+const response = await client.query<MyResponseBodyType>({
+  /* ... */
+});
+
+// response.body will be of type MyResponseBodyType
+console.log(response.body.data);
+```
+
+The `query` method accepts the following arguments:
+
+| Parameter      | Type                                | Required? | Default Value | Notes                                                             |
+| -------------- | ----------------------------------- | :-------: | :-----------: | ----------------------------------------------------------------- |
+| `data`         | `Record<string, unknown> \| string` |    Yes    |       -       | Either a string, or an object with a `query` and `variables`      |
+| `query`        | `Record<string, string \| number>`  |    No     |       -       | An optional query argument object to append to the request URL    |
+| `extraHeaders` | `Record<string, string \| number>`  |    No     |       -       | Add custom headers to your request                                |
+| `tries`        | `number`                            |    No     |      `1`      | The maximum number of times to retry the request _(must be >= 0)_ |
+
+It will return an object containing the response `headers` and `body` from Shopify.
+If there are any errors in the response, `query` will throw a `GraphqlQueryError` which includes details from the API response:
+
+```ts
+import {GraphqlQueryError} from '@shopify/shopify-api';
+
+try {
+  const products = await client.query({
+    data: `{
+      products (first: 10) {
+        edges {
+          node {
+            id
+            title
+            descriptionHtml
+          }
+        }
+      }
+    }`,
+  });
+
+  // No errors, proceed with logic
+} catch (error) {
+  if (error instanceof GraphqlQueryError) {
+    // look at error.response for details returned from API,
+    // specifically, error.response.errors[0].message
+  } else {
+    // handle other errors
+  }
+}
+```
+
+[Back to guide index](../../README.md#features)

package/docs/usage/oauth.md

@@ -0,0 +1,171 @@
+# Performing OAuth
+
+After you set up the library for your project, you'll be able to use it to interact with the APIs, and add your own functionality.
+The first thing your app will need to do is to get a token to access the Admin API by performing the OAuth process. Learn more about [OAuth on the Shopify platform](https://shopify.dev/apps/auth/oauth).
+
+To perform OAuth, you will need to create two endpoints in your app:
+
+1. [Start the process](#start-endpoint) by directing the merchant to Shopify to ask for permission to install the app.
+1. [Return the merchant to your app](#callback-endpoint) once they approve the app installation, to set up a session with an API access token.
+
+Once you complete the OAuth process, you'll be able to [use the session it creates](#using-sessions) to create API clients.
+
+**Note**: private apps are unable to perform OAuth, because they don't require an access token to interact with API.
+
+## Start endpoint
+
+The route for starting the OAuth process (in this case `/auth`) will use the library's `shopify.auth.begin` method. The method will set up the process and respond by redirecting the user to the Shopify Authentication screen, where the merchant will have to accept the required app scopes.
+
+Example `/auth` endpoint in an Express.js app:
+
+```ts
+app.get('/auth', async (req, res) => {
+  // The library will automatically redirect the user
+  await shopify.auth.begin({
+    shop: shopify.utils.sanitizeShop(req.query.shop, true),
+    callbackPath: '/auth/callback',
+    isOnline: false,
+    rawRequest: req,
+    rawResponse: res,
+  });
+});
+```
+
+Example `/auth` endpoint in a Cloudflare Worker:
+
+```ts
+async function handleFetch(request: Request): Promise<Response> {
+  const {searchParams} = new URL(request.url);
+
+  // The library will return a Response object
+  return shopify.auth.begin({
+    shop: shopify.utils.sanitizeShop(searchParams.get('shop'), true),
+    callbackPath: '/auth/callback',
+    isOnline: false,
+    rawRequest: request,
+  });
+}
+```
+
+This method takes an object with the following properties:
+
+| Parameter      | Type              |      Required?       | Default Value | Notes                                                                                                                                           |
+| -------------- | ----------------- | :------------------: | :-----------: | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `shop`         | `string`          |         Yes          |       -       | A Shopify domain name in the form `{exampleshop}.myshopify.com`.                                                                                |
+| `callbackPath` | `string`          |         Yes          |       -       | The path to the callback endpoint, with a leading `/`. This URL must be allowed in the Partners dashboard, or using the CLI to run your app.    |
+| `isOnline`     | `bool`            |         Yes          |       -       | `true` if the session is online and `false` otherwise. Learn more about [OAuth access modes](https://shopify.dev/apps/auth/oauth/access-modes). |
+| `rawRequest`   | `AdapterRequest`  |         Yes          |       -       | The HTTP Request object used by your runtime.                                                                                                   |
+| `rawResponse`  | `AdapterResponse` | _Depends on runtime_ |       -       | The HTTP Response object used by your runtime. Required for Node.js.                                                                            |
+
+## Callback endpoint
+
+Once the merchant approves the app's request for scopes, Shopify will redirect them back to your app, using the `callbackPath` parameter from `shopify.auth.begin`. Your app can then call `shopify.auth.callback` to complete the OAuth process, which will create a new Shopify `Session` and return the appropriate HTTP headers your app should respond with.
+
+Example `/auth/callback` endpoint in an Express.js app:
+
+```ts
+app.get('/auth/callback', async (req, res) => {
+  // The library will automatically set the appropriate HTTP headers
+  const callback = await shopify.auth.callback({
+    isOnline: false,
+    rawRequest: req,
+    rawResponse: res,
+  });
+
+  // You can now use callback.session to make API requests
+
+  res.redirect('/my-apps-entry-page');
+});
+```
+
+Example `/auth/callback` endpoint in a Cloudflare Worker:
+
+```ts
+async function handleFetch(request: Request): Promise<Response> {
+  const callback = await shopify.auth.callback<Headers>({
+    isOnline: false,
+    rawRequest: request,
+  });
+
+  // You can now use callback.session to make API requests
+
+  // The callback returns some HTTP headers, but you can redirect to any route here
+  return new Response('', {
+    status: 302,
+    // Headers are of type [string, string][]
+    headers: [...callback.headers, ['Location', '/my-apps-entry-page']],
+  });
+}
+```
+
+This method takes an object with the following properties:
+
+| Parameter     | Type              |      Required?       | Default Value | Notes                                                                                          |
+| ------------- | ----------------- | :------------------: | :-----------: | ---------------------------------------------------------------------------------------------- |
+| `isOnline`    | `bool`            |         Yes          |       -       | `true` if the session is online and `false` otherwise. Must match the value from `auth.begin`. |
+| `rawRequest`  | `AdapterRequest`  |         Yes          |       -       | The HTTP Request object used by your runtime.                                                  |
+| `rawResponse` | `AdapterResponse` | _Depends on runtime_ |       -       | The HTTP Response object used by your runtime. Required for Node.js.                           |
+
+It will save a new session using your configured `sessionStorage`, and return an object containing:
+
+| Property  | Type             | Notes                                                                                                                                                                              |
+| --------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `session` | `Session`        | The new Shopify session, containing the API access token.                                                                                                                          |
+| `headers` | `AdapterHeaders` | The HTTP headers to include in the response. In TypeScript, you can pass in a type to get a typed object back - see the Cloudflare example above. Returns `undefined` for Node.js. |
+
+## Using sessions
+
+Once you set up both of the above endpoints, you can navigate to `{your ngrok address}/auth` in your browser to begin OAuth. When it completes, you will have a Shopify session that enables you to make requests to the Admin API, for instance [the REST Admin API client](./rest.md).
+
+### Loading a session while handling a request
+
+To load a session while handling a request, you can use `shopify.session.getCurrent` to authenticate a request for both online and offline sessions:
+
+```ts
+app.get('/fetch-some-data', async (req, res) => {
+  const session = await shopify.session.getCurrent({
+    isOnline: true,
+    rawRequest: req,
+    rawResponse: res,
+  });
+
+  // Build a client and make requests with session.accessToken
+  // See the REST, GraphQL, or Storefront API documentation for more information
+});
+```
+
+**Note**: this method will rely on cookies for non-embedded apps, and the `Authorization` HTTP header for embedded apps using [App Bridge session tokens](https://shopify.dev/apps/auth/oauth/session-tokens), making all apps safe to use in modern browsers that block 3rd party cookies.
+
+For embedded apps, `shopify.session.getCurrent` will only be able to find a session if you use `authenticatedFetch` from the `@shopify/app-bridge-utils` client-side package. This function behaves like a [normal `fetch` call](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch), but ensures the appropriate headers are set.
+
+Learn more about [making authenticated requests](https://shopify.dev/apps/auth/oauth/session-tokens/getting-started#step-2-authenticate-your-requests) using App Bridge.
+
+### Loading a session for a background job
+
+If your app needs to access the API while not handling a direct request, for example in a background job, you can use `shopify.session.getOffline` to load an offline access token for your script.
+
+**Note**: this method **_does not_** perform any validation on the `shop` parameter. You should **_never_** read the shop from user inputs or URLs.
+
+```ts
+const session = await shopify.session.getOffline({
+  shop: '{exampleshop}.myshopify.com',
+});
+```
+
+## Detecting scope changes
+
+When the OAuth process is completed, the created session has a `scope` field which holds all of the scopes that were requested from the merchant at the time.
+
+When an app's scopes change, it needs to request merchants to go through OAuth again to renew its permissions. The library provides an easy way for you to check whether that is the case at any point in your code:
+
+```ts
+const session: Session; // Loaded from one of the methods above
+
+if (!shopify.config.scopes.equals(session.scope)) {
+  // Scopes have changed, the app should redirect the merchant to OAuth
+}
+```
+
+This is useful if you have a middleware or pre-request check in your app to ensure that the session is still valid.
+
+[Back to guide index](../../README.md#features)