@fourtwelvelabs/fetch-contentful 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,90 @@
 # @fourtwelvelabs/fetch-contentful
 
+## 0.4.0
+
+### Minor Changes
+
+- 73b5ec2: Separate `deliveryToken` and `previewToken`, and stop reading the preview
+  token from a `NEXT_PUBLIC_` variable.
+
+  ### The preview token can no longer leak into a client bundle
+
+  `readEnvSettings` used to fall back to
+  `NEXT_PUBLIC_CONTENTFUL_PREVIEW_ACCESS_TOKEN`. Next.js inlines
+  `NEXT_PUBLIC_` variables into client bundles by string-replacing the literal
+  `process.env.NEXT_PUBLIC_…` accesses this package ships, so a project that
+  set that variable had its preview token baked into public JavaScript —
+  whether or not any client code ever requested preview content. Importing the
+  library was enough.
+
+  The preview token is now resolved **only** from the unprefixed
+  `CONTENTFUL_PREVIEW_ACCESS_TOKEN`. In Next.js that name is still readable on
+  the server, so server-side preview keeps working; the migration is to drop
+  the `NEXT_PUBLIC_` prefix from that one variable. The space, environment and
+  delivery token keep their client-safe names — a delivery token is read-only
+  and commonly public.
+
+  If your app genuinely needs preview in the browser, pass `previewToken`
+  explicitly.
+
+  ### `deliveryToken` and `previewToken`
+
+  A single `token` could not serve both modes: it applied to whichever mode was
+  active, so a factory configured with one sent the wrong token as soon as a
+  call passed `preview: true` — and there was no way to configure both
+  explicitly at all.
+
+  ```ts
+  export const fetchContentful = createFetchContentful({
+    deliveryToken: process.env.CONTENTFUL_ACCESS_TOKEN,
+    previewToken: process.env.CONTENTFUL_PREVIEW_ACCESS_TOKEN,
+  });
+
+  await fetchContentful(QUERY); // → deliveryToken
+  await fetchContentful(QUERY, { preview: true }); // → previewToken
+  ```
+
+  `token` still works and still applies to the active mode, so existing code is
+  unaffected, but it is deprecated in favour of the two specific options.
+  `readEnvSettings()` gains `deliveryToken`; its `token` field remains as a
+  deprecated alias of the same value.
+
+  The GraphQL endpoint is unchanged — unlike Contentful's REST APIs, preview
+  uses the same `graphql.contentful.com` host and is selected by the token plus
+  the injected `preview: true` argument. (The REST locale lookup already
+  switched between `cdn.` and `preview.` hosts correctly.)
+
+## 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
@@ -64,7 +149,7 @@
 - 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, honouring `Retry-After`.
+  - 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.

package/README.md

@@ -3,10 +3,10 @@
 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).
@@ -22,7 +22,7 @@ yarn add @fourtwelvelabs/fetch-contentful graphql
 
 Settings resolve in this order — first hit wins, per setting:
 
-1. **Per-call options** — `fetchContentful(query, { space, token, ... })`
+1. **Per-call options** — `fetchContentful(query, { space, deliveryToken, ... })`
 2. **Factory defaults** — set once with `createFetchContentful` (below)
 3. **Environment variables** — framework-neutral names first, then `NEXT_PUBLIC_`-prefixed equivalents
 
@@ -34,12 +34,22 @@ If `space` or the appropriate token can't be resolved, the promise rejects with
 | --- | --- | --- |
 | `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` |
+| `deliveryToken` | `CONTENTFUL_ACCESS_TOKEN` | `NEXT_PUBLIC_CONTENTFUL_ACCESS_TOKEN` |
+| `previewToken` | `CONTENTFUL_PREVIEW_ACCESS_TOKEN` | **none, by design** |
+
+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.
+**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. This applies to the space, the environment and the delivery token; the preview token has no client-safe name, for the reason below.
+
+### The preview token is never read from a `NEXT_PUBLIC_` variable
+
+Next.js exposes `NEXT_PUBLIC_` variables to the browser by string-replacing literal `process.env.NEXT_PUBLIC_…` accesses at build time. This library contains such accesses, so if it read the preview token from a prefixed name, setting that variable would bake the token into your public JavaScript — whether or not any client code ever asked for preview content. Importing the library would be enough.
+
+A delivery token is read-only and commonly public. A **preview token reads unpublished content**, so it is resolved only from the unprefixed `CONTENTFUL_PREVIEW_ACCESS_TOKEN`. In Next.js that name is still readable on the server — the prefix only controls *client* exposure — so server-side preview (Draft Mode, route handlers, server components) works unchanged.
+
+If you have decided that your app genuinely needs preview in the browser, pass `previewToken` explicitly. Shipping it is then your deliberate choice rather than something the library did on your behalf.
 
 ### Project-level defaults with `createFetchContentful`
 
@@ -51,9 +61,13 @@ 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,
 });
+
+// Configure both tokens once, and every call picks the right one:
+//   fetchContentful(QUERY)                     → deliveryToken
+//   fetchContentful(QUERY, { preview: true })  → previewToken
 ```
 
 ```ts
@@ -102,6 +116,8 @@ 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:
@@ -111,11 +127,31 @@ yarn add -D gql.tada @0no-co/graphqlsp
 npx @fourtwelvelabs/fetch-contentful tada-init
 ```
 
-That downloads your space's schema as SDL, registers `@0no-co/graphqlsp` in your `tsconfig.json` and writes `src/graphql.ts`. It reads the same environment variables the library does, is safe to re-run, and takes `--dry-run`. Restart the TypeScript server afterwards, and queries type themselves:
+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';
+import { graphql } from '../graphql';
 
 const PageQuery = graphql(`
   query Page($slug: String!) {
@@ -183,11 +219,12 @@ 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
+  deliveryToken: '...',       // CDA token, used when preview is false
+  previewToken: '...',        // CPA token, used when preview is true
 
-  // Request behaviour
+  // Request behavior
   variables: { slug: 'home' },
   retries: 5,                 // retry count after the initial attempt
   retryDelayMs: 250,          // base backoff delay

package/dist/cli/index.mjs

@@ -12,10 +12,14 @@ function readEnvSettings() {
     return {
       space: void 0,
       environment: void 0,
+      deliveryToken: void 0,
       token: void 0,
       previewToken: void 0
     };
   }
+  const deliveryToken = orUndefined(
+    process.env.CONTENTFUL_ACCESS_TOKEN || process.env.NEXT_PUBLIC_CONTENTFUL_ACCESS_TOKEN
+  );
   return {
     space: orUndefined(
       process.env.CONTENTFUL_SPACE_ID || process.env.NEXT_PUBLIC_CONTENTFUL_SPACE_ID
@@ -23,12 +27,10 @@ function readEnvSettings() {
     environment: orUndefined(
       process.env.CONTENTFUL_ENVIRONMENT || process.env.NEXT_PUBLIC_CONTENTFUL_ENVIRONMENT
     ),
-    token: orUndefined(
-      process.env.CONTENTFUL_ACCESS_TOKEN || process.env.NEXT_PUBLIC_CONTENTFUL_ACCESS_TOKEN
-    ),
-    previewToken: orUndefined(
-      process.env.CONTENTFUL_PREVIEW_ACCESS_TOKEN || process.env.NEXT_PUBLIC_CONTENTFUL_PREVIEW_ACCESS_TOKEN
-    )
+    deliveryToken,
+    token: deliveryToken,
+    // No `NEXT_PUBLIC_` fallback: see the note at the top of this file.
+    previewToken: orUndefined(process.env.CONTENTFUL_PREVIEW_ACCESS_TOKEN)
   };
 }
 
@@ -673,7 +675,7 @@ the library reads them at runtime.`;
 function resolveConfig(args) {
   const env = readEnvSettings();
   const space = args.values.space ?? env.space;
-  const token = args.values.token ?? env.token;
+  const token = args.values.token ?? env.deliveryToken;
   const environment = args.values.environment ?? env.environment ?? "master";
   const missing = [];
   if (!space) {
@@ -916,7 +918,10 @@ async function dispatch(argv, io) {
 }
 function knownTokens(argv) {
   const env = readEnvSettings();
-  const tokens = [env.token, env.previewToken];
+  const tokens = [
+    env.deliveryToken,
+    env.previewToken
+  ];
   for (const [index, argument] of argv.entries()) {
     if (argument.startsWith("--token=")) tokens.push(argument.slice(8));
     else if (argument === "--token") tokens.push(argv[index + 1]);