@fourtwelvelabs/fetch-contentful 0.4.0 → 1.0.0

package/dist/index.d.cts

@@ -25,6 +25,21 @@ interface ContentfulGraphQLError {
     path?: Array<string | number>;
     extensions?: Record<string, unknown>;
 }
+/**
+ * What to do about a link Contentful could not resolve — a reference whose
+ * target was deleted, or (on the Delivery API) never published.
+ *
+ * Contentful answers these with HTTP 200, usable `data`, a `null` where the
+ * link should have been, and an `UNRESOLVABLE_LINK` object in `errors`. In a
+ * collection the null takes the *position* of the missing entry, so
+ * `items` is `(Entry | null)[]` and the obvious `.map()` over it throws on
+ * a day an editor happened to unpublish something.
+ *
+ * - `'omit'` — drop the null positions and resolve. The default.
+ * - `'null'` — resolve with the holes intact (Contentful's raw behavior).
+ * - `'error'` — reject the whole call, as this library did before 1.0.
+ */
+type UnresolvableLinkMode = 'omit' | 'null' | 'error';
 /** Options accepted by {@link fetchContentful}. */
 interface FetchContentfulOptions<TVariables extends GraphQLVariables = GraphQLVariables> {
     /** GraphQL variables for the query. */
@@ -90,15 +105,6 @@ interface FetchContentfulOptions<TVariables extends GraphQLVariables = GraphQLVa
      * shipping it to the browser is acceptable for your app.
      */
     previewToken?: string;
-    /**
-     * Access token for whichever mode is active.
-     *
-     * @deprecated Use {@link FetchContentfulOptions.deliveryToken} and
-     * {@link FetchContentfulOptions.previewToken}. A single `token` cannot
-     * serve both modes, so a factory configured with one sends the wrong
-     * token as soon as a call passes `preview: true`.
-     */
-    token?: string;
     /**
      * Number of retry attempts after the first failed request (per network
      * request, including subqueries). Defaults to `5`.
@@ -141,6 +147,54 @@ interface FetchContentfulOptions<TVariables extends GraphQLVariables = GraphQLVa
      * that. Defaults to `true`.
      */
     shapeResponseData?: boolean;
+    /**
+     * How to treat a reference Contentful could not resolve — a link whose
+     * target was deleted, or (on the Delivery API) is still a draft. Defaults
+     * to `'omit'`: the null positions are dropped from every collection and
+     * the call resolves with the entries that do exist.
+     *
+     * See {@link UnresolvableLinkMode} for the other two modes. Pair any of
+     * them with {@link FetchContentfulOptions.onUnresolvableLink} so a broken
+     * reference still reaches your logs.
+     *
+     * Two limits are 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 because the Preview API resolves drafts, a preview
+     * build sees links a production build does not — the same query can
+     * legitimately return different array lengths in the two modes.
+     *
+     * Written on the call itself, this narrows the return type: `'omit'`
+     * types collection items as `Entry[]` rather than `(Entry | null)[]`.
+     * Set on a factory it still applies at runtime, but the return type
+     * assumes the default — so prefer setting a non-default mode per call.
+     */
+    unresolvableLinks?: UnresolvableLinkMode;
+    /**
+     * Called once per request that returned an unresolvable link, with the
+     * `UNRESOLVABLE_LINK` errors Contentful reported. Each carries the
+     * `linkId`, `field` and `type` of the missing reference under
+     * `extensions.contentful.details`.
+     *
+     * Dropping a broken reference silently hides a real editorial mistake, so
+     * this is the way to keep one visible. It is never called when
+     * `unresolvableLinks` is `'error'` (the call rejects with those same
+     * errors instead), and anything it throws is swallowed — a logger must
+     * not be able to fail a fetch that otherwise succeeded.
+     */
+    onUnresolvableLink?: (errors: ContentfulGraphQLError[]) => void;
+    /**
+     * When Contentful rejects a query, append the query itself to the error
+     * message with a caret under the line and column it complained about.
+     * Defaults to `true`.
+     *
+     * ANSI color is used only when the environment looks like a terminal
+     * (`NO_COLOR` and `FORCE_COLOR` are honored), so log pipelines receive
+     * plain text. Set this to `false` to keep error messages to a single
+     * line — the query is still on the error as
+     * {@link FetchContentfulError.query}, and `annotateQuery` can format it
+     * on demand.
+     */
+    annotateQueryOnError?: boolean;
     /** Custom fetch implementation (useful for tests). Defaults to `globalThis.fetch`. */
     fetch?: typeof fetch;
     /** AbortSignal forwarded to every underlying fetch call. */
@@ -213,12 +267,33 @@ type ShapeCollections<T> = T extends ReadonlyArray<infer U> ? Array<ShapeCollect
 type IsCollectionEntry<K, V> = K extends `${infer Base}Collection` ? Base extends '' ? false : NonNullable<V> extends {
     items: ReadonlyArray<unknown>;
 } ? true : false : false;
-type ShapedKey<K, V> = IsCollectionEntry<K, V> extends true ? K extends `${infer Base}Collection` ? Base : K : K;
+type ShapedKey<K, V> = IsCollectionEntry<K, V> extends true ? (K extends `${infer Base}Collection` ? Base : K) : K;
 type ShapedValue<K, V> = IsCollectionEntry<K, V> extends true ? NonNullable<V> extends {
     items: ReadonlyArray<infer I>;
 } ? Array<ShapeCollections<I>> | Extract<V, null | undefined> : never : ShapeCollections<V>;
+/**
+ * The type-level twin of `omitUnresolvedLinks`: drops `null` from the items
+ * of every collection, recursively, leaving the rest of the response alone.
+ *
+ * It runs on the *raw* wire shape, exactly where the runtime pass runs — so
+ * `ShapeCollections` composes on top of it unchanged, and a caller who
+ * disabled shaping gets the same guarantee about `items`.
+ *
+ * Nullability is stripped from the entries, never from the collection
+ * wrapper itself: a `fooCollection` that is entirely absent is still `null`.
+ */
+type OmitUnresolvedLinks<T> = T extends ReadonlyArray<infer U> ? Array<OmitUnresolvedLinks<U>> : T extends object ? {
+    [K in keyof T]: IsCollectionEntry<K, T[K]> extends true ? OmitItemNulls<T[K]> : OmitUnresolvedLinks<T[K]>;
+} : T;
+/**
+ * Rewrites one collection wrapper's `items` to a non-nullable array, keeping
+ * its other fields (`total`, `skip`, `limit`) and its own nullability.
+ */
+type OmitItemNulls<V> = {
+    [K in keyof NonNullable<V>]: K extends 'items' ? NonNullable<V>[K] extends ReadonlyArray<infer I> ? Array<OmitUnresolvedLinks<NonNullable<I>>> : NonNullable<V>[K] : OmitUnresolvedLinks<NonNullable<V>[K]>;
+} | Extract<V, null | undefined>;
 /** `true` when `T` is a union of two or more members. */
-type IsUnion<T, U = T> = T extends unknown ? [U] extends [T] ? false : true : never;
+type IsUnion<T, U = T> = T extends unknown ? ([U] extends [T] ? false : true) : never;
 /**
  * The type-level twin of the single-root unwrap: when `T` is an object with
  * exactly one statically-known key, resolves to that key's value type;
@@ -228,11 +303,64 @@ type IsUnion<T, U = T> = T extends unknown ? [U] extends [T] ? false : true : ne
  */
 type UnwrapSingleRoot<T> = T extends ReadonlyArray<unknown> ? T : T extends object ? string extends keyof T ? T : [keyof T] extends [never] ? T : IsUnion<keyof T> extends true ? T : T[keyof T] : T;
 
+/**
+ * Rendering a rejected query back to the developer.
+ *
+ * Contentful's GraphQL errors carry `locations` — a line and column into
+ * the query **as sent**. That text is rarely the text anyone wrote: by the
+ * time it leaves this package, fragments have been inlined, `preview` and
+ * `locale` arguments injected, and split fields hoisted into generated
+ * subqueries. "Cannot query field X" plus a line number into a document you
+ * have never seen is a dead end, so this module prints that document back
+ * and puts a caret under the column Contentful named.
+ *
+ * Color is emitted as bare ANSI escapes rather than through a dependency:
+ * this package ships CJS as well as ESM, and the obvious candidate (chalk
+ * v5) is ESM-only. The four codes below are the entire surface we need.
+ */
+
+interface AnnotateQueryOptions {
+    /**
+     * How many source lines to show above and below each marked line.
+     * Defaults to `3`; pass `Infinity` to print the whole query.
+     */
+    contextLines?: number;
+    /**
+     * Whether to emit ANSI color. Defaults to {@link supportsColor}, so a
+     * developer watching a terminal gets color while a log pipeline gets
+     * plain text it can store.
+     */
+    color?: boolean;
+}
+/**
+ * Renders `query` with a caret under every position the errors reported:
+ *
+ * ```text
+ *   2 |   pageCollection(where: { slug: $slug }, limit: 1) {
+ *   3 |     items {
+ * > 4 |       titel
+ *     |       ^ Cannot query field "titel" on type "Page". Did you mean "title"?
+ *   5 |     }
+ * ```
+ *
+ * Returns an empty string when no error carries a usable location — there
+ * is nothing to point at, and dumping the whole query would only bury the
+ * message that matters.
+ */
+declare function annotateQuery(query: string, errors: readonly ContentfulGraphQLError[], options?: AnnotateQueryOptions): string;
+
 /** Error thrown (i.e. the rejection value) for every failure in fetch-contentful. */
 declare class FetchContentfulError extends Error {
     readonly code: FetchContentfulErrorCode;
     readonly status: number | undefined;
     readonly errors: ContentfulGraphQLError[] | undefined;
+    /**
+     * 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`.
+     */
+    readonly query: string | undefined;
     /** Internal: whether a retry may succeed. */
     readonly retryable: boolean;
     /** Internal: server-requested retry delay (from Retry-After), in ms. */
@@ -241,6 +369,7 @@ declare class FetchContentfulError extends Error {
         code: FetchContentfulErrorCode;
         status?: number;
         errors?: ContentfulGraphQLError[];
+        query?: string;
         retryable?: boolean;
         retryAfterMs?: number;
         cause?: unknown;
@@ -286,13 +415,6 @@ interface EnvSettings {
     environment: string | undefined;
     /** Content Delivery API token, for published content. */
     deliveryToken: string | undefined;
-    /**
-     * Content Delivery API token.
-     *
-     * @deprecated Renamed to {@link EnvSettings.deliveryToken}, which says
-     * which of the two tokens it is. Kept as an alias; same value.
-     */
-    token: string | undefined;
     /** Content Preview API token, for draft content. Server-side only. */
     previewToken: string | undefined;
 }
@@ -359,6 +481,42 @@ declare function shapeData<T>(data: T): ShapeCollections<T>;
  */
 declare function unwrapSingleRoot<T>(data: T): UnwrapSingleRoot<T>;
 
+/**
+ * The `extensions.contentful.code` Contentful sets on a link it could not
+ * resolve — the target was deleted, or is a draft the Delivery API cannot
+ * see. It arrives on an HTTP 200 alongside usable `data`.
+ */
+declare const UNRESOLVABLE_LINK_CODE = "UNRESOLVABLE_LINK";
+/** Whether one GraphQL error is Contentful's `UNRESOLVABLE_LINK`. */
+declare function isUnresolvableLinkError(error: ContentfulGraphQLError): boolean;
+/**
+ * Splits Contentful's `errors` into the links that merely could not be
+ * resolved and everything else.
+ *
+ * The distinction is the whole point: an unresolvable link describes content
+ * that is missing, and leaves the rest of the response intact and correct. A
+ * validation or complexity error describes a query that was wrong, and there
+ * is nothing to salvage. Only the first kind is ever tolerated.
+ */
+declare function partitionUnresolvableLinks(errors: ContentfulGraphQLError[]): {
+    unresolvable: ContentfulGraphQLError[];
+    fatal: ContentfulGraphQLError[];
+};
+/**
+ * Removes the `null` positions an unresolvable link leaves behind in every
+ * `fooCollection.items`, recursively. Everything else is returned untouched
+ * (deeply copied), including a `null` on a one-to-one reference field —
+ * there is no position there to drop, only a field that has no value.
+ *
+ * This runs on the raw wire shape, before `shapeData`, so it applies just as
+ * much to a caller who passed `shapeResponseData: false`. A null inside
+ * `items` is never legitimate data — Contentful puts one there only for a
+ * link it could not resolve — so the walk is structural and needs no
+ * cross-referencing against the `errors` array, which matters because a
+ * split subquery reports its own errors against its own generated query.
+ */
+declare function omitUnresolvedLinks<T>(data: T): OmitUnresolvedLinks<T>;
+
 /**
  * Replaces every named fragment spread with an equivalent inline fragment so
  * split planning can see the whole query shape uniformly.
@@ -376,36 +534,72 @@ declare function collectAtPath(data: unknown, path: string[]): Record<string, un
  *   stitches everything back together.
  * - Retries transient failures with exponential backoff.
  * - Rejects if any request in the tree fails; resolves only when the full
- *   query has succeeded.
+ *   query has succeeded. A link Contentful could not resolve is the one
+ *   thing that does not count as a failure — see below.
  * - Shapes the response so every `fooCollection.items` becomes `foo`
  *   (disable with `shapeResponseData: false` to receive the raw wire shape).
+ * - Drops the `null` positions an unresolvable link leaves in a collection,
+ *   in the data *and* in the return type, so `items` is safe to map over
+ *   (change with `unresolvableLinks`; report them with `onUnresolvableLink`).
  *
  * Pass a typed document — from gql.tada, graphql-codegen's client preset, or
  * anything else producing a `TypedDocumentNode` — and both the result and
  * the variables are inferred, with no type arguments to write by hand.
  */
 declare function fetchContentful<TResult, TVariables = GraphQLVariables>(document: TypedDocumentNode<TResult, TVariables>, options: TypedFetchContentfulOptions<TVariables> & {
+    unresolvableLinks: 'null';
     shapeResponseData: false;
     unwrapRootField: false;
 }): Promise<DocumentResult<TResult>>;
 declare function fetchContentful<TResult, TVariables = GraphQLVariables>(document: TypedDocumentNode<TResult, TVariables>, options: TypedFetchContentfulOptions<TVariables> & {
+    unresolvableLinks: 'null';
     shapeResponseData: false;
 }): Promise<UnwrapSingleRoot<DocumentResult<TResult>>>;
 declare function fetchContentful<TResult, TVariables = GraphQLVariables>(document: TypedDocumentNode<TResult, TVariables>, options: TypedFetchContentfulOptions<TVariables> & {
+    unresolvableLinks: 'null';
     unwrapRootField: false;
 }): Promise<ShapeCollections<DocumentResult<TResult>>>;
-declare function fetchContentful<TResult, TVariables = GraphQLVariables>(document: TypedDocumentNode<TResult, TVariables>, ...args: Record<string, never> extends CallerVariables<TVariables> ? [options?: TypedFetchContentfulOptions<TVariables>] : [options: TypedFetchContentfulOptions<TVariables>]): Promise<UnwrapSingleRoot<ShapeCollections<DocumentResult<TResult>>>>;
+declare function fetchContentful<TResult, TVariables = GraphQLVariables>(document: TypedDocumentNode<TResult, TVariables>, options: TypedFetchContentfulOptions<TVariables> & {
+    unresolvableLinks: 'null';
+}): Promise<UnwrapSingleRoot<ShapeCollections<DocumentResult<TResult>>>>;
 declare function fetchContentful<TData = Record<string, unknown>, TVariables extends GraphQLVariables = GraphQLVariables>(query: string, options: FetchContentfulOptions<TVariables> & {
+    unresolvableLinks: 'null';
     shapeResponseData: false;
     unwrapRootField: false;
 }): Promise<TData>;
 declare function fetchContentful<TData = Record<string, unknown>, TVariables extends GraphQLVariables = GraphQLVariables>(query: string, options: FetchContentfulOptions<TVariables> & {
+    unresolvableLinks: 'null';
     shapeResponseData: false;
 }): Promise<UnwrapSingleRoot<TData>>;
 declare function fetchContentful<TData = Record<string, unknown>, TVariables extends GraphQLVariables = GraphQLVariables>(query: string, options: FetchContentfulOptions<TVariables> & {
+    unresolvableLinks: 'null';
     unwrapRootField: false;
 }): Promise<ShapeCollections<TData>>;
-declare function fetchContentful<TData = Record<string, unknown>, TVariables extends GraphQLVariables = GraphQLVariables>(query: string, options?: FetchContentfulOptions<TVariables>): Promise<UnwrapSingleRoot<ShapeCollections<TData>>>;
+declare function fetchContentful<TData = Record<string, unknown>, TVariables extends GraphQLVariables = GraphQLVariables>(query: string, options: FetchContentfulOptions<TVariables> & {
+    unresolvableLinks: 'null';
+}): Promise<UnwrapSingleRoot<ShapeCollections<TData>>>;
+declare function fetchContentful<TResult, TVariables = GraphQLVariables>(document: TypedDocumentNode<TResult, TVariables>, options: TypedFetchContentfulOptions<TVariables> & {
+    shapeResponseData: false;
+    unwrapRootField: false;
+}): Promise<OmitUnresolvedLinks<DocumentResult<TResult>>>;
+declare function fetchContentful<TResult, TVariables = GraphQLVariables>(document: TypedDocumentNode<TResult, TVariables>, options: TypedFetchContentfulOptions<TVariables> & {
+    shapeResponseData: false;
+}): Promise<UnwrapSingleRoot<OmitUnresolvedLinks<DocumentResult<TResult>>>>;
+declare function fetchContentful<TResult, TVariables = GraphQLVariables>(document: TypedDocumentNode<TResult, TVariables>, options: TypedFetchContentfulOptions<TVariables> & {
+    unwrapRootField: false;
+}): Promise<ShapeCollections<OmitUnresolvedLinks<DocumentResult<TResult>>>>;
+declare function fetchContentful<TResult, TVariables = GraphQLVariables>(document: TypedDocumentNode<TResult, TVariables>, ...args: Record<string, never> extends CallerVariables<TVariables> ? [options?: TypedFetchContentfulOptions<TVariables>] : [options: TypedFetchContentfulOptions<TVariables>]): Promise<UnwrapSingleRoot<ShapeCollections<OmitUnresolvedLinks<DocumentResult<TResult>>>>>;
+declare function fetchContentful<TData = Record<string, unknown>, TVariables extends GraphQLVariables = GraphQLVariables>(query: string, options: FetchContentfulOptions<TVariables> & {
+    shapeResponseData: false;
+    unwrapRootField: false;
+}): Promise<OmitUnresolvedLinks<TData>>;
+declare function fetchContentful<TData = Record<string, unknown>, TVariables extends GraphQLVariables = GraphQLVariables>(query: string, options: FetchContentfulOptions<TVariables> & {
+    shapeResponseData: false;
+}): Promise<UnwrapSingleRoot<OmitUnresolvedLinks<TData>>>;
+declare function fetchContentful<TData = Record<string, unknown>, TVariables extends GraphQLVariables = GraphQLVariables>(query: string, options: FetchContentfulOptions<TVariables> & {
+    unwrapRootField: false;
+}): Promise<ShapeCollections<OmitUnresolvedLinks<TData>>>;
+declare function fetchContentful<TData = Record<string, unknown>, TVariables extends GraphQLVariables = GraphQLVariables>(query: string, options?: FetchContentfulOptions<TVariables>): Promise<UnwrapSingleRoot<ShapeCollections<OmitUnresolvedLinks<TData>>>>;
 /**
  * Creates a `fetchContentful` bound to default options — the recommended way
  * to configure the utility once per project:
@@ -420,32 +614,66 @@ declare function fetchContentful<TData = Record<string, unknown>, TVariables ext
  * ```
  *
  * Per-call options win over defaults (top-level shallow merge). Note that
- * `shapeResponseData: false` only changes the *return type* when written on
- * the call itself, so prefer setting it per call.
+ * `shapeResponseData: false`, `unwrapRootField: false` and
+ * `unresolvableLinks: 'null'` only change the *return type* when written on
+ * the call itself, so prefer setting those per call. Set on the factory they
+ * still take effect at runtime — the type just assumes the default.
  */
 declare function createFetchContentful<TDefaultVariables extends GraphQLVariables = GraphQLVariables>(defaults?: FetchContentfulOptions<TDefaultVariables>): {
     <TResult, TVariables = GraphQLVariables>(document: TypedDocumentNode<TResult, TVariables>, options: TypedFetchContentfulOptions<TVariables> & {
+        unresolvableLinks: "null";
         shapeResponseData: false;
         unwrapRootField: false;
     }): Promise<DocumentResult<TResult>>;
     <TResult, TVariables = GraphQLVariables>(document: TypedDocumentNode<TResult, TVariables>, options: TypedFetchContentfulOptions<TVariables> & {
+        unresolvableLinks: "null";
         shapeResponseData: false;
     }): Promise<UnwrapSingleRoot<DocumentResult<TResult>>>;
     <TResult, TVariables = GraphQLVariables>(document: TypedDocumentNode<TResult, TVariables>, options: TypedFetchContentfulOptions<TVariables> & {
+        unresolvableLinks: "null";
         unwrapRootField: false;
     }): Promise<ShapeCollections<DocumentResult<TResult>>>;
-    <TResult, TVariables = GraphQLVariables>(document: TypedDocumentNode<TResult, TVariables>, ...args: Record<string, never> extends CallerVariables<TVariables> ? [options?: TypedFetchContentfulOptions<TVariables>] : [options: TypedFetchContentfulOptions<TVariables>]): Promise<UnwrapSingleRoot<ShapeCollections<DocumentResult<TResult>>>>;
+    <TResult, TVariables = GraphQLVariables>(document: TypedDocumentNode<TResult, TVariables>, options: TypedFetchContentfulOptions<TVariables> & {
+        unresolvableLinks: "null";
+    }): Promise<UnwrapSingleRoot<ShapeCollections<DocumentResult<TResult>>>>;
     <TData = Record<string, unknown>, TVariables extends GraphQLVariables = GraphQLVariables>(query: string, options: FetchContentfulOptions<TVariables> & {
+        unresolvableLinks: "null";
         shapeResponseData: false;
         unwrapRootField: false;
     }): Promise<TData>;
     <TData = Record<string, unknown>, TVariables extends GraphQLVariables = GraphQLVariables>(query: string, options: FetchContentfulOptions<TVariables> & {
+        unresolvableLinks: "null";
         shapeResponseData: false;
     }): Promise<UnwrapSingleRoot<TData>>;
     <TData = Record<string, unknown>, TVariables extends GraphQLVariables = GraphQLVariables>(query: string, options: FetchContentfulOptions<TVariables> & {
+        unresolvableLinks: "null";
         unwrapRootField: false;
     }): Promise<ShapeCollections<TData>>;
-    <TData = Record<string, unknown>, TVariables extends GraphQLVariables = GraphQLVariables>(query: string, options?: FetchContentfulOptions<TVariables>): Promise<UnwrapSingleRoot<ShapeCollections<TData>>>;
+    <TData = Record<string, unknown>, TVariables extends GraphQLVariables = GraphQLVariables>(query: string, options: FetchContentfulOptions<TVariables> & {
+        unresolvableLinks: "null";
+    }): Promise<UnwrapSingleRoot<ShapeCollections<TData>>>;
+    <TResult, TVariables = GraphQLVariables>(document: TypedDocumentNode<TResult, TVariables>, options: TypedFetchContentfulOptions<TVariables> & {
+        shapeResponseData: false;
+        unwrapRootField: false;
+    }): Promise<OmitUnresolvedLinks<DocumentResult<TResult>>>;
+    <TResult, TVariables = GraphQLVariables>(document: TypedDocumentNode<TResult, TVariables>, options: TypedFetchContentfulOptions<TVariables> & {
+        shapeResponseData: false;
+    }): Promise<UnwrapSingleRoot<OmitUnresolvedLinks<DocumentResult<TResult>>>>;
+    <TResult, TVariables = GraphQLVariables>(document: TypedDocumentNode<TResult, TVariables>, options: TypedFetchContentfulOptions<TVariables> & {
+        unwrapRootField: false;
+    }): Promise<ShapeCollections<OmitUnresolvedLinks<DocumentResult<TResult>>>>;
+    <TResult, TVariables = GraphQLVariables>(document: TypedDocumentNode<TResult, TVariables>, ...args: Record<string, never> extends CallerVariables<TVariables> ? [options?: TypedFetchContentfulOptions<TVariables>] : [options: TypedFetchContentfulOptions<TVariables>]): Promise<UnwrapSingleRoot<ShapeCollections<OmitUnresolvedLinks<DocumentResult<TResult>>>>>;
+    <TData = Record<string, unknown>, TVariables extends GraphQLVariables = GraphQLVariables>(query: string, options: FetchContentfulOptions<TVariables> & {
+        shapeResponseData: false;
+        unwrapRootField: false;
+    }): Promise<OmitUnresolvedLinks<TData>>;
+    <TData = Record<string, unknown>, TVariables extends GraphQLVariables = GraphQLVariables>(query: string, options: FetchContentfulOptions<TVariables> & {
+        shapeResponseData: false;
+    }): Promise<UnwrapSingleRoot<OmitUnresolvedLinks<TData>>>;
+    <TData = Record<string, unknown>, TVariables extends GraphQLVariables = GraphQLVariables>(query: string, options: FetchContentfulOptions<TVariables> & {
+        unwrapRootField: false;
+    }): Promise<ShapeCollections<OmitUnresolvedLinks<TData>>>;
+    <TData = Record<string, unknown>, TVariables extends GraphQLVariables = GraphQLVariables>(query: string, options?: FetchContentfulOptions<TVariables>): Promise<UnwrapSingleRoot<ShapeCollections<OmitUnresolvedLinks<TData>>>>;
 };
 
-export { type AutoInjectedVariable, type CallerVariables, type ContentfulGraphQLError, type ContentfulLocale, type DocumentResult, FetchContentfulError, type FetchContentfulErrorCode, type FetchContentfulOptions, type GraphQLVariables, type NextFetchOptions, type ShapeCollections, type TypedFetchContentfulOptions, type UnwrapSingleRoot, type VariablesOption, clearLocaleCache, collectAtPath, createFetchContentful, fetchContentful as default, fetchContentful, getLocales, injectRootArgs, inlineFragments, isFetchContentfulError, readEnvSettings, shapeData, unwrapSingleRoot };
+export { type AnnotateQueryOptions, type AutoInjectedVariable, type CallerVariables, type ContentfulGraphQLError, type ContentfulLocale, type DocumentResult, FetchContentfulError, type FetchContentfulErrorCode, type FetchContentfulOptions, type GraphQLVariables, type NextFetchOptions, type OmitUnresolvedLinks, type ShapeCollections, type TypedFetchContentfulOptions, UNRESOLVABLE_LINK_CODE, type UnresolvableLinkMode, type UnwrapSingleRoot, type VariablesOption, annotateQuery, clearLocaleCache, collectAtPath, createFetchContentful, fetchContentful as default, fetchContentful, getLocales, injectRootArgs, inlineFragments, isFetchContentfulError, isUnresolvableLinkError, omitUnresolvedLinks, partitionUnresolvableLinks, readEnvSettings, shapeData, unwrapSingleRoot };