@shopify/shopify-app-remix 4.1.0 → 4.2.0

package/src/server/authenticate/login/login.ts

@@ -0,0 +1,53 @@
+import {redirect} from '@remix-run/server-runtime';
+
+import {BasicParams, LoginError, LoginErrorType} from '../../types';
+
+export function loginFactory(params: BasicParams) {
+  const {api, config, logger} = params;
+
+  return async function login(request: Request): Promise<LoginError | never> {
+    const url = new URL(request.url);
+    const shopParam = url.searchParams.get('shop');
+
+    if (request.method === 'GET' && !shopParam) {
+      return {};
+    }
+
+    const shop: string | null =
+      shopParam || ((await request.formData()).get('shop') as string);
+
+    if (!shop) {
+      logger.debug('Missing shop parameter', {shop});
+      return {shop: LoginErrorType.MissingShop};
+    }
+
+    const shopWithoutProtocol = shop
+      .replace(/^https?:\/\//, '')
+      .replace(/\/$/, '');
+    const shopWithDomain =
+      shop?.indexOf('.') === -1
+        ? `${shopWithoutProtocol}.myshopify.com`
+        : shopWithoutProtocol;
+    const sanitizedShop = api.utils.sanitizeShop(shopWithDomain);
+
+    if (!sanitizedShop) {
+      logger.debug('Invalid shop parameter', {shop});
+      return {shop: LoginErrorType.InvalidShop};
+    }
+
+    const authPath = `${config.appUrl}${config.auth.path}?shop=${sanitizedShop}`;
+
+    const adminPath = api.utils.legacyUrlToShopAdminUrl(sanitizedShop);
+    const installPath = `https://${adminPath}/oauth/install?client_id=${config.apiKey}`;
+
+    const shouldInstall =
+      config.isEmbeddedApp && config.future.unstable_newEmbeddedAuthStrategy;
+    const redirectUrl = shouldInstall ? installPath : authPath;
+
+    logger.info(`Redirecting login request to ${redirectUrl}`, {
+      shop: sanitizedShop,
+    });
+
+    throw redirect(redirectUrl);
+  };
+}

package/src/server/authenticate/public/appProxy/authenticate.public.app-proxy.doc.example.ts

@@ -0,0 +1,27 @@
+import type {LoaderFunctionArgs} from '@remix-run/node';
+
+import {authenticate} from '../shopify.server';
+
+export const loader = async ({request}: LoaderFunctionArgs) => {
+  const {storefront, liquid} = await authenticate.public.appProxy(request);
+
+  if (!storefront) {
+    return new Response();
+  }
+
+  const response = await storefront.graphql(
+    `#graphql
+    query productTitle {
+      products(first: 1) {
+        nodes {
+          title
+        }
+      }
+    }`,
+  );
+  const body = await response.json();
+
+  const title = body.data.products.nodes[0].title;
+
+  return liquid(`Found product ${title} from {{shop.name}}`);
+};

package/src/server/authenticate/public/appProxy/authenticate.public.app-proxy.doc.ts

@@ -0,0 +1,55 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'App proxy',
+  description:
+    '[App proxies](/docs/apps/online-store/app-proxies) take requests to Shopify links, and redirect them to external links.' +
+    '\nThe `authenticate.public.appProxy` function validates requests made to app proxies, and returns a context to enable querying Shopify APIs.' +
+    '\n\n> Note: If the store has not installed the app, store-related properties such as `admin` or `storefront` will be `undefined`',
+  category: 'Authenticate',
+  subCategory: 'Public',
+  type: 'object',
+  isVisualComponent: false,
+  definitions: [
+    {
+      title: 'authenticate.public.appProxy',
+      description:
+        'Authenticates requests coming to the app from Shopify app proxies.',
+      type: 'AuthenticateAppProxy',
+    },
+  ],
+  defaultExample: {
+    description: 'Authenticate and fetch product information',
+    codeblock: {
+      title: 'Authenticate and fetch product information',
+      tabs: [
+        {
+          title: '/app/routes/**.ts',
+          language: 'typescript',
+          code: './authenticate.public.app-proxy.doc.example.ts',
+        },
+      ],
+    },
+  },
+  jsDocTypeExamples: ['AppProxyContextWithSession'],
+  related: [
+    {
+      name: 'Admin API context',
+      subtitle: 'Interact with the Admin API.',
+      url: '/docs/api/shopify-app-remix/apis/admin-api',
+    },
+    {
+      name: 'Storefront API context',
+      subtitle: 'Interact with the Storefront API.',
+      url: '/docs/api/shopify-app-remix/apis/storefront-api',
+    },
+    {
+      name: 'Liquid reference',
+      subtitle: "Use the shop's theme to render a template.",
+      url: '/docs/api/liquid',
+      type: 'liquid',
+    },
+  ],
+};
+
+export default data;

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

@@ -0,0 +1,150 @@
+import {adminClientFactory, storefrontClientFactory} from '../../../clients';
+import {ensureValidOfflineSession} from '../../../helpers';
+import {BasicParams} from '../../../types';
+
+import {
+  AppProxyContext,
+  AppProxyContextWithSession,
+  AuthenticateAppProxy,
+  LiquidResponseFunction,
+} from './types';
+
+export function authenticateAppProxyFactory(
+  params: BasicParams,
+): AuthenticateAppProxy {
+  const {logger} = params;
+
+  return async function authenticate(
+    request: Request,
+  ): Promise<AppProxyContext | AppProxyContextWithSession> {
+    const url = new URL(request.url);
+    const shop = url.searchParams.get('shop')!;
+    logger.info('Authenticating app proxy request', {shop});
+
+    if (!(await validateAppProxyHmac(params, url))) {
+      logger.info('App proxy request has invalid signature', {shop});
+      throw new Response(undefined, {
+        status: 400,
+        statusText: 'Bad Request',
+      });
+    }
+
+    const session = await ensureValidOfflineSession(params, shop);
+
+    if (!session) {
+      logger.debug('Could not find offline session, returning empty context', {
+        shop,
+        ...Object.fromEntries(url.searchParams.entries()),
+      });
+
+      const context: AppProxyContext = {
+        liquid,
+        session: undefined,
+        admin: undefined,
+        storefront: undefined,
+      };
+
+      return context;
+    }
+
+    const context: AppProxyContextWithSession = {
+      liquid,
+      session,
+      admin: adminClientFactory({params, session}),
+      storefront: storefrontClientFactory({params, session}),
+    };
+
+    return context;
+  };
+}
+
+const liquid: LiquidResponseFunction = (body, initAndOptions) => {
+  const processedBody = processLiquidBody(body);
+
+  if (typeof initAndOptions !== 'object') {
+    return new Response(processedBody, {
+      status: initAndOptions || 200,
+      headers: {
+        'Content-Type': 'application/liquid',
+      },
+    });
+  }
+
+  const {layout, ...responseInit} = initAndOptions || {};
+  const responseBody =
+    layout === false ? `{% layout none %} ${processedBody}` : processedBody;
+
+  const headers = new Headers(responseInit.headers);
+  headers.set('Content-Type', 'application/liquid');
+
+  return new Response(responseBody, {
+    ...responseInit,
+    headers,
+  });
+};
+
+async function validateAppProxyHmac(
+  params: BasicParams,
+  url: URL,
+): Promise<boolean> {
+  const {api, logger} = params;
+
+  try {
+    let searchParams = new URLSearchParams(url.search);
+    if (!searchParams.get('index')) {
+      searchParams.delete('index');
+    }
+
+    let isValid = await api.utils.validateHmac(
+      Object.fromEntries(searchParams.entries()),
+      {signator: 'appProxy'},
+    );
+
+    if (!isValid) {
+      const cleanPath = url.pathname
+        .replace(/^\//, '')
+        .replace(/\/$/, '')
+        .replaceAll('/', '.');
+      const data = `routes%2F${cleanPath}`;
+
+      searchParams = new URLSearchParams(
+        `?_data=${data}&${searchParams.toString().replace(/^\?/, '')}`,
+      );
+
+      isValid = await api.utils.validateHmac(
+        Object.fromEntries(searchParams.entries()),
+        {signator: 'appProxy'},
+      );
+
+      if (!isValid) {
+        const searchParams = new URLSearchParams(
+          `?_data=${data}._index&${url.search.replace(/^\?/, '')}`,
+        );
+
+        isValid = await api.utils.validateHmac(
+          Object.fromEntries(searchParams.entries()),
+          {signator: 'appProxy'},
+        );
+      }
+    }
+
+    return isValid;
+  } catch (error) {
+    const shop = url.searchParams.get('shop')!;
+    logger.info(error.message, {shop});
+    throw new Response(undefined, {status: 400, statusText: 'Bad Request'});
+  }
+}
+
+function processLiquidBody(body: string) {
+  return (
+    body
+      // Add trailing slashes to relative form action URLs
+      .replaceAll(
+        /<(form[^>]+)action="(\/[^"?]+)(\?[^"]+)?">/g,
+        '<$1action="$2/$3">',
+      )
+      // Add trailing slashes to relative link href URLs
+      .replaceAll(/<(a[^>]+)href="(\/[^"?]+)(\?[^"]+)?">/g, '<$1href="$2/$3">')
+  );
+}

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

@@ -0,0 +1,215 @@
+import {Session} from '@shopify/shopify-api';
+
+import {AdminApiContext, StorefrontContext} from '../../../clients';
+
+export type AuthenticateAppProxy = (
+  request: Request,
+) => Promise<AppProxyContext | AppProxyContextWithSession>;
+
+interface Options {
+  /**
+   * Whether to use the shop's theme layout around the Liquid content.
+   */
+  layout?: boolean;
+}
+
+export type LiquidResponseFunction = (
+  body: string,
+  initAndOptions?: number | (ResponseInit & Options),
+) => Response;
+
+interface Context {
+  /**
+   * A utility for creating a Liquid Response.
+   *
+   * @example
+   * <caption>Rendering liquid content.</caption>
+   * <description>Use the `liquid` helper to render a `Response` with Liquid content using the shop's theme. See the [Liquid reference](https://shopify.dev/docs/api/liquid) for all the features it enables.</description>
+   * ```ts
+   * // /app/routes/**\/*.ts
+   * import {authenticate} from "~/shopify.server"
+   *
+   * export async function loader({ request }) {
+   *   const {liquid} = await authenticate.public.appProxy(request);
+   *
+   *   return liquid("Hello {{shop.name}}");
+   * }
+   * ```
+   *
+   * @example
+   * <caption>Rendering liquid content without a layout.</caption>
+   * <description>Set the `layout` option to `false` to render the Liquid content without a theme.</description>
+   * ```ts
+   * // /app/routes/**\/*.ts
+   * import {authenticate} from "~/shopify.server"
+   *
+   * export async function loader({ request }) {
+   *   const {liquid} = await authenticate.public.appProxy(request);
+   *
+   *   return liquid(
+   *     "Hello {{shop.name}}",
+   *     { layout: false }
+   *   );
+   * }
+   * ```
+   *
+   * @example
+   * <caption>Rendering a form in a Liquid response.</caption>
+   * <description>Handle form submissions through an app proxy.</description>
+   * ```ts
+   * // app/routes/apps.proxy.my-action.tsx
+   * import { redirect } from "@remix-run/node";
+   * import { authenticate } from "~/shopify.server";
+   *
+   * export async function loader({ request }) {
+   *   const { liquid } = await authenticate.public.appProxy(request);
+   *
+   *   return liquid(`
+   *     <form method="post" action="/apps/proxy/my-action">
+   *       <input type="text" name="field" />
+   *       <button type="submit">Submit</button>
+   *     </form>
+   *   `);
+   * }
+   *
+   * export async function action({ request }) {
+   *   await authenticate.public.appProxy(request);
+   *
+   *   const formData = await request.formData();
+   *   const field = formData.get("field")?.toString();
+   *
+   *   // Perform actions here
+   *   if (field) {
+   *     console.log("Field:", field);
+   *   }
+   *
+   *   // Return to the form page
+   *   return redirect("/apps/proxy/my-action");
+   * }
+   * ```
+   */
+  liquid: LiquidResponseFunction;
+}
+
+export interface AppProxyContext extends Context {
+  /**
+   * No session is available for the shop that made this request.
+   *
+   * This comes from the session storage which `shopifyApp` uses to store sessions in your database of choice.
+   */
+  session: undefined;
+
+  /**
+   * No session is available for the shop that made this request.
+   * Therefore no methods for interacting with the GraphQL Admin API are available.
+   */
+  admin: undefined;
+
+  /**
+   * No session is available for the shop that made this request.
+   * Therefore no method for interacting with the Storefront API is available.
+   */
+  storefront: undefined;
+}
+
+export interface AppProxyContextWithSession extends Context {
+  /**
+   * The session for the shop that made the request.
+   *
+   * This comes from the session storage which `shopifyApp` uses to store sessions in your database of choice.
+   *
+   * Use this to get shop or user-specific data.
+   *
+   * @example
+   * <caption>Using the session object.</caption>
+   * <description>Get the session for the shop that initiated the request to the app proxy.</description>
+   * ```ts
+   * // app/routes/**\/.ts
+   * import { json } from "@remix-run/node";
+   * import { authenticate } from "../shopify.server";
+   * import { getMyAppModelData } from "~/db/model.server";
+   *
+   * export const loader = async ({ request }) => {
+   *   // Get the session for the shop that initiated the request to the app proxy.
+   *   const { session } =
+   *     await authenticate.public.appProxy(request);
+   *
+   *   // Use the session data to make to queries to your database or additional requests.
+   *   return json(
+   *     await getMyAppModelData({shop: session.shop})
+   *   );
+   * };
+   * ```
+   */
+  session: Session;
+
+  /**
+   * Methods for interacting with the GraphQL Admin API for the store that made the request.
+   *
+   * @example
+   * <caption>Interacting with the Admin API.</caption>
+   * <description>Use the `admin` object to interact with the admin GraphQL API.</description>
+   * ```ts
+   * // app/routes/**\/.ts
+   * import { json } from "@remix-run/node";
+   * import { authenticate } from "../shopify.server";
+   *
+   * export async function action({ request }: ActionFunctionArgs) {
+   *   const { admin } = await authenticate.public.appProxy(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({ data: productData.data });
+   * }
+   * ```
+   */
+  admin: AdminApiContext;
+
+  /**
+   * Method for interacting with the Shopify Storefront Graphql API for the store that made the request.
+   *
+   * @example
+   * <caption>Interacting with the Storefront API.</caption>
+   * <description>Use the `storefront` object to interact with the GraphQL API.</description>
+   * ```ts
+   * // app/routes/**\/.ts
+   * import { json } from "@remix-run/node";
+   * import { authenticate } from "../shopify.server";
+   *
+   * export async function action({ request }: ActionFunctionArgs) {
+   *   const { storefront } = await authenticate.public.appProxy(request);
+   *
+   *   const response = await storefront.graphql(
+   *     `#graphql
+   *     query blogIds {
+   *       blogs(first: 10) {
+   *         edges {
+   *           node {
+   *             id
+   *           }
+   *         }
+   *       }
+   *     }`
+   *   );
+   *
+   *   return json(await response.json());
+   * }
+   * ```
+   */
+  storefront: StorefrontContext;
+}

package/src/server/authenticate/public/checkout/authenticate.public.checkout.doc.example.offers.ts

@@ -0,0 +1,21 @@
+// Most apps would load this from their database
+export function getOffers(shop: string) {
+  const offers: Record<any, any[]> = {
+    'shop.com': [
+      {
+        id: '1',
+        title: '10% off',
+        price: 10,
+        type: 'percentage',
+      },
+      {
+        id: '2',
+        title: 'Free shipping',
+        price: 0,
+        type: 'shipping',
+      },
+    ],
+  };
+
+  return offers[shop];
+}

package/src/server/authenticate/public/checkout/authenticate.public.checkout.doc.example.ts

@@ -0,0 +1,17 @@
+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.checkout(request);
+};
+
+export const action = async ({request}: ActionFunctionArgs) => {
+  const {cors, sessionToken} = await authenticate.public.checkout(request);
+
+  const offers = getOffers(sessionToken.dest);
+  return cors(json({offers}));
+};

package/src/server/authenticate/public/checkout/authenticate.public.checkout.doc.ts

@@ -0,0 +1,49 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Checkout',
+  description:
+    'The `authenticate.public.checkout` function ensures that checkout 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.checkout',
+      description:
+        'Authenticates requests coming from Shopify checkout extensions.',
+      type: 'AuthenticateCheckout',
+    },
+  ],
+  defaultExample: {
+    description: 'Authenticate and return offers for the shop',
+    codeblock: {
+      title: 'Authenticate and return offers for the shop',
+      tabs: [
+        {
+          title: '/app/routes/**.ts',
+          language: 'typescript',
+          code: './authenticate.public.checkout.doc.example.ts',
+        },
+        {
+          title: '/app/offers.server.ts',
+          language: 'typescript',
+          code: './authenticate.public.checkout.doc.example.offers.ts',
+        },
+      ],
+    },
+  },
+  jsDocTypeExamples: ['CheckoutContext'],
+  related: [
+    {
+      name: 'Session token API',
+      subtitle:
+        'Checkout UI extension API for interacting with session tokens.',
+      url: '/docs/api/checkout-ui-extensions/latest/apis/session-token',
+      type: 'shopify',
+    },
+  ],
+};
+
+export default data;

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

@@ -0,0 +1,13 @@
+import type {BasicParams} from '../../../types';
+import {authenticateExtensionFactory} from '../extension/authenticate';
+
+import type {AuthenticateCheckout} from './types';
+
+export function authenticateCheckoutFactory(
+  params: BasicParams,
+): AuthenticateCheckout {
+  return authenticateExtensionFactory(
+    params,
+    'checkout',
+  ) as AuthenticateCheckout;
+}

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

@@ -0,0 +1,65 @@
+import {JwtPayload} from '@shopify/shopify-api';
+
+import {EnsureCORSFunction} from '../../helpers/ensure-cors-headers';
+
+export type AuthenticateCheckout = (
+  request: Request,
+  options?: AuthenticateCheckoutOptions,
+) => Promise<CheckoutContext>;
+
+export interface AuthenticateCheckoutOptions {
+  corsHeaders?: string[];
+}
+
+/**
+ * Authenticated Context for a checkout request
+ */
+export interface CheckoutContext {
+  /**
+   * 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.checkout(
+   *     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 checkout 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.checkout(
+   *     request,
+   *     { corsHeaders: ["X-My-Custom-Header"] }
+   *   );
+   *   const data = await getMyAppData({shop: sessionToken.dest});
+   *   return cors(json(data));
+   * };
+   * ```
+   */
+  cors: EnsureCORSFunction;
+}