@fourtwelvelabs/fetch-contentful 0.4.1 → 1.1.0

package/dist/index.mjs

@@ -1,12 +1,113 @@
-import { Kind, parse, print, visit } from 'graphql';
+import { TokenKind, Lexer, Source, Kind, parse, print, visit } from 'graphql';
 
 // src/index.ts
 
+// src/annotate.ts
+var ESC = String.fromCharCode(27);
+var ANSI = {
+  reset: `${ESC}[0m`,
+  bold: `${ESC}[1m`,
+  dim: `${ESC}[2m`,
+  red: `${ESC}[31m`
+};
+var DEFAULT_CONTEXT_LINES = 3;
+function supportsColor() {
+  if (typeof process === "undefined" || !process.env) {
+    return false;
+  }
+  const forced = process.env.FORCE_COLOR;
+  const disabled = process.env.NO_COLOR;
+  if (forced) {
+    return forced !== "0" && forced !== "false";
+  }
+  if (disabled) {
+    return false;
+  }
+  return Boolean(process.stderr?.isTTY);
+}
+function makePalette(enabled) {
+  const paint = (code) => (text) => enabled ? `${code}${text}${ANSI.reset}` : text;
+  return {
+    dim: paint(ANSI.dim),
+    red: paint(ANSI.red),
+    bold: paint(ANSI.bold)
+  };
+}
+function collectMarks(errors, lineCount) {
+  const marks = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const error of errors) {
+    for (const location of error.locations ?? []) {
+      const line = Math.trunc(location.line);
+      if (!(line >= 1 && line <= lineCount)) continue;
+      const reported = Math.trunc(location.column);
+      const column = reported >= 1 ? reported : 1;
+      const key = `${line}:${column}:${error.message}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      marks.push({ line, column, message: error.message });
+    }
+  }
+  return marks.sort((a, b) => a.line - b.line || a.column - b.column);
+}
+function excerptsFor(marks, lineCount, contextLines) {
+  const excerpts = [];
+  for (const mark of marks) {
+    const start = Math.max(1, mark.line - contextLines);
+    const end = Math.min(lineCount, mark.line + contextLines);
+    const previous = excerpts[excerpts.length - 1];
+    if (previous && start <= previous.end + 1) {
+      previous.end = Math.max(previous.end, end);
+    } else {
+      excerpts.push({ start, end });
+    }
+  }
+  return excerpts;
+}
+function annotateQuery(query, errors, options = {}) {
+  const lines = query.split("\n");
+  const marks = collectMarks(errors, lines.length);
+  if (marks.length === 0) return "";
+  const color = makePalette(options.color ?? supportsColor());
+  const excerpts = excerptsFor(marks, lines.length, options.contextLines ?? DEFAULT_CONTEXT_LINES);
+  const gutter = String(
+    excerpts.reduce((widest, excerpt) => Math.max(widest, excerpt.end), 0)
+  ).length;
+  const blank = " ".repeat(gutter);
+  const out = [];
+  for (const [index, excerpt] of excerpts.entries()) {
+    if (index > 0) out.push(color.dim(`  ${blank} ...`));
+    const window = lines.slice(excerpt.start - 1, excerpt.end);
+    for (const [offset, source] of window.entries()) {
+      const line = excerpt.start + offset;
+      const number = String(line).padStart(gutter, " ");
+      const here = marks.filter((mark) => mark.line === line);
+      if (here.length === 0) {
+        out.push(`${color.dim(`  ${number} |`)} ${source}`);
+        continue;
+      }
+      out.push(`${color.red(`> ${number} |`)} ${color.bold(source)}`);
+      for (const mark of here) {
+        const lead = " ".repeat(mark.column - 1);
+        out.push(`${color.dim(`  ${blank} |`)} ${lead}${color.red(`^ ${mark.message}`)}`);
+      }
+    }
+  }
+  return out.join("\n");
+}
+
 // src/errors.ts
 var FetchContentfulError = class extends Error {
   code;
   status;
   errors;
+  /**
+   * The GraphQL query exactly as it was sent to Contentful — fragments
+   * inlined, arguments injected, and (for a subquery) generated. This is
+   * the text the `line`/`column` in {@link FetchContentfulError.errors}
+   * point into, so it is the text to annotate; see `annotateQuery`.
+   */
+  query;
   /** Internal: whether a retry may succeed. */
   retryable;
   /** Internal: server-requested retry delay (from Retry-After), in ms. */
@@ -17,6 +118,7 @@ var FetchContentfulError = class extends Error {
     this.code = options.code;
     this.status = options.status;
     this.errors = options.errors;
+    this.query = options.query;
     this.retryable = options.retryable ?? false;
     this.retryAfterMs = options.retryAfterMs;
   }
@@ -24,6 +126,48 @@ var FetchContentfulError = class extends Error {
 function isFetchContentfulError(value) {
   return value instanceof FetchContentfulError;
 }
+var WORD_LIKE = /* @__PURE__ */ new Set([TokenKind.NAME, TokenKind.INT, TokenKind.FLOAT]);
+function minifyQuery(query) {
+  const lexer = new Lexer(new Source(query));
+  let previousKind;
+  let out = "";
+  for (let token = lexer.advance(); token.kind !== TokenKind.EOF; token = lexer.advance()) {
+    if (previousKind && WORD_LIKE.has(previousKind) && WORD_LIKE.has(token.kind)) {
+      out += " ";
+    }
+    out += query.slice(token.start, token.end);
+    previousKind = token.kind;
+  }
+  return out;
+}
+
+// src/persisted-query.ts
+var PERSISTED_QUERY_VERSION = 1;
+function toHex(bytes) {
+  let hex = "";
+  for (const byte of bytes) {
+    hex += byte.toString(16).padStart(2, "0");
+  }
+  return hex;
+}
+async function sha256Hex(query) {
+  const data = new TextEncoder().encode(query);
+  const subtle = globalThis.crypto?.subtle;
+  if (subtle) {
+    const digest = await subtle.digest("SHA-256", data);
+    return toHex(new Uint8Array(digest));
+  }
+  const { createHash } = await import('crypto');
+  return createHash("sha256").update(data).digest("hex");
+}
+function persistedQueryExtensions(sha256Hash) {
+  return { persistedQuery: { version: PERSISTED_QUERY_VERSION, sha256Hash } };
+}
+function isPersistedQueryNotFoundError(error) {
+  if (error.message === "PersistedQueryNotFound") return true;
+  const extensions = error.extensions;
+  return extensions?.code === "PERSISTED_QUERY_NOT_FOUND";
+}
 
 // src/retry.ts
 function defaultSleep(ms) {
@@ -90,6 +234,9 @@ function withDirective(field, name) {
 function responseKeyOf(field) {
   return field.alias?.value ?? field.name.value;
 }
+function hasResponseKey(selection, key) {
+  return selection.kind === Kind.FIELD && responseKeyOf(selection) === key;
+}
 function isCollectionField(field) {
   if (!field.name.value.endsWith(COLLECTION_SUFFIX) || field.name.value === COLLECTION_SUFFIX || !field.selectionSet) {
     return false;
@@ -132,16 +279,14 @@ function getOperation(document) {
   );
   const operation = operations[0];
   if (!operation || operations.length > 1) {
-    throw new FetchContentfulError(
-      "fetch-contentful expects exactly one operation per document.",
-      { code: "CONFIG" }
-    );
+    throw new FetchContentfulError("fetch-contentful expects exactly one operation per document.", {
+      code: "CONFIG"
+    });
   }
   if (operation.operation !== "query") {
-    throw new FetchContentfulError(
-      "fetch-contentful only supports query operations.",
-      { code: "CONFIG" }
-    );
+    throw new FetchContentfulError("fetch-contentful only supports query operations.", {
+      code: "CONFIG"
+    });
   }
   return operation;
 }
@@ -153,41 +298,34 @@ function inlineFragments(document) {
     }
   }
   function inlineSelectionSet(selectionSet, stack) {
-    const selections = selectionSet.selections.map(
-      (selection) => {
-        if (selection.kind === Kind.FRAGMENT_SPREAD) {
-          const name = selection.name.value;
-          const fragment = fragments.get(name);
-          if (!fragment) {
-            throw new FetchContentfulError(
-              `Unknown fragment "${name}" referenced in query.`,
-              { code: "CONFIG" }
-            );
-          }
-          if (stack.includes(name)) {
-            throw new FetchContentfulError(
-              `Fragment cycle detected involving "${name}".`,
-              { code: "CONFIG" }
-            );
-          }
-          return {
-            kind: Kind.INLINE_FRAGMENT,
-            typeCondition: fragment.typeCondition,
-            selectionSet: inlineSelectionSet(fragment.selectionSet, [
-              ...stack,
-              name
-            ])
-          };
+    const selections = selectionSet.selections.map((selection) => {
+      if (selection.kind === Kind.FRAGMENT_SPREAD) {
+        const name = selection.name.value;
+        const fragment = fragments.get(name);
+        if (!fragment) {
+          throw new FetchContentfulError(`Unknown fragment "${name}" referenced in query.`, {
+            code: "CONFIG"
+          });
         }
-        if (selection.selectionSet) {
-          return {
-            ...selection,
-            selectionSet: inlineSelectionSet(selection.selectionSet, stack)
-          };
+        if (stack.includes(name)) {
+          throw new FetchContentfulError(`Fragment cycle detected involving "${name}".`, {
+            code: "CONFIG"
+          });
         }
-        return selection;
+        return {
+          kind: Kind.INLINE_FRAGMENT,
+          typeCondition: fragment.typeCondition,
+          selectionSet: inlineSelectionSet(fragment.selectionSet, [...stack, name])
+        };
       }
-    );
+      if (selection.selectionSet) {
+        return {
+          ...selection,
+          selectionSet: inlineSelectionSet(selection.selectionSet, stack)
+        };
+      }
+      return selection;
+    });
     return { ...selectionSet, selections };
   }
   const definitions = document.definitions.filter((definition) => definition.kind !== Kind.FRAGMENT_DEFINITION).map(
@@ -222,26 +360,23 @@ function planSplits(document, options) {
         continue;
       }
       if (selection.kind !== Kind.FIELD) {
-        throw new FetchContentfulError(
-          "Fragment spreads must be inlined before split planning.",
-          { code: "CONFIG" }
-        );
+        throw new FetchContentfulError("Fragment spreads must be inlined before split planning.", {
+          code: "CONFIG"
+        });
       }
       const field = selection;
       const isExplicitSplit = hasDirective(field, SPLIT_DIRECTIVE);
       const isAutoSplit = options.autoSplitNestedCollections && isCollectionField(field);
+      const isForcedSplit = options.forceSplit?.(field) ?? false;
       if (isExplicitSplit && depth === 0) {
         throw new FetchContentfulError(
           `Cannot split root field "${responseKeyOf(field)}": @split needs a parent entry to stitch the result back onto, and root fields have none. Move the directive to a nested field, or page through this field with its own \`limit\` and \`skip\` arguments.`,
           { code: "CONFIG" }
         );
       }
-      const shouldSplit = depth > 0 && field.selectionSet !== void 0 && !hasDirective(field, NO_SPLIT_DIRECTIVE) && (isExplicitSplit || isAutoSplit);
+      const shouldSplit = depth > 0 && field.selectionSet !== void 0 && !hasDirective(field, NO_SPLIT_DIRECTIVE) && (isExplicitSplit || isAutoSplit || isForcedSplit);
       if (shouldSplit) {
-        const planned = withDirective(
-          withoutDirective(field, SPLIT_DIRECTIVE),
-          NO_SPLIT_DIRECTIVE
-        );
+        const planned = withDirective(withoutDirective(field, SPLIT_DIRECTIVE), NO_SPLIT_DIRECTIVE);
         plans.push({
           path: [...path],
           responseKey: responseKeyOf(field),
@@ -270,8 +405,11 @@ function planSplits(document, options) {
         selections.push(field);
       }
     }
-    if (needsMarkers) {
-      selections.push(sysIdMarker(), typenameMarker());
+    if (needsMarkers && !selections.some((s) => hasResponseKey(s, SYS_ID_ALIAS))) {
+      selections.push(sysIdMarker());
+    }
+    if (needsMarkers && !selections.some((s) => hasResponseKey(s, TYPENAME_ALIAS))) {
+      selections.push(typenameMarker());
     }
     return { ...selectionSet, selections };
   }
@@ -289,6 +427,49 @@ function planSplits(document, options) {
     plans
   };
 }
+function findSplitCandidates(document) {
+  const operation = getOperation(document);
+  const candidates = [];
+  function walk2(selectionSet, depth) {
+    for (const selection of selectionSet.selections) {
+      if (selection.kind === Kind.INLINE_FRAGMENT) {
+        walk2(selection.selectionSet, depth);
+        continue;
+      }
+      if (selection.kind !== Kind.FIELD || !selection.selectionSet) continue;
+      const isMarker = hasResponseKey(selection, SYS_ID_ALIAS) || hasResponseKey(selection, TYPENAME_ALIAS);
+      if (depth > 0 && selection.name.value !== "items" && !isMarker) {
+        candidates.push({ field: selection, size: print(selection).length });
+      }
+      walk2(selection.selectionSet, depth + 1);
+    }
+  }
+  walk2(operation.selectionSet, 0);
+  return candidates;
+}
+function planSplitsWithSizeBudget(document, options) {
+  const first = planSplits(document, {
+    autoSplitNestedCollections: options.autoSplitNestedCollections
+  });
+  if (!options.autoSplitOnSize) return first;
+  let outer = first.document;
+  const plans = [...first.plans];
+  let remainingIterations = findSplitCandidates(outer).length;
+  while (options.measure(outer) > options.maxQuerySize && remainingIterations-- > 0) {
+    const candidates = findSplitCandidates(outer);
+    if (candidates.length === 0) break;
+    const target = candidates.reduce(
+      (largest, candidate) => candidate.size > largest.size ? candidate : largest
+    );
+    const next = planSplits(outer, {
+      autoSplitNestedCollections: false,
+      forceSplit: (field) => field === target.field
+    });
+    outer = next.document;
+    plans.push(...next.plans);
+  }
+  return { document: outer, plans };
+}
 function stringArgument(name, value) {
   return {
     kind: Kind.ARGUMENT,
@@ -340,10 +521,7 @@ function whereIdInArgument() {
 }
 function buildSubquery(plan, typename, batchSize, context) {
   const rootKey = `${lowerFirst(typename)}${COLLECTION_SUFFIX}`;
-  const args = [
-    whereIdInArgument(),
-    intArgument("limit", batchSize)
-  ];
+  const args = [whereIdInArgument(), intArgument("limit", batchSize)];
   if (context.preview) {
     args.push(booleanArgument("preview", true));
   }
@@ -352,10 +530,7 @@ function buildSubquery(plan, typename, batchSize, context) {
   }
   const rootField = {
     ...namedField(rootKey, void 0, [
-      namedField("items", void 0, [
-        namedField("sys", void 0, [namedField("id")]),
-        plan.field
-      ])
+      namedField("items", void 0, [namedField("sys", void 0, [namedField("id")]), plan.field])
     ]),
     arguments: args
   };
@@ -405,12 +580,68 @@ function stripInternalDirectives(document) {
   });
 }
 
+// src/unresolvable.ts
+var UNRESOLVABLE_LINK_CODE = "UNRESOLVABLE_LINK";
+var COLLECTION_SUFFIX2 = "Collection";
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isCollectionValue(value) {
+  return isRecord(value) && Array.isArray(value["items"]);
+}
+function isCollectionKey(key) {
+  return key.endsWith(COLLECTION_SUFFIX2) && key !== COLLECTION_SUFFIX2;
+}
+function isUnresolvableLinkError(error) {
+  const contentful = error.extensions?.["contentful"];
+  return isRecord(contentful) && contentful["code"] === UNRESOLVABLE_LINK_CODE;
+}
+function partitionUnresolvableLinks(errors) {
+  const unresolvable = [];
+  const fatal = [];
+  for (const error of errors) {
+    if (isUnresolvableLinkError(error)) {
+      unresolvable.push(error);
+    } else {
+      fatal.push(error);
+    }
+  }
+  return { unresolvable, fatal };
+}
+function walk(value) {
+  if (Array.isArray(value)) {
+    return value.map(walk);
+  }
+  if (isRecord(value)) {
+    const result = {};
+    for (const [key, child] of Object.entries(value)) {
+      result[key] = isCollectionKey(key) && isCollectionValue(child) ? stripCollection(child) : walk(child);
+    }
+    return result;
+  }
+  return value;
+}
+function stripCollection(collection) {
+  const result = {};
+  for (const [key, value] of Object.entries(collection)) {
+    result[key] = key === "items" ? value.filter((item) => item !== null && item !== void 0).map(walk) : walk(value);
+  }
+  return result;
+}
+function omitUnresolvedLinks(data) {
+  return walk(data);
+}
+
 // src/client.ts
 function graphqlEndpoint(space, environment) {
   return `https://graphql.contentful.com/content/v1/spaces/${encodeURIComponent(
     space
   )}/environments/${encodeURIComponent(environment)}`;
 }
+function printOutgoingQuery(document, context) {
+  const printed = print(stripInternalDirectives(document));
+  return context.minifyQuery === false ? printed : minifyQuery(printed);
+}
 function parseRetryAfter(header) {
   if (!header) return void 0;
   const seconds = Number(header);
@@ -440,14 +671,47 @@ function pickDeclaredVariables(document, variables) {
 function isRetryableStatus(status) {
   return status === 408 || status === 429 || status >= 500;
 }
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function reportUnresolvableLinks(errors, context) {
+  if (!context.onUnresolvableLink) return;
+  try {
+    context.onUnresolvableLink(errors);
+  } catch {
+  }
+}
+async function readGraphQLErrors(response) {
+  try {
+    const payload = await response.json();
+    const errors = payload?.errors;
+    return Array.isArray(errors) && errors.length > 0 ? errors : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function describeFailure(summary, errors, query, context) {
+  if (!errors || errors.length === 0) return summary;
+  const message = `${summary} ${errors.map((error) => error.message).join("; ")}`;
+  if (context.annotateQueryOnError === false) return message;
+  const annotated = annotateQuery(query, errors);
+  return annotated ? `${message}
+
+${annotated}
+` : message;
+}
 async function rawRequest(document, variables, context) {
-  const query = print(stripInternalDirectives(document));
-  const body = JSON.stringify({
-    query,
-    variables: pickDeclaredVariables(document, variables)
-  });
+  const query = printOutgoingQuery(document, context);
+  const pickedVariables = pickDeclaredVariables(document, variables);
   const url = graphqlEndpoint(context.space, context.environment);
-  return withRetries(async () => {
+  const usePersistedQuery = context.automaticPersistedQueries === true;
+  const sha256Hash = usePersistedQuery ? await sha256Hex(query) : void 0;
+  async function send(includeQuery) {
+    const body = JSON.stringify({
+      ...includeQuery ? { query } : {},
+      variables: pickedVariables,
+      ...sha256Hash ? { extensions: persistedQueryExtensions(sha256Hash) } : {}
+    });
     let response;
     try {
       const init = {
@@ -465,16 +729,24 @@ async function rawRequest(document, variables, context) {
     } catch (cause) {
       throw new FetchContentfulError(
         `Network error while contacting Contentful: ${String(cause)}`,
-        { code: "NETWORK", retryable: true, cause }
+        { code: "NETWORK", query, retryable: true, cause }
       );
     }
     if (!response.ok) {
       const retryable = isRetryableStatus(response.status);
+      const errors = retryable ? void 0 : await readGraphQLErrors(response);
       throw new FetchContentfulError(
-        `Contentful responded with HTTP ${response.status}.`,
+        describeFailure(
+          `Contentful responded with HTTP ${response.status}.`,
+          errors,
+          query,
+          context
+        ),
         {
           code: "HTTP",
           status: response.status,
+          errors,
+          query,
           retryable,
           retryAfterMs: retryable ? parseRetryAfter(response.headers.get("Retry-After")) : void 0
         }
@@ -484,24 +756,46 @@ async function rawRequest(document, variables, context) {
     try {
       payload = await response.json();
     } catch (cause) {
-      throw new FetchContentfulError(
-        "Contentful returned an unreadable response body.",
-        { code: "NETWORK", retryable: true, cause }
-      );
+      throw new FetchContentfulError("Contentful returned an unreadable response body.", {
+        code: "NETWORK",
+        query,
+        retryable: true,
+        cause
+      });
     }
     if (payload.errors && payload.errors.length > 0) {
-      throw new FetchContentfulError(
-        `Contentful returned GraphQL errors: ${payload.errors.map((error) => error.message).join("; ")}`,
-        { code: "GRAPHQL", errors: payload.errors }
-      );
+      const { unresolvable, fatal } = partitionUnresolvableLinks(payload.errors);
+      const tolerable = context.unresolvableLinks !== "error" && fatal.length === 0 && unresolvable.length > 0 && isRecord2(payload.data);
+      if (!tolerable) {
+        throw new FetchContentfulError(
+          describeFailure("Contentful returned GraphQL errors:", payload.errors, query, context),
+          { code: "GRAPHQL", errors: payload.errors, query }
+        );
+      }
+      reportUnresolvableLinks(unresolvable, context);
     }
     if (!payload.data || typeof payload.data !== "object") {
-      throw new FetchContentfulError(
-        "Contentful returned no data and no errors.",
-        { code: "GRAPHQL" }
-      );
+      throw new FetchContentfulError("Contentful returned no data and no errors.", {
+        code: "GRAPHQL",
+        query
+      });
     }
     return payload.data;
+  }
+  let mustIncludeQuery = !usePersistedQuery;
+  return withRetries(async () => {
+    if (mustIncludeQuery) {
+      return send(true);
+    }
+    try {
+      return await send(false);
+    } catch (error) {
+      if (isFetchContentfulError(error) && error.code === "GRAPHQL" && error.errors?.some(isPersistedQueryNotFoundError)) {
+        mustIncludeQuery = true;
+        return await send(true);
+      }
+      throw error;
+    }
   }, context.retry);
 }
 
@@ -515,7 +809,6 @@ function readEnvSettings() {
       space: void 0,
       environment: void 0,
       deliveryToken: void 0,
-      token: void 0,
       previewToken: void 0
     };
   }
@@ -530,7 +823,6 @@ function readEnvSettings() {
       process.env.CONTENTFUL_ENVIRONMENT || process.env.NEXT_PUBLIC_CONTENTFUL_ENVIRONMENT
     ),
     deliveryToken,
-    token: deliveryToken,
     // No `NEXT_PUBLIC_` fallback: see the note at the top of this file.
     previewToken: orUndefined(process.env.CONTENTFUL_PREVIEW_ACCESS_TOKEN)
   };
@@ -572,20 +864,18 @@ function injectIntoField(field, args) {
   return { ...field, arguments: [...argumentsOf(field), ...additions] };
 }
 function injectIntoSelectionSet(selectionSet, args) {
-  const selections = selectionSet.selections.map(
-    (selection) => {
-      if (selection.kind === Kind.FIELD) {
-        return injectIntoField(selection, args);
-      }
-      if (selection.kind === Kind.INLINE_FRAGMENT) {
-        return {
-          ...selection,
-          selectionSet: injectIntoSelectionSet(selection.selectionSet, args)
-        };
-      }
-      return selection;
+  const selections = selectionSet.selections.map((selection) => {
+    if (selection.kind === Kind.FIELD) {
+      return injectIntoField(selection, args);
     }
-  );
+    if (selection.kind === Kind.INLINE_FRAGMENT) {
+      return {
+        ...selection,
+        selectionSet: injectIntoSelectionSet(selection.selectionSet, args)
+      };
+    }
+    return selection;
+  });
   return { ...selectionSet, selections };
 }
 function injectRootArgs(document, args) {
@@ -626,27 +916,24 @@ async function fetchLocales(context) {
       if (context.signal) init.signal = context.signal;
       response = await context.fetch(localesEndpoint(context), init);
     } catch (cause) {
-      throw new FetchContentfulError(
-        `Network error while fetching locales: ${String(cause)}`,
-        { code: "NETWORK", retryable: true, cause }
-      );
+      throw new FetchContentfulError(`Network error while fetching locales: ${String(cause)}`, {
+        code: "NETWORK",
+        retryable: true,
+        cause
+      });
     }
     if (!response.ok) {
-      throw new FetchContentfulError(
-        `Locale request failed with HTTP ${response.status}.`,
-        {
-          code: "HTTP",
-          status: response.status,
-          retryable: response.status === 429 || response.status >= 500
-        }
-      );
+      throw new FetchContentfulError(`Locale request failed with HTTP ${response.status}.`, {
+        code: "HTTP",
+        status: response.status,
+        retryable: response.status === 429 || response.status >= 500
+      });
     }
     const payload = await response.json();
     if (!Array.isArray(payload.items)) {
-      throw new FetchContentfulError(
-        "Locale response did not include an items array.",
-        { code: "NETWORK" }
-      );
+      throw new FetchContentfulError("Locale response did not include an items array.", {
+        code: "NETWORK"
+      });
     }
     return payload.items.map((item) => ({
       code: item.code,
@@ -674,24 +961,22 @@ function clearLocaleCache() {
 }
 
 // src/shape.ts
-var COLLECTION_SUFFIX2 = "Collection";
-function isRecord(value) {
+var COLLECTION_SUFFIX3 = "Collection";
+function isRecord3(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function isCollectionValue(value) {
-  return isRecord(value) && Array.isArray(value["items"]);
+function isCollectionValue2(value) {
+  return isRecord3(value) && Array.isArray(value["items"]);
 }
 function shapeData(data) {
   if (Array.isArray(data)) {
     return data.map((item) => shapeData(item));
   }
-  if (isRecord(data)) {
+  if (isRecord3(data)) {
     const shaped = {};
     for (const [key, value] of Object.entries(data)) {
-      if (key.endsWith(COLLECTION_SUFFIX2) && key !== COLLECTION_SUFFIX2 && isCollectionValue(value)) {
-        shaped[key.slice(0, -COLLECTION_SUFFIX2.length)] = shapeData(
-          value.items
-        );
+      if (key.endsWith(COLLECTION_SUFFIX3) && key !== COLLECTION_SUFFIX3 && isCollectionValue2(value)) {
+        shaped[key.slice(0, -COLLECTION_SUFFIX3.length)] = shapeData(value.items);
       } else {
         shaped[key] = shapeData(value);
       }
@@ -701,7 +986,7 @@ function shapeData(data) {
   return data;
 }
 function unwrapSingleRoot(data) {
-  if (isRecord(data)) {
+  if (isRecord3(data)) {
     const keys = Object.keys(data);
     if (keys.length === 1) {
       return data[keys[0]];
@@ -716,7 +1001,9 @@ var DEFAULT_RETRIES = 5;
 var DEFAULT_RETRY_DELAY_MS = 250;
 var DEFAULT_MAX_RETRY_DELAY_MS = 8e3;
 var DEFAULT_SPLIT_BATCH_SIZE = 50;
-function isRecord2(value) {
+var DEFAULT_MAX_QUERY_SIZE = 7500;
+var DEFAULT_MAX_QUERY_SIZE_WITH_APQ = 15500;
+function isRecord4(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function collectAtPath(data, path) {
@@ -724,7 +1011,7 @@ function collectAtPath(data, path) {
   for (const segment of path) {
     const next = [];
     for (const value of current) {
-      if (isRecord2(value)) {
+      if (isRecord4(value)) {
         const child = value[segment];
         if (Array.isArray(child)) {
           next.push(...child);
@@ -735,14 +1022,14 @@ function collectAtPath(data, path) {
     }
     current = next;
   }
-  return current.filter(isRecord2);
+  return current.filter(isRecord4);
 }
 function resolveContext(options) {
   const env = readEnvSettings();
   const space = options.space ?? env.space;
   const environment = options.environment ?? env.environment ?? "master";
   const preview = options.preview ?? false;
-  const token = preview ? options.previewToken ?? options.token ?? env.previewToken : options.deliveryToken ?? options.token ?? env.deliveryToken;
+  const token = preview ? options.previewToken ?? env.previewToken : options.deliveryToken ?? env.deliveryToken;
   if (!space || !token) {
     const missing = [];
     if (!space) {
@@ -766,6 +1053,7 @@ function resolveContext(options) {
     maxDelayMs: options.maxRetryDelayMs ?? DEFAULT_MAX_RETRY_DELAY_MS
   };
   const fetchImpl = options.fetch ?? globalThis.fetch;
+  const automaticPersistedQueries = options.automaticPersistedQueries ?? false;
   const context = {
     space,
     environment,
@@ -776,8 +1064,19 @@ function resolveContext(options) {
     fetch: fetchImpl,
     retry,
     autoSplitNestedCollections: options.autoSplitNestedCollections ?? true,
-    splitBatchSize: options.splitBatchSize ?? DEFAULT_SPLIT_BATCH_SIZE
+    autoSplitOnSize: options.autoSplitOnSize ?? true,
+    // APQ lifts Contentful's size ceiling from 8 KB to 16 KB, so the budget
+    // that triggers a size-driven split follows suit unless overridden.
+    maxQuerySize: options.maxQuerySize ?? (automaticPersistedQueries ? DEFAULT_MAX_QUERY_SIZE_WITH_APQ : DEFAULT_MAX_QUERY_SIZE),
+    splitBatchSize: options.splitBatchSize ?? DEFAULT_SPLIT_BATCH_SIZE,
+    annotateQueryOnError: options.annotateQueryOnError ?? true,
+    unresolvableLinks: options.unresolvableLinks ?? "omit",
+    minifyQuery: options.minifyQuery ?? true,
+    automaticPersistedQueries
   };
+  if (options.onUnresolvableLink) {
+    context.onUnresolvableLink = options.onUnresolvableLink;
+  }
   if (options.signal) context.signal = options.signal;
   if (options.next) context.next = options.next;
   if (options.cache) context.cache = options.cache;
@@ -795,7 +1094,7 @@ async function resolvePlan(plan, data, variables, context) {
   for (const parent of relevant) {
     const typename = parent[TYPENAME_ALIAS];
     const sys = parent[SYS_ID_ALIAS];
-    if (!isRecord2(sys) || typeof sys["id"] !== "string") {
+    if (!isRecord4(sys) || typeof sys["id"] !== "string") {
       throw new FetchContentfulError(
         `Cannot split "${plan.responseKey}": a parent entry is missing its sys id.`,
         { code: "STITCH" }
@@ -818,19 +1117,14 @@ async function resolvePlan(plan, data, variables, context) {
       ];
       await Promise.all(
         chunk(ids, context.splitBatchSize).map(async (idBatch) => {
-          const { document, rootKey } = buildSubquery(
-            plan,
-            typename,
-            idBatch.length,
-            context
-          );
+          const { document, rootKey } = buildSubquery(plan, typename, idBatch.length, context);
           const subData = await executeDocument(
             document,
             { ...variables, _splitIds: idBatch },
             context
           );
           const collection = subData[rootKey];
-          const items = isRecord2(collection) && Array.isArray(collection["items"]) ? collection["items"] : void 0;
+          const items = isRecord4(collection) && Array.isArray(collection["items"]) ? collection["items"] : void 0;
           if (!items) {
             throw new FetchContentfulError(
               `Split subquery for "${typename}" returned no "${rootKey}.items". Check that the content type follows Contentful naming conventions.`,
@@ -838,9 +1132,9 @@ async function resolvePlan(plan, data, variables, context) {
             );
           }
           for (const item of items) {
-            if (isRecord2(item)) {
+            if (isRecord4(item)) {
               const sys = item["sys"];
-              if (isRecord2(sys) && typeof sys["id"] === "string") {
+              if (isRecord4(sys) && typeof sys["id"] === "string") {
                 resolved.set(`${typename}:${sys["id"]}`, item[plan.responseKey]);
               }
             }
@@ -870,12 +1164,18 @@ function cleanupMarkers(data, plans) {
     }
   }
 }
+function byteLength(text) {
+  return new TextEncoder().encode(text).length;
+}
 async function executeDocument(document, variables, context) {
-  const { document: outer, plans } = planSplits(document, context);
+  const { document: outer, plans } = planSplitsWithSizeBudget(document, {
+    autoSplitNestedCollections: context.autoSplitNestedCollections,
+    autoSplitOnSize: context.autoSplitOnSize,
+    maxQuerySize: context.maxQuerySize,
+    measure: (doc) => byteLength(printOutgoingQuery(doc, context))
+  });
   const data = await rawRequest(outer, variables, context);
-  await Promise.all(
-    plans.map((plan) => resolvePlan(plan, data, variables, context))
-  );
+  await Promise.all(plans.map((plan) => resolvePlan(plan, data, variables, context)));
   cleanupMarkers(data, plans);
   return data;
 }
@@ -889,10 +1189,10 @@ function toDocument(query) {
   try {
     return parse(typeof query === "string" ? query : String(query));
   } catch (cause) {
-    throw new FetchContentfulError(
-      `Failed to parse GraphQL query: ${String(cause)}`,
-      { code: "CONFIG", cause }
-    );
+    throw new FetchContentfulError(`Failed to parse GraphQL query: ${String(cause)}`, {
+      code: "CONFIG",
+      cause
+    });
   }
 }
 function withAutoVariables(document, variables, context) {
@@ -928,13 +1228,10 @@ async function runFetchContentful(query, options) {
       );
     }
   }
-  const variables = withAutoVariables(
-    document,
-    options.variables ?? {},
-    context
-  );
+  const variables = withAutoVariables(document, options.variables ?? {}, context);
   const data = await executeDocument(document, variables, context);
-  const result = options.shapeResponseData === false ? data : shapeData(data);
+  const resolved = context.unresolvableLinks === "null" ? data : omitUnresolvedLinks(data);
+  const result = options.shapeResponseData === false ? resolved : shapeData(resolved);
   if (options.unwrapRootField === false) {
     return result;
   }
@@ -954,6 +1251,6 @@ function createFetchContentful(defaults = {}) {
 }
 var index_default = fetchContentful;
 
-export { FetchContentfulError, clearLocaleCache, collectAtPath, createFetchContentful, index_default as default, fetchContentful, getLocales, injectRootArgs, inlineFragments, isFetchContentfulError, readEnvSettings, shapeData, unwrapSingleRoot };
+export { FetchContentfulError, UNRESOLVABLE_LINK_CODE, annotateQuery, clearLocaleCache, collectAtPath, createFetchContentful, index_default as default, fetchContentful, getLocales, injectRootArgs, inlineFragments, isFetchContentfulError, isUnresolvableLinkError, minifyQuery, omitUnresolvedLinks, partitionUnresolvableLinks, readEnvSettings, shapeData, unwrapSingleRoot };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map