feat(gatsby-source-contentful): update docs and improve errors (#30538)

* docs(contentful): add known limitations to the readme

* fix(contentful): tell users of environments that access tokens need to be able to access master env

fixes #26909

packages/gatsby-source-contentful/README.md

@@ -17,6 +17,18 @@ npm install gatsby-source-contentful
 
 First, you need a way to pass environment variables to the build process, so secrets and other secured data aren't committed to source control. We recommend using [`dotenv`][dotenv] which will then expose environment variables. [Read more about `dotenv` and using environment variables here][envvars]. Then we can _use_ these environment variables and configure our plugin.
 
+## Restrictions and limitations
+
+This plugin has several limitations, please be aware of these:
+
+1. At the moment, fields that do not have at least one populated instance will not be created in the GraphQL schema. This can break your site when field values get removed. You may workaround with an extra content entry with all fields filled out.
+
+2. When using reference fields, be aware that this source plugin will automatically create the reverse reference. You do not need to create references on both content types.
+
+3. When working with environments, your access token has to have access to your desired enviornment and the `master` environment.
+
+4. Using the preview functionallity might result in broken content over time, as syncing data on preview is not officially supported by Contentful. Make sure to regulary clean your cache when using Contentfuls preview API.
+
 ### Using Delivery API
 
 ```javascript
@@ -120,14 +132,6 @@ Additional config which will get passed to [Contentfuls JS SDK](https://github.c
 
 Use this with caution, you might override values this plugin does set for you to connect to Contentful.
 
-## Notes on Contentful Content Models
-
-There are currently some things to keep in mind when building your content models at Contentful.
-
-1. At the moment, fields that do not have at least one populated instance will not be created in the GraphQL schema.
-
-2. When using reference fields, be aware that this source plugin will automatically create the reverse reference. You do not need to create references on both content types.
-
 ## How to query for nodes
 
 Two standard node types are available from Contentful: `Asset` and `ContentType`.

packages/gatsby-source-contentful/src/__tests__/fetch.js

@@ -258,8 +258,13 @@ describe(`Displays troubleshooting tips and detailed plugin options on contentfu
       err.responseData = { status: 404 }
       throw err
     })
+    const masterOptions = { ...options, environment: `master` }
+    const masterConfig = createPluginConfig(masterOptions)
 
-    await fetchData({ pluginConfig, reporter })
+    await fetchData({
+      pluginConfig: masterConfig,
+      reporter,
+    })
 
     expect(reporter.panic).toBeCalledWith(
       expect.objectContaining({
@@ -283,7 +288,7 @@ describe(`Displays troubleshooting tips and detailed plugin options on contentfu
 
     expect(formatPluginOptionsForCLI).toBeCalledWith(
       expect.objectContaining({
-        ...options,
+        ...masterOptions,
       }),
       {
         host: `Check if setting is correct`,
@@ -292,6 +297,46 @@ describe(`Displays troubleshooting tips and detailed plugin options on contentfu
     )
   })
 
+  it(`API 404 response handling with environment set`, async () => {
+    mockClient.getLocales.mockImplementation(() => {
+      const err = new Error(`error`)
+      err.responseData = { status: 404 }
+      throw err
+    })
+
+    await fetchData({ pluginConfig, reporter })
+
+    expect(reporter.panic).toBeCalledWith(
+      expect.objectContaining({
+        context: {
+          sourceMessage: expect.stringContaining(
+            `Unable to access your space. Check if environment is correct and your accessToken has access to the env and the master environments.`
+          ),
+        },
+      })
+    )
+
+    expect(reporter.panic).toBeCalledWith(
+      expect.objectContaining({
+        context: {
+          sourceMessage: expect.stringContaining(
+            `formatPluginOptionsForCLIMock`
+          ),
+        },
+      })
+    )
+
+    expect(formatPluginOptionsForCLI).toBeCalledWith(
+      expect.objectContaining({
+        ...options,
+      }),
+      {
+        accessToken: `Check if setting is correct`,
+        environment: `Check if setting is correct`,
+      }
+    )
+  })
+
   it(`API authorization error handling`, async () => {
     mockClient.getLocales.mockImplementation(() => {
       const err = new Error(`error`)

packages/gatsby-source-contentful/src/fetch.js

@@ -160,7 +160,24 @@ module.exports = async function contentfulFetch({
         },
       })
     } else if (e.responseData) {
-      if (e.responseData.status === 404) {
+      if (
+        e.responseData.status === 404 &&
+        contentfulClientOptions.environment &&
+        contentfulClientOptions.environment !== `master`
+      ) {
+        // environments need to have access to master
+        details = `Unable to access your space. Check if ${chalk.yellow(
+          `environment`
+        )} is correct and your ${chalk.yellow(
+          `accessToken`
+        )} has access to the ${chalk.yellow(
+          contentfulClientOptions.environment
+        )} and the ${chalk.yellow(`master`)} environments.`
+        errors = {
+          accessToken: `Check if setting is correct`,
+          environment: `Check if setting is correct`,
+        }
+      } else if (e.responseData.status === 404) {
         // host and space used to generate url
         details = `Endpoint not found. Check if ${chalk.yellow(
           `host`