@fourtwelvelabs/fetch-contentful 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,324 @@
+import { DocumentNode } from 'graphql';
+
+/**
+ * Public types for fetch-contentful.
+ *
+ * This file is type-only (no runtime code) and is excluded from coverage.
+ */
+/** JSON-compatible variable values accepted by the GraphQL endpoint. */
+type GraphQLVariables = Record<string, unknown>;
+/** Next.js-specific fetch extensions (App Router data cache). */
+interface NextFetchOptions {
+    revalidate?: number | false;
+    tags?: string[];
+}
+/** Error categories a {@link FetchContentfulError} can carry. */
+type FetchContentfulErrorCode = 'CONFIG' | 'NETWORK' | 'HTTP' | 'GRAPHQL' | 'STITCH' | 'LOCALE';
+/** Shape of a GraphQL error object returned by Contentful. */
+interface ContentfulGraphQLError {
+    message: string;
+    locations?: Array<{
+        line: number;
+        column: number;
+    }>;
+    path?: Array<string | number>;
+    extensions?: Record<string, unknown>;
+}
+/** Options accepted by {@link fetchContentful}. */
+interface FetchContentfulOptions<TVariables extends GraphQLVariables = GraphQLVariables> {
+    /** GraphQL variables for the query. */
+    variables?: TVariables;
+    /**
+     * Contentful environment id.
+     * Defaults to `process.env.NEXT_PUBLIC_CONTENTFUL_ENVIRONMENT`, then `"master"`.
+     */
+    environment?: string;
+    /**
+     * Contentful space id.
+     * Defaults to `process.env.NEXT_PUBLIC_CONTENTFUL_SPACE`. Required.
+     */
+    space?: string;
+    /**
+     * Use the Preview API. Selects the preview token by default, is injected
+     * as a `preview: true` argument on root query fields (see
+     * {@link FetchContentfulOptions.autoInjectArgs}), and auto-fills a
+     * `$preview: Boolean` variable when your query declares one.
+     * Defaults to `false`.
+     */
+    preview?: boolean;
+    /**
+     * Locale code (e.g. `"en-US"`). Injected as a `locale` argument on root
+     * query fields (see {@link FetchContentfulOptions.autoInjectArgs}),
+     * auto-fills a `$locale: String` variable when your query declares one,
+     * and is applied to generated subqueries.
+     */
+    locale?: string;
+    /**
+     * Automatically add `preview: true` / `locale: "..."` arguments to the
+     * root fields of your query based on the `preview` and `locale` options,
+     * so queries never need to declare or thread those arguments themselves.
+     * Contentful cascades both arguments to all nested fields. Arguments you
+     * write explicitly are never overridden. Defaults to `true`.
+     */
+    autoInjectArgs?: boolean;
+    /**
+     * When `true`, the provided `locale` is validated against the locales
+     * configured in Contentful (fetched once per space/environment and cached).
+     */
+    validateLocale?: boolean;
+    /**
+     * Access token. Defaults to `process.env.CONTENTFUL_PREVIEW_ACCESS_TOKEN`
+     * when `preview` is true, otherwise `process.env.CONTENTFUL_ACCESS_TOKEN`
+     * (with `NEXT_PUBLIC_`-prefixed fallbacks for client-side use).
+     */
+    token?: string;
+    /**
+     * Number of retry attempts after the first failed request (per network
+     * request, including subqueries). Defaults to `5`.
+     */
+    retries?: number;
+    /** Base delay in ms for exponential backoff. Defaults to `250`. */
+    retryDelayMs?: number;
+    /** Maximum backoff delay in ms. Defaults to `8000`. */
+    maxRetryDelayMs?: number;
+    /**
+     * Automatically split nested reference collections (any `*Collection`
+     * field that is not a root query field) into their own subqueries to stay
+     * under Contentful's query complexity limits. Defaults to `true`.
+     * One-to-one references can be split by annotating them with `@split`.
+     */
+    autoSplitNestedCollections?: boolean;
+    /** How many parent entry ids to resolve per subquery request. Defaults to `50`. */
+    splitBatchSize?: number;
+    /**
+     * Whether to unwrap single-root responses. When the (optionally shaped)
+     * response object has exactly one root key — e.g. a query for only
+     * `siteSettingsCollection` — the promise resolves with that key's value
+     * directly instead of a one-key wrapper object. Responses with multiple
+     * root fields are always returned as-is. Defaults to `true`.
+     */
+    unwrapRootField?: boolean;
+    /**
+     * Whether to run the response through the collection shaper
+     * (`fooCollection.items` → `foo`) before resolving. When `false`, the data
+     * resolves in Contentful's raw wire shape and the return type reflects
+     * that. Defaults to `true`.
+     */
+    shapeResponseData?: boolean;
+    /** Custom fetch implementation (useful for tests). Defaults to `globalThis.fetch`. */
+    fetch?: typeof fetch;
+    /** AbortSignal forwarded to every underlying fetch call. */
+    signal?: AbortSignal;
+    /** Next.js App Router data-cache options, forwarded to fetch. */
+    next?: NextFetchOptions;
+    /** Standard fetch cache mode, forwarded to fetch. */
+    cache?: RequestCache;
+}
+/** A single locale as configured in Contentful. */
+interface ContentfulLocale {
+    code: string;
+    name: string;
+    default: boolean;
+    fallbackCode: string | null;
+}
+/**
+ * Recursively rewrites Contentful collection wrappers at the type level:
+ * every `fooCollection: { items: T[] }` becomes `foo: T[]`, preserving
+ * nullability. Mirrors the runtime behavior of `shapeData`.
+ */
+type ShapeCollections<T> = T extends ReadonlyArray<infer U> ? Array<ShapeCollections<U>> : T extends object ? {
+    [K in keyof T as ShapedKey<K, T[K]>]: ShapedValue<K, T[K]>;
+} : T;
+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 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>;
+/** `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;
+/**
+ * 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;
+ * otherwise resolves to `T` unchanged. Objects typed with index signatures
+ * (like the default `Record<string, unknown>`) are left as-is, since their
+ * keys aren't statically known.
+ */
+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;
+
+/** 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;
+    /** Internal: whether a retry may succeed. */
+    readonly retryable: boolean;
+    /** Internal: server-requested retry delay (from Retry-After), in ms. */
+    readonly retryAfterMs: number | undefined;
+    constructor(message: string, options: {
+        code: FetchContentfulErrorCode;
+        status?: number;
+        errors?: ContentfulGraphQLError[];
+        retryable?: boolean;
+        retryAfterMs?: number;
+        cause?: unknown;
+    });
+}
+/** Type guard for {@link FetchContentfulError}. */
+declare function isFetchContentfulError(value: unknown): value is FetchContentfulError;
+
+/**
+ * Environment-derived configuration.
+ *
+ * Two families of variable names are supported, checked in this order:
+ *
+ * 1. Framework-neutral names — `CONTENTFUL_SPACE_ID`, `CONTENTFUL_ENVIRONMENT`,
+ *    `CONTENTFUL_ACCESS_TOKEN`, `CONTENTFUL_PREVIEW_ACCESS_TOKEN`.
+ * 2. `NEXT_PUBLIC_`-prefixed equivalents for Next.js projects that call
+ *    Contentful from the browser.
+ *
+ * IMPORTANT: every lookup below is written as a literal
+ * `process.env.SOME_NAME` property access, never a dynamic `process.env[x]`.
+ * Next.js exposes `NEXT_PUBLIC_` variables to client bundles by
+ * string-replacing those literal expressions at build time — dynamic access
+ * is invisible to the inliner and resolves to `undefined` in the browser.
+ * Do not "refactor" these into a loop or a name table.
+ *
+ * This module reads the already-populated `process.env`; loading `.env`
+ * files from disk is deliberately left to the platform (Next.js, Vite,
+ * dotenv, ...), whose precedence rules would otherwise be duplicated here.
+ */
+interface EnvSettings {
+    space: string | undefined;
+    environment: string | undefined;
+    token: string | undefined;
+    previewToken: string | undefined;
+}
+/** Reads Contentful settings from `process.env` (neutral names first). */
+declare function readEnvSettings(): EnvSettings;
+
+/**
+ * Contentful cascades `preview` and `locale` from a root query field down to
+ * every nested field, so injecting the arguments at the root is equivalent to
+ * threading them through the whole query by hand — without the boilerplate.
+ */
+interface InjectableArgs {
+    preview: boolean;
+    locale: string | undefined;
+}
+/**
+ * Adds `preview: true` and/or `locale: "..."` arguments to every root field
+ * of the operation, unless the author already wrote that argument. Nested
+ * fields are left untouched — Contentful inherits both arguments downward.
+ */
+declare function injectRootArgs(document: DocumentNode, args: InjectableArgs): DocumentNode;
+
+interface RetryConfig {
+    /** Number of retries after the initial attempt. */
+    retries: number;
+    /** Base backoff delay in ms. */
+    baseDelayMs: number;
+    /** Maximum backoff delay in ms. */
+    maxDelayMs: number;
+    /** Random source, injectable for deterministic tests. */
+    random?: () => number;
+    /** Sleep implementation, injectable for deterministic tests. */
+    sleep?: (ms: number) => Promise<void>;
+}
+
+interface LocalesContext {
+    space: string;
+    environment: string;
+    preview: boolean;
+    token: string;
+    fetch: typeof fetch;
+    retry: RetryConfig;
+    signal?: AbortSignal;
+}
+/**
+ * Returns the locales configured in Contentful for a space/environment.
+ * Results are cached in-module, so repeated fetches are free; failed
+ * lookups are evicted so they can be retried later.
+ */
+declare function getLocales(context: LocalesContext): Promise<ContentfulLocale[]>;
+/** Clears the in-module locale cache (mainly useful in tests). */
+declare function clearLocaleCache(): void;
+
+/**
+ * Recursively rewrites Contentful collection wrappers:
+ * `{ fooCollection: { items: [...] } }` becomes `{ foo: [...] }`.
+ * Non-collection data is returned untouched (deeply copied).
+ */
+declare function shapeData<T>(data: T): ShapeCollections<T>;
+/**
+ * Unwraps a single-root response: `{ siteSettings: X }` becomes `X` when
+ * `siteSettings` is the only root key. Anything else — multiple roots,
+ * arrays, primitives — is returned untouched.
+ */
+declare function unwrapSingleRoot<T>(data: T): UnwrapSingleRoot<T>;
+
+/**
+ * Replaces every named fragment spread with an equivalent inline fragment so
+ * split planning can see the whole query shape uniformly.
+ */
+declare function inlineFragments(document: DocumentNode): DocumentNode;
+
+/** Collect every object reachable at a response path, flattening arrays. */
+declare function collectAtPath(data: unknown, path: string[]): Record<string, unknown>[];
+
+/**
+ * Fetches data from Contentful's GraphQL API.
+ *
+ * - Splits nested reference collections (and `@split`-annotated references)
+ *   into recursive subqueries to stay under query complexity limits, then
+ *   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.
+ * - Shapes the response so every `fooCollection.items` becomes `foo`
+ *   (disable with `shapeResponseData: false` to receive the raw wire shape).
+ */
+declare function fetchContentful<TData = Record<string, unknown>, TVariables extends GraphQLVariables = GraphQLVariables>(query: string | DocumentNode, options: FetchContentfulOptions<TVariables> & {
+    shapeResponseData: false;
+    unwrapRootField: false;
+}): Promise<TData>;
+declare function fetchContentful<TData = Record<string, unknown>, TVariables extends GraphQLVariables = GraphQLVariables>(query: string | DocumentNode, options: FetchContentfulOptions<TVariables> & {
+    shapeResponseData: false;
+}): Promise<UnwrapSingleRoot<TData>>;
+declare function fetchContentful<TData = Record<string, unknown>, TVariables extends GraphQLVariables = GraphQLVariables>(query: string | DocumentNode, options: FetchContentfulOptions<TVariables> & {
+    unwrapRootField: false;
+}): Promise<ShapeCollections<TData>>;
+declare function fetchContentful<TData = Record<string, unknown>, TVariables extends GraphQLVariables = GraphQLVariables>(query: string | DocumentNode, options?: FetchContentfulOptions<TVariables>): Promise<UnwrapSingleRoot<ShapeCollections<TData>>>;
+/**
+ * Creates a `fetchContentful` bound to default options — the recommended way
+ * to configure the utility once per project:
+ *
+ * ```ts
+ * // lib/contentful.ts
+ * export const fetchContentful = createFetchContentful({
+ *   space: 'abc123',
+ *   locale: 'en-US',
+ *   retries: 3,
+ * });
+ * ```
+ *
+ * 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.
+ */
+declare function createFetchContentful<TDefaultVariables extends GraphQLVariables = GraphQLVariables>(defaults?: FetchContentfulOptions<TDefaultVariables>): {
+    <TData = Record<string, unknown>, TVariables extends GraphQLVariables = GraphQLVariables>(query: string | DocumentNode, options: FetchContentfulOptions<TVariables> & {
+        shapeResponseData: false;
+        unwrapRootField: false;
+    }): Promise<TData>;
+    <TData = Record<string, unknown>, TVariables extends GraphQLVariables = GraphQLVariables>(query: string | DocumentNode, options: FetchContentfulOptions<TVariables> & {
+        shapeResponseData: false;
+    }): Promise<UnwrapSingleRoot<TData>>;
+    <TData = Record<string, unknown>, TVariables extends GraphQLVariables = GraphQLVariables>(query: string | DocumentNode, options: FetchContentfulOptions<TVariables> & {
+        unwrapRootField: false;
+    }): Promise<ShapeCollections<TData>>;
+    <TData = Record<string, unknown>, TVariables extends GraphQLVariables = GraphQLVariables>(query: string | DocumentNode, options?: FetchContentfulOptions<TVariables>): Promise<UnwrapSingleRoot<ShapeCollections<TData>>>;
+};
+
+export { type ContentfulGraphQLError, type ContentfulLocale, FetchContentfulError, type FetchContentfulErrorCode, type FetchContentfulOptions, type GraphQLVariables, type NextFetchOptions, type ShapeCollections, type UnwrapSingleRoot, clearLocaleCache, collectAtPath, createFetchContentful, fetchContentful as default, fetchContentful, getLocales, injectRootArgs, inlineFragments, isFetchContentfulError, readEnvSettings, shapeData, unwrapSingleRoot };