@fourtwelvelabs/fetch-contentful 0.4.0 → 1.0.0

package/docs/tada.md

@@ -1,7 +1,7 @@
 # Typed queries with gql.tada
 
 [gql.tada](https://gql-tada.0no.co) infers TypeScript types from your GraphQL
-documents *as you write them* — no codegen step in your dev loop, no
+documents _as you write them_ — no codegen step in your dev loop, no
 hand-written result interfaces that drift from the query. This package ships
 a companion that points it at a Contentful space: one command writes the
 schema, the editor plugin config and the `graphql` helper, and
@@ -25,10 +25,10 @@ peer dependencies — they only matter at author time, so they belong in
 yarn add -D gql.tada @0no-co/graphqlsp
 ```
 
-**2. Run `tada-init`.** With `CONTENTFUL_SPACE_ID` and
-`CONTENTFUL_ACCESS_TOKEN` already in your environment (the same variables the
-library reads at runtime — see the README's Configuration section), this
-needs no arguments:
+**2. Run `tada-init`.** It reads your credentials from `.env.local`, then
+`.env`, then the shell — the same variable names the library uses at runtime
+(see the README's Configuration section). In a typical Next.js project that
+means no arguments at all:
 
 ```bash
 npx @fourtwelvelabs/fetch-contentful tada-init
@@ -46,7 +46,7 @@ It downloads the schema as SDL, adds `@0no-co/graphqlsp` to
 Add `--dry-run` first if you'd rather see the changes before they happen.
 
 That last file is the one you import from as you write queries. It's yours —
-commit it, edit it — and it exists because it has to be bound to *your*
+commit it, edit it — and it exists because it has to be bound to _your_
 space's schema, so it could never ship inside the package:
 
 ```ts
@@ -70,7 +70,7 @@ that query's result and variable types by matching it against `introspection`.
 See [Manual setup](#manual-setup) for writing this file yourself.
 
 **3. Restart the TypeScript server** so the editor picks up the plugin. In
-VS Code: <kbd>⌘⇧P</kbd> → *TypeScript: Restart TS Server*.
+VS Code: <kbd>⌘⇧P</kbd> → _TypeScript: Restart TS Server_.
 
 **4. Write a query**, importing `graphql` from the file step 2 generated.
 Autocomplete, field validation and types all come from your space's real
@@ -88,7 +88,9 @@ const PageQuery = graphql(`
         title
         publishedAt
         sectionsCollection {
-          items { heading }
+          items {
+            heading
+          }
         }
       }
     }
@@ -106,7 +108,7 @@ No type arguments, no result interface, no cast.
 
 **The result type follows the response you actually receive.** gql.tada types
 the raw wire shape; `fetchContentful` then applies its own shaping and
-unwrapping to *that* type, so `pageCollection.items` arrives as `pages` — an
+unwrapping to _that_ type, so `pageCollection.items` arrives as `pages` — an
 array — in both the value and the type. `shapeResponseData: false` and
 `unwrapRootField: false` are reflected too:
 
@@ -114,7 +116,7 @@ array — in both the value and the type. `shapeResponseData: false` and
 const raw = await fetchContentful(PageQuery, {
   variables: { slug: 'home' },
   shapeResponseData: false,
-  unwrapRootField: false,
+  unwrapRootField: false
 });
 //    ^? { pageCollection: { items: [...] } | null }
 ```
@@ -135,14 +137,14 @@ await fetchContentful(PageQuery, { variables: { slgu: 'home' } });
 **Contentful's custom scalars are typed**, via the `ContentfulScalars` map
 that `tada-init` wires up. Without it every one of them would be `unknown`:
 
-| Scalar | TypeScript |
-| --- | --- |
-| `DateTime` | `string` (ISO 8601 at UTC) |
-| `Dimension` | `number` (1–4000, image transforms) |
-| `HexColor` | `string` (`"rgb:ffffff"`) |
-| `JSON` | `JsonValue` (recursive JSON) |
-| `Quality` | `number` (1–100) |
-| `Circle` | `{ lat, lon, radius }` — a `_within_circle` search area |
+| Scalar      | TypeScript                                                   |
+| ----------- | ------------------------------------------------------------ |
+| `DateTime`  | `string` (ISO 8601 at UTC)                                   |
+| `Dimension` | `number` (1–4000, image transforms)                          |
+| `HexColor`  | `string` (`"rgb:ffffff"`)                                    |
+| `JSON`      | `JsonValue` (recursive JSON)                                 |
+| `Quality`   | `number` (1–100)                                             |
+| `Circle`    | `{ lat, lon, radius }` — a `_within_circle` search area      |
 | `Rectangle` | `{ topLeftLat, topLeftLon, bottomRightLat, bottomRightLon }` |
 
 `Circle` and `Rectangle` are geographic search areas used by location
@@ -223,7 +225,7 @@ Contentful can tell you when the content model changes; the schema file can
 then update itself through a pull request rather than by someone remembering
 to run a command.
 
-**1. Add a Contentful webhook.** In *Settings → Webhooks*, create one that
+**1. Add a Contentful webhook.** In _Settings → Webhooks_, create one that
 fires on **ContentType → publish** and **unpublish**, pointing at GitHub's
 `repository_dispatch` endpoint:
 
@@ -301,19 +303,20 @@ fetch-contentful tada-refresh [options]   Re-download the schema only
 
 Both commands accept the same options. Flags win over environment variables.
 
-| Option | Default | Notes |
-| --- | --- | --- |
-| `--space <id>` | `CONTENTFUL_SPACE_ID` | Required |
-| `--environment <id>` | `CONTENTFUL_ENVIRONMENT`, then `master` | |
-| `--token <token>` | `CONTENTFUL_ACCESS_TOKEN` | Content Delivery API token |
-| `--schema-path <path>` | `./contentful-schema.graphql` | Where the SDL is written |
-| `--tada-output <path>` | `./src/contentful-env.d.ts` | Where gql.tada writes its types |
-| `--graphql-file <path>` | `./src/graphql.ts` | `tada-init` only |
-| `--tsconfig <path>` | `./tsconfig.json` | `tada-init` only |
-| `--dry-run` | | Print the changes; write nothing |
-| `--force` | | Overwrite an existing graphql file |
-| `--cwd <path>` | | Run against another directory |
-| `-h`, `--help` | | |
+| Option                  | Default                                 | Notes                                   |
+| ----------------------- | --------------------------------------- | --------------------------------------- |
+| `--space <id>`          | `CONTENTFUL_SPACE_ID`                   | Required                                |
+| `--environment <id>`    | `CONTENTFUL_ENVIRONMENT`, then `master` |                                         |
+| `--token <token>`       | `CONTENTFUL_ACCESS_TOKEN`               | Content Delivery API token              |
+| `--schema-path <path>`  | `./contentful-schema.graphql`           | Where the SDL is written                |
+| `--tada-output <path>`  | `./src/contentful-env.d.ts`             | Where gql.tada writes its types         |
+| `--graphql-file <path>` | `./src/graphql.ts`                      | `tada-init` only                        |
+| `--tsconfig <path>`     | `./tsconfig.json`                       | `tada-init` only                        |
+| `--dry-run`             |                                         | Print the changes; write nothing        |
+| `--force`               |                                         | Overwrite an existing graphql file      |
+| `--cwd <path>`          |                                         | Run against another directory           |
+| `--env-file <path>`     | `.env.local`, then `.env`               | Read credentials from this file instead |
+| `-h`, `--help`          |                                         |                                         |
 
 The `NEXT_PUBLIC_`-prefixed variable names are read as fallbacks, exactly as
 the library reads them at runtime.
@@ -324,4 +327,26 @@ and formatting, and never overwrites `graphql.ts` unless you pass `--force`.
 If it cannot patch a tsconfig safely, it changes nothing and prints the block
 for you to paste in.
 
+### Where configuration comes from
+
+The commands resolve each setting from the first of these that has a value:
+
+1. a flag — `--space`, `--token`, `--environment`
+2. the shell environment
+3. `.env.local`
+4. `.env`
+
+The library itself never reads files from disk — that would break bundlers
+and edge runtimes, and your framework already owns that job. The CLI is a
+different case: it runs from a shell before anything has populated
+`process.env`, and a Next.js project keeps its credentials in `.env.local`,
+which Next only reads when Next itself boots. So the CLI reads that file
+directly, without overwriting anything you have genuinely exported.
+
+If your credentials live somewhere else, point at the file:
+
+```bash
+npx @fourtwelvelabs/fetch-contentful tada-refresh --env-file .env.contentful
+```
+
 The access token is never printed — not in output, not in error messages.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fourtwelvelabs/fetch-contentful",
-  "version": "0.4.0",
+  "version": "1.0.0",
   "description": "Foolproof, type-safe GraphQL fetching utility for Contentful with automatic query splitting, retries, and response shaping.",
   "keywords": [
     "contentful",