Merge pull request #502 from Shopify/liz/app-proxy-docs-improvements

[Docs] Clarify App Proxy examples

.changeset/wise-meals-cover.md

@@ -0,0 +1,2 @@
+---
+---

packages/shopify-app-remix/docs/generated/generated_docs_data.json

@@ -1249,15 +1249,15 @@
   },
   {
     "name": "App proxy",
-    "description": "The `authenticate.public.appProxy` function validates app proxy requests made by Shopify, and returns a context to enable querying Shopify APIs.",
+    "description": "[App proxies](/docs/apps/online-store/app-proxies) take requests to Shopify links, and redirect them to external links. The `authenticate.public.appProxy` function validates requests made to app proxies, and returns a context to enable querying Shopify APIs.",
     "category": "Authenticate",
     "subCategory": "Public",
     "type": "object",
     "isVisualComponent": false,
     "definitions": [
       {
         "title": "authenticate.public.appProxy",
-        "description": "Authenticates requests coming from Shopify app proxies.",
+        "description": "Authenticates requests coming to the app from Shopify app proxies.",
         "type": "AuthenticateAppProxy",
         "typeDefinitions": {
           "AuthenticateAppProxy": {
@@ -1385,10 +1385,10 @@
                 "examples": [
                   {
                     "title": "Using the session object",
-                    "description": "Get your app's data using an offline session for the shop that made the request.",
+                    "description": "Get the session for the shop that initiated the request to the app proxy.",
                     "tabs": [
                       {
-                        "code": "import { json } from \"@remix-run/node\";\nimport { authenticate } from \"../shopify.server\";\nimport { getMyAppModelData } from \"~/db/model.server\";\n\nexport const loader = async ({ request }) => {\n  const { session } = await authenticate.public.appProxy(request);\n  return json(await getMyAppModelData({shop: session.shop));\n};",
+                        "code": "import { json } from \"@remix-run/node\";\nimport { authenticate } from \"../shopify.server\";\nimport { getMyAppModelData } from \"~/db/model.server\";\n\nexport const loader = async ({ request }) => {\n  // Get the session for the shop that initiated the request to the app proxy.\n  const { session } = await authenticate.public.appProxy(request);\n\n  // Use the session data to make to queries to your database or additional requests.\n  return json(await getMyAppModelData({shop: session.shop));\n};",
                         "title": "app/routes/**\\/.ts"
                       }
                     ]
@@ -1453,7 +1453,7 @@
                 ]
               }
             ],
-            "value": "export interface AppProxyContextWithSession<\n  Resources extends ShopifyRestResources = ShopifyRestResources,\n> extends Context {\n  /**\n   * The session for the shop that made the request.\n   *\n   * This comes from the session storage which `shopifyApp` uses to store sessions in your database of choice.\n   *\n   * Use this to get shop or user-specific data.\n   *\n   * @example\n   * <caption>Using the session object.</caption>\n   * <description>Get your app's data using an offline session for the shop that made the request.</description>\n   * ```ts\n   * // app/routes/**\\/.ts\n   * import { json } from \"@remix-run/node\";\n   * import { authenticate } from \"../shopify.server\";\n   * import { getMyAppModelData } from \"~/db/model.server\";\n   *\n   * export const loader = async ({ request }) => {\n   *   const { session } = await authenticate.public.appProxy(request);\n   *   return json(await getMyAppModelData({shop: session.shop));\n   * };\n   * ```\n   */\n  session: Session;\n\n  /**\n   * Methods for interacting with the GraphQL / REST Admin APIs for the store that made the request.\n   *\n   * @example\n   * <caption>Interacting with the Admin API.</caption>\n   * <description>Use the `admin` object to interact with the REST or GraphQL APIs.</description>\n   * ```ts\n   * // app/routes/**\\/.ts\n   * import { json } from \"@remix-run/node\";\n   * import { authenticate } from \"../shopify.server\";\n   *\n   * export async function action({ request }: ActionFunctionArgs) {\n   *   const { admin } = await authenticate.public.appProxy(request);\n   *\n   *   const response = await admin.graphql(\n   *     `#graphql\n   *     mutation populateProduct($input: ProductInput!) {\n   *       productCreate(input: $input) {\n   *         product {\n   *           id\n   *         }\n   *       }\n   *     }`,\n   *     { variables: { input: { title: \"Product Name\" } } }\n   *   );\n   *\n   *   const productData = await response.json();\n   *   return json({ data: productData.data });\n   * }\n   * ```\n   */\n  admin: AdminApiContext<Resources>;\n\n  /**\n   * Method for interacting with the Shopify Storefront Graphql API for the store that made the request.\n   *\n   * @example\n   * <caption>Interacting with the Storefront API.</caption>\n   * <description>Use the `storefront` object to interact with the GraphQL API.</description>\n   * ```ts\n   * // app/routes/**\\/.ts\n   * import { json } from \"@remix-run/node\";\n   * import { authenticate } from \"../shopify.server\";\n   *\n   * export async function action({ request }: ActionFunctionArgs) {\n   *   const { storefront } = await authenticate.public.appProxy(request);\n   *\n   *   const response = await storefront.graphql(`{blogs(first: 10) { edges { node { id } } } }`);\n   *\n   *   return json(await response.json());\n   * }\n   * ```\n   */\n  storefront: StorefrontContext;\n}"
+            "value": "export interface AppProxyContextWithSession<\n  Resources extends ShopifyRestResources = ShopifyRestResources,\n> extends Context {\n  /**\n   * The session for the shop that made the request.\n   *\n   * This comes from the session storage which `shopifyApp` uses to store sessions in your database of choice.\n   *\n   * Use this to get shop or user-specific data.\n   *\n   * @example\n   * <caption>Using the session object.</caption>\n   * <description>Get the session for the shop that initiated the request to the app proxy.</description>\n   * ```ts\n   * // app/routes/**\\/.ts\n   * import { json } from \"@remix-run/node\";\n   * import { authenticate } from \"../shopify.server\";\n   * import { getMyAppModelData } from \"~/db/model.server\";\n   *\n   * export const loader = async ({ request }) => {\n   *   // Get the session for the shop that initiated the request to the app proxy.\n   *   const { session } = await authenticate.public.appProxy(request);\n   *\n   *   // Use the session data to make to queries to your database or additional requests.\n   *   return json(await getMyAppModelData({shop: session.shop));\n   * };\n   * ```\n   */\n  session: Session;\n\n  /**\n   * Methods for interacting with the GraphQL / REST Admin APIs for the store that made the request.\n   *\n   * @example\n   * <caption>Interacting with the Admin API.</caption>\n   * <description>Use the `admin` object to interact with the REST or GraphQL APIs.</description>\n   * ```ts\n   * // app/routes/**\\/.ts\n   * import { json } from \"@remix-run/node\";\n   * import { authenticate } from \"../shopify.server\";\n   *\n   * export async function action({ request }: ActionFunctionArgs) {\n   *   const { admin } = await authenticate.public.appProxy(request);\n   *\n   *   const response = await admin.graphql(\n   *     `#graphql\n   *     mutation populateProduct($input: ProductInput!) {\n   *       productCreate(input: $input) {\n   *         product {\n   *           id\n   *         }\n   *       }\n   *     }`,\n   *     { variables: { input: { title: \"Product Name\" } } }\n   *   );\n   *\n   *   const productData = await response.json();\n   *   return json({ data: productData.data });\n   * }\n   * ```\n   */\n  admin: AdminApiContext<Resources>;\n\n  /**\n   * Method for interacting with the Shopify Storefront Graphql API for the store that made the request.\n   *\n   * @example\n   * <caption>Interacting with the Storefront API.</caption>\n   * <description>Use the `storefront` object to interact with the GraphQL API.</description>\n   * ```ts\n   * // app/routes/**\\/.ts\n   * import { json } from \"@remix-run/node\";\n   * import { authenticate } from \"../shopify.server\";\n   *\n   * export async function action({ request }: ActionFunctionArgs) {\n   *   const { storefront } = await authenticate.public.appProxy(request);\n   *\n   *   const response = await storefront.graphql(`{blogs(first: 10) { edges { node { id } } } }`);\n   *\n   *   return json(await response.json());\n   * }\n   * ```\n   */\n  storefront: StorefrontContext;\n}"
           },
           "AdminApiContext": {
             "filePath": "/server/clients/admin/types.ts",
@@ -1578,13 +1578,13 @@
           "title": "session",
           "examples": [
             {
-              "description": "Get your app's data using an offline session for the shop that made the request.",
+              "description": "Get the session for the shop that initiated the request to the app proxy.",
               "codeblock": {
                 "title": "Using the session object",
                 "tabs": [
                   {
                     "title": "app/routes/**\\/.ts",
-                    "code": "import { json } from \"@remix-run/node\";\nimport { authenticate } from \"../shopify.server\";\nimport { getMyAppModelData } from \"~/db/model.server\";\n\nexport const loader = async ({ request }) =&gt; {\n  const { session } = await authenticate.public.appProxy(request);\n  return json(await getMyAppModelData({shop: session.shop));\n};",
+                    "code": "import { json } from \"@remix-run/node\";\nimport { authenticate } from \"../shopify.server\";\nimport { getMyAppModelData } from \"~/db/model.server\";\n\nexport const loader = async ({ request }) =&gt; {\n  // Get the session for the shop that initiated the request to the app proxy.\n  const { session } = await authenticate.public.appProxy(request);\n\n  // Use the session data to make to queries to your database or additional requests.\n  return json(await getMyAppModelData({shop: session.shop));\n};",
                     "language": "typescript"
                   }
                 ]
@@ -4802,10 +4802,10 @@
                 "examples": [
                   {
                     "title": "Using the session object",
-                    "description": "Get your app's data using an offline session for the shop that made the request.",
+                    "description": "Get the session for the shop that initiated the request to the app proxy.",
                     "tabs": [
                       {
-                        "code": "import { json } from \"@remix-run/node\";\nimport { authenticate } from \"../shopify.server\";\nimport { getMyAppModelData } from \"~/db/model.server\";\n\nexport const loader = async ({ request }) => {\n  const { session } = await authenticate.public.appProxy(request);\n  return json(await getMyAppModelData({shop: session.shop));\n};",
+                        "code": "import { json } from \"@remix-run/node\";\nimport { authenticate } from \"../shopify.server\";\nimport { getMyAppModelData } from \"~/db/model.server\";\n\nexport const loader = async ({ request }) => {\n  // Get the session for the shop that initiated the request to the app proxy.\n  const { session } = await authenticate.public.appProxy(request);\n\n  // Use the session data to make to queries to your database or additional requests.\n  return json(await getMyAppModelData({shop: session.shop));\n};",
                         "title": "app/routes/**\\/.ts"
                       }
                     ]
@@ -4870,7 +4870,7 @@
                 ]
               }
             ],
-            "value": "export interface AppProxyContextWithSession<\n  Resources extends ShopifyRestResources = ShopifyRestResources,\n> extends Context {\n  /**\n   * The session for the shop that made the request.\n   *\n   * This comes from the session storage which `shopifyApp` uses to store sessions in your database of choice.\n   *\n   * Use this to get shop or user-specific data.\n   *\n   * @example\n   * <caption>Using the session object.</caption>\n   * <description>Get your app's data using an offline session for the shop that made the request.</description>\n   * ```ts\n   * // app/routes/**\\/.ts\n   * import { json } from \"@remix-run/node\";\n   * import { authenticate } from \"../shopify.server\";\n   * import { getMyAppModelData } from \"~/db/model.server\";\n   *\n   * export const loader = async ({ request }) => {\n   *   const { session } = await authenticate.public.appProxy(request);\n   *   return json(await getMyAppModelData({shop: session.shop));\n   * };\n   * ```\n   */\n  session: Session;\n\n  /**\n   * Methods for interacting with the GraphQL / REST Admin APIs for the store that made the request.\n   *\n   * @example\n   * <caption>Interacting with the Admin API.</caption>\n   * <description>Use the `admin` object to interact with the REST or GraphQL APIs.</description>\n   * ```ts\n   * // app/routes/**\\/.ts\n   * import { json } from \"@remix-run/node\";\n   * import { authenticate } from \"../shopify.server\";\n   *\n   * export async function action({ request }: ActionFunctionArgs) {\n   *   const { admin } = await authenticate.public.appProxy(request);\n   *\n   *   const response = await admin.graphql(\n   *     `#graphql\n   *     mutation populateProduct($input: ProductInput!) {\n   *       productCreate(input: $input) {\n   *         product {\n   *           id\n   *         }\n   *       }\n   *     }`,\n   *     { variables: { input: { title: \"Product Name\" } } }\n   *   );\n   *\n   *   const productData = await response.json();\n   *   return json({ data: productData.data });\n   * }\n   * ```\n   */\n  admin: AdminApiContext<Resources>;\n\n  /**\n   * Method for interacting with the Shopify Storefront Graphql API for the store that made the request.\n   *\n   * @example\n   * <caption>Interacting with the Storefront API.</caption>\n   * <description>Use the `storefront` object to interact with the GraphQL API.</description>\n   * ```ts\n   * // app/routes/**\\/.ts\n   * import { json } from \"@remix-run/node\";\n   * import { authenticate } from \"../shopify.server\";\n   *\n   * export async function action({ request }: ActionFunctionArgs) {\n   *   const { storefront } = await authenticate.public.appProxy(request);\n   *\n   *   const response = await storefront.graphql(`{blogs(first: 10) { edges { node { id } } } }`);\n   *\n   *   return json(await response.json());\n   * }\n   * ```\n   */\n  storefront: StorefrontContext;\n}"
+            "value": "export interface AppProxyContextWithSession<\n  Resources extends ShopifyRestResources = ShopifyRestResources,\n> extends Context {\n  /**\n   * The session for the shop that made the request.\n   *\n   * This comes from the session storage which `shopifyApp` uses to store sessions in your database of choice.\n   *\n   * Use this to get shop or user-specific data.\n   *\n   * @example\n   * <caption>Using the session object.</caption>\n   * <description>Get the session for the shop that initiated the request to the app proxy.</description>\n   * ```ts\n   * // app/routes/**\\/.ts\n   * import { json } from \"@remix-run/node\";\n   * import { authenticate } from \"../shopify.server\";\n   * import { getMyAppModelData } from \"~/db/model.server\";\n   *\n   * export const loader = async ({ request }) => {\n   *   // Get the session for the shop that initiated the request to the app proxy.\n   *   const { session } = await authenticate.public.appProxy(request);\n   *\n   *   // Use the session data to make to queries to your database or additional requests.\n   *   return json(await getMyAppModelData({shop: session.shop));\n   * };\n   * ```\n   */\n  session: Session;\n\n  /**\n   * Methods for interacting with the GraphQL / REST Admin APIs for the store that made the request.\n   *\n   * @example\n   * <caption>Interacting with the Admin API.</caption>\n   * <description>Use the `admin` object to interact with the REST or GraphQL APIs.</description>\n   * ```ts\n   * // app/routes/**\\/.ts\n   * import { json } from \"@remix-run/node\";\n   * import { authenticate } from \"../shopify.server\";\n   *\n   * export async function action({ request }: ActionFunctionArgs) {\n   *   const { admin } = await authenticate.public.appProxy(request);\n   *\n   *   const response = await admin.graphql(\n   *     `#graphql\n   *     mutation populateProduct($input: ProductInput!) {\n   *       productCreate(input: $input) {\n   *         product {\n   *           id\n   *         }\n   *       }\n   *     }`,\n   *     { variables: { input: { title: \"Product Name\" } } }\n   *   );\n   *\n   *   const productData = await response.json();\n   *   return json({ data: productData.data });\n   * }\n   * ```\n   */\n  admin: AdminApiContext<Resources>;\n\n  /**\n   * Method for interacting with the Shopify Storefront Graphql API for the store that made the request.\n   *\n   * @example\n   * <caption>Interacting with the Storefront API.</caption>\n   * <description>Use the `storefront` object to interact with the GraphQL API.</description>\n   * ```ts\n   * // app/routes/**\\/.ts\n   * import { json } from \"@remix-run/node\";\n   * import { authenticate } from \"../shopify.server\";\n   *\n   * export async function action({ request }: ActionFunctionArgs) {\n   *   const { storefront } = await authenticate.public.appProxy(request);\n   *\n   *   const response = await storefront.graphql(`{blogs(first: 10) { edges { node { id } } } }`);\n   *\n   *   return json(await response.json());\n   * }\n   * ```\n   */\n  storefront: StorefrontContext;\n}"
           },
           "StorefrontContext": {
             "filePath": "/server/clients/storefront/types.ts",

packages/shopify-app-remix/src/server/authenticate/public/appProxy/authenticate.public.app-proxy.doc.ts

@@ -3,15 +3,16 @@ import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
 const data: ReferenceEntityTemplateSchema = {
   name: 'App proxy',
   description:
-    'The `authenticate.public.appProxy` function validates app proxy requests made by Shopify, and returns a context to enable querying Shopify APIs.',
+    '[App proxies](/docs/apps/online-store/app-proxies) take requests to Shopify links, and redirect them to external links. The `authenticate.public.appProxy` function validates requests made to app proxies, and returns a context to enable querying Shopify APIs.',
   category: 'Authenticate',
   subCategory: 'Public',
   type: 'object',
   isVisualComponent: false,
   definitions: [
     {
       title: 'authenticate.public.appProxy',
-      description: 'Authenticates requests coming from Shopify app proxies.',
+      description:
+        'Authenticates requests coming to the app from Shopify app proxies.',
       type: 'AuthenticateAppProxy',
     },
   ],

packages/shopify-app-remix/src/server/authenticate/public/appProxy/types.ts

@@ -70,15 +70,18 @@ export interface AppProxyContextWithSession<
    *
    * @example
    * <caption>Using the session object.</caption>
-   * <description>Get your app's data using an offline session for the shop that made the request.</description>
+   * <description>Get the session for the shop that initiated the request to the app proxy.</description>
    * ```ts
    * // app/routes/**\/.ts
    * import { json } from "@remix-run/node";
    * import { authenticate } from "../shopify.server";
    * import { getMyAppModelData } from "~/db/model.server";
    *
    * export const loader = async ({ request }) => {
+   *   // Get the session for the shop that initiated the request to the app proxy.
    *   const { session } = await authenticate.public.appProxy(request);
+   *
+   *   // Use the session data to make to queries to your database or additional requests.
    *   return json(await getMyAppModelData({shop: session.shop));
    * };
    * ```