Generate TypeScript

Generate checked-in types and flat Fetch functions from one Backend OpenAPI contract.

Jetrepo publishes an exact OpenAPI 3.1 document for each Backend. A frontend can generate its own TypeScript types and flat SDK functions without a hosted generator or a Jetrepo-specific query language.

The recommended generator is pinned @hey-api/openapi-ts with its Fetch client and flat SDK plugins. Generation runs inside your frontend repository.

Save the contract

A delegated agent can inspect Delivery and read the returned OpenAPI resource before it has a Delivery key. A deployed application can fetch /openapi.json with its Delivery key.

Verify the response before saving it:

X-JetRepo-OpenAPI-SHA256 is the SHA-256 of the exact response bytes;
ETag is the same strong content identity;
never save the Delivery key with the document.

Keep the OpenAPI document and generated output in the frontend repository so schema changes produce reviewable diffs.

Configure Hey API

import { defineConfig } from '@hey-api/openapi-ts';

export default defineConfig({
  input: './openapi/delivery.openapi.json',
  output: {
    path: './src/generated/delivery',
    postProcess: ['oxfmt'],
  },
  plugins: ['@hey-api/typescript', '@hey-api/client-fetch', '@hey-api/sdk'],
});

Pin the generator version in the frontend lockfile. Treat the output directory as generated code and do not edit it.

Generated functions use stable names such as listMission and getMission. Request, success, and status-specific error types remain separate.

import { listMission } from './generated/delivery';
import { createClient } from './generated/delivery/client';

const client = createClient({
  baseUrl: process.env.JETREPO_DELIVERY_URL,
  headers: { 'x-api-key': process.env.JETREPO_DELIVERY_API_KEY },
});

const result = await listMission({
  client,
  query: { ids: ['MISSION_ID'], locale: 'en' },
});

if (result.error) {
  console.error(result.response?.status, result.error.error);
}

Nested filter serialization

Jetrepo filters use nested query keys such as filter[price][gte]=10. Deeply nested objects are not fully defined by OpenAPI serialization. Keep one golden URL test in the frontend and install a small recursive query serializer when the selected generator does not produce this grammar exactly.

Do not change the Delivery API or introduce a new query language to accommodate a generator.

Regeneration gate

A production frontend should run these checks in CI:

validate the saved document as OpenAPI 3.1;
generate from the local document without network access;
fail when generated output changes;
compare the live OpenAPI SHA-256 with the checked-in document in a separate authenticated job;
compile fixtures for Components, Assets, relationships, Taxonomy, errors, pagination, and provenance headers.

TanStack Query and Zod generation are optional. Add them only when the frontend uses them and the generated bundle has been measured.