@shopify/shopify-app-remix 4.1.0 → 4.2.0

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

@@ -0,0 +1,78 @@
+import {StorefrontOperations} from '@shopify/storefront-api-client';
+
+import {GraphQLClient} from '../types';
+
+export interface StorefrontContext {
+  /**
+   * Method for interacting with the Shopify Storefront GraphQL API
+   *
+   * If you're getting incorrect type hints in the Shopify template, follow [these instructions](https://github.com/Shopify/shopify-app-template-remix/tree/main#incorrect-graphql-hints).
+   *
+   * {@link https://shopify.dev/docs/api/storefront}
+   *
+   * @example
+   * <caption>Querying the GraphQL API.</caption>
+   * <description>Use `storefront.graphql` to make query / mutation requests.</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(`{blogs(first: 10) { edges { node { id } } } }`);
+   *
+   *   return json(await response.json());
+   * }
+   * ```
+   *
+   * @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 { storefront } = await authenticate.public.appProxy(request);
+   *
+   *   try {
+   *     const response = await storefront.graphql(
+   *       `#graphql
+   *       query incorrectQuery {
+   *         products(first: 10) {
+   *           nodes {
+   *             not_a_field
+   *           }
+   *         }
+   *       }`,
+   *     );
+   *
+   *     return json({ data: await response.json() });
+   *   } catch (error) {
+   *     if (error instanceof GraphqlQueryError) {
+   *       // { 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<StorefrontOperations>;
+}

package/src/server/clients/types.ts

@@ -0,0 +1,47 @@
+import type {
+  AllOperations,
+  ReturnData,
+  FetchResponseBody,
+  ApiClientRequestOptions,
+  ResponseWithType,
+} from '@shopify/admin-api-client';
+import {ApiVersion} from '@shopify/shopify-api';
+
+export interface GraphQLQueryOptions<
+  Operation extends keyof Operations,
+  Operations extends AllOperations,
+> {
+  /**
+   * The variables to pass to the operation.
+   */
+  variables?: ApiClientRequestOptions<Operation, Operations>['variables'];
+  /**
+   * The version of the API to use for the request.
+   */
+  apiVersion?: ApiVersion;
+  /**
+   * Additional headers to include in the request.
+   */
+  headers?: Record<string, any>;
+  /**
+   * The total number of times to try the request if it fails.
+   */
+  tries?: number;
+
+  /**
+   * An optional AbortSignal to cancel the request.
+   */
+  signal?: AbortSignal;
+}
+
+export type GraphQLResponse<
+  Operation extends keyof Operations,
+  Operations extends AllOperations,
+> = ResponseWithType<FetchResponseBody<ReturnData<Operation, Operations>>>;
+
+export type GraphQLClient<Operations extends AllOperations> = <
+  Operation extends keyof Operations,
+>(
+  query: Operation,
+  options?: GraphQLQueryOptions<Operation, Operations>,
+) => Promise<GraphQLResponse<Operation, Operations>>;

package/src/server/config-types.ts

@@ -0,0 +1,309 @@
+import {
+  ConfigParams as ApiConfigArg,
+  ConfigInterface as ApiConfig,
+  Session,
+  ApiVersion,
+  WebhookHandler,
+} from '@shopify/shopify-api';
+import {SessionStorage} from '@shopify/shopify-app-session-storage';
+
+import type {
+  ApiFutureFlags,
+  FutureFlagOptions,
+  FutureFlags,
+} from './future/flags';
+import type {AppDistribution} from './types';
+import type {AdminApiContext} from './clients';
+import {IdempotentPromiseHandler} from './authenticate/helpers/idempotent-promise-handler';
+
+export interface AppConfigArg<
+  Storage extends SessionStorage = SessionStorage,
+  Future extends FutureFlagOptions = FutureFlagOptions,
+> extends Omit<
+  ApiConfigArg<ApiFutureFlags<Future>>,
+  | 'hostName'
+  | 'hostScheme'
+  | 'isEmbeddedApp'
+  | 'apiVersion'
+  | 'isCustomStoreApp'
+  | 'future'
+> {
+  /**
+   * The URL your app is running on.
+   *
+   * The `@shopify/cli` provides this URL as `process.env.SHOPIFY_APP_URL`.  For development this is probably a tunnel URL that points to your local machine.  If this is a production app, this is your production URL.
+   */
+  appUrl: string;
+
+  /**
+   * An adaptor for storing sessions in your database of choice.
+   *
+   * Shopify provides multiple session storage adaptors and you can create your own.
+   *
+   * Optional for apps created in the Shopify Admin.
+   *
+   * {@link https://github.com/Shopify/shopify-app-js/blob/main/README.md#session-storage-options}
+   *
+   * @example
+   * <caption>Storing sessions with Prisma.</caption>
+   * <description>Add the `@shopify/shopify-app-session-storage-prisma` package to use the Prisma session storage.</description>
+   * ```ts
+   * import { shopifyApp } from "@shopify/shopify-app-remix/server";
+   * import { PrismaSessionStorage } from "@shopify/shopify-app-session-storage-prisma";
+   *
+   * import prisma from "~/db.server";
+   *
+   * const shopify = shopifyApp({
+   *   // ... etc
+   *   sessionStorage: new PrismaSessionStorage(prisma),
+   * });
+   * export default shopify;
+   * ```
+   */
+  sessionStorage?: Storage;
+
+  /**
+   * Whether your app use online or offline tokens.
+   *
+   * If your app uses online tokens, then both online and offline tokens will be saved to your database.  This ensures your app can perform background jobs.
+   *
+   * {@link https://shopify.dev/docs/apps/auth/oauth/access-modes}
+   *
+   * @defaultValue `false`
+   */
+  useOnlineTokens?: boolean;
+
+  /**
+   * The config for the shop-specific webhooks your app needs.
+   * 
+   * Use this to configure shop-specific webhooks. In many cases defining app-specific webhooks in the `shopify.app.toml` will be sufficient and easier to manage.  Please see:
+   * 
+   * {@link https://shopify.dev/docs/apps/build/webhooks/subscribe#app-specific-vs-shop-specific-subscriptions}
+   * 
+   * You should only use this if you need shop-specific webhooks. If you do need shop-specific webhooks this can be in used in conjunction with the afterAuth hook, loaders or processes such as background jobs.
+   *
+   * @example
+   * <caption>Registering shop-specific webhooks.</caption>
+   * ```ts
+   * // app/shopify.server.ts
+   * import { DeliveryMethod, shopifyApp } from "@shopify/shopify-app-remix/server";
+   *
+   * const shopify = shopifyApp({
+   *   webhooks: {
+   *     PRODUCTS_CREATE: {
+   *       deliveryMethod: DeliveryMethod.Http,
+   *        callbackUrl: "/webhooks/products/create",
+   *     },
+   *   },
+   *   hooks: {
+   *     afterAuth: async ({ session }) => {
+   *       // Register webhooks for the shop
+   *       // In this example, every shop will have these webhooks
+   *       // But you could wrap this in some custom shop specific conditional logic
+   *       shopify.registerWebhooks({ session });
+   *     }
+   *   },
+   *   // ...etc
+   * });
+   * export default shopify;
+   * export const authenticate = shopify.authenticate;
+   * ```
+   * 
+   * @example
+   * <caption>Registering app-specific webhooks (Recommended)</caption>
+   * ```toml
+   * # shopify.app.toml
+   * [webhooks]
+   * api_version = "2024-07"
+
+   *   [[webhooks.subscriptions]]
+   *   topics = ["products/create"]
+   *   uri = "/webhooks/products/create"
+   * 
+   * ```
+   * 
+   * @example
+   * <caption>Authenticating a webhook request</caption>
+   *
+   * ```ts
+   * // /app/routes/webhooks.ts
+   * import { ActionFunctionArgs } from "@remix-run/node";
+   * import { authenticate } from "../shopify.server";
+   * import db from "../db.server";
+   *
+   * export const action = async ({ request }: ActionFunctionArgs) => {
+   *   const { topic, shop, session, payload } = 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 the webhook
+   *   console.log(`${TOPIC} webhook received with`, JSON.stringify(payload))
+   *
+   *   throw new Response();
+   * };
+   * ```
+   */
+  webhooks?: WebhookConfig;
+
+  /**
+   * Functions to call at key places during your apps lifecycle.
+   *
+   * These functions are called in the context of the request that triggered them.  This means you can access the session.
+   *
+   * @example
+   * <caption>Seeding your database custom data when a merchant installs your app.</caption>
+   * ```ts
+   * import { DeliveryMethod, shopifyApp } from "@shopify/shopify-app-remix/server";
+   * import { seedStoreData } from "~/db/seeds"
+   *
+   * const shopify = shopifyApp({
+   *   hooks: {
+   *     afterAuth: async ({ session }) => {
+   *       seedStoreData({session})
+   *     }
+   *   },
+   *   // ...etc
+   * });
+   * ```
+   */
+  hooks?: HooksConfig;
+
+  /**
+   * Does your app render embedded inside the Shopify Admin or on its own.
+   *
+   * Unless you have very specific needs, this should be true.
+   *
+   * @defaultValue `true`
+   */
+  isEmbeddedApp?: boolean;
+
+  /**
+   * How your app is distributed. Default is `AppDistribution.AppStore`.
+   *
+   * AppStore should be used for public apps that are distributed in the Shopify App Store.
+   * SingleMerchant should be used for custom apps managed in the Partner Dashboard.
+   * ShopifyAdmin should be used for apps that are managed in the merchant's Shopify Admin.
+   *
+   * {@link https://shopify.dev/docs/apps/distribution}
+   */
+  distribution?: AppDistribution;
+
+  /**
+   * What version of Shopify's Admin API's would you like to use.
+   *
+   * {@link https://shopify.dev/docs/api/}
+   *
+   * @example
+   * <caption>Using a specific API Version</caption>
+   * ```ts
+   * import { ApiVersion, shopifyApp } from "@shopify/shopify-app-remix/server";
+   *
+   * const shopify = shopifyApp({
+   *   // ...etc
+   *   apiVersion: ApiVersion.July25,
+   * });
+   * ```
+   */
+  apiVersion: ApiVersion;
+
+  /**
+   * A path that Shopify can reserve for auth related endpoints.
+   *
+   * This must match a $ route in your Remix app.  That route must export a loader function that calls `shopify.authenticate.admin(request)`.
+   *
+   * @default `"/auth"`
+   *
+   * @example
+   * <caption>Using an authPathPrefix</caption>
+   * ```ts
+   * // /app/shopify.server.ts
+   * import { ApiVersion, shopifyApp } from "@shopify/shopify-app-remix/server";
+   *
+   * const shopify = shopifyApp({
+   *   // ...etc
+   *   authPathPrefix: "/auth",
+   * });
+   * export default shopify;
+   * export const authenticate = shopify.authenticate;
+   *
+   * // /app/routes/auth/$.jsx
+   * import { LoaderFunctionArgs } from "@remix-run/node";
+   * import { authenticate } from "../../shopify.server";
+   *
+   * export async function loader({ request }: LoaderFunctionArgs) {
+   *   await authenticate.admin(request);
+   *
+   *   return null
+   * }
+   * ```
+   */
+  authPathPrefix?: string;
+
+  /**
+   * Features that will be introduced in future releases of this package.
+   *
+   * You can opt in to these features by setting the corresponding flags. By doing so, you can prepare for future
+   * releases in advance and provide feedback on the new features.
+   */
+  future?: Future;
+}
+
+export interface AppConfig<
+  Storage extends SessionStorage = SessionStorage,
+> extends Omit<ApiConfig, 'future'> {
+  canUseLoginForm: boolean;
+  appUrl: string;
+  auth: AuthConfig;
+  sessionStorage?: Storage;
+  useOnlineTokens: boolean;
+  hooks: HooksConfig;
+  future: FutureFlags;
+  idempotentPromiseHandler: IdempotentPromiseHandler;
+  distribution: AppDistribution;
+}
+
+export interface AuthConfig {
+  path: string;
+  callbackPath: string;
+  exitIframePath: string;
+  patchSessionTokenPath: string;
+  loginPath: string;
+}
+
+export type WebhookConfig = Record<string, WebhookHandler | WebhookHandler[]>;
+
+interface HooksConfig {
+  /**
+   * A function to call after a merchant installs your app
+   *
+   * @param context - An object with context about the request that triggered the hook.
+   * @param context.session - The session of the merchant that installed your app. This is the output of sessionStorage.loadSession in case people want to load their own.
+   * @param context.admin - An object with access to the Shopify Admin API's.
+   *
+   * @example
+   * <caption>Seeding data when a merchant installs your app.</caption>
+   * ```ts
+   * import { DeliveryMethod, shopifyApp } from "@shopify/shopify-app-remix/server";
+   * import { seedStoreData } from "~/db/seeds"
+   *
+   * const shopify = shopifyApp({
+   *   hooks: {
+   *     afterAuth: async ({ session }) => {
+   *       seedStoreData({session})
+   *     }
+   *   },
+   *   // ...etc
+   * });
+   * ```
+   */
+  afterAuth?: (options: AfterAuthOptions) => void | Promise<void>;
+}
+
+export interface AfterAuthOptions {
+  session: Session;
+  admin: AdminApiContext;
+}

package/src/server/errors.ts

@@ -0,0 +1,3 @@
+import {ShopifyError} from '@shopify/shopify-api';
+
+export class SessionNotFoundError extends ShopifyError {}

package/src/server/future/flags.ts

@@ -0,0 +1,62 @@
+import type {ConfigParams, Shopify} from '@shopify/shopify-api';
+
+import {AppConfig} from '../config-types';
+
+// When adding new flags, you should also add them to the `TEST_FUTURE_FLAGS` object in `test-config.ts` to ensure that
+// it doesn't cause regressions.
+export interface FutureFlags {
+  /**
+   * When enabled, embedded apps will fetch access tokens via [token exchange](https://shopify.dev/docs/apps/auth/get-access-tokens/token-exchange).
+   * This assumes the app has scopes declared for [Shopify managing installation](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation).
+   *
+   * Learn more about this [new embedded app auth strategy](https://shopify.dev/docs/api/shopify-app-remix#embedded-auth-strategy).
+   *
+   * @default false
+   */
+  unstable_newEmbeddedAuthStrategy?: boolean;
+  /**
+   * When enabled, the app will start using expiring offline access tokens and automatically refresh them when they are close to expiring.
+   *
+   * @default false
+   */
+  expiringOfflineAccessTokens?: boolean;
+}
+
+// When adding new flags, use this format:
+// apiFutureFlag: Future extends FutureFlags ? Future['remixFutureFlag'] : false;
+export interface ApiFutureFlags<Future extends FutureFlagOptions> {
+  expiringOfflineAccessTokens: Future extends FutureFlags
+    ? Future['expiringOfflineAccessTokens']
+    : false;
+  unstable_managedPricingSupport: true;
+}
+
+export type ApiConfigWithFutureFlags<Future extends FutureFlagOptions> =
+  ConfigParams<ApiFutureFlags<Future>>;
+
+export type FutureFlagOptions = FutureFlags | undefined;
+
+export type FeatureEnabled<
+  Future extends FutureFlagOptions,
+  Flag extends keyof FutureFlags,
+> = Future extends FutureFlags
+  ? Future[Flag] extends true
+    ? true
+    : false
+  : false;
+
+export function logDisabledFutureFlags(
+  config: AppConfig,
+  logger: Shopify['logger'],
+) {
+  const logFlag = (flag: string, message: string) =>
+    logger.info(`Future flag ${flag} is disabled.\n\n  ${message}\n`);
+
+  if (!config.future.unstable_newEmbeddedAuthStrategy) {
+    logFlag(
+      'unstable_newEmbeddedAuthStrategy',
+      'Enable this to use OAuth token exchange instead of auth code to generate API access tokens.' +
+        '\n  Your app must be using Shopify managed install: https://shopify.dev/docs/apps/auth/installation',
+    );
+  }
+}

package/src/server/helpers/create-or-load-offline-session.ts

@@ -0,0 +1,19 @@
+import {AppDistribution, BasicParams} from '../types';
+
+export async function createOrLoadOfflineSession(
+  {api, config, logger}: BasicParams,
+  shop: string,
+) {
+  if (config.distribution === AppDistribution.ShopifyAdmin) {
+    logger.debug('Creating custom app session from configured access token', {
+      shop,
+    });
+    return api.session.customAppSession(shop);
+  } else {
+    logger.debug('Loading offline session from session storage', {shop});
+    const offlineSessionId = api.session.getOfflineId(shop);
+    const session = await config.sessionStorage!.loadSession(offlineSessionId);
+
+    return session;
+  }
+}

package/src/server/helpers/ensure-offline-token-is-not-expired.ts

@@ -0,0 +1,32 @@
+import {Session} from '@shopify/shopify-api';
+
+import {AppDistribution, BasicParams} from '../types';
+
+import refreshToken from './refresh-token';
+
+// 5 minutes
+export const WITHIN_MILLISECONDS_OF_EXPIRY = 5 * 60 * 1000;
+
+export async function ensureOfflineTokenIsNotExpired(
+  session: Session,
+  params: BasicParams,
+  shop: string,
+) {
+  const {config} = params;
+  if (
+    config.future?.expiringOfflineAccessTokens &&
+    session.isExpired(WITHIN_MILLISECONDS_OF_EXPIRY) &&
+    config.distribution !== AppDistribution.ShopifyAdmin &&
+    session.refreshToken
+  ) {
+    const offlineSession = await refreshToken(
+      params,
+      shop,
+      session.refreshToken,
+    );
+
+    await config.sessionStorage!.storeSession(offlineSession);
+    return offlineSession;
+  }
+  return session;
+}

package/src/server/helpers/ensure-valid-offline-session.ts

@@ -0,0 +1,15 @@
+import {BasicParams} from '../types';
+
+import {createOrLoadOfflineSession} from './create-or-load-offline-session';
+import {ensureOfflineTokenIsNotExpired} from './ensure-offline-token-is-not-expired';
+
+export async function ensureValidOfflineSession(
+  params: BasicParams,
+  shop: string,
+) {
+  const session = await createOrLoadOfflineSession(params, shop);
+
+  if (!session) return undefined;
+
+  return ensureOfflineTokenIsNotExpired(session, params, shop);
+}

package/src/server/helpers/index.ts

@@ -0,0 +1,4 @@
+export * from './ensure-valid-offline-session';
+export * from './ensure-offline-token-is-not-expired';
+export * from './create-or-load-offline-session';
+export * from './refresh-token';

package/src/server/helpers/refresh-token.ts

@@ -0,0 +1,35 @@
+import {
+  HttpResponseError,
+  InvalidJwtError,
+  Session,
+} from '@shopify/shopify-api';
+
+import {BasicParams} from '../types';
+
+export default async function refreshToken(
+  params: BasicParams,
+  shop: string,
+  refreshToken: string,
+): Promise<Session> {
+  const {api} = params;
+  try {
+    const {session} = await api.auth.refreshToken({
+      shop,
+      refreshToken,
+    });
+    return session;
+  } catch (error) {
+    if (
+      error instanceof InvalidJwtError ||
+      (error instanceof HttpResponseError &&
+        error.response.code === 400 &&
+        error.response.body?.error === 'invalid_subject_token')
+    ) {
+      throw error;
+    }
+    throw new Response(undefined, {
+      status: 500,
+      statusText: 'Internal Server Error',
+    });
+  }
+}

package/src/server/index.ts

@@ -0,0 +1,24 @@
+import '@shopify/shopify-api/adapters/web-api';
+import {setAbstractRuntimeString} from '@shopify/shopify-api/runtime';
+
+setAbstractRuntimeString(() => {
+  return `Remix`;
+});
+
+export {
+  LogSeverity,
+  DeliveryMethod,
+  BillingInterval,
+  BillingReplacementBehavior,
+  ApiVersion,
+  Session,
+} from '@shopify/shopify-api';
+
+export type {JwtPayload} from '@shopify/shopify-api';
+
+export type * from './types-contexts';
+export type {ShopifyApp, LoginError} from './types';
+export {LoginErrorType, AppDistribution} from './types';
+export {boundary} from './boundary';
+export {shopifyApp} from './shopify-app';
+export * from './errors';

package/src/server/override-logger.ts

@@ -0,0 +1,42 @@
+import {compare} from 'compare-versions';
+import {FeatureDeprecatedError, Shopify} from '@shopify/shopify-api';
+
+import {SHOPIFY_REMIX_LIBRARY_VERSION} from './version';
+
+// eslint-disable-next-line no-warning-comments
+// TODO This has been copied from shopify-app-express, it should be extracted into a shared package
+// https://github.com/orgs/Shopify/projects/6899/views/1?pane=issue&itemId=28358070
+export function overrideLogger(logger: Shopify['logger']): Shopify['logger'] {
+  const baseContext = {package: 'shopify-app'};
+
+  const warningFunction: Shopify['logger']['warning'] = (
+    message,
+    context = {},
+  ) => logger.warning(message, {...baseContext, ...context});
+
+  function deprecated(warningFunction: Shopify['logger']['warning']) {
+    return function (version: string, message: string): Promise<void> {
+      if (compare(SHOPIFY_REMIX_LIBRARY_VERSION, version, '>=')) {
+        throw new FeatureDeprecatedError(
+          `Feature was deprecated in version ${version}`,
+        );
+      }
+
+      return warningFunction(`[Deprecated | ${version}] ${message}`);
+    };
+  }
+
+  return {
+    ...logger,
+    log: (severity, message, context = {}) =>
+      logger.log(severity, message, {...baseContext, ...context}),
+    debug: (message, context = {}) =>
+      logger.debug(message, {...baseContext, ...context}),
+    info: (message, context = {}) =>
+      logger.info(message, {...baseContext, ...context}),
+    warning: warningFunction,
+    error: (message, context = {}) =>
+      logger.error(message, {...baseContext, ...context}),
+    deprecated: deprecated(warningFunction),
+  };
+}