@fourtwelvelabs/fetch-contentful 0.4.1 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,170 @@
 # @fourtwelvelabs/fetch-contentful
 
+## 1.1.0
+
+### Minor Changes
+
+- 4712d22: Added three ways to stay under (or get past) Contentful's `QUERY_TOO_BIG` limit, and to opt into Automatic Persisted Queries.
+  
+  **Every outgoing query is minified by default.** `graphql`'s `print()` is a pretty-printer — every level of nesting costs two bytes of indentation before a single field has been named, and Contentful's size limit counts that whitespace like anything else. Queries are now re-tokenized and rejoined with the least whitespace that keeps them distinct (the same idea as GQLMin), which is usually the single largest win available without touching a query's shape. Set `minifyQuery: false` to opt out — for example to read a request off the wire while debugging. `FetchContentfulError.query` and the annotated caret display always reflect whatever text was actually sent, minified or not.
+  
+  **A new `autoSplitOnSize` option (default `true`) adds a static-size pass on top of existing query splitting.** Today's `autoSplitNestedCollections` and `@split` decide what to split by shape — every nested `*Collection` field, or whatever's explicitly annotated — regardless of whether the query actually needs it. The new pass instead measures the (minified) query exactly as it will be sent and, only if it's still over `maxQuerySize` (7500 bytes by default), peels off the single largest remaining field — one-to-one references included, not just collections — and re-measures, repeating until it fits or nothing splittable is left. A query that still doesn't fit at that point is sent as-is; Contentful's own `QUERY_TOO_BIG` is the accurate error to see, since there's nothing left for this pass to remove.
+  
+  **A new `automaticPersistedQueries` option (default `false`) implements Contentful's APQ support.** The optimistic first attempt sends only a SHA-256 hash of the query; only the first time Contentful reports that hash unknown does the query text get sent (once), registering it for every request after. This is what actually raises Contentful's own size ceiling from 8 KB to 16 KB — `maxQuerySize` defaults to 15500 instead of 7500 whenever it's on — and it's off by default because it requires the Premium plan or above: on any other plan it would silently double every request's round trips for no benefit.
+
+## 1.0.0
+
+### Major Changes
+
+- **1.0.0 — the API is stable.**
+  
+  Everything the README documents is now covered by semver: `fetchContentful`,
+  `createFetchContentful`, every option on `FetchContentfulOptions`, the shape
+  of `FetchContentfulError`, and the exported helpers and types. Breaking
+  changes to any of them require a major release from here on.
+  
+  Two things are deliberately *not* part of that promise:
+  
+  - The `@split` directive's internal marker aliases (`_splitSysId`,
+    `_splitTypename`) and the generated subquery text. These are implementation
+    detail of query splitting, visible only if you inspect requests on the wire.
+  - The exact wording of error messages. `error.code`, `error.status`,
+    `error.errors` and `error.query` are stable; the prose is not.
+  
+  This release also clears out the last deprecation — see the `token` removal
+  above — so 1.0 starts with no options that are documented one way and behave
+  another.
+- **Breaking:** the deprecated `token` option is removed. Use `deliveryToken`
+  and `previewToken`.
+  
+  A single `token` could not serve both modes. It was applied to whichever mode
+  a call happened to be in, so a factory configured with one sent a *delivery*
+  token to any call that passed `preview: true` — authenticating against the
+  Preview API with a credential that cannot read drafts. The two-token form has
+  been the documented way to configure this since 0.4.0; this release stops
+  carrying the version that could silently authenticate against the wrong API.
+  
+  ```diff
+    export const fetchContentful = createFetchContentful({
+      space: 'abc123',
+  -   token: process.env.CONTENTFUL_ACCESS_TOKEN,
+  +   deliveryToken: process.env.CONTENTFUL_ACCESS_TOKEN,
+  +   previewToken: process.env.CONTENTFUL_PREVIEW_ACCESS_TOKEN,
+    });
+  ```
+  
+  If you only ever fetch published content, `deliveryToken` alone is enough —
+  `previewToken` is required only for calls that pass `preview: true`, and the
+  `CONFIG` error names exactly which one is missing.
+  
+  Passing `token` is now an unknown option: it is not silently ignored in a way
+  that sends an unauthenticated request, it simply is not a token, so the call
+  fails the same way passing none does.
+  
+  `EnvSettings.token`, the matching deprecated alias on `readEnvSettings()`, is
+  removed with it. Read `deliveryToken` instead — same value, and it says which
+  of the two tokens it is.
+- ffb17c0: Unpublished and deleted references no longer reject the call, and no longer
+  leave `null` holes in your collections.
+  
+  Contentful's GraphQL API does not omit a link it cannot resolve — a reference
+  whose target was deleted, or (on the Delivery API) never published. It returns
+  `null` **in that position**, on an HTTP 200, with an `UNRESOLVABLE_LINK` object
+  in the `errors` array:
+  
+  ```jsonc
+  {
+    "data": { "page": { "sectionsCollection": { "items": [{ "heading": "One" }, null] } } },
+    "errors": [{ "extensions": { "contentful": { "code": "UNRESOLVABLE_LINK", … } } }]
+  }
+  ```
+  
+  This library rejected on any non-empty `errors` array, so a single entry
+  unpublished by an editor failed the *entire* fetch — discarding a response that
+  was otherwise complete and correct. That is now the one GraphQL error that does
+  not reject on its own. Any other error still does, and one riding along with an
+  unresolvable link takes the whole list with it into `error.errors`.
+  
+  Left alone, the response then hands you `(Section | null)[]`, where the obvious
+  `sections.map((s) => s.heading)` throws — not in development, where everything
+  is published, but on the afternoon someone unpublishes one thing. So the null
+  positions are now **dropped by default**, in the data and in the return type:
+  
+  ```ts
+  const page = await fetchContentful<PageQuery>(QUERY);
+  page.sections.map((section) => section.heading); // Section[], no guard needed
+  ```
+  
+  Change it with the new `unresolvableLinks` option:
+  
+  | Value | Data | `items` type |
+  | --- | --- | --- |
+  | `'omit'` *(default)* | Null positions dropped | `Section[]` |
+  | `'null'` | Contentful's response, untouched | `(Section \| null)[]` |
+  | `'error'` | Rejects with a `GRAPHQL` error | — |
+  
+  `'error'` restores the pre-1.0 behavior exactly.
+  
+  Because dropping a null silently hides a real editorial mistake, `onUnresolvableLink`
+  is called once per request that carried one, with the errors Contentful sent —
+  each holding the `linkId`, `field` and `type` of the missing reference. Anything
+  it throws is swallowed: it runs inside the retry loop, so a failing logger would
+  otherwise look like a failed request and send the query again.
+  
+  ```ts
+  export const fetchContentful = createFetchContentful({
+    onUnresolvableLink: (errors) => logger.warn({ errors }, 'broken Contentful reference'),
+  });
+  ```
+  
+  Two limits worth knowing. A *one-to-one* reference has no position to drop, so
+  an unresolvable one stays `null` on its field in every mode but `'error'`. And
+  the Preview API resolves drafts, so the same query can legitimately return
+  different array lengths in preview and production — usually the explanation when
+  a page looks right in Draft Mode and short in production.
+  
+  Also exported: `omitUnresolvedLinks`, `isUnresolvableLinkError`,
+  `partitionUnresolvableLinks`, and the type-level `OmitUnresolvedLinks<T>` /
+  `UnresolvableLinkMode`.
+
+### Minor Changes
+
+- ffb17c0: Errors from Contentful now show the query, with a caret under the line the
+  error points at.
+  
+  Contentful reports `line` and `column` for most rejected queries, but those
+  coordinates are into the query **as sent** — after fragments are inlined,
+  `preview`/`locale` arguments injected, and split fields hoisted into
+  generated subqueries. Line 6 of a document nobody has ever seen is not a
+  clue, so the query now comes along with the message:
+  
+  ```
+  Contentful returned GraphQL errors: Cannot query field "titel" on type "Page".
+  
+    2 |   pageCollection(where: {slug: $slug}, limit: 1) {
+    3 |     items {
+  > 4 |       titel
+      |       ^ Cannot query field "titel" on type "Page".
+    5 |     }
+  ```
+  
+  The marked line is colored when stderr is a terminal, and left as plain text
+  when it is not, so log pipelines still get something they can store.
+  `NO_COLOR` and `FORCE_COLOR` are honored. No dependency was added.
+  
+  Two related changes come with it:
+  
+  - A non-2xx response is no longer reported by status alone. Contentful
+    answers an invalid query with HTTP 400 and the same `errors` array a 200
+    would have carried, so those messages (and their locations) now reach the
+    error instead of being dropped on the floor. 5xx bodies are still ignored —
+    they explain nothing and the request is on its way to a retry.
+  - `FetchContentfulError` carries the `query` that failed.
+  
+  Set `annotateQueryOnError: false` to keep messages to a single line. The
+  formatter is exported as `annotateQuery(query, errors, options)` for custom
+  reporting.
+
 ## 0.4.1
 
 ### Patch Changes

package/README.md

@@ -3,10 +3,12 @@
 A foolproof, type-safe GraphQL fetching utility for Contentful. One function in, shaped data out:
 
 - **Automatic query splitting** — nested reference collections (and `@split`-annotated one-to-one references) are broken into separate subqueries, fetched in id batches, and stitched back into the original response shape. Fully recursive, so deeply nested queries never hit Contentful's query complexity limit.
+- **Automatic query minification** — every outgoing query has its insignificant whitespace stripped before it's sent, which is usually the single biggest lever against Contentful's `QUERY_TOO_BIG` limit. Combined with a static-size pass (`autoSplitOnSize`, on by default) that splits off more fields only when a query still measures too big, and optional support for Automatic Persisted Queries. See [Staying under the query size limit](#staying-under-the-query-size-limit).
 - **Automatic retries** — transient failures (network errors, 408/429/5xx) retry with exponential backoff + jitter, honoring `Retry-After`. Configurable, default 5.
-- **Response shaping (built in)** — before the promise resolves, every `fooCollection.items` in the response becomes `foo` (a plain array), at runtime *and* in the return type. No separate call needed.
-- **Single-root unwrapping (built in)** — when a query has one root field, the promise resolves with that field's contents directly (`data` *is* the array/entry, not `{ siteSettings: ... }`). Multi-root queries stay wrapped.
+- **Response shaping (built in)** — before the promise resolves, every `fooCollection.items` in the response becomes `foo` (a plain array), at runtime _and_ in the return type. No separate call needed.
+- **Single-root unwrapping (built in)** — when a query has one root field, the promise resolves with that field's contents directly (`data` _is_ the array/entry, not `{ siteSettings: ... }`). Multi-root queries stay wrapped.
 - **No preview/locale boilerplate** — `preview` and `locale` are injected as arguments onto your query's root fields automatically (Contentful cascades them to every nested field), so queries never need to declare or thread them. The locale defaults to `en-US`.
+- **No null holes in collections (built in)** — an unpublished or deleted reference comes back from Contentful as a `null` _inside_ `items`. Those positions are dropped before the promise resolves, at runtime and in the return type, so `items.map(...)` is safe. Configurable via `unresolvableLinks`.
 - **All-or-nothing promise** — resolves only when every request in the tree succeeded; rejects with a typed `FetchContentfulError` if anything fails.
 - **Locale awareness** — locales are fetched from Contentful once and cached in-module, so validation costs nothing per fetch.
 - **Inferred types, optionally** — pass a [gql.tada](https://gql-tada.0no.co) or graphql-codegen document and the result and variable types come from the query itself. One command (`tada-init`) sets gql.tada up against your space. See [Typed queries with gql.tada](#typed-queries-with-gqltada).
@@ -30,24 +32,24 @@ If `space` or the appropriate token can't be resolved, the promise rejects with
 
 ### Environment variables
 
-| Setting | Neutral name | Next.js client-safe name |
-| --- | --- | --- |
-| `space` | `CONTENTFUL_SPACE_ID` | `NEXT_PUBLIC_CONTENTFUL_SPACE_ID` |
-| `environment` | `CONTENTFUL_ENVIRONMENT` | `NEXT_PUBLIC_CONTENTFUL_ENVIRONMENT` |
-| `deliveryToken` | `CONTENTFUL_ACCESS_TOKEN` | `NEXT_PUBLIC_CONTENTFUL_ACCESS_TOKEN` |
-| `previewToken` | `CONTENTFUL_PREVIEW_ACCESS_TOKEN` | **none, by design** |
+| Setting         | Neutral name                      | Next.js client-safe name              |
+| --------------- | --------------------------------- | ------------------------------------- |
+| `space`         | `CONTENTFUL_SPACE_ID`             | `NEXT_PUBLIC_CONTENTFUL_SPACE_ID`     |
+| `environment`   | `CONTENTFUL_ENVIRONMENT`          | `NEXT_PUBLIC_CONTENTFUL_ENVIRONMENT`  |
+| `deliveryToken` | `CONTENTFUL_ACCESS_TOKEN`         | `NEXT_PUBLIC_CONTENTFUL_ACCESS_TOKEN` |
+| `previewToken`  | `CONTENTFUL_PREVIEW_ACCESS_TOKEN` | **none, by design**                   |
 
 There is no environment variable for the locale: it defaults to **`en-US`**, and a project that wants a different one sets it once with `createFetchContentful` (below).
 
 The library reads the already-populated `process.env`; loading `.env` / `.env.local` files from disk is your platform's job (Next.js, Vite, dotenv all do this), so precedence between those files always matches your framework's rules.
 
-**In a Next.js project you don't need both names.** Set only the `NEXT_PUBLIC_` variant and it works everywhere: the server reads it like any other env var (the prefix only controls *client* exposure), and client bundles get it because the library reads these variables with literal `process.env.NEXT_PUBLIC_...` accesses — the exact pattern Next's build-time inliner string-replaces. Server-only projects (or any other framework) should use the neutral names. This applies to the space, the environment and the delivery token; the preview token has no client-safe name, for the reason below.
+**In a Next.js project you don't need both names.** Set only the `NEXT_PUBLIC_` variant and it works everywhere: the server reads it like any other env var (the prefix only controls _client_ exposure), and client bundles get it because the library reads these variables with literal `process.env.NEXT_PUBLIC_...` accesses — the exact pattern Next's build-time inliner string-replaces. Server-only projects (or any other framework) should use the neutral names. This applies to the space, the environment and the delivery token; the preview token has no client-safe name, for the reason below.
 
 ### The preview token is never read from a `NEXT_PUBLIC_` variable
 
 Next.js exposes `NEXT_PUBLIC_` variables to the browser by string-replacing literal `process.env.NEXT_PUBLIC_…` accesses at build time. This library contains such accesses, so if it read the preview token from a prefixed name, setting that variable would bake the token into your public JavaScript — whether or not any client code ever asked for preview content. Importing the library would be enough.
 
-A delivery token is read-only and commonly public. A **preview token reads unpublished content**, so it is resolved only from the unprefixed `CONTENTFUL_PREVIEW_ACCESS_TOKEN`. In Next.js that name is still readable on the server — the prefix only controls *client* exposure — so server-side preview (Draft Mode, route handlers, server components) works unchanged.
+A delivery token is read-only and commonly public. A **preview token reads unpublished content**, so it is resolved only from the unprefixed `CONTENTFUL_PREVIEW_ACCESS_TOKEN`. In Next.js that name is still readable on the server — the prefix only controls _client_ exposure — so server-side preview (Draft Mode, route handlers, server components) works unchanged.
 
 If you have decided that your app genuinely needs preview in the browser, pass `previewToken` explicitly. Shipping it is then your deliberate choice rather than something the library did on your behalf.
 
@@ -60,9 +62,9 @@ For utility-specific configuration, create a configured instance once and import
 import { createFetchContentful } from '@fourtwelvelabs/fetch-contentful';
 
 export const fetchContentful = createFetchContentful({
-  space: 'abc123',       // or leave unset to use env vars
-  locale: 'de-DE',       // override the 'en-US' default for the whole project
-  retries: 3,
+  space: 'abc123', // or leave unset to use env vars
+  locale: 'de-DE', // override the 'en-US' default for the whole project
+  retries: 3
 });
 
 // Configure both tokens once, and every call picks the right one:
@@ -73,10 +75,11 @@ export const fetchContentful = createFetchContentful({
 ```ts
 // anywhere else
 import { fetchContentful } from '@/lib/contentful';
+
 const data = await fetchContentful<PagesQuery>(QUERY);
 ```
 
-Per-call options override factory defaults (top-level shallow merge). One caveat: `shapeResponseData: false` and `unwrapRootField: false` change the return *type* only when written on the call itself, so set those per call rather than as factory defaults.
+Per-call options override factory defaults (top-level shallow merge). One caveat: `shapeResponseData: false`, `unwrapRootField: false` and `unresolvableLinks: 'null'` change the return _type_ only when written on the call itself, so set those per call rather than as factory defaults. Set on the factory they still take effect at runtime — the type just assumes the default.
 
 ## Quick start
 
@@ -107,7 +110,7 @@ const data = await fetchContentful<PagesQuery>(
       }
     }
   `,
-  { variables: { limit: 10 }, preview: true, locale: 'en-US' },
+  { variables: { limit: 10 }, preview: true, locale: 'en-US' }
 );
 
 // Shaped and unwrapped: the single root field's contents come back directly.
@@ -137,14 +140,14 @@ import type { introspection } from './contentful-env.d.ts';
 
 export const graphql = initGraphQLTada<{
   introspection: introspection; // your space's content model, as types
-  scalars: ContentfulScalars;   // DateTime → string, JSON → JsonValue, …
+  scalars: ContentfulScalars; // DateTime → string, JSON → JsonValue, …
 }>();
 
 export { readFragment } from 'gql.tada';
 export type { FragmentOf, ResultOf, VariablesOf } from 'gql.tada';
 ```
 
-`graphql` is a tagged template function doing two jobs at once: at runtime it parses your query into a GraphQL document, and at compile time it infers that query's result and variable types from the schema. It can't be an export of this package — it has to be bound to *your* space — which is why the command generates it.
+`graphql` is a tagged template function doing two jobs at once: at runtime it parses your query into a GraphQL document, and at compile time it infers that query's result and variable types from the schema. It can't be an export of this package — it has to be bound to _your_ space — which is why the command generates it.
 
 Restart the TypeScript server so `@0no-co/graphqlsp` loads (it's what gives you autocomplete and field validation inside the backticks). Then import `graphql` from wherever `tada-init` put it, and queries type themselves:
 
@@ -158,7 +161,11 @@ const PageQuery = graphql(`
     pageCollection(where: { slug: $slug }, limit: 1) {
       items {
         title
-        sectionsCollection { items { heading } }
+        sectionsCollection {
+          items {
+            heading
+          }
+        }
       }
     }
   }
@@ -198,7 +205,7 @@ import { draftMode } from 'next/headers';
 const { isEnabled } = await draftMode();
 const data = await fetchContentful<PageQuery>(PAGE_QUERY, {
   preview: isEnabled,
-  cache: isEnabled ? 'no-store' : undefined,
+  cache: isEnabled ? 'no-store' : undefined
 });
 ```
 
@@ -216,33 +223,45 @@ export const getStaticProps: GetStaticProps = async ({ preview = false }) => {
 ```ts
 fetchContentful(query, {
   // Contentful targeting
-  space: 'abc123',            // default: NEXT_PUBLIC_CONTENTFUL_SPACE
-  environment: 'master',      // default: NEXT_PUBLIC_CONTENTFUL_ENVIRONMENT ?? 'master'
-  preview: false,             // default: false
-  locale: 'en-US',            // default: 'en-US'. null sends no locale at all
-  validateLocale: true,       // reject with LOCALE if locale isn't configured
-  deliveryToken: '...',       // CDA token, used when preview is false
-  previewToken: '...',        // CPA token, used when preview is true
+  space: 'abc123', // default: NEXT_PUBLIC_CONTENTFUL_SPACE
+  environment: 'master', // default: NEXT_PUBLIC_CONTENTFUL_ENVIRONMENT ?? 'master'
+  preview: false, // default: false
+  locale: 'en-US', // default: 'en-US'. null sends no locale at all
+  validateLocale: true, // reject with LOCALE if locale isn't configured
+  deliveryToken: '...', // CDA token, used when preview is false
+  previewToken: '...', // CPA token, used when preview is true
 
   // Request behavior
   variables: { slug: 'home' },
-  retries: 5,                 // retry count after the initial attempt
-  retryDelayMs: 250,          // base backoff delay
-  maxRetryDelayMs: 8000,      // backoff ceiling
-  signal: controller.signal,  // AbortSignal, forwarded to fetch
-  cache: 'no-store',          // RequestCache, forwarded to fetch
-  next: { revalidate: 60 },   // Next.js App Router fetch extensions
-  fetch: customFetch,         // injectable fetch (testing / polyfills)
+  retries: 5, // retry count after the initial attempt
+  retryDelayMs: 250, // base backoff delay
+  maxRetryDelayMs: 8000, // backoff ceiling
+  signal: controller.signal, // AbortSignal, forwarded to fetch
+  cache: 'no-store', // RequestCache, forwarded to fetch
+  next: { revalidate: 60 }, // Next.js App Router fetch extensions
+  fetch: customFetch, // injectable fetch (testing / polyfills)
 
   // Response handling
-  shapeResponseData: true,          // false = skip collection shaping
-  unwrapRootField: true,            // false = keep single-root responses wrapped
+  shapeResponseData: true, // false = skip collection shaping
+  unwrapRootField: true, // false = keep single-root responses wrapped
+  unresolvableLinks: 'omit', // 'omit' | 'null' | 'error' — broken references
+
+  // Diagnostics
+  annotateQueryOnError: true, // false = keep error messages to one line
+  onUnresolvableLink: (errors) => {}, // notified when a broken reference is tolerated
 
   // Query rewriting
-  autoInjectArgs: true,             // inject preview/locale args on root fields
+  autoInjectArgs: true, // inject preview/locale args on root fields
   autoSplitNestedCollections: true, // auto-detect non-root *Collection fields
-                                    // (@split works regardless — see below)
-  splitBatchSize: 50,               // parent ids per subquery
+  // (@split works regardless — see below)
+  splitBatchSize: 50, // parent ids per subquery
+
+  // Query size
+  minifyQuery: true, // strip insignificant whitespace before sending
+  autoSplitOnSize: true, // split further if the query still measures too big
+  maxQuerySize: 7500, // byte budget that triggers autoSplitOnSize
+  // (15500 by default when automaticPersistedQueries is on — see below)
+  automaticPersistedQueries: false // requires the Premium plan or above
 });
 ```
 
@@ -286,7 +305,9 @@ Note that pagination metadata (`total`, `skip`, `limit`) selected alongside `ite
 query {
   pagedResults: pageCollection(limit: 10, skip: 20) {
     total
-    items { title }
+    items {
+      title
+    }
   }
 }
 # resolves as data.pagedResults: { total: number; items: [...] }
@@ -296,6 +317,63 @@ The generic you pass (`fetchContentful<PagesQuery>`) should always describe the
 
 The standalone `shapeData` / `ShapeCollections` exports exist only for advanced cases where you're transforming Contentful data that came from somewhere else; you never need them when using `fetchContentful`.
 
+## Unpublished and deleted references
+
+Contentful's GraphQL API does not omit a reference it cannot resolve — it returns `null` **in that position**:
+
+```jsonc
+// what Contentful sends when sections[1] was unpublished
+{
+  "data": { "page": { "sectionsCollection": { "items": [{ "heading": "One" }, null] } } },
+  "errors": [{ "message": "Query execution error. Link to entry 'xyz' … cannot be resolved",
+               "extensions": { "contentful": { "code": "UNRESOLVABLE_LINK", … } } }]
+}
+```
+
+Note the HTTP status is **200** and the rest of the data is exactly what you asked for. Only the missing entry is missing.
+
+That leaves `items` typed `(Section | null)[]`, and the natural `sections.map((s) => s.heading)` throws — not in development, where everything is published, but on the afternoon an editor unpublishes one thing. So by default this library **drops those positions** and resolves with the entries that exist:
+
+```ts
+const page = await fetchContentful<PageQuery>(QUERY);
+page.sections.map((section) => section.heading); // Section[], no null check needed
+```
+
+The return type is narrowed to match, so TypeScript agrees with the runtime rather than forcing a guard that can never fire.
+
+### Choosing a different behavior
+
+| `unresolvableLinks`  | Data                             | `items` type          |
+| -------------------- | -------------------------------- | --------------------- |
+| `'omit'` _(default)_ | Null positions dropped           | `Section[]`           |
+| `'null'`             | Contentful's response, untouched | `(Section \| null)[]` |
+| `'error'`            | Rejects with a `GRAPHQL` error   | —                     |
+
+`'error'` is what this library did before 1.0. It is the strictest option and the one to reach for if a broken reference should stop a build rather than quietly shorten a list.
+
+### Keep the broken references visible
+
+Dropping a null silently hides a real editorial mistake, so pair any non-`'error'` mode with a reporter:
+
+```ts
+export const fetchContentful = createFetchContentful({
+  onUnresolvableLink: (errors) => {
+    for (const error of errors) {
+      const { linkId, field, type } = error.extensions.contentful.details;
+      logger.warn({ linkId, field, type }, 'Contentful reference could not be resolved');
+    }
+  }
+});
+```
+
+It is called once per request that carried a broken link, never in `'error'` mode (the call rejects with those same errors instead), and anything it throws is swallowed — a logger must not be able to fail, or silently retry, a fetch that otherwise succeeded.
+
+### Two things this does not do
+
+**A one-to-one reference stays `null`.** `page.hero` has no position to drop, only a field with no value, so it remains `null` in every mode but `'error'` and still needs a check.
+
+**Preview and production legitimately disagree.** The Preview API resolves drafts, so a link that is a hole in production is a real entry in preview. The same query can return different array lengths in the two modes — which is usually the explanation when a page looks right in Draft Mode and short in production.
+
 ## How splitting works
 
 Contentful rejects queries whose complexity exceeds its limit — usually caused by nested reference fields multiplying. `fetch-contentful` avoids this transparently:
@@ -312,9 +390,12 @@ query {
   pageCollection {
     items {
       title
-      hero @split {        # fetched in a second, cheaper query
+      hero @split {
+        # fetched in a second, cheaper query
         headline
-        image { url }
+        image {
+          url
+        }
       }
     }
   }
@@ -335,7 +416,7 @@ Turn auto-splitting off and annotate only the fields that actually blow the comp
 
 ```ts
 const data = await fetchContentful(QUERY, {
-  autoSplitNestedCollections: false,
+  autoSplitNestedCollections: false
 });
 ```
 
@@ -345,14 +426,24 @@ query {
     items {
       title
       # Small and cheap: fetched inline, in the same request.
-      seo { description }
-      tagsCollection(limit: 5) { items { name } }
+      seo {
+        description
+      }
+      tagsCollection(limit: 5) {
+        items {
+          name
+        }
+      }
 
       # The expensive one: fetched separately, batched by parent id.
       sectionsCollection(limit: 50) @split {
         items {
           heading
-          mediaCollection(limit: 10) { items { url } }
+          mediaCollection(limit: 10) {
+            items {
+              url
+            }
+          }
         }
       }
     }
@@ -368,14 +459,43 @@ That sends two requests instead of the four auto mode would. Splits still nest r
 
 ```graphql
 query {
-  pageCollection @split {   # ✗ CONFIG error
-    items { title }
+  pageCollection @split {
+    # ✗ CONFIG error
+    items {
+      title
+    }
   }
 }
 ```
 
 A root field has no parent entry to stitch its result back onto, so there is nothing for the directive to do. Reach for `limit` and `skip` on the field itself instead. (Before 0.2.1 the directive was silently stripped here — if an existing query relies on that, remove the directive.)
 
+## Staying under the query size limit
+
+Separately from the complexity limit that query splitting exists for, Contentful also rejects a query whose **text** — whitespace and newlines included — exceeds [8 KB](https://www.contentful.com/developers/docs/references/graphql/overview/#query-size-limits) with a `QUERY_TOO_BIG` error. Three settings work together to avoid it, all on by default except the last:
+
+1. **`minifyQuery` (default `true`)** — every outgoing query is re-tokenized and rejoined with the least whitespace that keeps it valid, the same effect a tool like [GQLMin](https://github.com/drwpow/gqlmin) has. `graphql`'s pretty-printer spends two bytes of indentation per level of nesting before naming a single field, so this is usually the single biggest lever available, and it changes nothing about what the query asks for. Disable it only to read a request off the wire while debugging — `FetchContentfulError.query` and the annotated caret display always show whatever text was actually sent, so turning it off does not lose any diagnostic power.
+
+2. **`autoSplitOnSize` (default `true`)** — a static-size pass that runs after ordinary query splitting. `autoSplitNestedCollections` and `@split` decide what to split by a query's *shape*: every nested `*Collection` field, or whatever's explicitly annotated, whether or not the query actually needs the help. This pass instead measures the query exactly as it will be sent and, only when it's still over `maxQuerySize`, peels off the single largest remaining field — a one-to-one reference works exactly as well as a collection — and re-measures, repeating until it fits or nothing splittable is left. A query that still doesn't fit at that point is sent as-is: Contentful's own `QUERY_TOO_BIG` is the accurate error to see, since there's nothing left for this library to remove.
+
+   ```ts
+   const data = await fetchContentful(QUERY, {
+     maxQuerySize: 6000 // lower the default 7500-byte budget
+   });
+   ```
+
+3. **`automaticPersistedQueries` (default `false`)** — implements Contentful's [Automatic Persisted Queries](https://www.contentful.com/developers/docs/references/graphql/automatic-persisted-queries/) support, adopted from Apollo's spec. The optimistic first attempt sends only a SHA-256 hash of the query in `extensions`, with no `query` field at all; only the first time Contentful reports that hash unknown does the query text get sent (once, alongside the hash, which registers it). Every request after that — from this process or any other client — hits on the hash alone. This is what actually raises Contentful's ceiling from 8 KB to 16 KB, which is why `maxQuerySize` defaults to `15500` instead of `7500` whenever this is on.
+
+   **Requires the Premium plan or above.** On any other plan every request would silently cost two round trips forever instead of one, which is why this defaults to `false` rather than detecting the plan automatically — there is no API to check it from the client.
+
+   ```ts
+   const data = await fetchContentful(QUERY, {
+     automaticPersistedQueries: true
+   });
+   ```
+
+None of this touches `autoSplitNestedCollections` or `@split`, which remain about the complexity limit, not the size limit — a query can be simple enough to never need splitting and still be big enough (long field lists, deep `where` filters) to trip `QUERY_TOO_BIG`, which is exactly the case `autoSplitOnSize` exists for.
+
 ## Error handling
 
 Every rejection is a `FetchContentfulError`:
@@ -387,32 +507,82 @@ try {
   await fetchContentful(QUERY);
 } catch (error) {
   if (isFetchContentfulError(error)) {
-    error.code;   // 'CONFIG' | 'NETWORK' | 'HTTP' | 'GRAPHQL' | 'STITCH' | 'LOCALE'
+    error.code; // 'CONFIG' | 'NETWORK' | 'HTTP' | 'GRAPHQL' | 'STITCH' | 'LOCALE'
     error.status; // HTTP status, when applicable
     error.errors; // GraphQL errors, when applicable
+    error.query; // the query as sent, when a request was made
   }
 }
 ```
 
+A GraphQL response that reports **only** unresolvable links is the one thing that does not reject — see [Unpublished and deleted references](#unpublished-and-deleted-references). Any other error in the `errors` array still does, and if one rides along with an unresolvable link the whole list reaches `error.errors`.
+
+### Rejected queries are printed back with the bad line marked
+
+Contentful reports a `line` and `column` for most queries it rejects — into
+the query **as sent**, which is not the query you wrote: fragments have been
+inlined, `preview`/`locale` arguments injected, and `@split` fields hoisted
+into generated subqueries. So the query comes along with the message:
+
+```text
+Contentful returned GraphQL errors: Cannot query field "titel" on type "Page".
+
+  2 |   pageCollection(where: {slug: $slug}, limit: 1) {
+  3 |     items {
+> 4 |       titel
+    |       ^ Cannot query field "titel" on type "Page".
+  5 |     }
+```
+
+The marked line is colored when stderr is a terminal and plain when it is
+not, so a log pipeline still receives text it can store. `NO_COLOR` and
+`FORCE_COLOR` are honored.
+
+This also applies to the HTTP 400 Contentful returns for a query it cannot
+validate: the `errors` in that response body reach `error.errors` and the
+message, rather than being reported as a bare status.
+
+Pass `annotateQueryOnError: false` to keep messages to a single line. The
+query is still on the error either way, and the formatter is exported if you
+would rather render it yourself:
+
+```ts
+import { annotateQuery, isFetchContentfulError } from '@fourtwelvelabs/fetch-contentful';
+
+if (isFetchContentfulError(error) && error.query && error.errors) {
+  logger.debug(annotateQuery(error.query, error.errors, { contextLines: 5 }));
+}
+```
+
+`contextLines` defaults to `3`; pass `Infinity` to print the whole query, and
+`color: true | false` to override the terminal detection.
+
 ## Other exports
 
 ```ts
 import {
+  annotateQuery, // render a query with a caret under a reported error
+  clearLocaleCache, // reset the cache (tests, revalidation hooks)
   createFetchContentful, // project-level defaults (see Configuration)
-  getLocales,        // cached locale lookup (space/env/preview keyed)
-  clearLocaleCache,  // reset the cache (tests, revalidation hooks)
-  shapeData,         // the runtime collection shaper (already applied by fetchContentful)
-  unwrapSingleRoot,  // the runtime single-root unwrapper (already applied too)
-  inlineFragments,   // fragment inliner (advanced AST use)
-  injectRootArgs,    // the preview/locale argument injector (advanced AST use)
+  getLocales, // cached locale lookup (space/env/preview keyed)
+  injectRootArgs, // the preview/locale argument injector (advanced AST use)
+  inlineFragments, // fragment inliner (advanced AST use)
+  isUnresolvableLinkError, // classify one GraphQL error as a broken link
+  minifyQuery, // the whitespace minifier (already applied by fetchContentful)
+  omitUnresolvedLinks, // the runtime null-position dropper (applied too)
+  partitionUnresolvableLinks, // split an errors array into broken links vs the rest
+  shapeData, // the runtime collection shaper (already applied by fetchContentful)
+  unwrapSingleRoot, // the runtime single-root unwrapper (already applied too)
+  type FetchContentfulOptions,
+  type OmitUnresolvedLinks,
+  type ShapeCollections,
+  type UnresolvableLinkMode
 } from '@fourtwelvelabs/fetch-contentful';
-import type { ShapeCollections, FetchContentfulOptions } from '@fourtwelvelabs/fetch-contentful';
-
 // Type-only subpath, for wiring gql.tada up by hand (see docs/tada.md).
 import type { ContentfulScalars, JsonValue } from '@fourtwelvelabs/fetch-contentful/tada';
 ```
 
-`ShapeCollections<T>` and `UnwrapSingleRoot<T>` are the type-level twins of `shapeData` and `unwrapSingleRoot`. Neither is needed alongside `fetchContentful` (shaping is built into it) — they're for shaping Contentful-shaped data that arrived some other way.
+`ShapeCollections<T>`, `UnwrapSingleRoot<T>` and `OmitUnresolvedLinks<T>` are the type-level twins of `shapeData`, `unwrapSingleRoot` and `omitUnresolvedLinks`. Neither is needed alongside `fetchContentful` (shaping is built into it) — they're for shaping Contentful-shaped data that arrived some other way.
 
 ## Limitations
 
@@ -420,6 +590,7 @@ import type { ContentfulScalars, JsonValue } from '@fourtwelvelabs/fetch-content
 - Splitting relies on Contentful's naming conventions: a parent of type `BlogPost` must be re-queryable via `blogPostCollection`. Custom schemas that break this convention will fail with a `STITCH` error rather than return wrong data.
 - Root-level collections are never split (there is no parent to stitch onto); only nested ones are.
 - `@split`/auto-split fields inside `... on Entry { ... }` fragments are treated as unconditional, since `Entry` is an interface and never matches a concrete `__typename`.
+- `autoSplitOnSize` picks candidates by measured size, not by name, so it can choose a field whose parent type does not follow Contentful's `blogPostCollection` naming convention — the same `STITCH` error above, just reached automatically rather than by writing `@split` yourself.
 
 ## Development