@shopify/shopify-app-remix 4.1.1 → 4.2.0

package/src/server/authenticate/public/customer-account/authenticate.public.customerAccount.doc.example.offers.ts

@@ -0,0 +1,36 @@
+// Most apps would load this from their database
+export function getOffers(shop: string, customerID: string) {
+  const offers: Record<string, any[]> = {
+    'shop.com': [
+      {
+        id: '1',
+        title: '10% off',
+        price: 10,
+        type: 'percentage',
+        customerId: 'gid://shopify/Customer/1001',
+      },
+      {
+        id: '2',
+        title: 'Free shipping',
+        price: 0,
+        type: 'shipping',
+        customerId: 'gid://shopify/Customer/1001',
+      },
+      {
+        id: '3',
+        title: '5% off',
+        price: 5,
+        type: 'percentage',
+        customerId: 'gid://shopify/Customer/1001',
+      },
+    ],
+  };
+
+  const allOffers = offers[shop] || [];
+  // Filter offers to include only those that match the customerId
+  const filteredOffers = allOffers.filter(
+    (offer) => offer.customerId === customerID,
+  );
+
+  return filteredOffers;
+}

package/src/server/authenticate/public/customer-account/authenticate.public.customerAccount.doc.example.ts

@@ -0,0 +1,18 @@
+import type {ActionFunctionArgs, LoaderFunctionArgs} from '@remix-run/node';
+import {json} from '@remix-run/node';
+
+import {authenticate} from '../shopify.server';
+import {getOffers} from '../offers.server';
+
+// The loader responds to preflight requests from Shopify
+export const loader = async ({request}: LoaderFunctionArgs) => {
+  await authenticate.public.customerAccount(request);
+};
+
+export const action = async ({request}: ActionFunctionArgs) => {
+  const {cors, sessionToken} = await authenticate.public.customerAccount(request);
+
+  // Get offers for the customer
+  const offers = getOffers(sessionToken.des, sessionToken.sub);
+  return cors(json({offers}));
+};

package/src/server/authenticate/public/customer-account/authenticate.public.customerAccount.doc.ts

@@ -0,0 +1,49 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Customer account',
+  description:
+    'The `authenticate.public.customerAccount` function ensures that customer account extension requests are coming from Shopify, and returns helpers to respond with the correct headers.',
+  category: 'Authenticate',
+  subCategory: 'Public',
+  type: 'object',
+  isVisualComponent: false,
+  definitions: [
+    {
+      title: 'authenticate.public.customerAccount',
+      description:
+        'Authenticates requests coming from Shopify customer account extensions.',
+      type: 'AuthenticateCustomerAccount',
+    },
+  ],
+  defaultExample: {
+    description: 'Authenticate and return offers for the customer',
+    codeblock: {
+      title: 'Authenticate and return offers for the customer',
+      tabs: [
+        {
+          title: '/app/routes/**.ts',
+          language: 'typescript',
+          code: './authenticate.public.customerAccount.doc.example.ts',
+        },
+        {
+          title: '/app/offers.server.ts',
+          language: 'typescript',
+          code: './authenticate.public.customerAccount.doc.example.offers.ts',
+        },
+      ],
+    },
+  },
+  jsDocTypeExamples: ['CustomerAccountContext'],
+  related: [
+    {
+      name: 'Session token API',
+      subtitle:
+        'Customer account UI extensions API for interacting with session tokens.',
+      url: '/docs/api/customer-account-ui-extensions/latest/apis/session-token',
+      type: 'shopify',
+    },
+  ],
+};
+
+export default data;

package/src/server/authenticate/public/customer-account/authenticate.ts

@@ -0,0 +1,13 @@
+import {BasicParams} from '../../../types';
+import {authenticateExtensionFactory} from '../extension/authenticate';
+
+import {AuthenticateCustomerAccount} from './types';
+
+export function authenticateCustomerAccountFactory(
+  params: BasicParams,
+): AuthenticateCustomerAccount {
+  return authenticateExtensionFactory(
+    params,
+    'customer account',
+  ) as AuthenticateCustomerAccount;
+}

package/src/server/authenticate/public/customer-account/types.ts

@@ -0,0 +1,65 @@
+import {JwtPayload} from '@shopify/shopify-api';
+
+import {EnsureCORSFunction} from '../../helpers/ensure-cors-headers';
+
+export type AuthenticateCustomerAccount = (
+  request: Request,
+  options?: AuthenticateCustomerAccountOptions,
+) => Promise<CustomerAccountContext>;
+
+export interface AuthenticateCustomerAccountOptions {
+  corsHeaders?: string[];
+}
+
+/**
+ * Authenticated Context for a customer account extension request
+ */
+export interface CustomerAccountContext {
+  /**
+   * The decoded and validated session token for the request
+   *
+   * Refer to the OAuth docs for the [session token payload](https://shopify.dev/docs/apps/auth/oauth/session-tokens#payload).
+   *
+   * @example
+   * <caption>Using the decoded session token.</caption>
+   * <description>Get store-specific data using the `sessionToken` object.</description>
+   * ```ts
+   * // app/routes/public/my-route.ts
+   * import { LoaderFunctionArgs, json } from "@remix-run/node";
+   * import { authenticate } from "../shopify.server";
+   * import { getMyAppData } from "~/db/model.server";
+   *
+   * export const loader = async ({ request }: LoaderFunctionArgs) => {
+   *   const { sessionToken } = await authenticate.public.customerAccount(
+   *     request
+   *   );
+   *   return json(await getMyAppData({shop: sessionToken.dest}));
+   * };
+   * ```
+   */
+  sessionToken: JwtPayload;
+
+  /**
+   * A function that ensures the CORS headers are set correctly for the response.
+   *
+   * @example
+   * <caption>Setting CORS headers for a public request.</caption>
+   * <description>Use the `cors` helper to ensure your app can respond to customer account extension requests.</description>
+   * ```ts
+   * // app/routes/public/my-route.ts
+   * import { LoaderFunctionArgs, json } from "@remix-run/node";
+   * import { authenticate } from "../shopify.server";
+   * import { getMyAppData } from "~/db/model.server";
+   *
+   * export const loader = async ({ request }: LoaderFunctionArgs) => {
+   *   const { sessionToken, cors } = await authenticate.public.customerAccount(
+   *     request,
+   *     { corsHeaders: ["X-My-Custom-Header"] }
+   *   );
+   *   const data = await getMyAppData({shop: sessionToken.dest});
+   *   return cors(json(data));
+   * };
+   * ```
+   */
+  cors: EnsureCORSFunction;
+}

package/src/server/authenticate/public/extension/authenticate.ts

@@ -0,0 +1,54 @@
+import {BasicParams} from '../../../types';
+import {
+  respondToBotRequest,
+  respondToOptionsRequest,
+  getSessionTokenHeader,
+  validateSessionToken,
+  ensureCORSHeadersFactory,
+  getShopFromRequest,
+} from '../../helpers';
+
+import {AuthenticateExtension, ExtensionContext} from './types';
+
+export function authenticateExtensionFactory(
+  params: BasicParams,
+  requestType: string,
+): AuthenticateExtension {
+  return async function authenticateExtension(
+    request,
+    options = {},
+  ): Promise<ExtensionContext> {
+    const {logger} = params;
+
+    const corsHeaders = options.corsHeaders ?? [];
+
+    respondToBotRequest(params, request);
+    respondToOptionsRequest(params, request, corsHeaders);
+
+    const sessionTokenHeader = getSessionTokenHeader(request);
+
+    logger.info(`Authenticating ${requestType} request`, {
+      shop: getShopFromRequest(request),
+    });
+
+    if (!sessionTokenHeader) {
+      logger.debug('Request did not contain a session token', {
+        shop: getShopFromRequest(request),
+      });
+      throw new Response(undefined, {
+        status: 401,
+        statusText: 'Unauthorized',
+      });
+    }
+
+    return {
+      sessionToken: await validateSessionToken(
+        params,
+        request,
+        sessionTokenHeader,
+        {checkAudience: false, retryRequest: false},
+      ),
+      cors: ensureCORSHeadersFactory(params, request, corsHeaders),
+    };
+  };
+}

package/src/server/authenticate/public/extension/types.ts

@@ -0,0 +1,11 @@
+export type AuthenticateExtension = (
+  request: Request,
+  options?: AuthenticateExtensionOptions,
+) => Promise<ExtensionContext>;
+
+export interface AuthenticateExtensionOptions {
+  corsHeaders?: string[];
+}
+
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface ExtensionContext {}

package/src/server/authenticate/public/factory.ts

@@ -0,0 +1,24 @@
+import {BasicParams} from '../../types';
+
+import {authenticateCheckoutFactory} from './checkout/authenticate';
+import {authenticateAppProxyFactory} from './appProxy/authenticate';
+import {authenticateCustomerAccountFactory} from './customer-account/authenticate';
+import {AuthenticatePublic} from './types';
+import {authenticatePOSFactory} from './pos/authenticate';
+
+export function authenticatePublicFactory(params: BasicParams) {
+  const authenticateCheckout = authenticateCheckoutFactory(params);
+  const authenticateAppProxy = authenticateAppProxyFactory(params);
+  const authenticateCustomerAccount =
+    authenticateCustomerAccountFactory(params);
+  const authenticatePOS = authenticatePOSFactory(params);
+
+  const context: AuthenticatePublic = {
+    checkout: authenticateCheckout,
+    appProxy: authenticateAppProxy,
+    customerAccount: authenticateCustomerAccount,
+    pos: authenticatePOS,
+  };
+
+  return context;
+}

package/src/server/authenticate/public/index.ts

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

package/src/server/authenticate/public/pos/authenticate.ts

@@ -0,0 +1,8 @@
+import {BasicParams} from '../../../types';
+import {authenticateExtensionFactory} from '../extension/authenticate';
+
+import type {AuthenticatePOS} from './types';
+
+export function authenticatePOSFactory(params: BasicParams): AuthenticatePOS {
+  return authenticateExtensionFactory(params, 'pos') as AuthenticatePOS;
+}

package/src/server/authenticate/public/pos/types.ts

@@ -0,0 +1,65 @@
+import {JwtPayload} from '@shopify/shopify-api';
+
+import {EnsureCORSFunction} from '../../helpers/ensure-cors-headers';
+
+export type AuthenticatePOS = (
+  request: Request,
+  options?: AuthenticatePOSOptions,
+) => Promise<POSContext>;
+
+export interface AuthenticatePOSOptions {
+  corsHeaders?: string[];
+}
+
+/**
+ * Authenticated Context for a POS UI extension request
+ */
+export interface POSContext {
+  /**
+   * The decoded and validated session token for the request
+   *
+   * Refer to the OAuth docs for the [session token payload](https://shopify.dev/docs/apps/auth/oauth/session-tokens#payload).
+   *
+   * @example
+   * <caption>Using the decoded session token.</caption>
+   * <description>Get store-specific data using the `sessionToken` object.</description>
+   * ```ts
+   * // app/routes/public/my-route.ts
+   * import { LoaderFunctionArgs, json } from "@remix-run/node";
+   * import { authenticate } from "../shopify.server";
+   * import { getMyAppData } from "~/db/model.server";
+   *
+   * export const loader = async ({ request }: LoaderFunctionArgs) => {
+   *   const { sessionToken } = await authenticate.public.pos(
+   *     request
+   *   );
+   *   return json(await getMyAppData({shop: sessionToken.dest}));
+   * };
+   * ```
+   */
+  sessionToken: JwtPayload;
+
+  /**
+   * A function that ensures the CORS headers are set correctly for the response.
+   *
+   * @example
+   * <caption>Setting CORS headers for a public request.</caption>
+   * <description>Use the `cors` helper to ensure your app can respond to POS UI extension requests.</description>
+   * ```ts
+   * // app/routes/public/my-route.ts
+   * import { LoaderFunctionArgs, json } from "@remix-run/node";
+   * import { authenticate } from "../shopify.server";
+   * import { getMyAppData } from "~/db/model.server";
+   *
+   * export const loader = async ({ request }: LoaderFunctionArgs) => {
+   *   const { sessionToken, cors } = await authenticate.public.pos(
+   *     request,
+   *     { corsHeaders: ["X-My-Custom-Header"] }
+   *   );
+   *   const data = await getMyAppData({shop: sessionToken.dest});
+   *   return cors(json(data));
+   * };
+   * ```
+   */
+  cors: EnsureCORSFunction;
+}

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

@@ -0,0 +1,96 @@
+import type {AuthenticateCheckout} from './checkout/types';
+import type {AuthenticateAppProxy} from './appProxy/types';
+import type {AuthenticateCustomerAccount} from './customer-account/types';
+import type {AuthenticatePOS} from './pos/types';
+
+// Eventually this will be just the `{}` bit without `AuthenticateCheckout &`
+// We have this is because in v1 public WAS the only public authenticate method
+// But it became tightly coupled to authenticating Checkout requests.
+// In V2 you will have only public.checkout() and public.appProxy(), no public()
+
+export interface AuthenticatePublic {
+  /**
+   * Authenticate a request from a checkout extension
+   *
+   * @example
+   * <caption>Authenticating a checkout extension request</caption>
+   * ```ts
+   * // /app/routes/public/widgets.ts
+   * import { LoaderFunctionArgs, json } from "@remix-run/node";
+   * import { authenticate } from "../shopify.server";
+   *
+   * export const loader = async ({ request }: LoaderFunctionArgs) => {
+   *   const { sessionToken, cors } = await authenticate.public.checkout(
+   *     request,
+   *   );
+   *   return cors(json({my: "data", shop: sessionToken.dest}));
+   * };
+   * ```
+   */
+  checkout: AuthenticateCheckout;
+
+  /**
+   * Authenticate a request from an app proxy
+   *
+   * @example
+   * <caption>Authenticating an app proxy request</caption>
+   * ```ts
+   * // /app/routes/public/widgets.ts
+   * import { LoaderFunctionArgs, json } from "@remix-run/node";
+   * import { authenticate } from "../shopify.server";
+   *
+   * export const loader = async ({ request }: LoaderFunctionArgs) => {
+   *   await authenticate.public.appProxy(
+   *     request,
+   *   );
+   *
+   *   const {searchParams} = new URL(request.url);
+   *   const shop = searchParams.get("shop");
+   *   const customerId = searchParams.get("logged_in_customer_id")
+   *
+   *   return json({my: "data", shop, customerId});
+   * };
+   * ```
+   */
+  appProxy: AuthenticateAppProxy;
+
+  /**
+   * Authenticate a request from a customer account extension
+   *
+   * @example
+   * <caption>Authenticating a customer account extension request</caption>
+   * ```ts
+   * // /app/routes/public/widgets.ts
+   * import { LoaderFunctionArgs, json } from "@remix-run/node";
+   * import { authenticate } from "../shopify.server";
+   *
+   * export const loader = async ({ request }: LoaderFunctionArgs) => {
+   *   const { sessionToken, cors } = await authenticate.public.customerAccount(
+   *     request,
+   *   );
+   *   return cors(json({my: "data", shop: sessionToken.dest}));
+   * };
+   * ```
+   */
+  customerAccount: AuthenticateCustomerAccount;
+
+  /**
+   * Authenticate a request from a POS UI extension
+   *
+   * @example
+   * <caption>Authenticating a POS UI extension request</caption>
+   * ```ts
+   * // /app/routes/public/widgets.ts
+   * import { LoaderFunctionArgs, json } from "@remix-run/node";
+   * import { authenticate } from "../shopify.server";
+   *
+   * export const loader = async ({ request }: LoaderFunctionArgs) => {
+   *   const { sessionToken, cors } = await authenticate.public.pos(
+   *     request,
+   *   );
+   *   return cors(json({my: "data", shop: sessionToken.dest}));
+   * };
+   * ```
+   */
+  pos: AuthenticatePOS;
+}

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

@@ -0,0 +1,105 @@
+import {WebhookValidationErrorReason, WebhookType} from '@shopify/shopify-api';
+
+import type {BasicParams} from '../../types';
+import {adminClientFactory} from '../../clients';
+import {handleClientErrorFactory} from '../admin/helpers';
+import {ensureValidOfflineSession} from '../../helpers';
+
+import type {
+  AuthenticateWebhook,
+  WebhookContext,
+  WebhookContextWithoutSession,
+} from './types';
+
+export function authenticateWebhookFactory<Topics extends string>(
+  params: BasicParams,
+): AuthenticateWebhook<Topics> {
+  const {api, logger} = params;
+
+  return async function authenticate(
+    request: Request,
+  ): Promise<WebhookContext<Topics>> {
+    if (request.method !== 'POST') {
+      logger.debug(
+        'Received a non-POST request for a webhook. Only POST requests are allowed.',
+        {url: request.url, method: request.method},
+      );
+      throw new Response(undefined, {
+        status: 405,
+        statusText: 'Method not allowed',
+      });
+    }
+
+    const rawBody = await request.text();
+
+    const check = await api.webhooks.validate({
+      rawBody,
+      rawRequest: request,
+    });
+
+    if (!check.valid) {
+      if (check.reason === WebhookValidationErrorReason.InvalidHmac) {
+        logger.debug('Webhook HMAC validation failed', check);
+        throw new Response(undefined, {
+          status: 401,
+          statusText: 'Unauthorized',
+        });
+      } else {
+        logger.debug('Webhook validation failed', check);
+        throw new Response(undefined, {status: 400, statusText: 'Bad Request'});
+      }
+    }
+    const session = await ensureValidOfflineSession(params, check.domain);
+
+    let webhookContext: WebhookContextWithoutSession<Topics>;
+
+    if (check.webhookType === WebhookType.Webhooks) {
+      webhookContext = {
+        apiVersion: check.apiVersion,
+        shop: check.domain,
+        topic: check.topic as Topics,
+        webhookId: check.webhookId,
+        payload: JSON.parse(rawBody),
+        subTopic: check.subTopic || undefined,
+        session: undefined,
+        admin: undefined,
+        webhookType: check.webhookType,
+        name: check.name,
+        triggeredAt: check.triggeredAt,
+        eventId: check.eventId,
+      };
+    } else {
+      webhookContext = {
+        apiVersion: check.apiVersion,
+        shop: check.domain,
+        topic: check.topic as Topics,
+        webhookId: check.eventId,
+        payload: JSON.parse(rawBody),
+        session: undefined,
+        admin: undefined,
+        webhookType: check.webhookType,
+        handle: check.handle,
+        action: check.action,
+        resourceId: check.resourceId,
+        triggeredAt: check.triggeredAt,
+        eventId: check.eventId,
+      };
+    }
+
+    if (!session) {
+      return webhookContext;
+    }
+
+    const admin = adminClientFactory({
+      params,
+      session,
+      handleClientError: handleClientErrorFactory({request}),
+    });
+
+    return {
+      ...webhookContext,
+      session,
+      admin,
+    };
+  };
+}

package/src/server/authenticate/webhooks/authenticate.webhooks.doc.example.ts

@@ -0,0 +1,43 @@
+import {type ActionFunctionArgs} from '@remix-run/node';
+
+import {authenticate} from '../shopify.server';
+
+export const action = async ({request}: ActionFunctionArgs) => {
+  const {topic, admin, payload, 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();
+  }
+
+  switch (topic) {
+    case 'PRODUCTS_UPDATE':
+      await admin.graphql(
+        `#graphql
+        mutation setMetafield($productId: ID!, $time: String!) {
+          metafieldsSet(metafields: {
+            ownerId: $productId
+            namespace: "my-app",
+            key: "webhook_received_at",
+            value: $time,
+            type: "string",
+          }) {
+            metafields {
+              key
+              value
+            }
+          }
+        }
+      `,
+      {
+        variables: {
+          productId: payload.admin_graphql_api_id,
+          time: new Date().toISOString(),
+        },
+      },
+    );
+  }
+
+  return new Response();
+};

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

@@ -0,0 +1,39 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Webhook',
+  description: 'Contains functions for verifying Shopify webhooks.',
+  category: 'Authenticate',
+  type: 'object',
+  isVisualComponent: false,
+  definitions: [
+    {
+      title: 'authenticate.webhook',
+      description: 'Verifies requests coming from Shopify webhooks.',
+      type: 'AuthenticateWebhook',
+    },
+  ],
+  defaultExample: {
+    description: 'Update a metafield when a product is updated',
+    codeblock: {
+      title: 'Update a metafield when a product is updated',
+      tabs: [
+        {
+          title: '/app/routes/**.ts',
+          language: 'typescript',
+          code: './authenticate.webhooks.doc.example.ts',
+        },
+      ],
+    },
+  },
+  jsDocTypeExamples: ['WebhookContextWithSession'],
+  related: [
+    {
+      name: 'Admin API context',
+      subtitle: 'Interact with the Admin API.',
+      url: '/docs/api/shopify-app-remix/apis/admin-api',
+    },
+  ],
+};
+
+export default data;

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

@@ -0,0 +1 @@
+export {registerWebhooksFactory} from './register';