@shopify/shopify-app-remix 4.1.1 → 4.2.0

package/src/server/__test-helpers/setup-embedded-flow.ts

@@ -0,0 +1,30 @@
+import {shopifyApp} from '../shopify-app';
+
+import {APP_URL, BASE64_HOST, TEST_SHOP} from './const';
+import {getJwt} from './get-jwt';
+import {setUpValidSession} from './setup-valid-session';
+import {testConfig} from './test-config';
+
+export async function setUpEmbeddedFlow() {
+  const shopify = shopifyApp({
+    ...testConfig(),
+    future: {
+      unstable_newEmbeddedAuthStrategy: false,
+    },
+  });
+  const expectedSession = await setUpValidSession(shopify.sessionStorage);
+
+  const {token} = await getJwt();
+  const request = new Request(
+    `${APP_URL}?embedded=1&shop=${TEST_SHOP}&host=${BASE64_HOST}&id_token=${token}`,
+  );
+
+  const result = await shopify.authenticate.admin(request);
+
+  return {
+    shopify,
+    expectedSession,
+    ...result,
+    request,
+  };
+}

package/src/server/__test-helpers/setup-fetch-flow.ts

@@ -0,0 +1,29 @@
+import {shopifyApp} from '../shopify-app';
+
+import {APP_URL} from './const';
+import {getJwt} from './get-jwt';
+import {setUpValidSession} from './setup-valid-session';
+import {testConfig} from './test-config';
+
+export async function setUpFetchFlow(flags?: {
+  unstable_newEmbeddedAuthStrategy?: boolean;
+}) {
+  const shopify = shopifyApp({
+    ...testConfig(),
+    future: {...flags},
+  });
+
+  await setUpValidSession(shopify.sessionStorage);
+
+  const {token} = await getJwt();
+  const request = new Request(APP_URL, {
+    headers: {Authorization: `Bearer ${token}`},
+  });
+
+  const result = await shopify.authenticate.admin(request);
+
+  return {
+    shopify,
+    ...result,
+  };
+}

package/src/server/__test-helpers/setup-non-embedded-flow.ts

@@ -0,0 +1,31 @@
+import {SESSION_COOKIE_NAME} from '@shopify/shopify-api';
+
+import {shopifyApp} from '../shopify-app';
+
+import {APP_URL, TEST_SHOP} from './const';
+import {setUpValidSession} from './setup-valid-session';
+import {signRequestCookie} from './sign-request-cookie';
+import {testConfig} from './test-config';
+
+export async function setUpNonEmbeddedFlow() {
+  const shopify = shopifyApp({
+    ...testConfig({isEmbeddedApp: false}),
+  });
+  const session = await setUpValidSession(shopify.sessionStorage);
+
+  const request = new Request(`${APP_URL}?shop=${TEST_SHOP}`);
+  signRequestCookie({
+    request,
+    cookieName: SESSION_COOKIE_NAME,
+    cookieValue: session.id,
+  });
+
+  const result = await shopify.authenticate.admin(request);
+
+  return {
+    shopify,
+    ...result,
+    request,
+    session,
+  };
+}

package/src/server/__test-helpers/setup-valid-request.ts

@@ -0,0 +1,78 @@
+import {
+  RequestType,
+  ValidRequestOptions as ValidRequestOptionsImport,
+  setUpValidRequest as setUpValidRequestImport,
+} from '@shopify/shopify-api/test-helpers';
+
+import {ShopifyApp} from '../types';
+
+import {API_KEY, API_SECRET_KEY, APP_URL, TEST_SHOP_NAME} from './const';
+import {setUpValidSession} from './setup-valid-session';
+
+interface ValidBaseRequestOptions {
+  type: RequestType.Admin | RequestType.Bearer | RequestType.Public;
+}
+
+interface ValidExtensionRequestOptions {
+  type: RequestType.Extension;
+  body?: any;
+  headers?: Record<string, string>;
+}
+
+type ValidRequestOptions =
+  | ValidBaseRequestOptions
+  | ValidExtensionRequestOptions;
+
+export async function setupValidRequest(
+  shopify: ShopifyApp<any>,
+  options: ValidRequestOptions,
+) {
+  const session = await setUpValidSession(shopify.sessionStorage, {
+    isOnline: false,
+  });
+
+  let decoratedOptions: ValidRequestOptionsImport;
+  switch (options.type) {
+    case RequestType.Admin:
+      decoratedOptions = {
+        store: TEST_SHOP_NAME,
+        apiKey: API_KEY,
+        apiSecretKey: API_SECRET_KEY,
+        ...options,
+      };
+      break;
+    case RequestType.Bearer:
+      decoratedOptions = {
+        store: TEST_SHOP_NAME,
+        apiKey: API_KEY,
+        apiSecretKey: API_SECRET_KEY,
+        ...options,
+      };
+      break;
+    case RequestType.Extension:
+      decoratedOptions = {
+        store: TEST_SHOP_NAME,
+        apiSecretKey: API_SECRET_KEY,
+        ...options,
+      };
+      break;
+    case RequestType.Public:
+      decoratedOptions = {
+        store: TEST_SHOP_NAME,
+        apiSecretKey: API_SECRET_KEY,
+        ...options,
+        type: options.type,
+      };
+      break;
+  }
+
+  const url = new URL(APP_URL);
+  const request: Request = await setUpValidRequestImport(
+    decoratedOptions,
+    new Request(url),
+  );
+
+  return {shopify, session, request};
+}
+
+export {RequestType};

package/src/server/__test-helpers/setup-valid-session.ts

@@ -0,0 +1,28 @@
+import {SessionStorage} from '@shopify/shopify-app-session-storage';
+import {Session} from '@shopify/shopify-api';
+import {setUpValidSession as setUpValidSessionImport} from '@shopify/shopify-api/test-helpers';
+
+import {TEST_SHOP} from './const';
+
+export async function setUpValidSession(
+  sessionStorage: SessionStorage,
+  sessionParams?: Partial<Session>,
+): Promise<Session> {
+  const session = setUpValidSessionImport({
+    shop: TEST_SHOP,
+    ...sessionParams,
+  });
+
+  await sessionStorage.storeSession(session);
+
+  return session;
+}
+
+export function setupValidCustomAppSession(shop: string): Session {
+  return new Session({
+    id: '',
+    shop,
+    state: '',
+    isOnline: false,
+  });
+}

package/src/server/__test-helpers/sign-request-cookie.ts

@@ -0,0 +1,21 @@
+import {getHmac} from './get-hmac';
+
+export function signRequestCookie({
+  request,
+  cookieName,
+  cookieValue,
+}: {
+  request: Request;
+  cookieName: string;
+  cookieValue: string;
+}) {
+  const signedCookieValue = getHmac(cookieValue);
+
+  request.headers.set(
+    'Cookie',
+    [
+      `${cookieName}=${cookieValue}`,
+      `${cookieName}.sig=${signedCookieValue}`,
+    ].join(';'),
+  );
+}

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

@@ -0,0 +1,56 @@
+import {ApiVersion} from '@shopify/shopify-api';
+import {MemorySessionStorage} from '@shopify/shopify-app-session-storage-memory';
+
+import type {FutureFlagOptions, FutureFlags} from '../future/flags';
+import type {TestOverridesArg} from '../test-helpers/test-config';
+import {testConfig as testConfigImport} from '../test-helpers/test-config';
+
+/*
+ * This object mandates that all existing future flags be activated for tests. If a new flag is added, this object must
+ * be updated to include it, which will also cause all tests to use the new behaviour by default (and likely fail).
+ *
+ * This way, we'll always ensure our tests are covering all future flags. Please make sure to also have tests for the
+ * old behaviour.
+ */
+const TEST_FUTURE_FLAGS: Required<{[key in keyof FutureFlags]: true}> = {
+  unstable_newEmbeddedAuthStrategy: true,
+  expiringOfflineAccessTokens: true,
+} as const;
+
+// Override the helper's future flags and logger settings for our purposes
+const TEST_CONFIG = {
+  apiVersion: ApiVersion.July25,
+  isEmbeddedApp: true,
+  future: TEST_FUTURE_FLAGS,
+  logger: {
+    log: jest.fn(),
+  },
+};
+
+// Reset the config object before each test
+beforeEach(() => {
+  TEST_CONFIG.logger.log.mockReset();
+  (TEST_CONFIG as any).sessionStorage = new MemorySessionStorage();
+});
+
+export function testConfig<
+  Overrides extends TestOverridesArg,
+  Future extends FutureFlagOptions,
+>(
+  {future, ...overrides}: Overrides & {future?: Future} = {} as Overrides & {
+    future?: Future;
+  },
+) {
+  return testConfigImport({
+    ...TEST_CONFIG,
+    ...overrides,
+    future: {
+      ...TEST_CONFIG.future,
+      ...future,
+    },
+    logger: {
+      ...TEST_CONFIG.logger,
+      ...(overrides as NonNullable<Overrides>).logger,
+    },
+  });
+}

package/src/server/adapters/node/index.ts

@@ -0,0 +1,13 @@
+import {setAbstractRuntimeString} from '@shopify/shopify-api/runtime';
+
+import {setAppBridgeUrlOverride} from '../../authenticate/helpers';
+
+setAbstractRuntimeString(() => {
+  return `Remix (Node)`;
+});
+
+/* eslint-disable no-process-env */
+if (process.env.APP_BRIDGE_URL) {
+  setAppBridgeUrlOverride(process.env.APP_BRIDGE_URL);
+}
+/* eslint-enable no-process-env */

package/src/server/adapters/vercel/index.ts

@@ -0,0 +1,13 @@
+import {setAbstractFetchFunc} from '@shopify/shopify-api/runtime';
+import {installGlobals} from '@remix-run/node';
+
+import '../node';
+
+installGlobals();
+
+const fetchFunc = fetch;
+setAbstractFetchFunc(async (...args) => {
+  const response = await fetchFunc(...args);
+
+  return response as any;
+});

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

@@ -0,0 +1,34 @@
+import {type ActionFunctionArgs, json} from '@remix-run/node';
+import {GraphqlQueryError} from '@shopify/shopify-api';
+
+import {authenticate} from '../shopify.server';
+
+export const action = async ({request}: ActionFunctionArgs) => {
+  const {admin, redirect} = await authenticate.admin(request);
+
+  try {
+    await admin.graphql(
+      `#graphql
+      mutation updateProductTitle($input: ProductInput!) {
+        productUpdate(input: $input) {
+          product {
+            id
+          }
+        }
+      }`,
+      {
+        variables: {
+          input: {id: '123', title: 'New title'},
+        },
+      },
+    );
+
+    return redirect('/app/product-updated');
+  } catch (error) {
+    if (error instanceof GraphqlQueryError) {
+      return json({errors: error.body?.errors}, {status: 500});
+    }
+
+    return new Response('Failed to update product title', {status: 500});
+  }
+};

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

@@ -0,0 +1,51 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Admin',
+  description:
+    'Contains methods for authenticating and interacting with the Admin API.\n\nThis function can handle requests for apps embedded in the Admin, Admin extensions, or non-embedded apps.',
+  category: 'Authenticate',
+  type: 'object',
+  isVisualComponent: false,
+  definitions: [
+    {
+      title: 'authenticate.admin',
+      description:
+        'Authenticates requests coming from the Shopify admin.\n\nThe shape of the returned object changes depending on the `isEmbeddedApp` config.',
+      type: 'AuthenticateAdmin',
+    },
+  ],
+  defaultExample: {
+    description: 'Authenticate, run API mutation, and redirect',
+    codeblock: {
+      title: 'Authenticate, run API mutation, and redirect',
+      tabs: [
+        {
+          title: '/app/routes/**.ts',
+          language: 'typescript',
+          code: './authenticate.admin.doc.example.ts',
+        },
+      ],
+    },
+  },
+  jsDocTypeExamples: [
+    'EmbeddedAdminContext',
+    'AdminApiContext',
+    'BillingContext',
+    'ScopesApiContext',
+  ],
+  related: [
+    {
+      name: 'API context',
+      subtitle: 'Interact with the Admin API.',
+      url: '/docs/api/shopify-app-remix/apis/admin-api',
+    },
+    {
+      name: 'Billing context',
+      subtitle: 'Bill merchants for your app using the Admin API.',
+      url: '/docs/api/shopify-app-remix/apis/billing',
+    },
+  ],
+};
+
+export default data;

package/src/server/authenticate/admin/authenticate.ts

@@ -0,0 +1,232 @@
+import {JwtPayload, Session} from '@shopify/shopify-api';
+
+import type {BasicParams} from '../../types';
+import type {AppConfigArg} from '../../config-types';
+import {
+  getSessionTokenHeader,
+  ensureCORSHeadersFactory,
+  getSessionTokenFromUrlParam,
+  respondToBotRequest,
+  respondToOptionsRequest,
+  validateSessionToken,
+  getShopFromRequest,
+} from '../helpers';
+
+import {
+  cancelBillingFactory,
+  requestBillingFactory,
+  requireBillingFactory,
+  checkBillingFactory,
+  createUsageRecordFactory,
+  updateUsageCappedAmountFactory,
+} from './billing';
+import type {
+  AdminContext,
+  AuthenticateAdmin,
+  EmbeddedAdminContext,
+  NonEmbeddedAdminContext,
+} from './types';
+import {
+  createAdminApiContext,
+  ensureAppIsEmbeddedIfRequired,
+  ensureSessionTokenSearchParamIfRequired,
+  redirectFactory,
+  renderAppBridge,
+  validateShopAndHostParams,
+} from './helpers';
+import {AuthorizationStrategy} from './strategies/types';
+import {scopesApiFactory} from './scope/factory';
+
+export interface SessionTokenContext {
+  shop: string;
+  sessionId?: string;
+  sessionToken?: string;
+  payload?: JwtPayload;
+}
+
+interface AuthStrategyParams extends BasicParams {
+  strategy: AuthorizationStrategy;
+}
+
+export function authStrategyFactory<ConfigArg extends AppConfigArg>({
+  strategy,
+  ...params
+}: AuthStrategyParams): AuthenticateAdmin<ConfigArg> {
+  const {api, logger, config} = params;
+
+  async function respondToBouncePageRequest(request: Request) {
+    const url = new URL(request.url);
+
+    if (url.pathname === config.auth.patchSessionTokenPath) {
+      logger.debug('Rendering bounce page', {
+        shop: getShopFromRequest(request),
+      });
+      throw renderAppBridge({config, logger, api}, request);
+    }
+  }
+
+  async function respondToExitIframeRequest(request: Request) {
+    const url = new URL(request.url);
+
+    if (url.pathname === config.auth.exitIframePath) {
+      const destination = url.searchParams.get('exitIframe')!;
+
+      logger.debug('Rendering exit iframe page', {
+        shop: getShopFromRequest(request),
+        destination,
+      });
+      throw renderAppBridge({config, logger, api}, request, {url: destination});
+    }
+  }
+
+  type AdminContextBase =
+    | EmbeddedAdminContext<ConfigArg>
+    | NonEmbeddedAdminContext<ConfigArg>;
+
+  function createContext(
+    request: Request,
+    session: Session,
+    authStrategy: AuthorizationStrategy,
+    sessionToken?: JwtPayload,
+  ): AdminContext<ConfigArg> {
+    let context: AdminContextBase = {
+      admin: createAdminApiContext(
+        session,
+        params,
+        authStrategy.handleClientError(request),
+      ),
+      billing: {
+        require: requireBillingFactory(params, request, session),
+        check: checkBillingFactory(params, request, session),
+        request: requestBillingFactory(params, request, session),
+        cancel: cancelBillingFactory(params, request, session),
+        createUsageRecord: createUsageRecordFactory(params, request, session),
+        updateUsageCappedAmount: updateUsageCappedAmountFactory(
+          params,
+          request,
+          session,
+        ),
+      },
+
+      session,
+      cors: ensureCORSHeadersFactory(params, request),
+    };
+
+    context = addEmbeddedFeatures(context, request, session, sessionToken);
+    context = addScopesFeatures(context);
+
+    return context as AdminContext<ConfigArg>;
+  }
+
+  function addEmbeddedFeatures(
+    context: AdminContextBase,
+    request: Request,
+    session: Session,
+    sessionToken?: JwtPayload,
+  ) {
+    if (config.isEmbeddedApp) {
+      return {
+        ...context,
+        sessionToken,
+        redirect: redirectFactory(params, request, session.shop),
+      };
+    }
+    return context;
+  }
+
+  function addScopesFeatures(context: AdminContextBase) {
+    return {
+      ...context,
+      scopes: scopesApiFactory(params, context.session, context.admin),
+    };
+  }
+
+  return async function authenticateAdmin(request: Request) {
+    try {
+      respondToBotRequest(params, request);
+      respondToOptionsRequest(params, request);
+      await respondToBouncePageRequest(request);
+      await respondToExitIframeRequest(request);
+      await strategy.respondToOAuthRequests(request);
+
+      // If this is a valid request, but it doesn't have a session token header, this is a document request. We need to
+      // ensure we're embedded if needed and we have the information needed to load the session.
+      if (!getSessionTokenHeader(request)) {
+        validateShopAndHostParams(params, request);
+        await ensureAppIsEmbeddedIfRequired(params, request);
+        await ensureSessionTokenSearchParamIfRequired(params, request);
+      }
+
+      logger.info('Authenticating admin request', {
+        shop: getShopFromRequest(request),
+      });
+
+      const {payload, shop, sessionId, sessionToken} =
+        await getSessionTokenContext(params, request);
+
+      logger.debug('Loading session from storage', {shop, sessionId});
+      const existingSession = sessionId
+        ? await config.sessionStorage!.loadSession(sessionId)
+        : undefined;
+
+      const session = await strategy.authenticate(request, {
+        session: existingSession,
+        sessionToken,
+        shop,
+      });
+
+      return createContext(request, session, strategy, payload);
+    } catch (errorOrResponse) {
+      if (errorOrResponse instanceof Response) {
+        logger.debug('Authenticate returned a response', {
+          shop: getShopFromRequest(request),
+        });
+        ensureCORSHeadersFactory(params, request)(errorOrResponse);
+      }
+
+      throw errorOrResponse;
+    }
+  };
+}
+
+async function getSessionTokenContext(
+  params: BasicParams,
+  request: Request,
+): Promise<SessionTokenContext> {
+  const {api, config, logger} = params;
+
+  const headerSessionToken = getSessionTokenHeader(request);
+  const searchParamSessionToken = getSessionTokenFromUrlParam(request);
+  const sessionToken = (headerSessionToken || searchParamSessionToken)!;
+
+  logger.debug('Attempting to authenticate session token', {
+    shop: getShopFromRequest(request),
+    sessionToken: JSON.stringify({
+      header: headerSessionToken,
+      search: searchParamSessionToken,
+    }),
+  });
+
+  if (config.isEmbeddedApp) {
+    const payload = await validateSessionToken(params, request, sessionToken);
+    const dest = new URL(payload.dest);
+    const shop = dest.hostname;
+
+    logger.debug('Session token is valid - authenticated', {shop, payload});
+    const sessionId = config.useOnlineTokens
+      ? api.session.getJwtSessionId(shop, payload.sub)
+      : api.session.getOfflineId(shop);
+
+    return {shop, payload, sessionId, sessionToken};
+  }
+
+  const url = new URL(request.url);
+  const shop = url.searchParams.get('shop')!;
+
+  const sessionId = await api.session.getCurrentId({
+    isOnline: config.useOnlineTokens,
+    rawRequest: request,
+  });
+
+  return {shop, sessionId, payload: undefined, sessionToken};
+}

package/src/server/authenticate/admin/billing/authenticate.admin.billing.doc.ts

@@ -0,0 +1,29 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Billing',
+  description:
+    'Contains function used to bill merchants for your app with the Billing API.\n\nThis object is returned on authenticated Admin requests.' +
+    '\n\n> Note: [Managed App Pricing](/docs/apps/launch/billing/managed-pricing) is now available. Define your app’s pricing plans directly in the Shopify Partner Dashboard, without needing to use the Billing API.',
+  category: 'APIs',
+  type: 'object',
+  isVisualComponent: false,
+  definitions: [
+    {
+      title: 'billing',
+      description:
+        'Provides utilities that apps can use to request billing for the app using the Admin API.',
+      type: 'BillingContext',
+    },
+  ],
+  jsDocTypeExamples: ['BillingContext'],
+  related: [
+    {
+      name: 'Admin context',
+      subtitle: 'Authenticate requests from Shopify Admin.',
+      url: '/docs/api/shopify-app-remix/authenticate/admin',
+    },
+  ],
+};
+
+export default data;

package/src/server/authenticate/admin/billing/cancel.ts

@@ -0,0 +1,38 @@
+import {HttpResponseError, Session} from '@shopify/shopify-api';
+
+import type {BasicParams} from '../../../types';
+import {redirectToAuthPage} from '../helpers';
+import {invalidateAccessToken} from '../../helpers';
+
+import type {CancelBillingOptions} from './types';
+
+export function cancelBillingFactory(
+  params: BasicParams,
+  request: Request,
+  session: Session,
+) {
+  return async function cancelBilling(options: CancelBillingOptions) {
+    const {api, logger} = params;
+
+    logger.debug('Cancelling billing', {shop: session.shop, ...options});
+
+    try {
+      return await api.billing.cancel({
+        session,
+        subscriptionId: options.subscriptionId,
+        isTest: options.isTest,
+        prorate: options.prorate,
+      });
+    } catch (error) {
+      if (error instanceof HttpResponseError && error.response.code === 401) {
+        logger.debug('API token was invalid, redirecting to OAuth', {
+          shop: session.shop,
+        });
+        await invalidateAccessToken(params, session);
+        throw await redirectToAuthPage(params, request, session.shop);
+      } else {
+        throw error;
+      }
+    }
+  };
+}