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

package/docs/usage/rest.md

@@ -0,0 +1,179 @@
+# REST Admin API client
+
+Once OAuth is complete, we can use this library to interact with the Admin REST API.
+It can do that in two different ways:
+
+1. [Using the client class](#using-the-client-class)
+1. [Using REST resources](#using-rest-resources)
+
+For detailed information on individual endpoints, please visit our [REST API reference](https://shopify.dev/api/admin-rest).
+
+## Using the client class
+
+The simplest way to interact with the API is using an instance of `shopify.clients.Rest`. To create a client, you'll need a session, for example:
+
+```ts
+// Requests to /my-endpoint must be made with authenticatedFetch for embedded apps
+app.get('/my-endpoint', async (req, res) => {
+  const session = await shopify.session.getCurrent({
+    isOnline: true,
+    rawRequest: req,
+    rawResponse: res,
+  });
+
+  const client = new shopify.clients.Rest({
+    domain: session.shop,
+    accessToken: session.accessToken,
+  });
+});
+```
+
+Once you've constructed a client, you can use it to call API endpoints by their methods:
+
+- `client.get`
+- `client.post`
+- `client.put`
+- `client.delete`
+
+For example, this is how you can make `GET` and `POST` requests to the `/products.json` endpoint using the client created above:
+
+```ts
+const response = await client.get({
+  path: 'products',
+});
+console.log(response.headers, response.body);
+
+const response = await client.post({
+  path: 'products',
+  data: {
+    title: 'My product title',
+  },
+});
+console.log(response.headers, response.body);
+```
+
+Note that if you're using TypeScript, you can also pass in a type argument to cast the response body:
+
+```ts
+interface MyResponseBodyType {
+  products: {
+    /* ... */
+  };
+}
+
+const response = await client.get<MyResponseBodyType>({
+  path: 'products',
+});
+
+// response.body will be of type MyResponseBodyType
+console.log(response.body.products);
+```
+
+The `get`, `post`, `put`, and `delete` methods accept the following arguments:
+
+| Parameter      | Type                                |   Required?   |  Default Value  | Notes                                                                                                                                                                                                                                                                                    |
+| -------------- | ----------------------------------- | :-----------: | :-------------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `path`         | `string`                            |      Yes      |        -        | The requested API endpoint path. This can be one of two formats:<ul><li>The path starting after the `/admin/api/{version}/` prefix, such as `'products'`, which executes `/admin/api/{version}/products.json`</li><li>The full path, such as `/admin/oauth/access_scopes.json`</li></ul> |
+| `data`         | `Record<string, unknown> \| string` | `post`, `put` |        -        | The request payload                                                                                                                                                                                                                                                                      |
+| `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 the request                                                                                                                                                                                                                                                        |
+| `type`         | `DataType`                          |      No       | `DataType.JSON` | The `Content-Type` for the request (`JSON`, `GraphQL`, `URLEncoded`)                                                                                                                                                                                                                     |
+| `tries`        | `number`                            |      No       |       `1`       | The maximum number of times to retry the request _(must be >= 0)_                                                                                                                                                                                                                        |
+
+They will return an object containing the response `headers` and `body` from Shopify.
+
+## Using REST resources
+
+The Admin API has a lot of endpoints, and the differences between them can be subtle.
+To make it easier to interact with the API, this library provides resource classes, which map these endpoints to OO code and can make API queries feel more natural.
+
+**Note**: we provide auto-generated resources for all **_stable_** API versions, so your app must include the appropriate set (see [mounting REST resources](#mounting-rest-resources) below), matching your `apiVersion` configuration. The library will throw an error if the versions don't match.
+
+Below is an example of how REST resources can make it easier to fetch the first product and update it:
+
+<div>With a plain REST client:
+
+```ts
+// App must provide response types
+interface ProductResponse {
+  product: {
+    id: number;
+    title: string;
+    // ...
+  };
+}
+
+const session = await shopify.session.getCurrent({
+  rawRequest: req,
+  rawResponse: res,
+});
+const client = new shopify.clients.Rest({
+  domain: session.shop,
+  accessToken: session.accessToken,
+});
+
+// The following line sends a HTTP GET request to this constructed URL:
+// https://${session.shop}/admin/api/${shopify.config.api_version}/products.json?limit=1
+const response = await client.get<ProductResponse>({
+  path: 'products',
+  query: {limit: 1},
+});
+
+// Apps needs to dig into the response body to find the object
+response.body.product.title = 'A new title';
+
+// The following sends a HTTP PUT request to this constructed URL...
+// https://${session.shop}/admin/api/${shopify.config.api_version}/products/${response.body.product.id}.json
+// ... with this body
+// {"product":{"id":response.body.product.id,"title":"A new title"}}
+await client.put({
+  path: `products/${response.body.product.id}`,
+  data: response.body.product,
+});
+```
+
+</div><div>With REST resources:
+
+```ts
+const session = await shopify.session.getCurrent({
+  rawRequest: req,
+  rawResponse: res,
+});
+
+// Has type Product[], an OO representation of API products
+const products = await shopify.rest.Product.all({session, limit: 1});
+
+products[0].title = 'A new title';
+await products[0].save();
+```
+
+</div>
+
+The resource classes provide representations of all endpoints for the API resource they cover. A few examples:
+
+1. `GET /products.json` maps to `Product.all()`
+1. `POST /products.json` maps to `product.save()` (as an instance method)
+1. `GET /products/count.json` maps to `Product.count()`
+
+Please visit our [REST API reference documentation](https://shopify.dev/api/admin-rest) for detailed instructions on how to call each of the endpoints.
+
+### Mounting REST resources
+
+The library doesn't include all available resources automatically to make loading it more efficient, since there are hundreds of resource classes.
+To use REST resources, you can import the desired version and mount it onto your `shopify` object when creating it:
+
+```ts
+import {shopifyApi} from '@shopify/shopify-api';
+import {restResources} from '@shopify/shopify-api/rest/admin/2022-07';
+
+const shopify = shopifyApi({
+  ...,
+  apiVersion: ApiVersion.July22,
+  restResources,
+});
+```
+
+This will automatically load all REST resources onto `shopify.rest`, as per the example above.
+From this point, you can start using the resources to interact with the API.
+
+[Back to guide index](../../README.md#features)

package/docs/usage/runtimes.md

@@ -0,0 +1,54 @@
+# Adding custom runtimes
+
+This package provides support for a set of JavaScript runtimes, but it won't cover all possible use cases.
+It's designed in a way that can support any runtime, as long as an adapter provides the implementations for runtime-specific functionality.
+
+**Note**: this is an advanced feature, so using TypeScript and an IDE with intellisense is strongly recommended to help guide you through the implementation.
+
+See the [available adapters](../../adapters/) for some implementation examples.
+In general, an adapter needs to teach the library to convert the runtime's own request / response objects into the `NormalizedRequest` and `NormalizedResponse` objects used by the library, and to define some reasonable defaults for the runtime, like a session storage strategy.
+
+To create an adapter, you'll need to import the runtime functions to provide implementations.
+These are the functions you'll need to create:
+
+- `setAbstractFetchFunc`
+- `setAbstractConvertRequestFunc`
+- `setAbstractConvertResponseFunc`
+- `setAbstractConvertHeadersFunc`
+- `setAbstractCreateDefaultStorage`
+- `setAbstractRuntimeString`
+- `setCrypto`
+
+Below is a _very_ simplified example with some functions:
+
+```ts
+import {
+  setAbstractConvertHeadersFunc,
+  setAbstractRuntimeString,
+  AbstractRuntimeStringFunc,
+  AbstractConvertHeadersFunc,
+  Headers,
+  AdapterArgs,
+} from '@shopify/shopify-api/runtime';
+
+type MyRequestType = any;
+type MyResponseType = any;
+
+interface MyRuntimeAdapterArgs extends AdapterArgs {
+  rawRequest: MyRequestType;
+  rawResponse?: MyResponseType;
+}
+
+const myRuntimeStringFunc: AbstractRuntimeStringFunc = () => {
+  return `My runtime adapter ${myAdapterVersion}`;
+};
+setAbstractRuntimeString(myRuntimeStringFunc);
+
+const myRuntimeHeaderFunc: AbstractConvertHeadersFunc = async (
+  headers: Headers,
+  adapterArgs: MyRuntimeAdapterArgs,
+) => {
+  return magicHeaderConversion(headers);
+};
+setAbstractConvertHeadersFunc(myRuntimeHeaderFunc);
+```

package/docs/usage/storefront.md

@@ -0,0 +1,72 @@
+# GraphQL Storefront API client
+
+The library also allows you to send GraphQL requests to the [Shopify Storefront API](https://shopify.dev/docs/storefront-api). To do that, you can use `shopify.clients.Storefront` with the current shop URL and a storefront-specific `accessToken`.
+
+⚠️ This API limits request rates based on the IP address that calls it, which will be your server's address for all requests made by the library. The API uses a leaky bucket algorithm, with a default bucket size of 60 seconds of request processing time (minimum 0.5s per request), with a leak rate of 1/s. Learn more about [rate limits](https://shopify.dev/api/usage/rate-limits).
+
+## Requirements
+
+You can create Storefront API access tokens for both **private apps** and **sales channels**, but you **must use offline access tokens** for sales channels. Please read [our documentation](https://shopify.dev/docs/storefront-api/getting-started) to learn more about Storefront Access Tokens.
+
+If you are building a private app, you can set a default Storefront Access Token for all `Storefront` client instances by setting the `config.privateAppStorefrontAccessToken` property.
+
+## Creating and using tokens
+
+The `Storefront` client extends the `Graphql` client, so it supports the same parameters. Please refer to the [Graphql client documentation](graphql.md) for details.
+
+Below is a (simplified) example of how you may create a token (see [REST](https://shopify.dev/api/admin-rest/2022-07/resources/storefrontaccesstoken) or [GraphQL](https://shopify.dev/api/admin-graphql/2022-07/mutations/storefrontAccessTokenCreate) Admin API reference) and make a request:
+
+```ts
+app.get('/my-endpoint', async (req, res) => {
+  const session = await shopify.session.getCurrent({
+    isOnline: true,
+    rawRequest: req,
+    rawResponse: res,
+  });
+
+  // Create a new storefront access token using the REST Admin API (you can also use the GraphQL API)
+  const adminApiClient = new shopify.clients.Rest({
+    domain: session.shop,
+    accessToken: session.accessToken,
+  });
+  const storefrontTokenResponse = await adminApiClient.post({
+    path: 'storefront_access_tokens',
+    data: {
+      storefront_access_token: {
+        title: 'This is my test access token',
+      },
+    },
+  });
+
+  const storefrontAccessToken =
+    storefrontTokenResponse.body.storefront_access_token.access_token;
+
+  // For simplicity, this example creates a token every time it's called, but that is not ideal.
+  // You can fetch existing Storefront access tokens using the Admin API clients.
+  const storefrontClient = new shopify.clients.Storefront({
+    domain: session.shop,
+    accessToken: storefrontAccessToken,
+  });
+
+  const products = await client.query({
+    data: `{
+      products (first: 10) {
+        edges {
+          node {
+            id
+            title
+            descriptionHtml
+          }
+        }
+      }
+    }`,
+  });
+
+  // do something with the returned data
+});
+```
+
+Once you've created your access token, you can query the Storefront API based on the `unauthenticated_*` scopes your app requests.
+See the [API reference documentation](https://shopify.dev/api/storefront) for detailed instructions on each component.
+
+[Back to guide index](../../README.md#features)

package/docs/usage/utils.md

@@ -0,0 +1,30 @@
+# utils
+
+## Get the application URL for embedded apps using `getEmbeddedAppUrl`
+
+If you need to redirect a request to your embedded app URL you can use `getEmbeddedAppUrl`
+
+```ts
+const redirectURL = Shopify.Utils.getEmbeddedAppUrl(request);
+res.redirect(redirectURL);
+```
+
+Using this utility ensures that embedded app URL is properly constructed and brings the merchant to the right place. It is more reliable than using the shop param.
+
+This utility relies on the host query param being a Base 64 encoded string. All requests from Shopify should include this param in the correct format.
+
+## Sanitize a Shopify shop domain and host address
+
+When receiving input from users, like in URL query arguments, you should always make sure to sanitize that data.
+To make it easier to do that, this library provides the following methods:
+
+```ts
+const shop = Shopify.Utils.sanitizeShop(req.query.shop, true);
+const host = Shopify.Utils.sanitizeHost(req.query.host, true);
+```
+
+Both of these return the string itself if it's valid, or `null` otherwise.
+You can also optionally set the method to throw an exception if the validation fails.
+If you're using custom shop domains for testing, you can add them to the `config.customShopDomains` setting.
+
+[Back to guide index](../../README.md#features)

package/docs/usage/webhooks.md

@@ -0,0 +1,215 @@
+# Webhooks
+
+If your application's functionality depends on knowing when events occur on a given shop, you need to register a webhook. You need an access token to register webhooks, so you must complete the OAuth process beforehand.
+
+The Shopify library enables you to handle all webhooks in a single endpoint (see [Webhook processing](#webhook-processing)
+) below), but you are not restricted to a single endpoint. You can only register each topic once per shop, but the library will ensure your handler is up to date if you call `register` more than once.
+
+To subscribe to webhooks using this library, there are 3 main steps to take:
+
+1. [Load your handlers](#load-your-handlers)
+1. [Register webhooks with Shopify](#webhook-registration)
+1. [Process incoming webhooks](#webhook-processing)
+
+## Load your handlers
+
+The first step to process webhooks in your app is telling the library how you expect to handle them. To do that, you can call the `shopify.webhooks.addHttpHandler` method to set the callback you want the library to trigger when a certain topic is received.
+
+For example, you can load one or more handlers when setting up your app's `config` (or any other location, as long as it happens before the call to `shopify.webhooks.process`) by running:
+
+```typescript
+import {shopifyApi} from '@shopify/shopify-api';
+const shopify = shopifyApi({ apiKey: '...', ... });
+
+const handleWebhookRequest = async (topic: string, shop: string, webhookRequestBody: string) => {
+  // handler triggered when a webhook is sent by the Shopify platform to your application
+}
+
+shopify.webhooks.addHttpHandler({
+  topic: "PRODUCTS_CREATE",
+  handler: handleWebhookRequest,
+});
+```
+
+The parameters this method accepts are:
+
+| Parameter | Type                     | Required? | Default Value | Notes                                                                                                                        |
+| ----------| ------------------------ | :-------: | :-----------: | ---------------------------------------------------------------------------------------------------------------------------- |
+| `topic`   | `string`                 |    Yes    |       -       | The topic to subscribe to, [see the full list](https://shopify.dev/api/admin-graphql/latest/enums/WebhookSubscriptionTopic). |
+| `handler` | `WebhookHandlerFunction` |    Yes    |       -       | The `async` callback to call when a shop triggers a `topic` event.                                                           |
+
+When a shop triggers an event you subscribed to, the `process` method [below](#webhook-processing) will call your handler with the following arguments:
+
+| Parameter            | Type     | Notes                                            |
+| -------------------- | -------- | ------------------------------------------------ |
+| `topic`              | `string` | The webhook topic.                               |
+| `shop`               | `string` | The shop for which the webhook was triggered.    |
+| `webhookRequestBody` | `string` | The payload of the POST request made by Shopify. |
+
+**Note**: You only need to add handlers for webhooks delivered to your app via HTTPS. For webhooks delivered to Amazon EventBridge or Google Cloud Pub/Sub, you don't add any handlers - you just call `register` (see [webhook registration](#webhook-registration) and [EventBridge and Pub/Sub webhooks](#eventbridge-and-pubsub-webhooks) for more details).
+
+A similar `addHttpHandlers` method is also provided for convenience, which takes in an array of objects with `topic` and `handler` properties, e.g.,
+
+```typescript
+  shopify.webhooks.addHttpHandlers([
+    {topic: 'PRODUCTS_CREATE', handler: productCreateWebhookHandler},
+    {topic: 'PRODUCTS_DELETE', handler: productDeleteWebhookHandler},
+  ]);
+```
+
+## Get HTTP webhook registry information
+
+To see topics loaded in the HTTP registry, `shopify.webhooks.getTopicsAdded` returns an array of topics names, as strings, or an empty array if there are no topics and handlers loaded.
+
+```typescript
+  shopify.webhooks.addHttpHandlers([
+    {topic: 'PRODUCTS_CREATE', handler: productCreateWebhookHandler},
+    {topic: 'PRODUCTS_DELETE', handler: productDeleteWebhookHandler},
+  ]);
+  const topics = shopify.webhooks.getTopicsAdded();
+  // topics = ['PRODUCTS_CREATE', 'PRODUCTS_DELETE']
+```
+
+To retrieve the handler information for a given topic, `shopify.webhooks.getHttpHandler()` takes a topic string as an argument and returns the handler or `null` if not found.
+
+```typescript
+  shopify.webhooks.addHttpHandler({
+    topic: 'PRODUCTS',
+    handler: productsWebhookHandler,
+  });
+  const productsHandler = shopify.webhooks.getHttpHandler('PRODUCTS');
+  // productsHandler = productsWebhookHandler
+```
+
+## Webhook Registration
+
+After loading your handlers, you need to register which topics you want your app to listen to with Shopify. This can only happen after the merchant has installed your app, so the best place to register webhooks is after OAuth completes.
+
+In your OAuth callback action, you can use the `shopify.webhooks.register` method to subscribe to any topic allowed by your app's scopes. You can safely call this method multiple times for a shop, as it will add or update subscriptions as necessary.
+
+The parameters this method accepts are:
+
+| Parameter        | Type     | Required? |     Default Value     | Notes                                                                         |
+| :--------------- | :------- | :-------: | :-------------------: | :---------------------------------------------------------------------------- |
+| `path`           | `string` |    Yes    |           -           | The URL path for the callback for HTTPS delivery, EventBridge or Pub/Sub URLs |
+| `topic`          | `string` |    Yes    |           -           | The topic to subscribe to.                                                    |
+| `shop`           | `string` |    Yes    |           -           | The shop to use for requests.                                                 |
+| `accessToken`    | `string` |    Yes    |           -           | The access token to use for requests.                                         |
+| `deliveryMethod` | `string` |    No     | `DeliveryMethod.Http` | The delivery method for this webhook.                                         |
+
+This method will return a `RegisterReturn` object, which holds the following data:
+
+| Method    | Return type | Notes                                                                                                                 |
+| --------- | ----------- | --------------------------------------------------------------------------------------------------------------------- |
+| `success` | `bool`      | Whether the registration was successful.                                                                              |
+| `result`  | `array`     | The body from the Shopify request to register the webhook. May be null even when successful if no request was needed. |
+
+> **Note**: If you want to register all your webhook topics, you can call the `shopify.webhooks.registerAllHttp({path, accessToken, shop})` method, which will iterate over your handlers and set them all up.
+>
+> `registerAllHttp()` accepts the following parameters:
+>
+> | Parameter        | Type     | Required? |     Default Value     | Notes                                            |
+> | :--------------- | :------- | :-------: | :-------------------: | :----------------------------------------------- |
+> | `path`           | `string` |    Yes    |           -           | The URL path for the callback for HTTPS delivery |
+> | `shop`           | `string` |    Yes    |           -           | The shop to use for requests.                    |
+> | `accessToken`    | `string` |    Yes    |           -           | The access token to use for requests.            |
+>
+
+For example, to subscribe to the `PRODUCTS_CREATE` event, you can run this code in your OAuth callback action:
+
+```ts
+// Register webhooks after OAuth completes
+app.get('/auth/callback', async (req, res) => {
+  try {
+    const callbackResponse = await shopify.auth.callback({
+      isOnline: true,
+      rawRequest: req,
+      rawResponse: res,
+    });
+
+    const response = await shopify.webhooks.register({
+      path: '/webhooks',
+      topic: 'PRODUCTS_CREATE',
+      accessToken: callbackResponse.session.accessToken,
+      shop: callbackResponse.session.shop,
+    });
+
+    if (!response['PRODUCTS_CREATE'].success) {
+      console.log(
+        `Failed to register PRODUCTS_CREATE webhook: ${response['PRODUCTS_CREATE'].result}`
+      );
+    }
+  } catch (error) {
+    console.error(error); // in practice these should be handled more gracefully
+  }
+  return res.redirect('/'); // or wherever you want your user to end up after OAuth completes
+});
+```
+
+### EventBridge and PubSub Webhooks
+
+You can also register webhooks for delivery to Amazon EventBridge or Google Cloud Pub/Sub. In this case the `path` argument to `register` needs to be of a specific form.
+
+For EventBridge, the `path` must be the [ARN of the partner event source](https://docs.aws.amazon.com/eventbridge/latest/APIReference/API_EventSource.html).
+
+For Pub/Sub, the `path` must be of the form `pubsub://[PROJECT-ID]:[PUB-SUB-TOPIC-ID]`. For example, if you created a topic with id `red` in the project `blue`, then the value of `path` would be `pubsub://blue:red`.
+
+## Webhook Processing
+
+To process an HTTPS webhook, you need to listen on the route(s) you provided during the webhook registration process, then call the appropriate handler. The library provides a convenient method that acts as a middleware to handle webhooks. It takes care of validating the request, and calling the correct handler for registered webhook topics.
+
+The `process` method will handle extracting the necessary information from your request and response objects, and triggering the appropriate handler with the parameters detailed above. If it can't find a handler for a topic, it will raise an error.
+
+**Note**: In Node, the `process` method will always respond to Shopify, even if your call throws an error. You can catch and log errors, but you can't change the response.
+
+```typescript
+app.post('/webhooks', express.text({type: '*/*'}), async (req, res) => {
+  try {
+    // Note: the express.text() given above is an Express middleware that will read
+    // in the body as a string, and make it available at req.body, for this path only.
+    await shopify.webhooks.process({
+      rawBody: req.body, // is a string
+      rawRequest: req,
+      rawResponse: res,
+    });
+  } catch (error) {
+    console.log(error.message);
+  }
+});
+```
+
+**Note**: In a worker environment, e.g., CloudFlare Workers, the return value of the `process` method can be used to reply to Shopify. If the `process` call throws an error, the response will be contained in the thrown error, in `error.response`.  This will enable the calling method in a worker environment to return a suitable response to Shopify.
+
+```typescript
+  let response;
+
+  try {
+    response = await shopify.webhooks.process({
+      rawBody: req.body,
+      rawRequest: req,
+      rawResponse: res,
+    });
+  } catch (error) {
+    console.log(error.message);
+    response = error.response;
+  }
+  return response;
+```
+
+### Note regarding use of body parsers
+
+Unlike `v5` and earlier versions of this library, `shopify.webhooks.process()` now expects to receive the body content (in string format) as a parameter and no longer reads in the request body directly.
+
+This allows for the use of body-parsers in your code.
+
+To use Express as an example, if you wish to use the `express.json()` middleware in your app, the webhook processing can now occur after calling `app.use(express.json())`.  For any path that's a webhooks path, `express.text({type: '*/*'})` should be used so that `req.body` is a string that `shopify.webhooks.process()` expects:
+
+```typescript
+  await shopify.webhooks.process({
+    rawBody: req.body,
+    rawRequest: req,
+    rawResponse: res,
+  });
+```
+
+[Back to guide index](../../README.md#features)

package/docs/usage/withsession.md

@@ -0,0 +1,74 @@
+# Create a Client using `withSession`
+
+This library provides a utility method `withSession` that you can use to create either a REST or GraphQL client, with
+either the current active online session, or a specific offline session. The method will return both the requested
+client, and the session with which that client will be authenticated.
+
+This method accepts a `withSessionParams` object as its argument, which accepts options for the fields: `clientType`,
+`isOnline`, `req`, `res`, and `shop`.
+
+| Parameter    | Type                   | Notes                                                                |
+| ------------ | ---------------------- | -------------------------------------------------------------------- |
+| `clientType` | string                 | must be either `graphql` or `rest`                                   |
+| `isOnline`   | boolean                | optional parameters needed are based on the value of `isOnline`      |
+| `req`        | `http.IncomingMessage` | required if `isOnline`                                               |
+| `res`        | `http.ServerResponse`  | required if `isOnline`                                               |
+| `shop`       | string                 | required if `!isOnline` and should be passed without protocol prefix |
+
+## Code Usage Examples
+
+The following are specific examples of GraphQL/online session, and REST/offline session, but any combination of `clientType` and `isOnline` is valid.
+
+<details>
+<summary>Example: GraphQL Client with online Session</summary>
+
+```ts
+// create a `WithSessionParams` object with the necessary information to pass to `withSession`
+const clientWithSessionParams: WithSessionParams = {
+  clientType: 'graphql',
+  isOnline: true,
+  req: request, // http.IncomingMessage object
+  res: response, // http.ServerResponse object
+};
+
+const {client, session} = (await Shopify.Utils.withSession(
+  clientWithSessionParams,
+)) as GraphqlWithSession;
+
+// now you can make requests to the API using this client:
+const shopName = await client.query({
+  data: `{
+      shop {
+        name
+      }
+    }`,
+});
+
+// you can also introspect on the returned Session, if you need to
+const currentSessionUser = session.onlineAccessInfo.associated_user;
+```
+
+</details>
+
+<details>
+<summary>Example: REST Client with offline session</summary>
+
+```ts
+const clientWithSessionParams: WithSessionParams = {
+  clientType: 'rest',
+  isOnline: false,
+  shop: SHOP, // Shopify store url, without protocol, ie: "{shop}.myshopify.com"
+};
+
+const {client, session} = (await Shopify.Utils.withSession(
+  clientWithSessionParams,
+)) as RestWithSession;
+
+const products = await client.get({path: 'products'});
+
+const currentSessionScope = session.scope;
+```
+
+</details>
+
+[Back to guide index](../../README.md#features)

package/lib/auth/get-embedded-app-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-embedded-app-url.d.ts","sourceRoot":"","sources":["get-embedded-app-url.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,eAAe,EAAC,MAAM,eAAe,CAAC;AAI9C,OAAO,EAAC,uBAAuB,EAAC,MAAM,SAAS,CAAC;AAEhD,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,eAAe,wBAC7B,uBAAuB,KAAG,QAAQ,MAAM,CAAC,CA0B1E;AAED,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,eAAe,UACjD,MAAM,KAAG,MAAM,CAY9B"}