@fourtwelvelabs/fetch-contentful 0.1.0 → 0.3.0

package/dist/tada/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.mjs"}

package/docs/tada.md

@@ -0,0 +1,327 @@
+# 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
+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
+`fetchContentful` infers both the result and the variables from whatever
+document you hand it.
+
+- [Five-minute quickstart](#five-minute-quickstart)
+- [What you get](#what-you-get)
+- [Manual setup](#manual-setup)
+- [Keeping the schema fresh](#keeping-the-schema-fresh)
+- [CI recipe](#ci-recipe)
+- [CLI reference](#cli-reference)
+
+## Five-minute quickstart
+
+**1. Install the peers.** gql.tada and its TypeScript plugin are optional
+peer dependencies — they only matter at author time, so they belong in
+`devDependencies`:
+
+```bash
+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:
+
+```bash
+npx @fourtwelvelabs/fetch-contentful tada-init
+```
+
+```
+Configuring gql.tada for space abc123, environment master.
+  created      contentful-schema.graphql (412.7 kB)
+  updated      tsconfig.json
+  created      src/graphql.ts
+```
+
+It downloads the schema as SDL, adds `@0no-co/graphqlsp` to
+`compilerOptions.plugins` in your `tsconfig.json`, and writes `src/graphql.ts`.
+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*
+space's schema, so it could never ship inside the package:
+
+```ts
+// src/graphql.ts
+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;
+  scalars: ContentfulScalars;
+}>();
+
+export { readFragment } from 'gql.tada';
+export type { FragmentOf, ResultOf, VariablesOf } from 'gql.tada';
+```
+
+`graphql` is a tagged template function that does 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 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*.
+
+**4. Write a query**, importing `graphql` from the file step 2 generated.
+Autocomplete, field validation and types all come from your space's real
+content model:
+
+```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
+        publishedAt
+        sectionsCollection {
+          items { heading }
+        }
+      }
+    }
+  }
+`);
+
+const pages = await fetchContentful(PageQuery, { variables: { slug: 'home' } });
+//    ^? Array<{ title: string | null; publishedAt: string | null;
+//               sections: Array<{ heading: string | null }> }> | null
+```
+
+No type arguments, no result interface, no cast.
+
+## What you get
+
+**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
+array — in both the value and the type. `shapeResponseData: false` and
+`unwrapRootField: false` are reflected too:
+
+```ts
+const raw = await fetchContentful(PageQuery, {
+  variables: { slug: 'home' },
+  shapeResponseData: false,
+  unwrapRootField: false,
+});
+//    ^? { pageCollection: { items: [...] } | null }
+```
+
+**Variables are required when — and only when — you have to supply them.**
+`$preview` and `$locale` are injected by the library, so a document that
+declares only those needs no `variables` at all. Anything else is enforced,
+and a typo is a compile error rather than a silently dropped argument:
+
+```ts
+await fetchContentful(PageQuery);
+//                    ~~~~~~~~~ `variables` is required: $slug
+
+await fetchContentful(PageQuery, { variables: { slgu: 'home' } });
+//                                             ~~~~ not a variable of this document
+```
+
+**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 |
+| `Rectangle` | `{ topLeftLat, topLeftLon, bottomRightLat, bottomRightLon }` |
+
+`Circle` and `Rectangle` are geographic search areas used by location
+filters, not numbers — Contentful rejects anything else.
+
+**Fragments work as usual.** `tada-init` re-exports the helpers you need
+from the generated module:
+
+```ts
+import { readFragment, type FragmentOf } from './graphql';
+```
+
+## Manual setup
+
+The CLI is a convenience, not a requirement. `ContentfulScalars` is exported
+as a plain type, so you can hand it to `initGraphQLTada` yourself — useful if
+you already generate the schema another way, or keep several spaces side by
+side:
+
+```ts
+// src/graphql.ts
+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;
+  scalars: ContentfulScalars;
+}>();
+
+export { readFragment } from 'gql.tada';
+export type { FragmentOf, ResultOf, VariablesOf } from 'gql.tada';
+```
+
+with, in `tsconfig.json`:
+
+```jsonc
+{
+  "compilerOptions": {
+    "plugins": [
+      {
+        "name": "@0no-co/graphqlsp",
+        "schema": "./contentful-schema.graphql",
+        "tadaOutputLocation": "./src/contentful-env.d.ts"
+      }
+    ]
+  }
+}
+```
+
+The `/tada` entry point is types only — nothing in it imports gql.tada, and
+the built module is empty — so importing it adds nothing to your bundle.
+
+`fetchContentful` targets `TypedDocumentNode`, which gql.tada's documents
+satisfy structurally. Documents from graphql-codegen's client preset satisfy
+it too, so everything above applies equally if you use codegen instead.
+
+## Keeping the schema fresh
+
+The SDL file is a snapshot of your content model. After you publish a
+content-type change, re-download it:
+
+```bash
+npx @fourtwelvelabs/fetch-contentful tada-refresh
+```
+
+If nothing changed, the file is left untouched — same bytes, same mtime, no
+entry in `git status`. Commit `contentful-schema.graphql`: it's what makes a
+fresh checkout type-check without network access.
+
+The gql.tada output file (`src/contentful-env.d.ts`) is regenerated from the
+SDL by gql.tada itself, either by the editor plugin or with
+`npx gql.tada generate-output`.
+
+## CI recipe
+
+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
+fires on **ContentType → publish** and **unpublish**, pointing at GitHub's
+`repository_dispatch` endpoint:
+
+- URL: `https://api.github.com/repos/<owner>/<repo>/dispatches`
+- Method: `POST`
+- Headers: `Accept: application/vnd.github+json`,
+  `Authorization: Bearer <a GitHub token with contents:write>`
+- Payload (custom): `{ "event_type": "contentful-schema-changed" }`
+
+**2. Add the workflow:**
+
+```yaml
+# .github/workflows/contentful-schema.yml
+name: Refresh Contentful schema
+
+on:
+  repository_dispatch:
+    types: [contentful-schema-changed]
+  schedule:
+    - cron: '0 6 * * 1' # a Monday safety net, in case a webhook is missed
+  workflow_dispatch:
+
+jobs:
+  refresh:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: yarn
+      - run: yarn install --immutable
+
+      - run: yarn fetch-contentful tada-refresh
+        env:
+          CONTENTFUL_SPACE_ID: ${{ secrets.CONTENTFUL_SPACE_ID }}
+          CONTENTFUL_ACCESS_TOKEN: ${{ secrets.CONTENTFUL_ACCESS_TOKEN }}
+
+      # gql.tada's generated types follow the SDL.
+      - run: yarn gql.tada generate-output
+
+      # Fails the PR if the new schema broke an existing query.
+      - run: yarn tsc --noEmit
+        continue-on-error: true
+
+      - uses: peter-evans/create-pull-request@v7
+        with:
+          title: 'chore: refresh Contentful schema'
+          body: |
+            The Contentful content model changed. Review the schema diff and
+            check that every query still type-checks.
+          branch: chore/contentful-schema
+          commit-message: 'chore: refresh Contentful schema'
+          add-paths: |
+            contentful-schema.graphql
+            src/contentful-env.d.ts
+```
+
+`create-pull-request` opens a PR only when something actually changed, and
+`tada-refresh` writes nothing when the schema is identical — so a no-op
+webhook costs one CI run and produces no noise.
+
+Use a **Content Delivery API** token here, not a Content Management one: it
+is read-only, and introspection is all this needs.
+
+## CLI reference
+
+```
+fetch-contentful tada-init [options]      Set up gql.tada in this project
+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` | | |
+
+The `NEXT_PUBLIC_`-prefixed variable names are read as fallbacks, exactly as
+the library reads them at runtime.
+
+`tada-init` is safe to run repeatedly. It updates the graphqlsp entry in your
+tsconfig in place rather than adding a second one, preserves your comments
+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.
+
+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.1.0",
+  "version": "0.3.0",
   "description": "Foolproof, type-safe GraphQL fetching utility for Contentful with automatic query splitting, retries, and response shaping.",
   "keywords": [
     "contentful",
@@ -22,6 +22,7 @@
   },
   "type": "module",
   "sideEffects": false,
+  "bin": "./dist/cli/index.mjs",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
@@ -36,10 +37,21 @@
         "default": "./dist/index.cjs"
       }
     },
+    "./tada": {
+      "import": {
+        "types": "./dist/tada/index.d.ts",
+        "default": "./dist/tada/index.mjs"
+      },
+      "require": {
+        "types": "./dist/tada/index.d.cts",
+        "default": "./dist/tada/index.cjs"
+      }
+    },
     "./package.json": "./package.json"
   },
   "files": [
     "dist",
+    "docs",
     "README.md",
     "LICENSE"
   ],
@@ -59,18 +71,32 @@
     "test:coverage": "vitest run --coverage",
     "clean": "rm -rf dist .turbo"
   },
+  "dependencies": {
+    "@graphql-typed-document-node/core": "^3.2.0"
+  },
   "peerDependencies": {
+    "@0no-co/graphqlsp": "^1.12.0",
+    "gql.tada": "^1.8.0",
     "graphql": "^16.14.2 || ^17.0.0"
   },
+  "peerDependenciesMeta": {
+    "@0no-co/graphqlsp": {
+      "optional": true
+    },
+    "gql.tada": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@repo/eslint-config": "*",
     "@repo/typescript-config": "*",
     "@types/node": "^22.15.3",
     "@vitest/coverage-v8": "^2.1.9",
     "eslint": "^9.39.1",
+    "gql.tada": "^1.11.3",
     "graphql": "^16.14.2",
     "tsup": "^8.5.1",
     "typescript": "5.9.2",
     "vitest": "^2.1.9"
   }
-}
+}