shopify-app-js 0.0.1-security → 1.0.1

package/packages/shopify-app-remix/src/server/authenticate/admin/billing/cancel.ts

@@ -0,0 +1,37 @@
+import {HttpResponseError, Session} from '@shopify/shopify-api';
+
+import type {BasicParams} from '../../../types';
+import {redirectToAuthPage} 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, config} = 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 config.sessionStorage.deleteSession(session.id);
+        throw await redirectToAuthPage(params, request, session.shop);
+      } else {
+        throw error;
+      }
+    }
+  };
+}

package/packages/shopify-app-remix/src/server/authenticate/admin/billing/check.ts

@@ -0,0 +1,38 @@
+import {HttpResponseError, Session} from '@shopify/shopify-api';
+
+import type {BasicParams} from '../../../types';
+import {redirectToAuthPage} from '../helpers';
+import type {AppConfigArg} from '../../../config-types';
+
+import type {CheckBillingOptions} from './types';
+
+export function checkBillingFactory<Config extends AppConfigArg>(
+  params: BasicParams,
+  request: Request,
+  session: Session,
+) {
+  return async function checkBilling(options: CheckBillingOptions<Config>) {
+    const {api, logger, config} = params;
+
+    logger.debug('Checking billing plans', {shop: session.shop, ...options});
+
+    try {
+      return await api.billing.check({
+        session,
+        plans: options.plans as string[],
+        isTest: options.isTest,
+        returnObject: true,
+      });
+    } catch (error) {
+      if (error instanceof HttpResponseError && error.response.code === 401) {
+        logger.debug('API token was invalid, redirecting to OAuth', {
+          shop: session.shop,
+        });
+        await config.sessionStorage.deleteSession(session.id);
+        throw await redirectToAuthPage(params, request, session.shop);
+      } else {
+        throw error;
+      }
+    }
+  };
+}

package/packages/shopify-app-remix/src/server/authenticate/admin/billing/index.ts

@@ -0,0 +1,4 @@
+export {cancelBillingFactory} from './cancel';
+export {requireBillingFactory} from './require';
+export {requestBillingFactory} from './request';
+export {checkBillingFactory} from './check';

package/packages/shopify-app-remix/src/server/authenticate/admin/billing/request.ts

@@ -0,0 +1,101 @@
+import {
+  BillingRequestResponseObject,
+  HttpResponseError,
+  Session,
+} from '@shopify/shopify-api';
+import {redirect} from '@remix-run/server-runtime';
+
+import {AppConfigArg} from '../../../config-types';
+import {BasicParams} from '../../../types';
+import {getAppBridgeHeaders, redirectToAuthPage} from '../helpers';
+
+import type {RequestBillingOptions} from './types';
+
+export function requestBillingFactory<Config extends AppConfigArg>(
+  params: BasicParams,
+  request: Request,
+  session: Session,
+) {
+  return async function requestBilling({
+    plan,
+    isTest,
+    returnUrl,
+    ...overrides
+  }: RequestBillingOptions<Config>): Promise<never> {
+    const {api, logger, config} = params;
+
+    logger.info('Requesting billing', {
+      shop: session.shop,
+      plan,
+      isTest,
+      returnUrl,
+    });
+
+    let result: BillingRequestResponseObject;
+    try {
+      result = await api.billing.request({
+        plan: plan as string,
+        session,
+        isTest,
+        returnUrl,
+        returnObject: true,
+        ...overrides,
+      });
+    } catch (error) {
+      if (error instanceof HttpResponseError && error.response.code === 401) {
+        logger.debug('API token was invalid, redirecting to OAuth', {
+          shop: session.shop,
+        });
+        await config.sessionStorage.deleteSession(session.id);
+        throw await redirectToAuthPage(params, request, session.shop);
+      } else {
+        throw error;
+      }
+    }
+
+    throw redirectOutOfApp(
+      params,
+      request,
+      result.confirmationUrl,
+      session.shop,
+    );
+  };
+}
+
+function redirectOutOfApp(
+  params: BasicParams,
+  request: Request,
+  url: string,
+  shop: string,
+): never {
+  const {config, logger} = params;
+
+  logger.debug('Redirecting out of app', {url});
+
+  const requestUrl = new URL(request.url);
+  const isEmbeddedRequest = requestUrl.searchParams.get('embedded') === '1';
+  const isXhrRequest = request.headers.get('authorization');
+
+  if (isXhrRequest) {
+    // eslint-disable-next-line no-warning-comments
+    // TODO Check this with the beta flag disabled (with the bounce page)
+    // Remix is not including the X-Shopify-API-Request-Failure-Reauthorize-Url when throwing a Response
+    // https://github.com/remix-run/remix/issues/5356
+    throw new Response(undefined, {
+      status: 401,
+      statusText: 'Unauthorized',
+      headers: getAppBridgeHeaders(url),
+    });
+  } else if (isEmbeddedRequest) {
+    const params = new URLSearchParams({
+      shop,
+      host: requestUrl.searchParams.get('host')!,
+      exitIframe: url,
+    });
+
+    throw redirect(`${config.auth.exitIframePath}?${params.toString()}`);
+  } else {
+    // This will only ever happen for non-embedded apps, because the authenticator will stop before reaching this point
+    throw redirect(url);
+  }
+}

package/packages/shopify-app-remix/src/server/authenticate/admin/billing/require.ts

@@ -0,0 +1,56 @@
+import {
+  BillingCheckResponseObject,
+  HttpResponseError,
+  Session,
+} from '@shopify/shopify-api';
+
+import type {BasicParams} from '../../../types';
+import type {AppConfigArg} from '../../../config-types';
+import {redirectToAuthPage} from '../helpers';
+
+import type {RequireBillingOptions} from './types';
+
+export function requireBillingFactory<Config extends AppConfigArg>(
+  params: BasicParams,
+  request: Request,
+  session: Session,
+) {
+  const {api, logger, config} = params;
+
+  return async function requireBilling(options: RequireBillingOptions<Config>) {
+    const logContext = {
+      shop: session.shop,
+      plans: options.plans,
+      isTest: options.isTest,
+    };
+
+    logger.debug('Checking billing for the shop', logContext);
+
+    let data: BillingCheckResponseObject;
+    try {
+      data = await api.billing.check({
+        session,
+        plans: options.plans as string[],
+        isTest: options.isTest,
+        returnObject: true,
+      });
+    } catch (error) {
+      if (error instanceof HttpResponseError && error.response.code === 401) {
+        logger.debug('API token was invalid, redirecting to OAuth', logContext);
+        await config.sessionStorage.deleteSession(session.id);
+        throw await redirectToAuthPage(params, request, session.shop);
+      } else {
+        throw error;
+      }
+    }
+
+    if (!data.hasActivePayment) {
+      logger.debug('Billing check failed', logContext);
+      throw await options.onFailure(new Error('Billing check failed'));
+    }
+
+    logger.debug('Billing check succeeded', logContext);
+
+    return data;
+  };
+}

package/packages/shopify-app-remix/src/server/authenticate/admin/billing/types.ts

@@ -0,0 +1,383 @@
+import {
+  AppSubscription,
+  BillingCheckParams,
+  BillingCheckResponseObject,
+  BillingRequestParams,
+} from '@shopify/shopify-api';
+
+import type {AppConfigArg} from '../../../config-types';
+
+export interface RequireBillingOptions<Config extends AppConfigArg>
+  extends Omit<BillingCheckParams, 'session' | 'plans' | 'returnObject'> {
+  /**
+   * The plans to check for. Must be one of the values defined in the `billing` config option.
+   */
+  plans: (keyof Config['billing'])[];
+  /**
+   * How to handle the request if the shop doesn't have an active payment for any plan.
+   */
+  onFailure: (error: any) => Promise<Response>;
+}
+
+export interface CheckBillingOptions<Config extends AppConfigArg>
+  extends Omit<BillingCheckParams, 'session' | 'plans' | 'returnObject'> {
+  /**
+   * The plans to check for. Must be one of the values defined in the `billing` config option.
+   */
+  plans: (keyof Config['billing'])[];
+}
+
+export interface RequestBillingOptions<Config extends AppConfigArg>
+  extends Omit<BillingRequestParams, 'session' | 'plan' | 'returnObject'> {
+  /**
+   * The plan to request. Must be one of the values defined in the `billing` config option.
+   */
+  plan: keyof Config['billing'];
+  /**
+   * Whether to use the test mode. This prevents the credit card from being charged. Test shops and demo shops cannot be charged.
+   */
+  isTest?: boolean;
+  /**
+   * The URL to return to after the merchant approves the payment.
+   */
+  returnUrl?: string;
+}
+
+export interface CancelBillingOptions {
+  /**
+   * The ID of the subscription to cancel.
+   */
+  subscriptionId: string;
+  /**
+   * Whether to prorate the cancellation.
+   *
+   * {@link https://shopify.dev/docs/apps/billing/subscriptions/cancel-recurring-charges}
+   */
+  prorate?: boolean;
+  /*
+   * Whether to use the test mode. This prevents the credit card from being charged. Test shops and demo shops cannot be charged.
+   */
+  isTest?: boolean;
+}
+
+export interface BillingContext<Config extends AppConfigArg> {
+  /**
+   * Checks if the shop has an active payment for any plan defined in the `billing` config option.
+   *
+   * @returns A promise that resolves to an object containing the active purchases for the shop.
+   *
+   * @example
+   * <caption>Requesting billing right away.</caption>
+   * <description>Call `billing.request` in the `onFailure` callback to immediately redirect to the Shopify page to request payment.</description>
+   * ```ts
+   * // /app/routes/**\/*.ts
+   * import { LoaderFunctionArgs } from "@remix-run/node";
+   * import { authenticate, MONTHLY_PLAN } from "../shopify.server";
+   *
+   * export const loader = async ({ request }: LoaderFunctionArgs) => {
+   *   const { billing } = await authenticate.admin(request);
+   *   await billing.require({
+   *     plans: [MONTHLY_PLAN],
+   *     isTest: true,
+   *     onFailure: async () => billing.request({ plan: MONTHLY_PLAN }),
+   *   });
+   *
+   *   // App logic
+   * };
+   * ```
+   * ```ts
+   * // shopify.server.ts
+   * import { shopifyApp, BillingInterval } from "@shopify/shopify-app-remix/server";
+   *
+   * export const MONTHLY_PLAN = 'Monthly subscription';
+   * export const ANNUAL_PLAN = 'Annual subscription';
+   *
+   * const shopify = shopifyApp({
+   *   // ...etc
+   *   billing: {
+   *     [MONTHLY_PLAN]: {
+   *       amount: 5,
+   *       currencyCode: 'USD',
+   *       interval: BillingInterval.Every30Days,
+   *     },
+   *     [ANNUAL_PLAN]: {
+   *       amount: 50,
+   *       currencyCode: 'USD',
+   *       interval: BillingInterval.Annual,
+   *     },
+   *   }
+   * });
+   * export default shopify;
+   * export const authenticate = shopify.authenticate;
+   * ```
+   *
+   * @example
+   * <caption>Redirect to a plan selection page.</caption>
+   * <description> When the app has multiple plans, create a page in your App that allows the merchant to select a plan. If a merchant does not have the required plan you can redirect them to page in your app to select one.</description>
+   * ```ts
+   * // /app/routes/**\/*.ts
+   * import { LoaderFunctionArgs, redirect } from "@remix-run/node";
+   * import { authenticate, MONTHLY_PLAN, ANNUAL_PLAN } from "../shopify.server";
+   *
+   * export const loader = async ({ request }: LoaderFunctionArgs) => {
+   *   const { billing } = await authenticate.admin(request);
+   *   const billingCheck = await billing.require({
+   *     plans: [MONTHLY_PLAN, ANNUAL_PLAN],
+   *     isTest: true,
+   *     onFailure: () => redirect('/select-plan'),
+   *   });
+   *
+   *   const subscription = billingCheck.appSubscriptions[0];
+   *   console.log(`Shop is on ${subscription.name} (id ${subscription.id})`);
+   *
+   *   // App logic
+   * };
+   * ```
+   * ```ts
+   * // shopify.server.ts
+   * import { shopifyApp, BillingInterval } from "@shopify/shopify-app-remix/server";
+   *
+   * export const MONTHLY_PLAN = 'Monthly subscription';
+   * export const ANNUAL_PLAN = 'Annual subscription';
+   *
+   * const shopify = shopifyApp({
+   *   // ...etc
+   *   billing: {
+   *     [MONTHLY_PLAN]: {
+   *       amount: 5,
+   *       currencyCode: 'USD',
+   *       interval: BillingInterval.Every30Days,
+   *     },
+   *     [ANNUAL_PLAN]: {
+   *       amount: 50,
+   *       currencyCode: 'USD',
+   *       interval: BillingInterval.Annual,
+   *     },
+   *   }
+   * });
+   * export default shopify;
+   * export const authenticate = shopify.authenticate;
+   * ```
+   * @example
+   * <caption>Requesting billing with line items</caption>
+   * <description>Call `billing.request` with the `v3_lineItemBilling` future flag enabled</description>
+   * ```ts
+   * // /app/routes/**\/*.ts
+   * import { LoaderFunctionArgs } from "@remix-run/node";
+   * import { authenticate, MONTHLY_PLAN } from "../shopify.server";
+   *
+   * export const loader = async ({ request }: LoaderFunctionArgs) => {
+   *   const { billing } = await authenticate.admin(request);
+   *   await billing.require({
+   *     plans: [MONTHLY_PLAN],
+   *     isTest: true,
+   *     onFailure: async () => billing.request({ plan: MONTHLY_PLAN }),
+   *   });
+   *
+   *   // App logic
+   * };
+   * ```
+   * ```ts
+   * // shopify.server.ts
+   * import { shopifyApp, BillingInterval } from "@shopify/shopify-app-remix/server";
+   *
+   * export const MONTHLY_PLAN = 'Monthly subscription';
+   * export const ANNUAL_PLAN = 'Annual subscription';
+   *
+   * const shopify = shopifyApp({
+   *   // ...etc
+   *   billing: {
+   *     [MONTHLY_PLAN]: {
+   *       lineItems: [
+   *        {
+   *          amount: 5,
+   *          currencyCode: 'USD',
+   *          interval: BillingInterval.Every30Days,
+   *         },
+   *         {
+   *          amount: 1,
+   *          currencyCode: 'USD',
+   *          interval: BillingInterval.Usage.
+   *          terms: '1 dollar per 1000 emails',
+   *         },
+   *       ],
+   *     },
+   *   }
+   *  future: {v3_lineItemBilling: true}
+   * });
+   * export default shopify;
+   * export const authenticate = shopify.authenticate;
+   * ```
+   */
+  require: (
+    options: RequireBillingOptions<Config>,
+  ) => Promise<BillingCheckResponseObject>;
+
+  /**
+   * Checks if the shop has an active payment for any plan defined in the `billing` config option.
+   *
+   * @returns A promise that resolves to an object containing the active purchases for the shop.
+   *
+   * @example
+   * <caption>Check what billing plans a merchant is subscribed to.</caption>
+   * <description>Use billing.check if you want to determine which plans are in use. Unlike `require`, `check` does not
+   * throw an error if no active billing plans are present. </description>
+   * ```ts
+   * // /app/routes/**\/*.ts
+   * import { LoaderFunctionArgs } from "@remix-run/node";
+   * import { authenticate, MONTHLY_PLAN } from "../shopify.server";
+   *
+   * export const loader = async ({ request }: LoaderFunctionArgs) => {
+   *   const { billing } = await authenticate.admin(request);
+   *   const { hasActivePayment, appSubscriptions } = await billing.check({
+   *     plans: [MONTHLY_PLAN],
+   *     isTest: false,
+   *   });
+   *  console.log(hasActivePayment)
+   *  console.log(appSubscriptions)
+   * };
+   * ```
+   * ```ts
+   * // shopify.server.ts
+   * import { shopifyApp, BillingInterval } from "@shopify/shopify-app-remix/server";
+   *
+   * export const MONTHLY_PLAN = 'Monthly subscription';
+   * export const ANNUAL_PLAN = 'Annual subscription';
+   *
+   * const shopify = shopifyApp({
+   *   // ...etc
+   *   billing: {
+   *     [MONTHLY_PLAN]: {
+   *       amount: 5,
+   *       currencyCode: 'USD',
+   *       interval: BillingInterval.Every30Days,
+   *     },
+   *     [ANNUAL_PLAN]: {
+   *       amount: 50,
+   *       currencyCode: 'USD',
+   *       interval: BillingInterval.Annual,
+   *     },
+   *   }
+   * });
+   * export default shopify;
+   * export const authenticate = shopify.authenticate;
+   * ```
+   *
+   */
+  check: (
+    options: CheckBillingOptions<Config>,
+  ) => Promise<BillingCheckResponseObject>;
+
+  /**
+   * Requests payment for the plan.
+   *
+   * @returns Redirects to the confirmation URL for the payment.
+   *
+   * @example
+   * <caption>Using a custom return URL.</caption>
+   * <description>Change where the merchant is returned to after approving the purchase using the `returnUrl` option.</description>
+   * ```ts
+   * // /app/routes/**\/*.ts
+   * import { LoaderFunctionArgs } from "@remix-run/node";
+   * import { authenticate, MONTHLY_PLAN } from "../shopify.server";
+   *
+   * export const loader = async ({ request }: LoaderFunctionArgs) => {
+   *   const { billing } = await authenticate.admin(request);
+   *   await billing.require({
+   *     plans: [MONTHLY_PLAN],
+   *     onFailure: async () => billing.request({
+   *       plan: MONTHLY_PLAN,
+   *       isTest: true,
+   *       returnUrl: 'https://admin.shopify.com/store/my-store/apps/my-app/billing-page',
+   *     }),
+   *   });
+   *
+   *   // App logic
+   * };
+   * ```
+   * ```ts
+   * // shopify.server.ts
+   * import { shopifyApp, BillingInterval } from "@shopify/shopify-app-remix/server";
+   *
+   * export const MONTHLY_PLAN = 'Monthly subscription';
+   * export const ANNUAL_PLAN = 'Annual subscription';
+   *
+   * const shopify = shopifyApp({
+   *   // ...etc
+   *   billing: {
+   *     [MONTHLY_PLAN]: {
+   *       amount: 5,
+   *       currencyCode: 'USD',
+   *       interval: BillingInterval.Every30Days,
+   *     },
+   *     [ANNUAL_PLAN]: {
+   *       amount: 50,
+   *       currencyCode: 'USD',
+   *       interval: BillingInterval.Annual,
+   *     },
+   *   }
+   * });
+   * export default shopify;
+   * export const authenticate = shopify.authenticate;
+   * ```
+   */
+  request: (options: RequestBillingOptions<Config>) => Promise<never>;
+
+  /**
+   * Cancels an ongoing subscription, given its ID.
+   *
+   * @returns The cancelled subscription.
+   *
+   * @example
+   * <caption>Cancelling a subscription.</caption>
+   * <description>Use the `billing.cancel` function to cancel an active subscription with the id returned from `billing.require`.</description>
+   * ```ts
+   * // /app/routes/cancel-subscription.ts
+   * import { LoaderFunctionArgs } from "@remix-run/node";
+   * import { authenticate, MONTHLY_PLAN } from "../shopify.server";
+   *
+   * export const loader = async ({ request }: LoaderFunctionArgs) => {
+   *   const { billing } = await authenticate.admin(request);
+   *   const billingCheck = await billing.require({
+   *     plans: [MONTHLY_PLAN],
+   *     onFailure: async () => billing.request({ plan: MONTHLY_PLAN }),
+   *   });
+   *
+   *   const subscription = billingCheck.appSubscriptions[0];
+   *   const cancelledSubscription = await billing.cancel({
+   *     subscriptionId: subscription.id,
+   *     isTest: true,
+   *     prorate: true,
+   *    });
+   *
+   *   // App logic
+   * };
+   * ```
+   * ```ts
+   * // shopify.server.ts
+   * import { shopifyApp, BillingInterval } from "@shopify/shopify-app-remix/server";
+   *
+   * export const MONTHLY_PLAN = 'Monthly subscription';
+   * export const ANNUAL_PLAN = 'Annual subscription';
+   *
+   * const shopify = shopifyApp({
+   *   // ...etc
+   *   billing: {
+   *     [MONTHLY_PLAN]: {
+   *       amount: 5,
+   *       currencyCode: 'USD',
+   *       interval: BillingInterval.Every30Days,
+   *     },
+   *     [ANNUAL_PLAN]: {
+   *       amount: 50,
+   *       currencyCode: 'USD',
+   *       interval: BillingInterval.Annual,
+   *     },
+   *   }
+   * });
+   * export default shopify;
+   * export const authenticate = shopify.authenticate;
+   * ```
+   */
+  cancel: (options: CancelBillingOptions) => Promise<AppSubscription>;
+}