@fourtwelvelabs/fetch-contentful 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fourtwelve Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,301 @@
+# @fourtwelvelabs/fetch-contentful
+
+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 retries** — transient failures (network errors, 408/429/5xx) retry with exponential backoff + jitter, honouring `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.
+- **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.
+- **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.
+- **ESM + CJS, Next.js-ready** — first-class App Router support (`next.revalidate` / `next.tags` passthrough), works in Pages Router and any Node ≥ 18 runtime.
+
+## Install
+
+```bash
+yarn add @fourtwelvelabs/fetch-contentful graphql
+```
+
+## Configuration
+
+Settings resolve in this order — first hit wins, per setting:
+
+1. **Per-call options** — `fetchContentful(query, { space, token, ... })`
+2. **Factory defaults** — set once with `createFetchContentful` (below)
+3. **Environment variables** — framework-neutral names first, then `NEXT_PUBLIC_`-prefixed equivalents
+
+If `space` or the appropriate token can't be resolved, the promise rejects with a single `CONFIG` error listing **every** missing setting and the exact option/env names that would satisfy it.
+
+### 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` |
+| Delivery token | `CONTENTFUL_ACCESS_TOKEN` | `NEXT_PUBLIC_CONTENTFUL_ACCESS_TOKEN` |
+| Preview token | `CONTENTFUL_PREVIEW_ACCESS_TOKEN` | `NEXT_PUBLIC_CONTENTFUL_PREVIEW_ACCESS_TOKEN` |
+
+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. Think twice before exposing tokens to the browser at all: Contentful delivery tokens are read-only and commonly made public, but preview tokens should stay server-side.
+
+### Project-level defaults with `createFetchContentful`
+
+For utility-specific configuration, create a configured instance once and import it everywhere — this is the config file, just one you import instead of one the library discovers at runtime (which would break bundlers and edge runtimes, and invite committed secrets):
+
+```ts
+// lib/contentful.ts
+import { createFetchContentful } from '@fourtwelvelabs/fetch-contentful';
+
+export const fetchContentful = createFetchContentful({
+  space: 'abc123',       // or leave unset to use env vars
+  locale: 'en-US',
+  retries: 3,
+});
+```
+
+```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.
+
+## Quick start
+
+```ts
+import { fetchContentful } from '@fourtwelvelabs/fetch-contentful';
+
+interface PagesQuery {
+  pageCollection: {
+    items: Array<{
+      title: string;
+      sectionsCollection: { items: Array<{ heading: string }> };
+    }>;
+  } | null;
+}
+
+const data = await fetchContentful<PagesQuery>(
+  /* GraphQL */ `
+    query Pages($limit: Int) {
+      pageCollection(limit: $limit) {
+        items {
+          title
+          sectionsCollection(limit: 10) {
+            items {
+              heading
+            }
+          }
+        }
+      }
+    }
+  `,
+  { variables: { limit: 10 }, preview: true, locale: 'en-US' },
+);
+
+// Shaped and unwrapped: the single root field's contents come back directly.
+// data: Array<{ title: string; sections: Array<{ heading: string }> }>
+```
+
+Notice there is no `$preview` or `$locale` anywhere in the query: the options are injected as `preview: true` / `locale: "en-US"` arguments on the root field before the query is sent, and Contentful cascades both to every nested field. Arguments you write explicitly are never overridden, so per-field overrides like `title(locale: "de-DE")` keep working. Set `autoInjectArgs: false` to opt out. (The older style still works too — `$preview: Boolean` / `$locale: String` variables are auto-filled whenever a query declares them.)
+
+## Next.js
+
+### App Router (recommended)
+
+```ts
+// app/pages/[slug]/page.tsx
+import { fetchContentful } from '@fourtwelvelabs/fetch-contentful';
+
+export default async function Page({ params }: { params: { slug: string } }) {
+  const data = await fetchContentful<PageQuery>(PAGE_QUERY, {
+    variables: { slug: params.slug },
+    next: { revalidate: 300, tags: ['contentful'] }, // forwarded to fetch()
+  });
+  return <Article page={data.page[0]} />;
+}
+```
+
+Draft Mode preview:
+
+```ts
+import { draftMode } from 'next/headers';
+
+const { isEnabled } = await draftMode();
+const data = await fetchContentful<PageQuery>(PAGE_QUERY, {
+  preview: isEnabled,
+  cache: isEnabled ? 'no-store' : undefined,
+});
+```
+
+### Pages Router
+
+```ts
+export const getStaticProps: GetStaticProps = async ({ preview = false }) => {
+  const data = await fetchContentful<PageQuery>(PAGE_QUERY, { preview });
+  return { props: { data }, revalidate: 300 };
+};
+```
+
+## Options
+
+```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: 'de-DE',            // injected as a root-field argument (and $locale)
+  validateLocale: true,       // reject with LOCALE if locale isn't configured
+  token: '...',               // override the env-derived token
+
+  // Request behaviour
+  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)
+
+  // Response handling
+  shapeResponseData: true,          // false = skip collection shaping
+  unwrapRootField: true,            // false = keep single-root responses wrapped
+
+  // Query rewriting
+  autoInjectArgs: true,             // inject preview/locale args on root fields
+  autoSplitNestedCollections: true, // split every non-root *Collection field
+  splitBatchSize: 50,               // parent ids per subquery
+});
+```
+
+## Response shaping
+
+Shaping happens **inside `fetchContentful` — you never call anything yourself**. The data the promise resolves with is already shaped, and the return type (`ShapeCollections<TData>`) matches it, so autocomplete and the runtime always agree. If you'd rather receive Contentful's raw wire shape, pass `shapeResponseData: false` — the return type follows along and becomes plain `TData`:
+
+```ts
+const raw = await fetchContentful<WireQuery>(QUERY, { shapeResponseData: false });
+// raw.pageCollection.items — untouched wire shape, pagination metadata intact
+```
+
+Splitting, stitching, retries, and argument injection all still apply in raw mode; only the final rename/hoist step is skipped.
+
+The transform: every key ending in `Collection` whose value has an `items` array is renamed to drop the suffix, and `items` is hoisted up to become the value — recursively, at every depth. Everything else passes through untouched.
+
+```ts
+// What Contentful returns on the wire          // What fetchContentful resolves with
+{                                               [
+  pageCollection: {                               {
+    items: [                                        title: 'Home',
+      {                                             sections: [{ heading: 'Hero' }],
+        title: 'Home',                            },
+        sectionsCollection: {                   ]
+          items: [{ heading: 'Hero' }],
+        },
+      },
+    ],
+  },
+}
+```
+
+Two transforms produce that result, both reflected in the return type:
+
+1. **Collection shaping** (`shapeResponseData`, default `true`) — the rename/hoist described above.
+2. **Single-root unwrapping** (`unwrapRootField`, default `true`) — when the (shaped) response has exactly one root key, the promise resolves with that key's value directly, so you skip the `data.page` hop. Applies to collections and one-to-one roots alike (`{ siteSettings: {...} }` resolves as the settings entry itself). Queries with **multiple root fields always stay wrapped** — unwrapping would be ambiguous — so adding a second root field changes the result shape from `T` back to `{ a: ..., b: ... }`; the types track this, so TypeScript flags every affected call site.
+
+Note that pagination metadata (`total`, `skip`, `limit`) selected alongside `items` is dropped by the hoist. If you need it for a particular collection, alias that field to a name that doesn't end in `Collection` and it will pass through completely untouched:
+
+```graphql
+query {
+  pagedResults: pageCollection(limit: 10, skip: 20) {
+    total
+    items { title }
+  }
+}
+# resolves as data.pagedResults: { total: number; items: [...] }
+```
+
+The generic you pass (`fetchContentful<PagesQuery>`) should always describe the **wire shape** (with `fooCollection.items`) — the library derives the shaped type from it for you, and the aliasing trick above is reflected there too, since the type transform keys off the same `Collection` suffix.
+
+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`.
+
+## How splitting works
+
+Contentful rejects queries whose complexity exceeds its limit — usually caused by nested reference fields multiplying. `fetch-contentful` avoids this transparently:
+
+1. Named fragments are inlined and the query is scanned. Every **nested** `*Collection` field (auto) and every field annotated **`@split`** (one-to-one references) is removed from the outer query and recorded as a plan.
+2. The outer query runs with tiny markers (`sys { id }`, `__typename`) injected where fields were removed.
+3. Parents are grouped by their concrete `__typename`, and each split field is re-fetched via `"{typeName}Collection"(where: { sys: { id_in: [...] } })` in batches of `splitBatchSize`, in parallel. Subqueries go through the same pipeline, so splits nest recursively to any depth.
+4. Results are stitched back onto their parents by `sys.id`. If any entry can't be resolved, the whole promise rejects with a `STITCH` error — you never get silently incomplete data.
+
+Marking a one-to-one reference:
+
+```graphql
+query {
+  pageCollection {
+    items {
+      title
+      hero @split {        # fetched in a second, cheaper query
+        headline
+        image { url }
+      }
+    }
+  }
+}
+```
+
+The `@split` directive is stripped before anything is sent to Contentful.
+
+## Error handling
+
+Every rejection is a `FetchContentfulError`:
+
+```ts
+import { fetchContentful, isFetchContentfulError } from '@fourtwelvelabs/fetch-contentful';
+
+try {
+  await fetchContentful(QUERY);
+} catch (error) {
+  if (isFetchContentfulError(error)) {
+    error.code;   // 'CONFIG' | 'NETWORK' | 'HTTP' | 'GRAPHQL' | 'STITCH' | 'LOCALE'
+    error.status; // HTTP status, when applicable
+    error.errors; // GraphQL errors, when applicable
+  }
+}
+```
+
+## Other exports
+
+```ts
+import {
+  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)
+} from '@fourtwelvelabs/fetch-contentful';
+import type { ShapeCollections, FetchContentfulOptions } from '@fourtwelvelabs/fetch-contentful';
+```
+
+`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.
+
+## Limitations
+
+- One `query` operation per document (no mutations/subscriptions, no multi-operation documents).
+- 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`.
+
+## Development
+
+```bash
+npm test               # vitest
+npm run test:coverage  # enforces 100% statements/branches/functions/lines
+npm run typecheck
+npm run build          # emits ESM + d.ts to dist/
+```