@shopify/shopify-app-remix 4.1.1 → 4.2.0

package/src/server/authenticate/webhooks/register.ts

@@ -0,0 +1,48 @@
+import type {BasicParams} from '../../types';
+
+import type {RegisterWebhooksOptions} from './types';
+
+export function registerWebhooksFactory({api, logger}: BasicParams) {
+  return async function registerWebhooks({session}: RegisterWebhooksOptions) {
+    return api.webhooks
+      .register({session})
+      .then((response) => {
+        Object.entries(response).forEach(([topic, topicResults]) => {
+          topicResults.forEach(({success, ...rest}) => {
+            if (success) {
+              logger.debug('Registered webhook', {
+                topic,
+                shop: session.shop,
+                operation: rest.operation,
+              });
+            } else {
+              logger.error('Failed to register webhook', {
+                topic,
+                shop: session.shop,
+                result: JSON.stringify(rest.result),
+              });
+            }
+          });
+        });
+
+        return response;
+      })
+      .catch((error) => {
+        const graphQLErrors: {extensions: {code?: string}}[] =
+          error.body?.errors?.graphQLErrors || [];
+
+        const throttled = graphQLErrors.find(
+          ({extensions: {code}}) => code === 'THROTTLED',
+        );
+
+        if (throttled) {
+          logger.error('Failed to register webhooks', {
+            shop: session.shop,
+            error: JSON.stringify(error),
+          });
+        } else {
+          throw error;
+        }
+      });
+  };
+}

package/src/server/authenticate/webhooks/types.ts

@@ -0,0 +1,266 @@
+import {Session, WebhookTypeValue} from '@shopify/shopify-api';
+
+import type {AdminApiContext} from '../../clients';
+
+export interface RegisterWebhooksOptions {
+  /**
+   * The Shopify session used to register webhooks using the Admin API.
+   */
+  session: Session;
+}
+
+interface Context<Topics = string | number | symbol> {
+  /**
+   * The API version used for the webhook.
+   *
+   * @example
+   * <caption>Webhook API version.</caption>
+   * <description>Get the API version used for webhook request.</description>
+   * ```ts
+   * // /app/routes/webhooks.tsx
+   * import { ActionFunctionArgs } from "@remix-run/node";
+   * import { authenticate } from "../shopify.server";
+   *
+   * export const action = async ({ request }: ActionFunctionArgs) => {
+   *   const { apiVersion } = await authenticate.webhook(request);
+   *   return new Response();
+   * };
+   * ```
+   */
+  apiVersion: string;
+
+  /**
+   * The shop where the webhook was triggered.
+   *
+   * @example
+   * <caption>Webhook shop.</caption>
+   * <description>Get the shop that triggered a webhook.</description>
+   * ```ts
+   * // /app/routes/webhooks.tsx
+   * import { ActionFunctionArgs } from "@remix-run/node";
+   * import { authenticate } from "../shopify.server";
+   *
+   * export const action = async ({ request }: ActionFunctionArgs) => {
+   *   const { shop } = await authenticate.webhook(request);
+   *   return new Response();
+   * };
+   * ```
+   */
+  shop: string;
+
+  /**
+   * The topic of the webhook.
+   *
+   * @example
+   * <caption>Webhook topic.</caption>
+   * <description>Get the event topic for the webhook.</description>
+   * ```ts
+   * // /app/routes/webhooks.tsx
+   * import { ActionFunctionArgs } from "@remix-run/node";
+   * import { authenticate } from "../shopify.server";
+   *
+   * export const action = async ({ request }: ActionFunctionArgs) => {
+   *   const { topic } = await authenticate.webhook(request);
+   *
+   *   switch (topic) {
+   *     case "APP_UNINSTALLED":
+   *       // Do something when the app is uninstalled.
+   *       break;
+   *   }
+   *
+   *   return new Response();
+   * };
+   * ```
+   */
+  topic: Topics;
+
+  /**
+   * A unique ID for the webhook. Useful to keep track of which events your app has already processed.
+   *
+   * For events webhooks (`webhookType === 'events'`), this is set to the `eventId` value for
+   * backwards compatibility. Prefer using `eventId` directly for events webhooks — `webhookId`
+   * will be removed from events webhooks in the next major version.
+   *
+   * @example
+   * <caption>Webhook ID.</caption>
+   * <description>Get the webhook ID.</description>
+   * ```ts
+   * // /app/routes/webhooks.tsx
+   * import { ActionFunctionArgs } from "@remix-run/node";
+   * import { authenticate } from "../shopify.server";
+   *
+   * export const action = async ({ request }: ActionFunctionArgs) => {
+   *   const { webhookId } = await authenticate.webhook(request);
+   *   return new Response();
+   * };
+   * ```
+   */
+  webhookId: string;
+
+  /**
+   * The payload from the webhook request.
+   *
+   * @example
+   * <caption>Webhook payload.</caption>
+   * <description>Get the request's POST payload.</description>
+   * ```ts
+   * // /app/routes/webhooks.tsx
+   * import { ActionFunctionArgs } from "@remix-run/node";
+   * import { authenticate } from "../shopify.server";
+   *
+   * export const action = async ({ request }: ActionFunctionArgs) => {
+   *   const { payload } = await authenticate.webhook(request);
+   *   return new Response();
+   * };
+   * ```
+   */
+  payload: Record<string, any>;
+
+  /**
+   * The type of webhook: 'webhooks' for traditional webhooks or 'events' for events webhooks.
+   */
+  webhookType: WebhookTypeValue;
+
+  /**
+   * The sub-topic of the webhook. Only available for traditional webhooks.
+   *
+   * @example
+   * <caption>Webhook sub-topic.</caption>
+   * <description>Get the webhook sub-topic.</description>
+   * ```ts
+   * // /app/routes/webhooks.tsx
+   * import { ActionFunctionArgs } from "@remix-run/node";
+   * import { authenticate } from "../shopify.server";
+   *
+   * export const action = async ({ request }: ActionFunctionArgs) => {
+   *   const { subTopic } = await authenticate.webhook(request);
+   *   return new Response();
+   * };
+   * ```
+   *
+   */
+  subTopic?: string;
+
+  /**
+   * The name assigned to the webhook subscription. Only available for traditional webhooks.
+   */
+  name?: string;
+
+  /**
+   * The handle for the webhook subscription. Only available for events webhooks.
+   */
+  handle?: string;
+
+  /**
+   * The action type: 'create', 'update', or 'delete'. Only available for events webhooks.
+   */
+  action?: string;
+
+  /**
+   * The GID of the resource that triggered the webhook. Only available for events webhooks.
+   */
+  resourceId?: string;
+
+  /**
+   * The timestamp when the webhook was triggered.
+   */
+  triggeredAt?: string;
+
+  /**
+   * The unique event identifier.
+   */
+  eventId?: string;
+}
+
+export interface WebhookContextWithoutSession<
+  Topics = string | number | symbol,
+> extends Context<Topics> {
+  session: undefined;
+  admin: undefined;
+}
+
+export interface WebhookContextWithSession<
+  Topics = string | number | symbol,
+> extends Context<Topics> {
+  /**
+   * A session with an offline token for the shop.
+   *
+   * Returned only if there is a session for the shop.
+   * Webhook requests can trigger after an app is uninstalled
+   * If the app is already uninstalled, the session may be undefined.
+   * Therefore, you should check for the session before using it.
+   *
+   * @example
+   * <caption>Protecting against uninstalled apps.</caption>
+   * ```ts
+   * // /app/routes/webhooks.tsx
+   * import type { ActionFunctionArgs } from "@remix-run/node";
+   * import { authenticate } from "~/shopify.server";
+
+   * export const action = async ({ request }: ActionFunctionArgs) => {
+   *   const { session } = await authenticate.webhook(request);
+   *   
+   *   // Webhook requests can trigger after an app is uninstalled
+   *   // If the app is already uninstalled, the session may be undefined.
+   *   if (!session) {
+   *     throw new Response();
+   *   }
+   *
+   *   // Handle webhook request
+   *   console.log("Received webhook webhook");
+   *
+   *   return new Response();
+   * };
+   * ```
+   */
+  session: Session;
+
+  /**
+   * An admin context for the webhook.
+   *
+   * Returned only if there is a session for the shop.
+   *
+   * @example
+   * <caption>Webhook admin context.</caption>
+   * <description>Use the `admin` object in the context to interact with the Admin API.</description>
+   * ```ts
+   * // /app/routes/webhooks.tsx
+   * import { ActionFunctionArgs } from "@remix-run/node";
+   * import { authenticate } from "../shopify.server";
+   *
+   * export async function action({ request }: ActionFunctionArgs) {
+   *   const { admin } = await authenticate.webhook(request);
+   *
+   *   // Webhook requests can trigger after an app is uninstalled
+   *   // If the app is already uninstalled, the session may be undefined.
+   *   if (!session) {
+   *     throw new Response();
+   *   }
+   *
+   *   const response = await admin?.graphql(
+   *     `#graphql
+   *     mutation populateProduct($input: ProductInput!) {
+   *       productCreate(input: $input) {
+   *         product {
+   *           id
+   *         }
+   *       }
+   *     }`,
+   *     { variables: { input: { title: "Product Name" } } }
+   *   );
+   *
+   *   const productData = await response.json();
+   *   return json({ data: productData.data });
+   * }
+   * ```
+   */
+  admin: AdminApiContext;
+}
+
+export type WebhookContext<Topics = string | number | symbol> =
+  | WebhookContextWithoutSession<Topics>
+  | WebhookContextWithSession<Topics>;
+
+export type AuthenticateWebhook<Topics = string | number | symbol> = (
+  request: Request,
+) => Promise<WebhookContext<Topics>>;

package/src/server/boundary/error.tsx

@@ -0,0 +1,14 @@
+export function errorBoundary(error: any) {
+  if (
+    error.constructor.name === 'ErrorResponse' ||
+    error.constructor.name === 'ErrorResponseImpl'
+  ) {
+    return (
+      <div
+        dangerouslySetInnerHTML={{__html: error.data || 'Handling response'}}
+      />
+    );
+  }
+
+  throw error;
+}

package/src/server/boundary/headers.ts

@@ -0,0 +1,15 @@
+import {HeadersArgs} from '@remix-run/server-runtime';
+
+export function headersBoundary(headers: HeadersArgs): Headers {
+  const {parentHeaders, loaderHeaders, actionHeaders, errorHeaders} = headers;
+
+  if (errorHeaders && Array.from(errorHeaders.entries()).length > 0) {
+    return errorHeaders;
+  }
+
+  return new Headers([
+    ...(parentHeaders ? Array.from(parentHeaders.entries()) : []),
+    ...(loaderHeaders ? Array.from(loaderHeaders.entries()) : []),
+    ...(actionHeaders ? Array.from(actionHeaders.entries()) : []),
+  ]);
+}

package/src/server/boundary/index.ts

@@ -0,0 +1,39 @@
+import {headersBoundary} from './headers';
+import {errorBoundary} from './error';
+
+/**
+ * A collection of functions that handle the necessary code for error boundaries in routes using authenticate.admin.
+ */
+export const boundary = {
+  /**
+   * A function that handles errors or thrown responses.
+   *
+   * @example
+   * <caption>Catching errors in a route</caption>
+   * ```ts
+   * // /app/routes/admin/widgets.ts
+   * import { boundary } from "@shopify/shopify-app-remix/server";
+   *
+   * export function ErrorBoundary() {
+   *   return boundary.error(useRouteError());
+   * }
+   * ```
+   */
+  error: errorBoundary,
+
+  /**
+   * A function that sets the appropriate document response headers.
+   *
+   * @example
+   * <caption>Catching errors in a route</caption>
+   * ```ts
+   * // /app/routes/admin/widgets.ts
+   * import { boundary } from "@shopify/shopify-app-remix/server";
+   *
+   * export const headers = (headersArgs) => {
+   *   return boundary.headers(headersArgs);
+   * };
+   * ```
+   */
+  headers: headersBoundary,
+};

package/src/server/boundary/types.ts

@@ -0,0 +1,4 @@
+import {HeadersArgs} from '@remix-run/server-runtime';
+
+export type ErrorBoundary = (error: unknown) => string | never;
+export type HeadersBoundary = (headers: HeadersArgs) => Headers;

package/src/server/clients/admin/authenticate.admin.api.doc.ts

@@ -0,0 +1,34 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Admin API',
+  description:
+    'Contains objects used to interact with the Admin API.' +
+    '\n\nThis object is returned as part of different contexts, such as [`admin`](/docs/api/shopify-app-remix/authenticate/admin), [`unauthenticated.admin`](/docs/api/shopify-app-remix/unauthenticated/unauthenticated-admin), and [`webhook`](/docs/api/shopify-app-remix/authenticate/webhook).',
+  category: 'APIs',
+  type: 'object',
+  isVisualComponent: false,
+  definitions: [
+    {
+      title: 'admin',
+      description:
+        'Provides utilities that apps can use to make requests to the Admin API.',
+      type: 'AdminApiContext',
+    },
+  ],
+  jsDocTypeExamples: ['AdminApiContext'],
+  related: [
+    {
+      name: 'Authenticated context',
+      subtitle: 'Authenticate requests from Shopify Admin.',
+      url: '/docs/api/shopify-app-remix/authenticate/admin',
+    },
+    {
+      name: 'Unauthenticated context',
+      subtitle: 'Interact with the Admin API on non-Shopify requests.',
+      url: '/docs/api/shopify-app-remix/unauthenticated/unauthenticated-admin',
+    },
+  ],
+};
+
+export default data;

package/src/server/clients/admin/factory.ts

@@ -0,0 +1,22 @@
+import {Session} from '@shopify/shopify-api';
+
+import {BasicParams} from '../../types';
+
+import {graphqlClientFactory} from './graphql';
+import type {AdminApiContext} from './types';
+
+interface AdminClientOptions {
+  params: BasicParams;
+  session: Session;
+  handleClientError?: (error: any) => Promise<void>;
+}
+
+export function adminClientFactory({
+  params,
+  handleClientError,
+  session,
+}: AdminClientOptions): AdminApiContext {
+  return {
+    graphql: graphqlClientFactory({params, session, handleClientError}),
+  };
+}

package/src/server/clients/admin/graphql.ts

@@ -0,0 +1,39 @@
+import {AdminOperations} from '@shopify/admin-api-client';
+
+import {GraphQLClient} from '../types';
+
+import {AdminClientOptions} from './types';
+
+// eslint-disable-next-line no-warning-comments
+// TODO: This is actually just a call through to the Shopify API client, but with a different API. We should eventually
+// move this over to the library layer.
+export function graphqlClientFactory({
+  params,
+  handleClientError,
+  session,
+}: AdminClientOptions): GraphQLClient<AdminOperations> {
+  return async function query(operation, options) {
+    const client = new params.api.clients.Graphql({
+      session,
+      apiVersion: options?.apiVersion,
+    });
+
+    try {
+      // We convert the incoming response to a Response object to bring this client closer to the Remix client.
+      const apiResponse = await client.request(operation, {
+        variables: options?.variables,
+        retries: options?.tries ? options.tries - 1 : 0,
+        headers: options?.headers,
+        signal: options?.signal,
+      });
+
+      return new Response(JSON.stringify(apiResponse));
+    } catch (error) {
+      if (handleClientError) {
+        throw await handleClientError({error, params, session});
+      }
+
+      throw error;
+    }
+  };
+}

package/src/server/clients/admin/index.ts

@@ -0,0 +1,2 @@
+export * from './factory';
+export * from './types';

package/src/server/clients/admin/types.ts

@@ -0,0 +1,120 @@
+import {AdminOperations} from '@shopify/admin-api-client';
+import {Session} from '@shopify/shopify-api';
+
+import {BasicParams} from '../../types';
+import {GraphQLClient} from '../types';
+
+export interface AdminClientOptions {
+  params: BasicParams;
+  session: Session;
+  handleClientError?: HandleAdminClientError;
+}
+
+export type HandleAdminClientError = (arg: {
+  error: any;
+  params: BasicParams;
+  session: Session;
+}) => Promise<void>;
+
+export interface AdminApiContext {
+  /**
+   * Methods for interacting with the Shopify Admin GraphQL API
+   *
+   * {@link https://shopify.dev/docs/api/admin-graphql}
+   * {@link https://github.com/Shopify/shopify-app-js/blob/main/packages/apps/shopify-api/docs/reference/clients/Graphql.md}
+   *
+   * @example
+   * <caption>Querying the GraphQL API.</caption>
+   * <description>Use `admin.graphql` to make query / mutation requests.</description>
+   * ```ts
+   * // /app/routes/**\/*.ts
+   * import { ActionFunctionArgs } from "@remix-run/node";
+   * import { authenticate } from "../shopify.server";
+   *
+   * export const action = async ({ request }: ActionFunctionArgs) => {
+   *   const { admin } = await authenticate.admin(request);
+   *
+   *   const response = await admin.graphql(
+   *     `#graphql
+   *     mutation populateProduct($input: ProductInput!) {
+   *       productCreate(input: $input) {
+   *         product {
+   *           id
+   *         }
+   *       }
+   *     }`,
+   *     {
+   *       variables: {
+   *         input: { title: "Product Name" },
+   *       },
+   *     },
+   *   );
+   *
+   *   const productData = await response.json();
+   *   return json({
+   *     productId: productData.data?.productCreate?.product?.id,
+   *   });
+   * }
+   * ```
+   *
+   * ```ts
+   * // /app/shopify.server.ts
+   * import { shopifyApp } from "@shopify/shopify-app-remix/server";
+   *
+   * const shopify = shopifyApp({
+   *   // ...
+   * });
+   * export default shopify;
+   * export const authenticate = shopify.authenticate;
+   * ```
+   *
+   * @example
+   * <caption>Handling GraphQL errors.</caption>
+   * <description>Catch `GraphqlQueryError` errors to see error messages from the API.</description>
+   * ```ts
+   * // /app/routes/**\/*.ts
+   * import { ActionFunctionArgs } from "@remix-run/node";
+   * import { authenticate } from "../shopify.server";
+   *
+   * export const action = async ({ request }: ActionFunctionArgs) => {
+   *   const { admin } = await authenticate.admin(request);
+   *
+   *   try {
+   *     const response = await admin.graphql(
+   *       `#graphql
+   *       query incorrectQuery {
+   *         products(first: 10) {
+   *           nodes {
+   *             not_a_field
+   *           }
+   *         }
+   *       }`,
+   *     );
+   *
+   *     return json({ data: await response.json() });
+   *   } catch (error) {
+   *     if (error instanceof GraphqlQueryError) {
+   *       // error.body.errors:
+   *       // { graphQLErrors: [
+   *       //   { message: "Field 'not_a_field' doesn't exist on type 'Product'" }
+   *       // ] }
+   *       return json({ errors: error.body?.errors }, { status: 500 });
+   *     }
+   *     return json({ message: "An error occurred" }, { status: 500 });
+   *   }
+   * }
+   * ```
+   *
+   * ```ts
+   * // /app/shopify.server.ts
+   * import { shopifyApp } from "@shopify/shopify-app-remix/server";
+   *
+   * const shopify = shopifyApp({
+   *   // ...
+   * });
+   * export default shopify;
+   * export const authenticate = shopify.authenticate;
+   * ```
+   */
+  graphql: GraphQLClient<AdminOperations>;
+}

package/src/server/clients/index.ts

@@ -0,0 +1,2 @@
+export * from './admin';
+export * from './storefront';

package/src/server/clients/storefront/authenticate.storefront.api.doc.ts

@@ -0,0 +1,34 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Storefront API',
+  description:
+    'Contains objects used to interact with the Storefront API.' +
+    '\n\nThis object is returned as part of different contexts, such as [`appProxy`](/docs/api/shopify-app-remix/authenticate/public/app-proxy), and [`unauthenticated.storefront`](/docs/api/shopify-app-remix/unauthenticated/unauthenticated-storefront).',
+  category: 'APIs',
+  type: 'object',
+  isVisualComponent: false,
+  definitions: [
+    {
+      title: 'storefront',
+      description:
+        'Provides utilities that apps can use to make requests to the Storefront API.',
+      type: 'StorefrontContext',
+    },
+  ],
+  jsDocTypeExamples: ['StorefrontContext'],
+  related: [
+    {
+      name: 'App proxy context',
+      subtitle: 'Authenticate requests from Shopify app proxies.',
+      url: '/docs/api/shopify-app-remix/authenticate/public/app-proxy',
+    },
+    {
+      name: 'Unauthenticated context',
+      subtitle: 'Interact with the Storefront API on non-Shopify requests.',
+      url: '/docs/api/shopify-app-remix/unauthenticated/unauthenticated-storefront',
+    },
+  ],
+};
+
+export default data;

package/src/server/clients/storefront/factory.ts

@@ -0,0 +1,32 @@
+import {Session} from '@shopify/shopify-api';
+
+import {BasicParams} from '../../types';
+
+import type {StorefrontContext} from '.';
+
+export function storefrontClientFactory({
+  params,
+  session,
+}: {
+  params: BasicParams;
+  session: Session;
+}): StorefrontContext {
+  const {api} = params;
+
+  return {
+    graphql: async (query, options = {}) => {
+      const client = new api.clients.Storefront({
+        session,
+        apiVersion: options.apiVersion,
+      });
+
+      const apiResponse = await client.request(query, {
+        variables: options?.variables,
+        retries: options?.tries ? options.tries - 1 : 0,
+        headers: options?.headers,
+      });
+
+      return new Response(JSON.stringify(apiResponse));
+    },
+  };
+}

package/src/server/clients/storefront/index.ts

@@ -0,0 +1,2 @@
+export * from './factory';
+export * from './types';