@shopify/shopify-app-remix 0.0.0-experimental-20231213172144

package/LICENSE.md

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2022-present, Shopify Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,179 @@
+# `@shopify/shopify-app-remix`
+
+<!-- ![Build Status]() -->
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE.md)
+[![npm version](https://badge.fury.io/js/%40shopify%2Fshopify-app-remix.svg)](https://badge.fury.io/js/%40shopify%2Fshopify-app-remix)
+
+This package makes it easy to use [Remix](https://remix.run/) to build Shopify apps.
+It builds on the `@shopify/shopify-api` package and exposes a `shopifyApp` function. You can use `shopifyApp` to configure your app and then authenticate requests from Shopify.
+
+Visit the [`shopify.dev` documentation](https://shopify.dev/docs/api/shopify-app-remix) for more details on the Remix app package.
+
+## Requirements
+
+To use this package, you will need to have:
+
+- a Shopify Partner account and development store
+- an app already set up on your partner account
+- a JavaScript package manager such as [yarn](https://yarnpkg.com) installed
+
+## Getting started
+
+### Shopify CLI
+
+The easiest way to get started with developing Shopify apps is using the [Shopify CLI](https://shopify.dev/docs/apps/tools/cli).
+It helps you set up your environment for developing and publishing your apps and extensions.
+
+We strongly recommend using the CLI to create and manage your Remix apps and extensions!
+Refer to the [getting started documentation](https://shopify.dev/docs/apps/getting-started/create) to create your app using the Shopify CLI.
+
+### Using a plain Remix app
+
+This package works with any Remix app. If you're starting an app from scratch, then you can create a brand new Remix app that uses the indie-stack:
+
+```bash
+npx create-remix@latest --template remix-run/indie-stack
+cd ./name-of-your-app
+```
+
+Now let's install this package:
+
+```bash
+npm install @shopify/shopify-app-remix
+```
+
+Next, you'll need to set up some routes and headers so you can embed your app in the Shopify admin.
+You can find more details on all the steps described here in the [package documentation](https://shopify.dev/docs/api/shopify-app-remix).
+
+Create `app/shopify.server.js`. We will use this file to configure our Shopify app by calling the [`shopifyApp` function](https://shopify.dev/docs/api/shopify-app-remix/latest/entrypoints/shopifyapp):
+
+```ts
+// app/shopify.server.js
+// Note that you don't need to import the node adapter if you're running on a different runtime.
+import '@shopify/shopify-app-remix/server/adapters/node';
+// Memory storage makes it easy to set an app up, but should never be used in production.
+import {MemorySessionStorage} from '@shopify/shopify-app-session-storage-memory';
+
+import {LATEST_API_VERSION, shopifyApp} from '@shopify/shopify-app-remix';
+
+const shopify = shopifyApp({
+  apiKey: process.env.SHOPIFY_API_KEY!,
+  apiSecretKey: process.env.SHOPIFY_API_SECRET!,
+  appUrl: process.env.SHOPIFY_APP_URL!,
+  scopes: ['read_products'],
+  apiVersion: LATEST_API_VERSION,
+  sessionStorage: new MemorySessionStorage(),
+});
+export default shopify;
+```
+
+This will require some environment variables. So let's create an `.env` file:
+
+```env
+SHOPIFY_API_KEY="[Copy from partners dashboard]"
+SHOPIFY_API_SECRET="[Copy from partners dashboard]"
+SHOPIFY_APP_URL="[The tunnel URL you are using to run your app]"
+```
+
+`shopifyApp` needs to reserve a [splat route](https://remix.run/docs/en/main/guides/routing#splats) for auth.
+It should export a loader that uses `shopifyApp` to authenticate:
+
+```ts
+// app/routes/auth/$.tsx
+import {LoaderFunctionArgs} from '@remix-run/node';
+
+import shopify from '~/shopify.server';
+
+export async function loader({request}: LoaderFunctionArgs) {
+  await shopify.authenticate.admin(request);
+
+  return null;
+}
+```
+
+Next, set up the [`AppProvider` component](https://shopify.dev/docs/api/shopify-app-remix/latest/entrypoints/appprovider) in your app's routes. To do this pass the `process.env.SHOPIFY_API_KEY` to the frontend via the loader.
+
+Here is an example:
+
+```ts
+// root.tsx
+import {LoaderFunctionArgs} from '@remix-run/node';
+import {AppProvider} from '@shopify/shopify-app-remix/react';
+
+import shopify from '~/shopify.server';
+
+export async function loader({request}: LoaderFunctionArgs) {
+  await shopify.authenticate.admin(request);
+
+  return json({
+    apiKey: process.env.SHOPIFY_API_KEY,
+  });
+}
+
+export default function App() {
+  const {apiKey} = useLoaderData<typeof loader>();
+
+  return (
+    <html>
+      <head>
+        <Meta />
+        <Links />
+      </head>
+      <body>
+        <AppProvider apiKey={apiKey} isEmbeddedApp>
+          <Outlet />
+        </AppProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+This component will set up [Polaris](https://polaris.shopify.com/components/utilities/app-provider) and [App Bridge](https://shopify.dev/tools/app-bridge). If your app isn't embedded, set the `isEmbeddedApp` prop to `false`.
+
+Now that your app is ready to respond to requests, it will also need to add the required `Content-Security-Policy` header directives, as per [our documentation](https://shopify.dev/docs/apps/store/security/iframe-protection).
+To do that, this package provides the `shopify.addDocumentResponseHeaders` method.
+
+You should return these headers from any endpoint that renders HTML in your app.
+Most likely you'll want to add this to every HTML response by updating the entry.server.tsx file:
+
+```ts
+// entry.server.tsx
+import shopify from './shopify.server';
+
+export default function handleRequest(
+  request: Request,
+  responseStatusCode: number,
+  responseHeaders: Headers,
+  remixContext: EntryContext,
+) {
+  shopify.addDocumentResponseHeaders(request, responseHeaders);
+
+  /// ..etc
+}
+```
+
+### Running your app
+
+To run your app and load it within the Shopify Admin, you need to:
+
+1. Update your app's URL in your Partners Dashboard app setup page to `http://localhost:8080`
+1. Update your app's callback URL to `http://localhost:8080/api/auth/callback` in that same page
+1. Go to **Test your app** in Partners Dashboard and select your development store
+
+## Next steps
+
+Once your app is up and running, you can start using this package to interact with Shopify APIs, webhooks and more.
+
+Here are some guides to help you set up your app:
+
+- [Interacting with Shopify Admin](https://shopify.dev/docs/api/shopify-app-remix/latest/guide-admin)
+- [Subscribing to webhooks](https://shopify.dev/docs/api/shopify-app-remix/latest/guide-webhooks)
+
+You can also authenticate requests from surfaces other than the admin.
+To see all supported methods, see [the `shopify.authenticate` object documentation](https://shopify.dev/docs/api/shopify-app-remix/latest/authenticate).
+
+## Gotchas / Troubleshooting
+
+If you're experiencing unexpected behaviors when using this package, check our [app template's documentation](https://github.com/Shopify/shopify-app-template-remix#gotchas--troubleshooting) for the solution to common issues.

package/build/cjs/react/components/AppProvider/AppProvider.js

@@ -0,0 +1,98 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var polaris = require('@shopify/polaris');
+var englishI18n = require('@shopify/polaris/locales/en.json');
+var _const = require('../../const.js');
+var RemixPolarisLink = require('../RemixPolarisLink.js');
+var jsxRuntime = require('react/jsx-runtime');
+
+function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
+
+var englishI18n__default = /*#__PURE__*/_interopDefaultLegacy(englishI18n);
+
+/**
+ * Sets up the Polaris `AppProvider` and injects the App Bridge script.
+ *
+ * This component extends the [`AppProvider`](https://polaris.shopify.com/components/utilities/app-provider) component
+ * from Polaris, and accepts all of its props except for `linkComponent`, which is overridden to use the Remix `Link`
+ * component.
+ *
+ * {@link https://polaris.shopify.com/components/utilities/app-provider}
+ * {@link https://shopify.dev/tools/app-bridge}
+ *
+ * @example
+ * <caption>Set up AppProvider.</caption>
+ * <description>Wrap your app in the `AppProvider` component and pass in your API key.</description>
+ * ```ts
+ * import {authenticate} from '~/shopify.server';
+ * import {AppProvider} from '@shopify/shopify-app-remix/react';
+ *
+ * export async function loader({ request }) {
+ *   await authenticate.admin(request);
+ *
+ *   return json({ apiKey: process.env.SHOPIFY_API_KEY });
+ * }
+ *
+ * export default function App() {
+ *   const { apiKey } = useLoaderData();
+ *
+ *   return (
+ *     <AppProvider isEmbeddedApp apiKey={apiKey}>
+ *       <Outlet />
+ *     </AppProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * <caption>Localize Polaris components.</caption>
+ * <description>Pass in a different locale for Polaris to translate its components.</description>
+ * ```ts
+ * import {authenticate} from '~/shopify.server';
+ * import {AppProvider} from '@shopify/shopify-app-remix/react';
+ *
+ * export async function loader({ request }) {
+ *   await authenticate.admin(request);
+ *
+ *   return json({
+ *     apiKey: process.env.SHOPIFY_API_KEY,
+ *     polarisTranslations: require("@shopify/polaris/locales/fr.json"),
+ *   });
+ * }
+ *
+ * export default function App() {
+ *   const { apiKey, polarisTranslations } = useLoaderData();
+ *
+ *   return (
+ *     <AppProvider apiKey={apiKey} i18n={polarisTranslations}>
+ *       <Outlet />
+ *     </AppProvider>
+ *   );
+ * }
+ * ```
+ */
+function AppProvider(props) {
+  const {
+    children,
+    apiKey,
+    i18n,
+    isEmbeddedApp = true,
+    __APP_BRIDGE_URL = _const.APP_BRIDGE_URL,
+    ...polarisProps
+  } = props;
+  return /*#__PURE__*/jsxRuntime.jsxs(jsxRuntime.Fragment, {
+    children: [isEmbeddedApp && /*#__PURE__*/jsxRuntime.jsx("script", {
+      src: __APP_BRIDGE_URL,
+      "data-api-key": apiKey
+    }), /*#__PURE__*/jsxRuntime.jsx(polaris.AppProvider, {
+      ...polarisProps,
+      linkComponent: RemixPolarisLink.RemixPolarisLink,
+      i18n: i18n || englishI18n__default["default"],
+      children: children
+    })]
+  });
+}
+
+exports.AppProvider = AppProvider;

package/build/cjs/react/components/RemixPolarisLink.js

@@ -0,0 +1,22 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var React = require('react');
+var react = require('@remix-run/react');
+var jsxRuntime = require('react/jsx-runtime');
+
+function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
+
+var React__default = /*#__PURE__*/_interopDefaultLegacy(React);
+
+const RemixPolarisLink = /*#__PURE__*/React__default["default"].forwardRef((props, ref) => {
+  var _props$url;
+  return /*#__PURE__*/jsxRuntime.jsx(react.Link, {
+    ...props,
+    to: (_props$url = props.url) !== null && _props$url !== void 0 ? _props$url : props.to,
+    ref: ref
+  });
+});
+
+exports.RemixPolarisLink = RemixPolarisLink;

package/build/cjs/react/const.js

@@ -0,0 +1,7 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+const APP_BRIDGE_URL = 'https://cdn.shopify.com/shopifycloud/app-bridge.js';
+
+exports.APP_BRIDGE_URL = APP_BRIDGE_URL;

package/build/cjs/react/index.js

@@ -0,0 +1,9 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var AppProvider = require('./components/AppProvider/AppProvider.js');
+
+
+
+exports.AppProvider = AppProvider.AppProvider;

package/build/cjs/server/adapters/node/index.js

@@ -0,0 +1,22 @@
+'use strict';
+
+var crypto = require('crypto');
+var runtime = require('@shopify/shopify-api/runtime');
+var appBridgeUrl = require('../../authenticate/helpers/app-bridge-url.js');
+require('isbot');
+require('@remix-run/server-runtime');
+
+function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
+
+var crypto__default = /*#__PURE__*/_interopDefaultLegacy(crypto);
+
+runtime.setCrypto(crypto__default["default"]);
+runtime.setAbstractRuntimeString(() => {
+  return `Remix (Node)`;
+});
+
+/* eslint-disable no-process-env */
+if (process.env.APP_BRIDGE_URL) {
+  appBridgeUrl.setAppBridgeUrlOverride(process.env.APP_BRIDGE_URL);
+}
+/* eslint-enable no-process-env */

package/build/cjs/server/authenticate/admin/authenticate.js

@@ -0,0 +1,176 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var ensureCorsHeaders = require('../helpers/ensure-cors-headers.js');
+var validateSessionToken = require('../helpers/validate-session-token.js');
+var getSessionTokenHeader = require('../helpers/get-session-token-header.js');
+var rejectBotRequest = require('../helpers/reject-bot-request.js');
+var respondToOptionsRequest = require('../helpers/respond-to-options-request.js');
+require('@remix-run/server-runtime');
+var cancel = require('./billing/cancel.js');
+var require$1 = require('./billing/require.js');
+var request = require('./billing/request.js');
+var createAdminApiContext = require('./helpers/create-admin-api-context.js');
+var ensureAppIsEmbeddedIfRequired = require('./helpers/ensure-app-is-embedded-if-required.js');
+var ensureSessionTokenSearchParamIfRequired = require('./helpers/ensure-session-token-search-param-if-required.js');
+require('@shopify/shopify-api');
+var redirect = require('./helpers/redirect.js');
+var renderAppBridge = require('./helpers/render-app-bridge.js');
+var validateShopAndHostParams = require('./helpers/validate-shop-and-host-params.js');
+
+function authStrategyFactory({
+  strategy,
+  ...params
+}) {
+  const {
+    api,
+    logger,
+    config
+  } = params;
+  async function respondToBouncePageRequest(request) {
+    const url = new URL(request.url);
+    if (url.pathname === config.auth.patchSessionTokenPath) {
+      logger.debug('Rendering bounce page');
+      throw renderAppBridge.renderAppBridge({
+        config,
+        logger,
+        api
+      }, request);
+    }
+  }
+  async function respondToExitIframeRequest(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', {
+        destination
+      });
+      throw renderAppBridge.renderAppBridge({
+        config,
+        logger,
+        api
+      }, request, {
+        url: destination
+      });
+    }
+  }
+  function createContext(request$1, session, sessionToken) {
+    const context = {
+      admin: createAdminApiContext.createAdminApiContext(request$1, session, {
+        api,
+        logger,
+        config
+      }),
+      billing: {
+        require: require$1.requireBillingFactory(params, request$1, session),
+        request: request.requestBillingFactory(params, request$1, session),
+        cancel: cancel.cancelBillingFactory(params, request$1, session)
+      },
+      session,
+      cors: ensureCorsHeaders.ensureCORSHeadersFactory(params, request$1)
+    };
+    if (config.isEmbeddedApp) {
+      return {
+        ...context,
+        sessionToken,
+        redirect: redirect.redirectFactory(params, request$1)
+      };
+    } else {
+      return context;
+    }
+  }
+  return async function authenticateAdmin(request) {
+    try {
+      rejectBotRequest.respondToBotRequest(params, request);
+      respondToOptionsRequest.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.getSessionTokenHeader(request)) {
+        validateShopAndHostParams.validateShopAndHostParams(params, request);
+        await ensureAppIsEmbeddedIfRequired.ensureAppIsEmbeddedIfRequired(params, request);
+        await ensureSessionTokenSearchParamIfRequired.ensureSessionTokenSearchParamIfRequired(params, request);
+      }
+      logger.info('Authenticating admin request');
+      const {
+        payload,
+        shop,
+        sessionId,
+        sessionToken
+      } = await getSessionTokenContext(params, request);
+      logger.debug('Loading session from storage', {
+        sessionId
+      });
+      const existingSession = sessionId ? await config.sessionStorage.loadSession(sessionId) : undefined;
+      const session = await strategy.authenticate(request, {
+        session: existingSession,
+        sessionToken,
+        shop
+      });
+      logger.debug('Request is valid, loaded session from session token', {
+        shop: session.shop,
+        isOnline: session.isOnline
+      });
+      return createContext(request, session, payload);
+    } catch (errorOrResponse) {
+      if (errorOrResponse instanceof Response) {
+        ensureCorsHeaders.ensureCORSHeadersFactory(params, request)(errorOrResponse);
+      }
+      throw errorOrResponse;
+    }
+  };
+}
+async function getSessionTokenContext(params, request) {
+  const {
+    api,
+    config,
+    logger
+  } = params;
+  const headerSessionToken = getSessionTokenHeader.getSessionTokenHeader(request);
+  const searchParamSessionToken = getSessionTokenHeader.getSessionTokenFromUrlParam(request);
+  const sessionToken = headerSessionToken || searchParamSessionToken;
+  logger.debug('Attempting to authenticate session token', {
+    sessionToken: JSON.stringify({
+      header: headerSessionToken,
+      search: searchParamSessionToken
+    })
+  });
+  if (config.isEmbeddedApp) {
+    const payload = await validateSessionToken.validateSessionToken({
+      config,
+      logger,
+      api
+    }, sessionToken);
+    const dest = new URL(payload.dest);
+    const shop = dest.hostname;
+    logger.debug('Session token is valid', {
+      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
+  };
+}
+
+exports.authStrategyFactory = authStrategyFactory;

package/build/cjs/server/authenticate/admin/billing/cancel.js

@@ -0,0 +1,40 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var shopifyApi = require('@shopify/shopify-api');
+require('@shopify/shopify-api/runtime');
+var redirectToAuthPage = require('../helpers/redirect-to-auth-page.js');
+require('@remix-run/server-runtime');
+
+function cancelBillingFactory(params, request, session) {
+  return async function cancelBilling(options) {
+    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 shopifyApi.HttpResponseError && error.response.code === 401) {
+        logger.debug('API token was invalid, redirecting to OAuth', {
+          shop: session.shop
+        });
+        throw await redirectToAuthPage.redirectToAuthPage(params, request, session.shop);
+      } else {
+        throw error;
+      }
+    }
+  };
+}
+
+exports.cancelBillingFactory = cancelBillingFactory;

package/build/cjs/server/authenticate/admin/billing/request.js

@@ -0,0 +1,85 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var shopifyApi = require('@shopify/shopify-api');
+var serverRuntime = require('@remix-run/server-runtime');
+require('@shopify/shopify-api/runtime');
+var redirectToAuthPage = require('../helpers/redirect-to-auth-page.js');
+var redirectWithAppBridgeHeaders = require('../helpers/redirect-with-app-bridge-headers.js');
+
+function requestBillingFactory(params, request, session) {
+  return async function requestBilling({
+    plan,
+    isTest,
+    returnUrl,
+    ...overrides
+  }) {
+    const {
+      api,
+      logger
+    } = params;
+    logger.info('Requesting billing', {
+      shop: session.shop,
+      plan,
+      isTest,
+      returnUrl
+    });
+    let result;
+    try {
+      result = await api.billing.request({
+        plan: plan,
+        session,
+        isTest,
+        returnUrl,
+        returnObject: true,
+        ...overrides
+      });
+    } catch (error) {
+      if (error instanceof shopifyApi.HttpResponseError && error.response.code === 401) {
+        logger.debug('API token was invalid, redirecting to OAuth', {
+          shop: session.shop
+        });
+        throw await redirectToAuthPage.redirectToAuthPage(params, request, session.shop);
+      } else {
+        throw error;
+      }
+    }
+    throw redirectOutOfApp(params, request, result.confirmationUrl, session.shop);
+  };
+}
+function redirectOutOfApp(params, request, url, shop) {
+  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: redirectWithAppBridgeHeaders.getAppBridgeHeaders(url)
+    });
+  } else if (isEmbeddedRequest) {
+    const params = new URLSearchParams({
+      shop,
+      host: requestUrl.searchParams.get('host'),
+      exitIframe: url
+    });
+    throw serverRuntime.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 serverRuntime.redirect(url);
+  }
+}
+
+exports.requestBillingFactory = requestBillingFactory;