shopify-app-js 0.0.1-security → 1.0.1

package/packages/shopify-app-remix/docs/staticPages/admin.doc.ts

@@ -0,0 +1,130 @@
+import {LandingTemplateSchema} from '@shopify/generate-docs';
+
+const data: LandingTemplateSchema = {
+  id: 'guide-admin',
+  title: 'Interacting with Shopify Admin',
+  description:
+    'Once you [set up your backend](/docs/api/shopify-app-remix#shopify-app), you can use the [`authenticate.admin` function](/docs/api/shopify-app-remix/authenticate/admin) to integrate your app with Shopify Admin.' +
+    '\n\nThis function works for both embedded and non-embedded apps, and ensures the app is installed on the current store.' +
+    '\n\nIt returns a context with functions to enable loaders and actions to respond to any requests made by or in Shopify Admin.' +
+    '\n\nThis page goes over the basics of authenticating those requests, and some of the things you can do with it, like querying the Admin API.',
+  sections: [
+    {
+      type: 'Generic',
+      anchorLink: 'auth',
+      title: 'Authenticating requests',
+      sectionContent:
+        'To authenticate admin requests you can call `authenticate.admin(request)` in a loader or an action.' +
+        "\n\nIf there's a session for this user, then this loader will return null. If there's no session for the user, then the loader will throw the appropriate redirect Response." +
+        '\n\n> Tip: If you are authenticating more than one route, then we recommend using [Remix layout routes](https://remix.run/docs/en/1.18.1/file-conventions/routes-files#layout-routes) to automatically authenticate them.',
+      codeblock: {
+        title: 'Authenticating requests',
+        tabs: [
+          {
+            title: '/app/routes/**/*.tsx',
+            code: './examples/guides/admin/auth.example.tsx',
+            language: 'tsx',
+          },
+        ],
+      },
+    },
+    {
+      type: 'Generic',
+      anchorLink: 'headers',
+      title: 'Headers',
+      sectionContent:
+        "The OAuth process can't happen inside the admin iframe, and this package is capable of detecting that scenario and properly redirecting using the [Remix `ErrorBoundary`](https://remix.run/docs/en/main/guides/errors) export to set the correct headers for App Bridge." +
+        '\n\nUse the abstractions provided by this package in your authenticated routes, to automatically set up the error and headers boundaries to redirect outside the iframe when needed.' +
+        '\n\n> Tip: You can also add this to a [Remix layout](https://remix.run/docs/en/main/file-conventions/route-files-v2) if you want to authenticate more than one route, but make sure to call the Shopify boundary methods whenever you need to add your own exports.',
+      codeblock: {
+        title: 'Configure header boundaries',
+        tabs: [
+          {
+            title: '/app/routes/**/*.tsx',
+            code: './examples/guides/admin/headers.example.tsx',
+            language: 'tsx',
+          },
+        ],
+      },
+    },
+    {
+      type: 'Generic',
+      anchorLink: 'cors-auth',
+      title: 'Authenticating cross-origin admin requests',
+      sectionContent:
+        'If your Remix server is authenticating an admin extension, then a request from the extension to Remix will be cross-origin.' +
+        '\n\nHere `authenticate.admin` provides a `cors` function to add the required cross-origin headers.',
+      codeblock: {
+        title: 'Add cross-origin headers',
+        tabs: [
+          {
+            title: '/app/routes/**/*.tsx',
+            code: './examples/guides/admin/auth-cors.example.tsx',
+            language: 'tsx',
+          },
+        ],
+      },
+    },
+    {
+      type: 'Generic',
+      anchorLink: 'graphql-api',
+      title: 'Using the GraphQL API',
+      sectionContent:
+        'Once a request is authenticated, `authenticate.admin` will return an `admin` object that contains a GraphQL client that can interact with the [GraphQL Admin API](/docs/api/admin-graphql).',
+      codeblock: {
+        title: 'Make GraphQL requests',
+        tabs: [
+          {
+            title: '/app/routes/**/*.tsx',
+            code: './examples/guides/admin/graphql.example.tsx',
+            language: 'tsx',
+          },
+        ],
+      },
+      sectionCard: [
+        {
+          url: '/docs/api/shopify-app-remix/guide-graphql-types',
+          name: 'Typing GraphQL operations',
+          type: 'tutorial',
+        },
+      ],
+    },
+    {
+      type: 'Generic',
+      anchorLink: 'rest-api',
+      title: 'Using the REST API',
+      sectionContent:
+        'Once a request is authenticated, `authenticate.admin` will return an `admin` object that contains a REST client that can interact with the [REST Admin API](/docs/api/admin-rest).' +
+        '\n\nYou can also import a set of resource classes from the `@shopify/shopify-api` package, which is included in `@shopify/shopify-app-remix`.' +
+        '\n\nThese classes map to the individual REST endpoints, and will be returned under `admin.rest.resources`.',
+      codeblock: {
+        title: 'Interacting with the REST API',
+        tabs: [
+          {
+            title: '/app/shopify.server.ts',
+            code: './examples/guides/admin/rest-resources.example.tsx',
+            language: 'tsx',
+          },
+          {
+            title: '/app/routes/**/*.tsx',
+            code: './examples/guides/admin/rest.example.tsx',
+            language: 'tsx',
+          },
+        ],
+      },
+    },
+    {
+      type: 'Resource',
+      title: 'Resources',
+      anchorLink: 'resources',
+      resources: [
+        {
+          name: 'authenticate.admin',
+          url: '/docs/api/shopify-app-remix/authenticate/admin',
+        },
+      ],
+    },
+  ],
+};
+
+export default data;

package/packages/shopify-app-remix/docs/staticPages/examples/guides/admin/auth-cors.example.tsx

@@ -0,0 +1,11 @@
+import {json, LoaderFunction} from '@remix-run/node';
+
+import {authenticate} from '~/shopify.server';
+
+export const loader: LoaderFunction = async ({request}) => {
+  const {cors} = await authenticate.admin(request);
+
+  // App logic
+
+  return cors(json({my: 'data'}));
+};

package/packages/shopify-app-remix/docs/staticPages/examples/guides/admin/auth.example.tsx

@@ -0,0 +1,19 @@
+import {LoaderFunction, ActionFunction} from '@remix-run/node';
+
+import {authenticate} from '~/shopify.server';
+
+export const loader: LoaderFunction = async ({request}) => {
+  await authenticate.admin(request);
+
+  // App logic
+
+  return null;
+};
+
+export const action: ActionFunction = async ({request}) => {
+  await authenticate.admin(request);
+
+  // App logic
+
+  return null;
+};

package/packages/shopify-app-remix/docs/staticPages/examples/guides/admin/graphql.example.tsx

@@ -0,0 +1,29 @@
+import {ActionFunction, json} from '@remix-run/node';
+
+import {authenticate} from '../shopify.server';
+
+export const action: ActionFunction = async ({request}) => {
+  const {admin} = await authenticate.admin(request);
+
+  const response = await admin.graphql(
+    `#graphql
+    mutation populateProduct($input: ProductInput!) {
+      productCreate(input: $input) {
+        product {
+          id
+        }
+      }
+    }`,
+    {
+      variables: {
+        input: {
+          title: 'New product',
+          variants: [{price: 100}],
+        },
+      },
+    },
+  );
+  const parsedResponse = await response.json();
+
+  return json({data: parsedResponse.data});
+};

package/packages/shopify-app-remix/docs/staticPages/examples/guides/admin/headers.example.tsx

@@ -0,0 +1,10 @@
+import {useRouteError} from '@remix-run/react';
+import {boundary} from '@shopify/shopify-app-remix';
+
+export function ErrorBoundary() {
+  return boundary.error(useRouteError());
+}
+
+export const headers = (headersArgs) => {
+  return boundary.headers(headersArgs);
+};

package/packages/shopify-app-remix/docs/staticPages/examples/guides/admin/rest-resources.example.tsx

@@ -0,0 +1,9 @@
+import {shopifyApp} from '@shopify/shopify-app-remix/server';
+import {restResources} from '@shopify/shopify-api/rest/admin/2023-07';
+
+const shopify = shopifyApp({
+  restResources,
+  // ...etc
+});
+
+export const authenticate = shopify.authenticate;

package/packages/shopify-app-remix/docs/staticPages/examples/guides/admin/rest.example.tsx

@@ -0,0 +1,17 @@
+import {LoaderFunction, json} from '@remix-run/node';
+import {useRouteError} from '@remix-run/react';
+
+import {authenticate} from '~/shopify.server';
+
+export const loader: LoaderFunction = async ({request}) => {
+  const {admin, session} = await authenticate.admin(request);
+
+  // Use REST resources
+  const data = await admin.rest.resources.Product.count({session});
+
+  // Or use the REST client
+  const response = await admin.rest.get({path: 'products/count'});
+  const data = response.body;
+
+  return json({productCount: data.count});
+};

package/packages/shopify-app-remix/docs/staticPages/examples/guides/future-flags/config.example.ts

@@ -0,0 +1,8 @@
+import {shopifyApp} from '@shopify/shopify-app-remix/server';
+
+export const shopify = shopifyApp({
+  // ...
+  future: {
+    unstable_newFeature: true,
+  },
+});

package/packages/shopify-app-remix/docs/staticPages/examples/guides/future-flags/unstable.example.ts

@@ -0,0 +1,9 @@
+import type {LoaderFunctionArgs} from '@remix-run/node';
+
+import {shopify} from '~/shopify.server';
+
+export const loader = async ({request}: LoaderFunctionArgs) => {
+  const result = shopify.newFeature(params);
+
+  return null;
+};

package/packages/shopify-app-remix/docs/staticPages/examples/guides/graphql-types/.graphqlrc.ts

@@ -0,0 +1,16 @@
+import {shopifyApiProject, ApiType} from '@shopify/api-codegen-preset';
+
+export default {
+  // For syntax highlighting / auto-complete when writing operations
+  schema: 'https://shopify.dev/admin-graphql-direct-proxy/2023-10',
+  documents: ['./app/**/*.{js,ts,jsx,tsx}'],
+  projects: {
+    // To produce variable / return types for Admin API operations
+    default: shopifyApiProject({
+      apiType: ApiType.Admin,
+      apiVersion: '2023-10',
+      documents: ['./app/**/*.{js,ts,jsx,tsx}'],
+      outputDir: './app/types',
+    }),
+  },
+};

package/packages/shopify-app-remix/docs/staticPages/examples/guides/graphql-types/install.npm.example.sh

@@ -0,0 +1,2 @@
+npm add --save-dev @shopify/api-codegen-preset
+npm add @shopify/admin-api-client @shopify/storefront-api-client

package/packages/shopify-app-remix/docs/staticPages/examples/guides/graphql-types/install.pnpm.example.sh

@@ -0,0 +1,2 @@
+pnpm add --save-dev @shopify/api-codegen-preset
+pnpm add @shopify/admin-api-client @shopify/storefront-api-client

package/packages/shopify-app-remix/docs/staticPages/examples/guides/graphql-types/install.yarn.example.sh

@@ -0,0 +1,2 @@
+yarn add --dev @shopify/api-codegen-preset
+yarn add @shopify/admin-api-client @shopify/storefront-api-client

package/packages/shopify-app-remix/docs/staticPages/examples/guides/graphql-types/package.json

@@ -0,0 +1,5 @@
+{
+  "scripts": {
+    "graphql-codegen": "graphql-codegen"
+  }
+}

package/packages/shopify-app-remix/docs/staticPages/examples/guides/graphql-types/run.npm.example.sh

@@ -0,0 +1 @@
+npm run graphql-codegen

package/packages/shopify-app-remix/docs/staticPages/examples/guides/graphql-types/run.pnpm.example.sh

@@ -0,0 +1 @@
+pnpm run graphql-codegen

package/packages/shopify-app-remix/docs/staticPages/examples/guides/graphql-types/run.yarn.example.sh

@@ -0,0 +1 @@
+yarn graphql-codegen

package/packages/shopify-app-remix/docs/staticPages/examples/guides/webhooks/config.example.ts

@@ -0,0 +1,19 @@
+import {shopifyApp, DeliveryMethod} from '@shopify/shopify-app-remix/server';
+
+const shopify = shopifyApp({
+  apiKey: 'abcde1234567890',
+  // ...etc
+  webhooks: {
+    APP_UNINSTALLED: {
+      deliveryMethod: DeliveryMethod.Http,
+      callbackUrl: '/webhooks',
+    },
+  },
+  hooks: {
+    afterAuth: async ({session}) => {
+      shopify.registerWebhooks({session});
+    },
+  },
+});
+
+export const authenticate = shopify.authenticate;

package/packages/shopify-app-remix/docs/staticPages/examples/guides/webhooks/endpoint.example.ts

@@ -0,0 +1,24 @@
+import {ActionFunction} from '@remix-run/node';
+
+import db from '../db.server';
+
+import {authenticate} from '~/shopify.server';
+
+export const action: ActionFunction = async ({request}) => {
+  const {topic, shop, session} = await authenticate.webhook(request);
+
+  switch (topic) {
+    case 'APP_UNINSTALLED':
+      if (session) {
+        await db.session.deleteMany({where: {shop}});
+      }
+      break;
+    case 'CUSTOMERS_DATA_REQUEST':
+    case 'CUSTOMERS_REDACT':
+    case 'SHOP_REDACT':
+    default:
+      throw new Response('Unhandled webhook topic', {status: 404});
+  }
+
+  throw new Response();
+};

package/packages/shopify-app-remix/docs/staticPages/examples/index/app-provider.example.ts

@@ -0,0 +1,30 @@
+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>
+  );
+}

package/packages/shopify-app-remix/docs/staticPages/examples/index/boundaries.example.ts

@@ -0,0 +1,9 @@
+import {boundary} from '@shopify/shopify-app-remix/server';
+
+export function ErrorBoundary() {
+  return boundary.error(useRouteError());
+}
+
+export const headers = (headersArgs) => {
+  return boundary.headers(headersArgs);
+};

package/packages/shopify-app-remix/docs/staticPages/examples/index/create.npm.example.sh

@@ -0,0 +1 @@
+npm init @shopify/app@latest

package/packages/shopify-app-remix/docs/staticPages/examples/index/create.pnpm.example.sh

@@ -0,0 +1 @@
+pnpm create @shopify/app

package/packages/shopify-app-remix/docs/staticPages/examples/index/create.yarn.example.sh

@@ -0,0 +1 @@
+yarn create @shopify/app

package/packages/shopify-app-remix/docs/staticPages/examples/index/embedded-app-auth-strategy-config.example.ts

@@ -0,0 +1,10 @@
+// ... imports
+const shopify = shopifyApp({
+  // .. and the rest of the config
+  isEmbeddedApp: true,
+  future: {
+    unstable_newEmbeddedAuthStrategy: true,
+  },
+)};
+
+// ... exports

package/packages/shopify-app-remix/docs/staticPages/examples/index/entry-server.example.ts

@@ -0,0 +1,12 @@
+import shopify from './shopify.server';
+
+export default function handleRequest(
+  request: Request,
+  responseStatusCode: number,
+  responseHeaders: Headers,
+  remixContext: EntryContext,
+) {
+  shopify.addDocumentResponseHeaders(request, responseHeaders);
+
+  // ..etc
+}

package/packages/shopify-app-remix/docs/staticPages/examples/index/install.npm.example.sh

@@ -0,0 +1 @@
+npm i --save @shopify/shopify-app-remix

package/packages/shopify-app-remix/docs/staticPages/examples/index/install.pnpm.example.sh

@@ -0,0 +1 @@
+pnpm add @shopify/shopify-app-remix

package/packages/shopify-app-remix/docs/staticPages/examples/index/install.yarn.example.sh

@@ -0,0 +1 @@
+yarn add @shopify/shopify-app-remix

package/packages/shopify-app-remix/docs/staticPages/examples/index/shopify-app.example.ts

@@ -0,0 +1,14 @@
+import '@shopify/shopify-app-remix/server/adapters/node';
+import {
+  LATEST_API_VERSION,
+  shopifyApp,
+} from '@shopify/shopify-app-remix/server';
+
+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,
+});
+export default shopify;

package/packages/shopify-app-remix/docs/staticPages/examples/index/splat-route.example.ts

@@ -0,0 +1,11 @@
+import {LoaderFunctionArgs} from '@remix-run/node';
+
+import shopify from '~/shopify.server';
+
+export async function loader({request}: LoaderFunctionArgs) {
+  await shopify.authenticate.admin(request);
+
+  // App logic goes here
+
+  return null;
+}

package/packages/shopify-app-remix/docs/staticPages/future-flags.doc.ts

@@ -0,0 +1,94 @@
+import {LandingTemplateSchema} from '@shopify/generate-docs';
+
+const data: LandingTemplateSchema = {
+  id: 'guide-future-flags',
+  title: 'Future flags',
+  description:
+    'Similarly to how [Remix approaches breaking changes](https://remix.run/docs/en/main/start/future-flags), the `@shopify/shopify-app-remix` package also uses future flags.' +
+    "\n\nBigger features and breaking changes are initially added behind a future flag. This means that they're disabled by default, and must be manually enabled by setting the appropriate flag in the `future` option of the `shopifyApp` function." +
+    '\n\nThis allows apps to gradually adopt new features, and prepare for breaking changes and major releases ahead of time.',
+  sections: [
+    {
+      type: 'Generic',
+      anchorLink: 'configuration',
+      title: 'Setting future flags',
+      sectionContent:
+        'To opt in to a feature, simply enable the appropriate flag in the `future` option of the `shopifyApp` function.' +
+        '\n\nOnce a flag is set, the returned `shopify` object will start using the new APIs, including using any new types. That allows apps to rely on TypeScript to use a feature regardless of a flag being enabled or not.',
+      codeblock: {
+        title: 'Enable future flags',
+        tabs: [
+          {
+            title: '/app/shopify.server.ts',
+            language: 'ts',
+            code: './examples/guides/future-flags/config.example.ts',
+          },
+        ],
+      },
+    },
+    {
+      type: 'Generic',
+      anchorLink: 'unstable-apis',
+      title: 'Unstable APIs',
+      sectionContent:
+        'When introducing new features to the package for which we want to gather feedback, we will add them behind a future flag, starting with the `unstable_` prefix.' +
+        '\n\nThat allows early adopters to try them out individually, without having to install a release candidate package.' +
+        '\n\nWhen the feature is ready for release, the future flag will be removed and it will be available by default.' +
+        '\n\nIn this example, `shopify` has a new function called `newFeature`. If the future flag is disabled, TypeScript will be unaware of the new function, and the app will fail to compile if it tries to use it.',
+      codeblock: {
+        title: 'Use unstable APIs',
+        tabs: [
+          {
+            title: '/app/routes/*.tsx',
+            language: 'ts',
+            code: './examples/guides/future-flags/unstable.example.ts',
+          },
+        ],
+      },
+    },
+    {
+      type: 'Generic',
+      anchorLink: 'breaking-changes',
+      title: 'Breaking changes',
+      sectionContent:
+        'Similarly to unstable APIs, breaking changes will be introduced behind a future flag, but the prefix will be the next major version (e.g. `v3_`).' +
+        '\n\nThis allows apps to prepare for the next major version ahead of time, and to gradually adopt the new APIs.' +
+        '\n\nWhen the next major version is released, the future flag will be removed, and the old code it changes will be removed. Apps that adopted the flag before then will continue to work the same way with no new changes.',
+    },
+    {
+      type: 'GenericList',
+      anchorLink: 'flags',
+      title: 'Supported flags',
+      sectionContent:
+        'These are the future flags supported in the current version.',
+      listItems: [
+        {
+          name: 'v3_webhookAdminContext',
+          value: '',
+          description:
+            'Returns the same `admin` context (`AdminApiContext`) from `authenticate.webhook` that is returned from `authenticate.admin`.' +
+            '\n\nSee [authenticate.webhook](/docs/api/shopify-app-remix/authenticate/webhook#example-admin) for more details.',
+          isOptional: true,
+        },
+        {
+          name: 'v3_lineItemBilling',
+          value: '',
+          description:
+            'Allows you to pass billing plans with up to two line items when creating a new app subscription.' +
+            '\n\n This allows you to create app subscriptions with both recurring and usage based components.',
+          isOptional: true,
+        },
+        {
+          name: 'unstable_newEmbeddedAuthStrategy',
+          value: '',
+          description:
+            'Embedded apps will fetch access tokens via token exchange. This assumes the app has declared scopes for Shopify managed installations.' +
+            '\n\nLearn more about this [new embedded app auth strategy](https://shopify.dev/docs/api/shopify-app-remix#embedded-auth-strategy).',
+          isOptional: true,
+        },
+      ],
+    },
+  ],
+};
+
+export default data;