Generated operations

Codegen runs one entry per module, over that module's own operations.graphql, so identical fragment names repeated across modules never collide in a single run. Which modules those are is read off the disk rather than listed: three of the fourteen ship no operations at all, and a list would be a fourth copy of a fact the directory already answers.

The eleven families

Counts are top-level definitions in each operations.graphql — 515 operations and 109 fragments across the eleven. Outside the app — a Node script, the wizard — the same files are reachable as @chatfuel/api-client/generated/<family>.

admin, auth and channels have no family. auth talks to Supabase over RPC; admin goes through the proxy's own admin routes; channels reads and writes through core, which is where its operations live.

A module may import its own family or core, and nothing else. Validate pass 10 fails the build on a crossing import, which is what keeps one module's screen from quietly depending on another module's schema knowledge.

How the names are formed

documentMode: 'string' means every document is a printed TypedDocumentString, not an AST. An operation becomes <OperationName>Document and a fragment becomes <Name>FragmentDoc: query InstagramAccountState is exported as InstagramAccountStateDocument, and fragment InstagramAccountRef as InstagramAccountRefFragmentDoc.

The string mode was chosen for size. Every AST mode inlines each fragment's object literal into every operation that spreads it — a 5.5 MB chunk no bundler can dedupe. String mode has the same problem in text: codegen prints an operation's whole transitive fragment closure into that operation's string, and ElementParts alone came out 153 times, three quarters of a 1.9 MB file. So a post-codegen pass prints each fragment once per file and interpolates the constant instead. The operation stays first in the text, which is the only thing getDocMeta reads it for, and each fragment appears exactly once per operation so no server ever sees two definitions of one name. The pass is idempotent: running it twice changes nothing.

You never name the generated types in module code. Import the document, hand it to the client, and the result type comes with it:

import { InstagramAccountStateDocument } from '~api/generated/publishing/graphql';

  useEffect(() => {
    let live = true;
    setGate({ state: 'loading' });
    client
      .query(InstagramAccountStateDocument, { botID: botId })
      .then((data) => {
        if (!live) return;
        const scope = data.bot.contactScopes.find(
          (candidate): candidate is Extract<typeof candidate, { instagramAccount: Account }> =>
            'instagramAccount' in candidate && Boolean(candidate.instagramAccount),
        );
        const account = scope?.instagramAccount ?? null;
        if (!account) setGate({ state: 'absent' });
        else setGate(canPublish(account) ? { state: 'ready', account } : { state: 'unpermitted', account });
      })
      .catch((err: unknown) => {
        if (!live) return;
        setGate({ state: 'error', message: errorMessage(err) });
      });
    return () => {
      live = false;
    };
  }, [client, botId, tick, refreshToken]);

What the generator emits

The generator body is content/codegen/, and it is copied into every scaffolded app as scripts/codegen/ so both ends run the same one. Nothing in it imports @graphql-codegen/* — the config shape is written out by hand in types.ts, because an app that never extends the API still runs tsc over its scripts/ directory and would otherwise go red on a package it has no reason to install. This repository is where the two are held together: content/api-client/codegen.ts assigns the built config to a real CodegenConfig, so the type check fails the day the hand-written shape stops being one.

The schema everything is checked against is content/schema/schema.graphql — 6,896 lines, generated from a larger one, names and types only, with no descriptions and no deprecated members. possible-types.json sits beside it, holding each interface's and union's concrete types.

Adding an operation in your app

A scaffolded app carries the same three inputs under src/vendor/, and regenerates from them without leaving the repository.

1. Edit src/vendor/api/operations/<module>.graphql.
2. Run npm run codegen. The first run prints the one command that installs the toolchain — filled in for whichever package manager wrote your lockfile, versions exact — and stops.
3. Commit the regenerated files under src/vendor/api/generated/ together with the document.

Then npm run check. Never edit src/vendor/api/generated/ by hand: it is output, and the next run overwrites the edit with no trace. Regenerating an app you have not touched leaves an empty diff, so a diff you did not expect is a real difference in the inputs.

src/vendor/api/generated/.codegen-inputs.json is the stamp — the digest of the schema and of every operation document as they were when the client beside them was generated. It answers "are these types current?" without regenerating to find out. update refreshes the inputs but never the generated files, so when it moves one it says so under regenerate the client and leaves the run to you.

Adding one here

Edit content/modules/<id>/skill/examples/operations.graphql — that file is the source document, not the generated one — then run pnpm codegen at the repository root, which runs graphql-codegen and the fragment hoist. pnpm codegen:check re-runs it and fails on any diff. pnpm validate is what checks the result.

The same operations.graphql is copied into a scaffolded app as part of the module's agent skill, so the coding agent working in that app reads the validated operations rather than guessing at the schema. What runs them is the client the module receives.