@shopify/shopify-app-remix 4.1.0 → 4.2.0

package/src/server/unauthenticated/storefront/types.ts

@@ -0,0 +1,105 @@
+import {Session} from '@shopify/shopify-api';
+
+import type {StorefrontContext} from '../../clients';
+
+export interface UnauthenticatedStorefrontContext {
+  /**
+   * The session for the given shop.
+   *
+   * This comes from the session storage which `shopifyApp` uses to store sessions in your database of choice.
+   *
+   * This will always be an offline session. You can use this to get shop specific data.
+   *
+   * @example
+   * <caption>Using the offline session.</caption>
+   * <description>Get your app's shop-specific data using the returned offline `session` object.</description>
+   * ```ts
+   * // app/routes/**\/.ts
+   * import { LoaderFunctionArgs, json } from "@remix-run/node";
+   * import { unauthenticated } from "../shopify.server";
+   * import { getMyAppData } from "~/db/model.server";
+   *
+   * export const loader = async ({ request }: LoaderFunctionArgs) => {
+   *   const shop = getShopFromExternalRequest(request);
+   *   const { session } = await unauthenticated.storefront(shop);
+   *   return json(await getMyAppData({shop: session.shop));
+   * };
+   * ```
+   */
+  session: Session;
+
+  /**
+   * Method for interacting with the Shopify GraphQL Storefront API for the given store.
+   *
+   * @example
+   * <caption>Querying the GraphQL API.</caption>
+   * <description>Use `storefront.graphql` to make query / mutation requests.</description>
+   * ```ts
+   * // app/routes/**\/.ts
+   * import { json } from "@remix-run/node";
+   * import { authenticate } from "../shopify.server";
+   *
+   * export async function action({ request }: ActionFunctionArgs) {
+   *   const shop = getShopFromExternalRequest(request);
+   *   const { storefront } = await unauthenticated.storefront(shop);
+   *
+   *   const response = await storefront.graphql(`{blogs(first: 10) { edges { node { id } } } }`);
+   *
+   *   return json(await response.json());
+   * }
+   * ```
+   *
+   * @example
+   * <caption>Handling GraphQL errors.</caption>
+   * <description>Catch `GraphqlQueryError` errors to see error messages from the API.</description>
+   * ```ts
+   * // /app/routes/**\/*.ts
+   * import { ActionFunctionArgs } from "@remix-run/node";
+   * import { authenticate } from "../shopify.server";
+   *
+   * export const action = async ({ request }: ActionFunctionArgs) => {
+   *   const shop = getShopFromExternalRequest(request);
+   *   const { storefront } = await unauthenticated.storefront(shop);
+   *
+   *   try {
+   *     const response = await storefront.graphql(
+   *       `#graphql
+   *       query incorrectQuery {
+   *         products(first: 10) {
+   *           nodes {
+   *             not_a_field
+   *           }
+   *         }
+   *       }`,
+   *     );
+   *
+   *     return json({ data: await response.json() });
+   *   } catch (error) {
+   *     if (error instanceof GraphqlQueryError) {
+   *       // { errors: { graphQLErrors: [
+   *       //   { message: "Field 'not_a_field' doesn't exist on type 'Product'" }
+   *       // ] } }
+   *       return json({ errors: error.body?.errors }, { status: 500 });
+   *     }
+   *     return json({ message: "An error occurred" }, { status: 500 });
+   *   }
+   * }
+   * ```
+   *
+   * ```ts
+   * // /app/shopify.server.ts
+   * import { shopifyApp } from "@shopify/shopify-app-remix/server";
+   *
+   * const shopify = shopifyApp({
+   *   // ...
+   * });
+   * export default shopify;
+   * export const unauthenticated = shopify.unauthenticated;
+   * ```
+   */
+  storefront: StorefrontContext;
+}
+
+export type GetUnauthenticatedStorefrontContext = (
+  shop: string,
+) => Promise<UnauthenticatedStorefrontContext>;

package/src/server/unauthenticated/storefront/unauthenticated.storefront.doc.ts

@@ -0,0 +1,40 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Unauthenticated storefront',
+  description: `Allows interacting with the Storefront API when working outside of Shopify requests.
+This enables apps to integrate with 3rd party services and perform background tasks.
+
+> Caution:
+> This function doesn't perform **any** validation and shouldn't rely on raw user input.
+
+When using this function, consider the following:
+
+#### Background tasks
+
+Apps should ensure that the shop domain is authenticated when enqueueing jobs.
+
+#### 3rd party service requests
+
+Apps must obtain the shop domain from the 3rd party service in a secure way.`,
+  category: 'Unauthenticated',
+  type: 'object',
+  isVisualComponent: false,
+  definitions: [
+    {
+      title: 'unauthenticated.storefront',
+      description: 'Creates an unauthenticated Storefront context.',
+      type: 'GetUnauthenticatedStorefrontContext',
+    },
+  ],
+  jsDocTypeExamples: ['UnauthenticatedStorefrontContext'],
+  related: [
+    {
+      name: 'API context',
+      subtitle: 'Interact with the Storefront API.',
+      url: '/docs/api/shopify-app-remix/apis/storefront-api',
+    },
+  ],
+};
+
+export default data;

package/src/server/unauthenticated/types.ts

@@ -0,0 +1,65 @@
+import type {GetUnauthenticatedAdminContext} from './admin/types';
+import type {GetUnauthenticatedStorefrontContext} from './storefront/types';
+
+export interface Unauthenticated {
+  /**
+   * Get an admin context by passing a shop
+   *
+   * **Warning** This should only be used for Requests that do not originate from Shopify.
+   * You must do your own authentication before using this method.
+   * This method throws an error if there is no session for the shop.
+   *
+   * @example
+   * <caption>Responding to a request not controlled by Shopify.</caption>
+   * ```ts
+   * // /app/shopify.server.ts
+   * import { ApiVersion, shopifyApp } from "@shopify/shopify-app-remix/server";
+   *
+   * const shopify = shopifyApp({
+   *   // ...etc
+   * });
+   * export default shopify;
+   * ```
+   * ```ts
+   * // /app/routes/**\/*.jsx
+   * import { LoaderFunctionArgs, json } from "@remix-run/node";
+   * import { authenticateExternal } from "~/helpers/authenticate"
+   * import shopify from "../../shopify.server";
+   *
+   * export async function loader({ request }: LoaderFunctionArgs) {
+   *   const shop = await authenticateExternal(request)
+   *   const {admin} = await shopify.unauthenticated.admin(shop);
+   *   const response = await admin.graphql("{ shop { name} }")
+   *
+   *   return json(await response.json());
+   * }
+   * ```
+   */
+  admin: GetUnauthenticatedAdminContext;
+
+  /**
+   * Get a storefront context by passing a shop
+   *
+   * **Warning** This should only be used for Requests that do not originate from Shopify.
+   * You must do your own authentication before using this method.
+   * This method throws an error if there is no session for the shop.
+   *
+   * @example
+   * <caption>Responding to a request not controlled by Shopify</caption>
+   * ```ts
+   * // /app/routes/**\/*.jsx
+   * import { LoaderFunctionArgs, json } from "@remix-run/node";
+   * import { authenticateExternal } from "~/helpers/authenticate"
+   * import shopify from "../../shopify.server";
+   *
+   * export async function loader({ request }: LoaderFunctionArgs) {
+   *   const shop = await authenticateExternal(request)
+   *   const {storefront} = await shopify.unauthenticated.storefront(shop);
+   *   const response = await storefront.graphql(`{blogs(first: 10) { edges { node { id } } } }`);
+   *
+   *   return json(await response.json());
+   * }
+   * ```
+   */
+  storefront: GetUnauthenticatedStorefrontContext;
+}

package/src/server/version.ts

@@ -0,0 +1 @@
+export const SHOPIFY_REMIX_LIBRARY_VERSION = '4.2.0';