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.

The eleven families

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

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, and flow-builder spreads ElementParts from 153 places — a 5.5 MB chunk no bundler can dedupe. A post-codegen pass then prints each fragment once per file and interpolates the constant, so the operation text still carries its fragments, as text that gzips.

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

Adding or changing an operation

Edit 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 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.