@fourtwelvelabs/fetch-contentful 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,83 @@
 # @fourtwelvelabs/fetch-contentful
 
+## 0.4.1
+
+### Patch Changes
+
+- fce4b46: The CLI now reads `.env.local` and `.env`.
+
+  `tada-init` and `tada-refresh` previously reported the space and token
+  missing in any project that keeps them in `.env.local` — which is most
+  Next.js projects. The message was technically true (nothing had populated
+  `process.env`, because Next reads that file only when Next itself boots) but
+  gave no hint that a file sitting in the same directory had been ignored.
+
+  Each setting now resolves from the first of: a flag, the shell environment,
+  `.env.local`, then `.env`. Anything genuinely exported still wins over a
+  file, so CI and shell overrides behave as before. A new `--env-file <path>`
+  reads somewhere else instead, and fails loudly if the path does not exist.
+
+  When configuration is still missing, the error now says which files were
+  read, or where it looked and found none.
+
+  Only the CLI does this. The library continues never to touch the disk:
+  reading files would break bundlers and edge runtimes, and platforms own that
+  job at runtime.
+
+## 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

package/README.md

@@ -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,14 +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`
 
@@ -56,6 +64,10 @@ export const fetchContentful = createFetchContentful({
   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
@@ -209,7 +221,8 @@ fetchContentful(query, {
   preview: false,             // default: false
   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 behavior
   variables: { slug: 'home' },

package/dist/cli/index.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { mkdirSync, writeFileSync, existsSync, readFileSync } from 'fs';
+import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'fs';
 import { resolve, dirname, relative, isAbsolute, sep, join } from 'path';
 import { getIntrospectionQuery, printSchema, buildClientSchema } from 'graphql';
 
@@ -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)
   };
 }
 
@@ -51,7 +53,8 @@ var VALUE_FLAGS = [
   "tada-output",
   "graphql-file",
   "tsconfig",
-  "cwd"
+  "cwd",
+  "env-file"
 ];
 function isBooleanFlag(name) {
   return BOOLEAN_FLAGS.includes(name);
@@ -156,6 +159,55 @@ function formatBytes(bytes) {
   if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} kB`;
   return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
 }
+var ENV_FILES = [".env.local", ".env"];
+var ASSIGNMENT = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/;
+function parseEnvFile(source) {
+  const values = {};
+  for (const rawLine of source.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (line === "" || line.startsWith("#")) continue;
+    const match = ASSIGNMENT.exec(line);
+    if (!match) continue;
+    const key = match[1];
+    let value = match[2].trim();
+    const quote = value[0];
+    if ((quote === '"' || quote === "'") && value.length > 1 && value.endsWith(quote)) {
+      value = value.slice(1, -1);
+      if (quote === '"') value = value.replace(/\\n/g, "\n");
+    } else {
+      const comment = value.search(/\s#/);
+      if (comment !== -1) value = value.slice(0, comment).trimEnd();
+    }
+    values[key] = value;
+  }
+  return values;
+}
+function loadEnvFiles(directory, explicit) {
+  const load = { directory, files: [], applied: [] };
+  if (explicit !== void 0 && !existsSync(resolve(directory, explicit))) {
+    throw new CliError(`No env file at ${explicit}.`);
+  }
+  for (const candidate of explicit === void 0 ? ENV_FILES : [explicit]) {
+    const path = resolve(directory, candidate);
+    if (!existsSync(path)) continue;
+    load.files.push(candidate);
+    for (const [key, value] of Object.entries(
+      parseEnvFile(readFileSync(path, "utf8"))
+    )) {
+      if (!process.env[key]) {
+        process.env[key] = value;
+        load.applied.push(key);
+      }
+    }
+  }
+  return load;
+}
+function describeEnvFiles(load) {
+  if (load.files.length === 0) {
+    return `No ${ENV_FILES.join(" or ")} file was found in ${load.directory}, so only the shell environment was read. Point at one with --env-file if it lives elsewhere.`;
+  }
+  return `Read ${load.files.join(" and ")}; anything already set in the environment takes precedence over them.`;
+}
 var PACKAGE_NAME = "@fourtwelvelabs/fetch-contentful";
 function relativeSpecifier(fromFile, toFile) {
   const path = relative(dirname(fromFile), toFile).split(sep).join("/");
@@ -666,14 +718,17 @@ Other:
   --dry-run               Show what would change; write nothing
   --force                 Overwrite an existing graphql file (tada-init)
   --cwd <path>            Run against another directory
+  --env-file <path>       Read this file instead of .env.local / .env
   -h, --help              Show this help
 
-The NEXT_PUBLIC_-prefixed variable names are read as fallbacks, exactly as
-the library reads them at runtime.`;
-function resolveConfig(args) {
+Configuration is read from .env.local, then .env, then the shell \u2014 anything
+already exported wins over a file, and flags win over everything. The
+NEXT_PUBLIC_-prefixed names are accepted as fallbacks, exactly as the
+library reads them at runtime.`;
+function resolveConfig(args, envFiles) {
   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) {
@@ -691,7 +746,8 @@ function resolveConfig(args) {
       `Missing required Contentful configuration:
   - ${missing.join(
         "\n  - "
-      )}`
+      )}
+${describeEnvFiles(envFiles)}`
     );
   }
   return { space, environment, token };
@@ -842,8 +898,9 @@ function reportPeers(paths, io) {
   io.stdout(`  ${installCommand(detectPackageManager(paths.root), missing)}`);
 }
 async function tadaInit(args, io) {
-  const config = resolveConfig(args);
   const paths = resolvePaths(args, io);
+  const envFiles = loadEnvFiles(paths.root, args.values["env-file"]);
+  const config = resolveConfig(args, envFiles);
   const dryRun = args.flags.has("dry-run");
   const tsconfigAction = planTsconfig(paths);
   const sdl = await fetchSchemaSdl({ ...config, fetch: io.fetch });
@@ -881,8 +938,9 @@ async function tadaInit(args, io) {
   return 0;
 }
 async function tadaRefresh(args, io) {
-  const config = resolveConfig(args);
   const paths = resolvePaths(args, io);
+  const envFiles = loadEnvFiles(paths.root, args.values["env-file"]);
+  const config = resolveConfig(args, envFiles);
   const dryRun = args.flags.has("dry-run");
   const sdl = await fetchSchemaSdl({ ...config, fetch: io.fetch });
   const action = planSchema(sdl, paths);
@@ -916,7 +974,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]);