Merge branch 'main' into dependabot/npm_and_yarn/swc/core-1.3.107

.changeset/loud-camels-sell.md

@@ -0,0 +1,7 @@
+---
+"@shopify/shopify-api": minor
+---
+
+Added support for validating Flow extension requests, using `shopify.authenticate.flow`.
+
+Please see [the `flow` object documentation](./docs/reference/flow/README.md) for more information.

.changeset/odd-poems-smash.md

@@ -0,0 +1,2 @@
+---
+---

.github/workflows/markdown_link_check.yml

@@ -10,3 +10,4 @@ jobs:
       - uses: gaurav-nelson/github-action-markdown-link-check@v1
         with:
           config-file: '.github/workflows/markdown_link_checker_config.json'
+          folder-path: 'packages'

packages/shopify-api/docs/reference/flow/README.md

@@ -0,0 +1,9 @@
+# shopify.flow
+
+This object contains functions used to authenticate Flow extension requests coming from Shopify.
+
+| Property                  | Description                                                         |
+| ------------------------- | ------------------------------------------------------------------- |
+| [validate](./validate.md) | Verify whether a request is a valid Shopify Flow extension request. |
+
+[Back to shopifyApi](../shopifyApi.md)

packages/shopify-api/docs/reference/flow/validate.md

@@ -0,0 +1,66 @@
+# shopify.flow.validate
+
+Takes in a raw request and the raw body for that request, and validates that it's a legitimate Shopify Flow extension request.
+
+Refer to [the Flow documentation](https://shopify.dev/docs/apps/flow/actions/endpoints#custom-validation) for more information on how this validation works.
+
+## Example
+
+```ts
+app.post('/flow', express.text({type: '*/*'}), async (req, res) => {
+  const result = await shopify.flow.validate({
+    rawBody: req.body, // is a string
+    rawRequest: req,
+    rawResponse: res,
+  });
+
+  if (!result.valid) {
+    console.log(`Received invalid Flow extension request: ${result.reason}`);
+    res.send(400);
+  }
+
+  res.send(200);
+});
+```
+
+## Parameters
+
+Receives an object containing:
+
+### rawBody
+
+`string` | :exclamation: required
+
+The raw body of the request received by the app.
+
+### rawRequest
+
+`AdapterRequest` | :exclamation: required
+
+The HTTP Request object used by your runtime.
+
+### rawResponse
+
+`AdapterResponse` | :exclamation: required for Node.js
+
+The HTTP Response object used by your runtime. Required for Node.js.
+
+## Return
+
+Returns an object containing:
+
+### valid
+
+`boolean`
+
+Whether the request is a valid Flow extension request from Shopify.
+
+### If valid is `false`:
+
+#### reason
+
+`FlowValidationErrorReason`
+
+The reason why the check was considered invalid.
+
+[Back to shopify.flow](./README.md)

packages/shopify-api/docs/reference/shopifyApi.md

@@ -172,6 +172,7 @@ This function returns an object containing the following properties:
 | [session](./session/README.md)      | Object containing functions to manage Shopify sessions.                                                                                                 |
 | [webhooks](./webhooks/README.md)    | Object containing functions to configure and handle Shopify webhooks.                                                                                   |
 | [billing](./billing/README.md)      | Object containing functions to enable apps to bill merchants.                                                                                           |
+| [flow](./flow/README.md)            | Object containing functions to authenticate Flow extension requests.                                                                                    |
 | [utils](./utils/README.md)          | Object containing general functions to help build apps.                                                                                                 |
 | [rest](../guides/rest-resources.md) | Object containing OO representations of the Admin REST API. See the [API reference documentation](https://shopify.dev/docs/api/admin-rest) for details. |
 

packages/shopify-api/future/flags.ts

@@ -1,8 +1,20 @@
+/**
+ * Future flags are used to enable features that are not yet available by default.
+ */
 export interface FutureFlags {
+  /**
+   * Enable the token exchange OAuth flow.
+   */
   unstable_tokenExchange?: boolean;
+  /**
+   * Enable line item billing, to make billing configuration more similar to the GraphQL API.
+   */
   unstable_lineItemBilling?: boolean;
 }
 
+/**
+ * Configuration option for future flags.
+ */
 export type FutureFlagOptions = FutureFlags | undefined;
 
 export type FeatureEnabled<

packages/shopify-api/lib/auth/oauth/types.ts

@@ -23,16 +23,49 @@ export interface AccessTokenResponse {
 }
 
 export interface OnlineAccessInfo {
+  /**
+   * How long the access token is valid for, in seconds.
+   */
   expires_in: number;
+  /**
+   * The effective set of scopes for the session.
+   */
   associated_user_scope: string;
+  /**
+   * The user associated with the access token.
+   */
   associated_user: {
+    /**
+     * The user's ID.
+     */
     id: number;
+    /**
+     * The user's first name.
+     */
     first_name: string;
+    /**
+     * The user's last name.
+     */
     last_name: string;
+    /**
+     * The user's email address.
+     */
     email: string;
+    /**
+     * Whether the user has verified their email address.
+     */
     email_verified: boolean;
+    /**
+     * Whether the user is the account owner.
+     */
     account_owner: boolean;
+    /**
+     * The user's locale.
+     */
     locale: string;
+    /**
+     * Whether the user is a collaborator.
+     */
     collaborator: boolean;
   };
 }

packages/shopify-api/lib/auth/scopes/index.ts

@@ -1,3 +1,6 @@
+/**
+ * A class that represents a set of access token scopes.
+ */
 class AuthScopes {
   public static SCOPE_DELIMITER = ',';
 
@@ -31,6 +34,9 @@ class AuthScopes {
     this.expandedScopes = new Set([...scopeSet, ...impliedSet]);
   }
 
+  /**
+   * Checks whether the current set of scopes includes the given one.
+   */
   public has(scope: string | string[] | AuthScopes | undefined) {
     let other: AuthScopes;
 
@@ -45,6 +51,9 @@ class AuthScopes {
     );
   }
 
+  /**
+   * Checks whether the current set of scopes equals the given one.
+   */
   public equals(otherScopes: string | string[] | AuthScopes | undefined) {
     let other: AuthScopes;
 
@@ -60,10 +69,16 @@ class AuthScopes {
     );
   }
 
+  /**
+   * Returns a comma-separated string with the current set of scopes.
+   */
   public toString() {
     return this.toArray().join(AuthScopes.SCOPE_DELIMITER);
   }
 
+  /**
+   * Returns an array with the current set of scopes.
+   */
   public toArray() {
     return [...this.compressedScopes];
   }

packages/shopify-api/lib/base-types.ts

@@ -5,32 +5,107 @@ import {AuthScopes} from './auth/scopes';
 import {BillingConfig} from './billing/types';
 import {ApiVersion, LogSeverity} from './types';
 
+/**
+ * A function used by the library to log events related to Shopify.
+ */
 export type LogFunction = (severity: LogSeverity, msg: string) => void;
 
 export interface ConfigParams<
   Resources extends ShopifyRestResources = ShopifyRestResources,
   Future extends FutureFlagOptions = FutureFlagOptions,
 > {
+  /**
+   * The API key for your app.
+   *
+   * Also known as Client ID in your Partner Dashboard.
+   */
   apiKey?: string;
+  /**
+   * The API secret key for your app.
+   *
+   * Also known as Client Secret in your Partner Dashboard.
+   */
   apiSecretKey: string;
+  /**
+   * The scopes your app needs to access the API.
+   */
   scopes?: string[] | AuthScopes;
+  /**
+   * The host name of your app.
+   */
   hostName: string;
+  /**
+   * The scheme to use for the app host.
+   */
   hostScheme?: 'http' | 'https';
+  /**
+   * The API version to use.
+   */
   apiVersion: ApiVersion;
+  /**
+   * Whether the app is embedded in the Shopify admin.
+   */
   isEmbeddedApp: boolean;
+  /**
+   * Whether the app is a Shopify admin custom store app.
+   *
+   * @link https://shopify.dev/docs/apps/distribution
+   */
   isCustomStoreApp?: boolean;
+  /**
+   * An app-wide API access token.
+   *
+   * Only applies to custom apps.
+   */
   adminApiAccessToken?: string;
+  /**
+   * The user agent prefix to use for API requests.
+   */
   userAgentPrefix?: string;
+  /**
+   * An app-wide API access token for the storefront API.
+   *
+   * Only applies to custom apps.
+   */
   privateAppStorefrontAccessToken?: string;
+  /**
+   * Override values for Shopify shop domains.
+   */
   customShopDomains?: (RegExp | string)[];
+  /**
+   * Billing configurations for the app.
+   */
   billing?: BillingConfig<Future>;
+  /**
+   * REST resources to access the Admin API.
+   *
+   * You can import these from `@shopify/shopify-api/rest/admin/*`.
+   */
   restResources?: Resources;
+  /**
+   * Customization options for Shopify logs.
+   */
   logger?: {
+    /**
+     * A custom log function.
+     */
     log?: LogFunction;
+    /**
+     * The minimum severity level to log.
+     */
     level?: LogSeverity;
+    /**
+     * Whether to log HTTP requests.
+     */
     httpRequests?: boolean;
+    /**
+     * Whether to log timestamps.
+     */
     timestamps?: boolean;
   };
+  /**
+   * Future flags to include for this app.
+   */
   future?: Future;
 }