@fourtwelvelabs/fetch-contentful 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,102 @@
+# @fourtwelvelabs/fetch-contentful
+
+## 0.3.0
+
+### Minor Changes
+
+- 6013f57: `locale` now defaults to `"en-US"`.
+
+  Previously, omitting `locale` meant no `locale` argument was sent at all, and
+  Contentful served whichever locale the space itself defaults to. Now `en-US`
+  is requested explicitly unless you say otherwise.
+
+  **This changes which content comes back for a space whose default locale is
+  not `en-US`.** If that describes your space, either set the locale once for
+  the project:
+
+  ```ts
+  export const fetchContentful = createFetchContentful({ locale: "de-DE" });
+  ```
+
+  or restore the previous behavior — no `locale` argument, space decides — with
+  the new `null` opt-out:
+
+  ```ts
+  await fetchContentful(QUERY, { locale: null });
+  ```
+
+  `locale: null` is accepted anywhere `locale` is, including as a
+  `createFetchContentful` default and as a per-call override of one. A space
+  that has no `en-US` locale configured will now reject with a `LOCALE` error
+  under `validateLocale: true`, rather than silently returning the space
+  default.
+
+## 0.2.1
+
+### Patch Changes
+
+- 641367c: `@split` on a **root field** now throws instead of being silently ignored.
+
+  Root fields have no parent entry to stitch a result back onto, so they have
+  never been splittable — but the directive was quietly stripped before the
+  request went out, leaving the query just as expensive as before with nothing
+  to explain why. It now raises a `CONFIG` `FetchContentfulError` naming the
+  field.
+
+  **This can surface in existing queries.** If a query annotates a root field,
+  that call will now reject where it previously succeeded (having ignored the
+  directive). The fix is to remove the directive — it was never doing anything
+  — and page through the field with its own `limit` / `skip` arguments instead.
+  Nested `@split` annotations are unaffected.
+
+  Also clarifies and pins the relationship between `@split` and
+  `autoSplitNestedCollections`: the option gates **only** the automatic
+  detection of nested `*Collection` fields, while `@split` is an independent
+  explicit trigger that splits its field — collection or one-to-one reference —
+  regardless of the option. This enables a "manual mode"
+  (`autoSplitNestedCollections: false` plus targeted annotations) where only
+  the fields that actually exceed Contentful's complexity limit are split. That
+  behavior was already correct; it is now documented and covered by tests.
+
+## 0.2.0
+
+### Minor Changes
+
+- 9c9eef3: Add a gql.tada companion.
+
+  - **`@fourtwelvelabs/fetch-contentful/tada`** — a new type-only subpath export
+    providing `ContentfulScalars`, the scalar map for Contentful's GraphQL
+    Content API, for `initGraphQLTada<{ scalars: ContentfulScalars }>`. Nothing
+    in it imports gql.tada at runtime.
+  - **`tada-init` and `tada-refresh` CLI commands**, via a new
+    `fetch-contentful` binary. `tada-init` downloads the space's schema as SDL,
+    registers `@0no-co/graphqlsp` in the project's `tsconfig.json` (preserving
+    comments and formatting, and updating an existing entry rather than
+    duplicating it) and writes a `graphql.ts` bound to the schema and the scalar
+    map. `tada-refresh` re-downloads the schema only, leaving the file untouched
+    when nothing changed. Both support `--dry-run`, resolve credentials through
+    the same environment variables the library reads, and never print the access
+    token.
+  - **Typed document support in `fetchContentful`** — passing a
+    `TypedDocumentNode` (gql.tada, or graphql-codegen's client preset) infers
+    both the result and the variable types, with response shaping and single-root
+    unwrapping applied to the inferred type. `variables` is required exactly when
+    the document declares one the library does not inject itself, and unknown
+    variable names are rejected. Existing string and `DocumentNode` usage is
+    unchanged.
+
+  `gql.tada` and `@0no-co/graphqlsp` are optional peer dependencies, needed only
+  at author time.
+
+## 0.1.0
+
+### Minor Changes
+
+- b6e2577: Initial release. A type-safe GraphQL fetching utility for Contentful:
+
+  - Automatic query splitting for nested reference collections (and `@split`-annotated one-to-one references), fetched in id batches and stitched back into the original response shape.
+  - Automatic retries with exponential backoff and jitter, honoring `Retry-After`.
+  - Response shaping (`fooCollection.items` → `foo`) and single-root unwrapping, at runtime and in the return type.
+  - Automatic `preview` / `locale` argument injection, with optional locale validation against the space.
+  - Typed `FetchContentfulError` carrying an error code, HTTP status, and GraphQL errors.
+  - Next.js App Router support via `next.revalidate` / `next.tags` passthrough.

package/README.md

@@ -3,12 +3,13 @@
 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.
+- **Automatic retries** — transient failures (network errors, 408/429/5xx) retry with exponential backoff + jitter, honoring `Retry-After`. Configurable, default 5.
 - **Response shaping (built in)** — before the promise resolves, every `fooCollection.items` in the response becomes `foo` (a plain array), at runtime *and* in the return type. No separate call needed.
 - **Single-root unwrapping (built in)** — when a query has one root field, the promise resolves with that field's contents directly (`data` *is* the array/entry, not `{ siteSettings: ... }`). Multi-root queries stay wrapped.
-- **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.
+- **No preview/locale boilerplate** — `preview` and `locale` are injected as arguments onto your query's root fields automatically (Contentful cascades them to every nested field), so queries never need to declare or thread them. The locale defaults to `en-US`.
 - **All-or-nothing promise** — resolves only when every request in the tree succeeded; rejects with a typed `FetchContentfulError` if anything fails.
 - **Locale awareness** — locales are fetched from Contentful once and cached in-module, so validation costs nothing per fetch.
+- **Inferred types, optionally** — pass a [gql.tada](https://gql-tada.0no.co) or graphql-codegen document and the result and variable types come from the query itself. One command (`tada-init`) sets gql.tada up against your space. See [Typed queries with gql.tada](#typed-queries-with-gqltada).
 - **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
@@ -36,6 +37,8 @@ If `space` or the appropriate token can't be resolved, the promise rejects with
 | Delivery token | `CONTENTFUL_ACCESS_TOKEN` | `NEXT_PUBLIC_CONTENTFUL_ACCESS_TOKEN` |
 | Preview token | `CONTENTFUL_PREVIEW_ACCESS_TOKEN` | `NEXT_PUBLIC_CONTENTFUL_PREVIEW_ACCESS_TOKEN` |
 
+There is no environment variable for the locale: it defaults to **`en-US`**, and a project that wants a different one sets it once with `createFetchContentful` (below).
+
 The library reads the already-populated `process.env`; loading `.env` / `.env.local` files from disk is your platform's job (Next.js, Vite, dotenv all do this), so precedence between those files always matches your framework's rules.
 
 **In a Next.js project you don't need both names.** Set only the `NEXT_PUBLIC_` variant and it works everywhere: the server reads it like any other env var (the prefix only controls *client* exposure), and client bundles get it because the library reads these variables with literal `process.env.NEXT_PUBLIC_...` accesses — the exact pattern Next's build-time inliner string-replaces. Server-only projects (or any other framework) should use the neutral names. 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.
@@ -50,7 +53,7 @@ import { createFetchContentful } from '@fourtwelvelabs/fetch-contentful';
 
 export const fetchContentful = createFetchContentful({
   space: 'abc123',       // or leave unset to use env vars
-  locale: 'en-US',
+  locale: 'de-DE',       // override the 'en-US' default for the whole project
   retries: 3,
 });
 ```
@@ -101,6 +104,63 @@ const data = await fetchContentful<PagesQuery>(
 
 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.)
 
+`locale` is optional here — it defaults to `en-US`, so the same argument is injected whether or not you pass it. Pass a different code to override it, or `locale: null` to send no `locale` argument at all and let the space serve its own default locale.
+
+## Typed queries with gql.tada
+
+Everything above types the response by hand (`fetchContentful<PagesQuery>`). You can instead have the types come from the query itself. Install the author-time peers, then run the setup command:
+
+```bash
+yarn add -D gql.tada @0no-co/graphqlsp
+npx @fourtwelvelabs/fetch-contentful tada-init
+```
+
+It reads the same environment variables the library does, is safe to re-run, and takes `--dry-run`. Three things happen: your space's schema is downloaded as SDL, `@0no-co/graphqlsp` is registered in your `tsconfig.json`, and **`src/graphql.ts`** is written — a small file of your own that binds gql.tada to your schema:
+
+```ts
+// src/graphql.ts — generated for you. Commit it; edit it freely.
+import { initGraphQLTada } from 'gql.tada';
+import type { ContentfulScalars } from '@fourtwelvelabs/fetch-contentful/tada';
+import type { introspection } from './contentful-env.d.ts';
+
+export const graphql = initGraphQLTada<{
+  introspection: introspection; // your space's content model, as types
+  scalars: ContentfulScalars;   // DateTime → string, JSON → JsonValue, …
+}>();
+
+export { readFragment } from 'gql.tada';
+export type { FragmentOf, ResultOf, VariablesOf } from 'gql.tada';
+```
+
+`graphql` is a tagged template function doing two jobs at once: at runtime it parses your query into a GraphQL document, and at compile time it infers that query's result and variable types from the schema. It can't be an export of this package — it has to be bound to *your* space — which is why the command generates it.
+
+Restart the TypeScript server so `@0no-co/graphqlsp` loads (it's what gives you autocomplete and field validation inside the backticks). Then import `graphql` from wherever `tada-init` put it, and queries type themselves:
+
+```ts
+// src/lib/pages.ts
+import { fetchContentful } from '@fourtwelvelabs/fetch-contentful';
+import { graphql } from '../graphql';
+
+const PageQuery = graphql(`
+  query Page($slug: String!) {
+    pageCollection(where: { slug: $slug }, limit: 1) {
+      items {
+        title
+        sectionsCollection { items { heading } }
+      }
+    }
+  }
+`);
+
+const pages = await fetchContentful(PageQuery, { variables: { slug: 'home' } });
+//    ^? Array<{ title: string | null;
+//               sections: Array<{ heading: string | null }> }> | null
+```
+
+No type argument, and `variables` is required exactly when the document declares one the library doesn't inject itself (`$preview` and `$locale` are filled in automatically). Response shaping and single-root unwrapping are applied to the inferred type, so what you see is what you get. After a content-model change, run `tada-refresh` to re-download the schema.
+
+**[Full gql.tada guide →](./docs/tada.md)** — the scalar map, manual setup without the CLI, the CLI reference, and a CI recipe that opens a PR when your content model changes.
+
 ## Next.js
 
 ### App Router (recommended)
@@ -147,11 +207,11 @@ fetchContentful(query, {
   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)
+  locale: 'en-US',            // default: 'en-US'. null sends no locale at all
   validateLocale: true,       // reject with LOCALE if locale isn't configured
   token: '...',               // override the env-derived token
 
-  // Request behaviour
+  // Request behavior
   variables: { slug: 'home' },
   retries: 5,                 // retry count after the initial attempt
   retryDelayMs: 250,          // base backoff delay
@@ -167,7 +227,8 @@ fetchContentful(query, {
 
   // Query rewriting
   autoInjectArgs: true,             // inject preview/locale args on root fields
-  autoSplitNestedCollections: true, // split every non-root *Collection field
+  autoSplitNestedCollections: true, // auto-detect non-root *Collection fields
+                                    // (@split works regardless — see below)
   splitBatchSize: 50,               // parent ids per subquery
 });
 ```
@@ -226,7 +287,7 @@ The standalone `shapeData` / `ShapeCollections` exports exist only for advanced
 
 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.
+1. Named fragments are inlined and the query is scanned. Every **nested** `*Collection` field (auto) and every field annotated **`@split`** 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.
@@ -249,6 +310,59 @@ query {
 
 The `@split` directive is stripped before anything is sent to Contentful.
 
+### `@split` and `autoSplitNestedCollections` are independent
+
+`autoSplitNestedCollections` controls **only automatic detection** — whether nested `*Collection` fields are split without being asked. `@split` is an explicit instruction that always applies to the field it annotates, whatever the option is set to, and works on **nested collections just as well as one-to-one references**. An annotated collection takes exactly the same path as an auto-detected one: its arguments (`limit`, `where`, `order`, …) and selection set are re-selected verbatim in the subquery.
+
+The two triggers never double up — a field caught by both produces one subquery, not two.
+
+### Manual mode
+
+Turn auto-splitting off and annotate only the fields that actually blow the complexity limit. Everything else then runs as a single round trip, which is usually faster and always easier to reason about:
+
+```ts
+const data = await fetchContentful(QUERY, {
+  autoSplitNestedCollections: false,
+});
+```
+
+```graphql
+query {
+  pageCollection(limit: 10) {
+    items {
+      title
+      # Small and cheap: fetched inline, in the same request.
+      seo { description }
+      tagsCollection(limit: 5) { items { name } }
+
+      # The expensive one: fetched separately, batched by parent id.
+      sectionsCollection(limit: 50) @split {
+        items {
+          heading
+          mediaCollection(limit: 10) { items { url } }
+        }
+      }
+    }
+  }
+}
+```
+
+That sends two requests instead of the four auto mode would. Splits still nest recursively in manual mode: a `@split` inside a subquery is planned when that subquery runs, so you can annotate as deeply as you need.
+
+### Root fields cannot be split
+
+`@split` on a **root** field raises a `CONFIG` `FetchContentfulError` rather than being quietly ignored:
+
+```graphql
+query {
+  pageCollection @split {   # ✗ CONFIG error
+    items { title }
+  }
+}
+```
+
+A root field has no parent entry to stitch its result back onto, so there is nothing for the directive to do. Reach for `limit` and `skip` on the field itself instead. (Before 0.2.1 the directive was silently stripped here — if an existing query relies on that, remove the directive.)
+
 ## Error handling
 
 Every rejection is a `FetchContentfulError`:
@@ -280,6 +394,9 @@ import {
   injectRootArgs,    // the preview/locale argument injector (advanced AST use)
 } from '@fourtwelvelabs/fetch-contentful';
 import type { ShapeCollections, FetchContentfulOptions } from '@fourtwelvelabs/fetch-contentful';
+
+// Type-only subpath, for wiring gql.tada up by hand (see docs/tada.md).
+import type { ContentfulScalars, JsonValue } from '@fourtwelvelabs/fetch-contentful/tada';
 ```
 
 `ShapeCollections<T>` and `UnwrapSingleRoot<T>` are the type-level twins of `shapeData` and `unwrapSingleRoot`. Neither is needed alongside `fetchContentful` (shaping is built into it) — they're for shaping Contentful-shaped data that arrived some other way.