@shopify/shopify-app-remix 4.1.1 → 4.2.0

package/src/server/shopify-app.doc.ts

@@ -0,0 +1,45 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'shopifyApp',
+  description:
+    "Returns a set of functions that can be used by the app's backend to be able to respond to all Shopify requests." +
+    '\n\nThe shape of the returned object changes depending on the value of `distribution`. If it is `AppDistribution.ShopifyAdmin`, then only `ShopifyAppBase` objects are returned, otherwise `ShopifyAppLogin` objects are included.',
+  category: 'Entrypoints',
+  type: 'function',
+  isVisualComponent: false,
+  definitions: [
+    {
+      title: 'shopifyApp',
+      description: 'Function to create a new Shopify API object.',
+      type: 'ShopifyAppGeneratedType',
+    },
+    {
+      title: 'Future flags',
+      description:
+        'Set future flags using the `future` configuration field to opt in to upcoming breaking changes.' +
+        '\n\nWith this feature, you can prepare for major releases ahead of time, as well as try out new features before they are released.',
+      type: 'FutureFlags',
+      filePath: 'src/server/future/flags.ts',
+    },
+  ],
+  jsDocTypeExamples: [
+    'ShopifyAppGeneratedType',
+    'ShopifyAppBase',
+    'ShopifyAppLogin',
+  ],
+  related: [
+    {
+      name: 'Authenticated contexts',
+      subtitle: 'Authenticate requests coming from Shopify.',
+      url: '/docs/api/shopify-app-remix/authenticate',
+    },
+    {
+      name: 'Unauthenticated contexts',
+      subtitle: 'Interact with the API on non-Shopify requests.',
+      url: '/docs/api/shopify-app-remix/unauthenticated',
+    },
+  ],
+};
+
+export default data;

package/src/server/shopify-app.ts

@@ -0,0 +1,215 @@
+import '@shopify/shopify-api/adapters/web-api';
+import {
+  ConfigInterface as ApiConfig,
+  ShopifyError,
+  shopifyApi,
+} from '@shopify/shopify-api';
+import {SessionStorage} from '@shopify/shopify-app-session-storage';
+
+import {type AppConfig, type AppConfigArg} from './config-types';
+import {
+  AppDistribution,
+  type BasicParams,
+  type ShopifyApp,
+  type ShopifyAppBase,
+  type AdminApp,
+  type SingleMerchantApp,
+  type AppStoreApp,
+} from './types';
+import {SHOPIFY_REMIX_LIBRARY_VERSION} from './version';
+import {registerWebhooksFactory} from './authenticate/webhooks';
+import {authStrategyFactory} from './authenticate/admin/authenticate';
+import {authenticateWebhookFactory} from './authenticate/webhooks/authenticate';
+import {overrideLogger} from './override-logger';
+import {addDocumentResponseHeadersFactory} from './authenticate/helpers';
+import {loginFactory} from './authenticate/login/login';
+import {unauthenticatedAdminContextFactory} from './unauthenticated/admin';
+import {authenticatePublicFactory} from './authenticate/public';
+import {unauthenticatedStorefrontContextFactory} from './unauthenticated/storefront';
+import {AuthCodeFlowStrategy} from './authenticate/admin/strategies/auth-code-flow';
+import {TokenExchangeStrategy} from './authenticate/admin/strategies/token-exchange';
+import {MerchantCustomAuth} from './authenticate/admin/strategies/merchant-custom-app';
+import {IdempotentPromiseHandler} from './authenticate/helpers/idempotent-promise-handler';
+import {authenticateFlowFactory} from './authenticate/flow/authenticate';
+import {authenticateFulfillmentServiceFactory} from './authenticate/fulfillment-service/authenticate';
+import {FutureFlagOptions, logDisabledFutureFlags} from './future/flags';
+
+/**
+ * Creates an object your app will use to interact with Shopify.
+ *
+ * @param appConfig Configuration options for your Shopify app, such as the scopes your app needs.
+ * @returns `ShopifyApp` An object constructed using your appConfig.  It has methods for interacting with Shopify.
+ *
+ * @example
+ * <caption>The minimum viable configuration</caption>
+ * ```ts
+ * // /shopify.server.ts
+ * import { shopifyApp } from "@shopify/shopify-app-remix/server";
+ *
+ * const shopify = shopifyApp({
+ *   apiKey: process.env.SHOPIFY_API_KEY!,
+ *   apiSecretKey: process.env.SHOPIFY_API_SECRET!,
+ *   scopes: process.env.SCOPES?.split(",")!,
+ *   appUrl: process.env.SHOPIFY_APP_URL!,
+ * });
+ * export default shopify;
+ * ```
+ */
+export function shopifyApp<
+  Config extends AppConfigArg<Storage, Future>,
+  Storage extends SessionStorage,
+  Future extends FutureFlagOptions = Config['future'],
+>(appConfig: Readonly<Config>): ShopifyApp<Config> {
+  const api = deriveApi(appConfig);
+  const config = deriveConfig<Storage>(appConfig, api.config);
+  const logger = overrideLogger(api.logger);
+
+  if (appConfig.webhooks) {
+    api.webhooks.addHandlers(appConfig.webhooks);
+  }
+
+  const params: BasicParams = {api, config, logger};
+
+  let strategy;
+  if (config.distribution === AppDistribution.ShopifyAdmin) {
+    strategy = new MerchantCustomAuth(params);
+  } else if (
+    config.future.unstable_newEmbeddedAuthStrategy &&
+    config.isEmbeddedApp
+  ) {
+    strategy = new TokenExchangeStrategy(params);
+  } else {
+    strategy = new AuthCodeFlowStrategy(params);
+  }
+
+  const authStrategy = authStrategyFactory<Config>({
+    ...params,
+    strategy,
+  });
+
+  const shopify:
+    | AdminApp<Config>
+    | AppStoreApp<Config>
+    | SingleMerchantApp<Config> = {
+    sessionStorage: config.sessionStorage,
+    addDocumentResponseHeaders: addDocumentResponseHeadersFactory(params),
+    registerWebhooks: registerWebhooksFactory(params),
+    authenticate: {
+      admin: authStrategy,
+      flow: authenticateFlowFactory(params),
+      public: authenticatePublicFactory(params),
+      fulfillmentService: authenticateFulfillmentServiceFactory(params),
+      webhook: authenticateWebhookFactory<string>(params),
+    },
+    unauthenticated: {
+      admin: unauthenticatedAdminContextFactory(params),
+      storefront: unauthenticatedStorefrontContextFactory(params),
+    },
+  };
+
+  if (
+    isAppStoreApp(shopify, appConfig) ||
+    isSingleMerchantApp(shopify, appConfig)
+  ) {
+    shopify.login = loginFactory(params);
+  }
+
+  logDisabledFutureFlags(config, logger);
+
+  return shopify as ShopifyApp<Config>;
+}
+
+function isAppStoreApp<Config extends AppConfigArg>(
+  _shopify: ShopifyAppBase<Config>,
+  config: Config,
+): _shopify is AppStoreApp<Config> {
+  return config.distribution === AppDistribution.AppStore;
+}
+
+function isSingleMerchantApp<Config extends AppConfigArg>(
+  _shopify: ShopifyAppBase<Config>,
+  config: Config,
+): _shopify is SingleMerchantApp<Config> {
+  return config.distribution === AppDistribution.SingleMerchant;
+}
+
+// This function is only exported so we can unit test it without having to mock the underlying module.
+// It's not available to consumers of the library because it is not exported in the index module, and never should be.
+export function deriveApi(appConfig: AppConfigArg): BasicParams['api'] {
+  let appUrl: URL;
+  try {
+    appUrl = new URL(appConfig.appUrl);
+  } catch (error) {
+    const message =
+      appConfig.appUrl === ''
+        ? `Detected an empty appUrl configuration, please make sure to set the necessary environment variables.\n` +
+          `If you're deploying your app, you can find more information at https://shopify.dev/docs/apps/launch/deployment/deploy-web-app/deploy-to-hosting-service#step-4-set-up-environment-variables`
+        : `Invalid appUrl configuration '${appConfig.appUrl}', please provide a valid URL.`;
+    throw new ShopifyError(message);
+  }
+
+  /* eslint-disable no-process-env */
+  if (appUrl.hostname === 'localhost' && !appUrl.port && process.env.PORT) {
+    appUrl.port = process.env.PORT;
+  }
+  /* eslint-enable no-process-env */
+  appConfig.appUrl = appUrl.origin;
+
+  let userAgentPrefix = `Shopify Remix Library v${SHOPIFY_REMIX_LIBRARY_VERSION}`;
+  if (appConfig.userAgentPrefix) {
+    userAgentPrefix = `${appConfig.userAgentPrefix} | ${userAgentPrefix}`;
+  }
+
+  return shopifyApi({
+    ...appConfig,
+    hostName: appUrl.host,
+    hostScheme: appUrl.protocol.replace(':', '') as 'http' | 'https',
+    userAgentPrefix,
+    isEmbeddedApp: appConfig.isEmbeddedApp ?? true,
+    apiVersion: appConfig.apiVersion,
+    isCustomStoreApp: appConfig.distribution === AppDistribution.ShopifyAdmin,
+    billing: appConfig.billing as ApiConfig['billing'],
+    future: {
+      unstable_managedPricingSupport: true,
+    },
+    _logDisabledFutureFlags: false,
+  });
+}
+
+function deriveConfig<Storage extends SessionStorage>(
+  appConfig: AppConfigArg,
+  apiConfig: ApiConfig,
+): AppConfig<Storage> {
+  if (
+    !appConfig.sessionStorage &&
+    appConfig.distribution !== AppDistribution.ShopifyAdmin
+  ) {
+    throw new ShopifyError(
+      'Please provide a valid session storage. Refer to https://github.com/Shopify/shopify-app-js/blob/main/README.md#session-storage-options for options.',
+    );
+  }
+
+  const authPathPrefix = appConfig.authPathPrefix || '/auth';
+  appConfig.distribution = appConfig.distribution ?? AppDistribution.AppStore;
+
+  return {
+    ...appConfig,
+    ...apiConfig,
+    billing: appConfig.billing as ApiConfig['billing'],
+    scopes: apiConfig.scopes,
+    idempotentPromiseHandler: new IdempotentPromiseHandler(),
+    canUseLoginForm: appConfig.distribution !== AppDistribution.ShopifyAdmin,
+    useOnlineTokens: appConfig.useOnlineTokens ?? false,
+    hooks: appConfig.hooks ?? {},
+    sessionStorage: appConfig.sessionStorage as Storage,
+    future: appConfig.future ?? {},
+    auth: {
+      path: authPathPrefix,
+      callbackPath: `${authPathPrefix}/callback`,
+      patchSessionTokenPath: `${authPathPrefix}/session-token`,
+      exitIframePath: `${authPathPrefix}/exit-iframe`,
+      loginPath: `${authPathPrefix}/login`,
+    },
+    distribution: appConfig.distribution,
+  };
+}

package/src/server/test-helpers/index.ts

@@ -0,0 +1 @@
+export {testConfig} from './test-config';

package/src/server/test-helpers/test-config.ts

@@ -0,0 +1,79 @@
+import {LogSeverity} from '@shopify/shopify-api';
+import {SessionStorage} from '@shopify/shopify-app-session-storage';
+import {MemorySessionStorage} from '@shopify/shopify-app-session-storage-memory';
+import {
+  API_KEY,
+  API_SECRET_KEY,
+  APP_URL,
+} from '@shopify/shopify-api/test-helpers';
+
+import type {AppConfigArg} from '../config-types';
+import type {FutureFlagOptions} from '../future/flags';
+
+const TEST_CONFIG = {
+  apiKey: API_KEY,
+  apiSecretKey: API_SECRET_KEY,
+  scopes: ['testScope'] as any,
+  appUrl: APP_URL,
+  adminApiAccessToken: API_KEY,
+  privateAppStorefrontAccessToken: API_KEY,
+  logger: {
+    level: LogSeverity.Debug,
+  },
+  sessionStorage: new MemorySessionStorage(),
+  isTesting: true,
+} as const;
+
+export function testConfig<
+  Overrides extends TestOverridesArg,
+  Future extends FutureFlagOptions,
+>(
+  {future, ...overrides}: Overrides & {future?: Future} = {} as Overrides & {
+    future?: Future;
+  },
+): TestConfig<Overrides> {
+  return {
+    ...TEST_CONFIG,
+    ...overrides,
+    logger: {
+      ...TEST_CONFIG.logger,
+      ...(overrides as NonNullable<Overrides>).logger,
+    },
+    future,
+  } as any;
+}
+
+/*
+ * This type combines both passed in types, by ignoring any keys from Type1 that are present (and not undefined)
+ * in Type2, and then adding any keys from Type1 that are not present in Type2.
+ *
+ * This effectively enables us to create a type that is the const TEST_CONFIG below, plus any overrides passed in with
+ * the output being a const object.
+ */
+type Modify<Type1, Type2> = {
+  [key in keyof Type2 as Type2[key] extends undefined
+    ? never
+    : key]: Type2[key];
+} & {
+  [key in keyof Type1 as key extends keyof Type2 ? never : key]: Type1[key];
+};
+
+/*
+ * We omit the future prop and then redefine it with a partial of that object so we can pass the fully typed object in
+ * to AppConfigArg.
+ */
+type TestOverrides = Partial<
+  Omit<AppConfigArg<SessionStorage, FutureFlagOptions>, 'future'> & {
+    future: Partial<FutureFlagOptions>;
+  }
+>;
+
+export type TestOverridesArg = undefined | TestOverrides;
+
+export type TestConfig<Overrides extends TestOverridesArg> = Modify<
+  typeof TEST_CONFIG,
+  Overrides
+> & {
+  future: FutureFlagOptions;
+  logger: AppConfigArg['logger'];
+};

package/src/server/types-contexts.ts

@@ -0,0 +1,44 @@
+// This file contains types we want to export to make it easier for apps to pass the contexts we return as types
+
+import type {AppConfigArg} from './config-types';
+import type {ShopifyApp} from './types';
+import type {AdminContext as IAdminContext} from './authenticate/admin/types';
+import type {WebhookContext as IWebhookContext} from './authenticate/webhooks/types';
+import type {
+  AppProxyContext as IAppProxyContext,
+  AppProxyContextWithSession as IAppProxyContextWithSession,
+} from './authenticate/public/appProxy/types';
+import type {
+  AdminApiContext as IAdminApiContext,
+  StorefrontContext as IStorefrontContext,
+} from './clients';
+
+// Direct re-exports for types without transformations
+export type {UnauthenticatedAdminContext} from './unauthenticated/admin/types';
+export type {UnauthenticatedStorefrontContext} from './unauthenticated/storefront/types';
+export type {FlowContext} from './authenticate/flow/types';
+export type {FulfillmentServiceContext} from './authenticate/fulfillment-service/types';
+export type {ScopesDetail} from './authenticate/admin/scope/types';
+export type {AdminApiContext} from './clients';
+export type {ScopesContext} from './authenticate/admin/types';
+export type {CheckoutContext} from './authenticate/public/checkout/types';
+export type {CustomerAccountContext} from './authenticate/public/customer-account/types';
+export type {StorefrontContext as StorefrontApiContext} from './clients';
+
+type ShopifyConfig<App> =
+  App extends ShopifyApp<infer Config extends AppConfigArg> ? Config : never;
+
+type DefaultApp = ShopifyApp<AppConfigArg>;
+
+// Types that need transformations or generic parameters
+export type AdminContext<App = DefaultApp> = IAdminContext<ShopifyConfig<App>>;
+
+// Types that need modifications
+export type AppProxyContext = IAppProxyContext | IAppProxyContextWithSession;
+
+export type WebhookContext = IWebhookContext<string>;
+
+// Extra types for API contexts
+export type AdminGraphqlClient = IAdminApiContext['graphql'];
+
+export type StorefrontGraphqlClient = IStorefrontContext['graphql'];