@contoprix/codegen

Programmatic TypeScript generator for a tenant's Contoprix GraphQL schema. It converts a standard GraphQL introspection result into deterministic interfaces, unions, enums, input types, and root query variable/result types.

Most applications should use contoprix graphql sync from @contoprix/cli. Use this package directly when building custom generators or CI tooling.

Installation

npm install --save-dev @contoprix/codegen @contoprix/client

Generate TypeScript

The schema export endpoint requires schema:read and should be called from trusted tooling:

import { writeFile } from "node:fs/promises";
import { ContoprixClient } from "@contoprix/client";
import { generateTypeScript } from "@contoprix/codegen";

const client = new ContoprixClient({
  baseUrl: process.env.CONTOPRIX_BASE_URL!,
  auth: {
    type: "clientCredentials",
    clientId: process.env.CONTOPRIX_CLIENT_ID!,
    clientSecret: process.env.CONTOPRIX_CLIENT_SECRET!
  }
});

const schema = await client.sdk.getGraphQLSchema();

const source = generateTypeScript(schema.introspection, {
  schemaRevision: schema.schemaRevision,
  schemaFingerprint: schema.schemaFingerprint
});

await writeFile("src/contoprix/graphql-generated.ts", source, "utf8");

The first argument must be the introspection data envelope shaped as { __schema: ... }, not the full SDK export response.

Generated output

The generator creates:

• interfaces for GraphQL object, interface, and input-object types;
• string unions for GraphQL enums;
• discriminated TypeScript unions for GraphQL unions;
• aliases for custom scalars;
• {RootField}QueryVariables and {RootField}QueryResult interfaces for every Query field;
• a source banner containing the optional schema revision and fingerprint.

GraphQL built-in scalars map as follows:

| GraphQL | TypeScript | | --- | --- | | String, ID | string | | Int, Float | number | | Boolean | boolean | | Custom scalar | Generated named alias initially typed as unknown |

Object interfaces include a literal __typename, allowing normal discriminated-union narrowing:

function renderBlock(block: PageBlockContent) {
  switch (block.__typename) {
    case "Hero":
      return block.title;
    case "Gallery":
      return block.images;
  }
}

Use generated query types

import { createContoprixGraphQLClient } from "@contoprix/graphql-client";
import type {
  ArticleQueryResult,
  ArticleQueryVariables
} from "./contoprix/graphql-generated";

const variables: ArticleQueryVariables = {
  slug: "welcome",
  locale: "en"
};

const data = await graphql.request<ArticleQueryResult>(document, variables);

The exact names depend on the tenant's root field names.

Deterministic generation

Types and query fields are sorted before generation. The same introspection document and options therefore produce byte-identical output, which keeps generated-file diffs reviewable.

Do not edit generated files by hand. Regenerate them whenever the schema revision or fingerprint changes.

Validation

generateTypeScript throws when the input does not contain __schema:

try {
  const source = generateTypeScript(value);
} catch (error) {
  console.error("Invalid introspection document", error);
}

License

MIT