Codegen Artifact Generation Scripts

Two scripts in packages/api-core/scripts/ turn the hand-written OpenAPI source into the generated TypeScript artifacts that @primitivedotdev/api-core exports. Both run as part of pnpm generate in packages/api-core, and both are wired into the root make node-generate target described in Regenerating SDK Code from the OpenAPI Spec.

For the overall pipeline shape (why api-core exists, how sdk-node and cli-node bundle it), see Architecture: Shared Codegen Pipeline. For the OpenAPI 3.1 → 3.0.3 normalization rules applied here, see OpenAPI Spec Normalization and Codegen Artifacts.

generate-openapi-artifacts.ts#

Reads openapi/primitive-api.yaml (the authored OpenAPI 3.1 source of truth) and writes three files. Run it directly with:

cd packages/api-core
pnpm generate:openapi

Internally this is tsx scripts/generate-openapi-artifacts.ts, declared in packages/api-core/package.json.

Inputs and outputs#

What normalization does#

Before writing the codegen JSON, the script runs normalizeForCodegen over a deep clone of the raw spec:

• Nullable-type unwrapping: an OpenAPI 3.1 type: ["string", "null"] array becomes type: "string" plus nullable: true, since @hey-api/openapi-ts's 3.0.3-oriented generator does not consume the 3.1 array form.
• Content-type remapping for binary bodies: message/rfc822 and application/gzip request/response content are rekeyed to application/octet-stream so the generator treats them as binary payloads.
• The result is stamped openapi: "3.0.3" and written to primitive-api.codegen.json.

The raw (non-normalized) spec is written unchanged into openapi.generated.ts as the openapiDocument constant. That constant is what CLI tooling and the operation manifest infrastructure serve as the literal OpenAPI document, distinct from the codegen-only JSON.

Building the operation manifest#

For every HTTP method (delete, get, head, options, patch, post, put) on every path in the raw spec, the script emits one PrimitiveOperationManifest entry when the operation declares an operationId:

The manifest is sorted by tagCommand, then command.

When to re-run it#

Re-run generate-openapi-artifacts.ts (directly, or via pnpm generate / make node-generate) whenever openapi/primitive-api.yaml changes: new operations, changed parameters, changed request/response schemas, or changed tags. Downstream consumers (operationManifest, openapiDocument, and the codegen JSON that generate:api reads next) are all stale until this runs.

fix-generated-api-imports.ts#

fix-generated-api-imports.ts post-processes the @hey-api/openapi-ts output under packages/api-core/src/api to repair three known generator gaps: extensionless relative imports, unconditional Content-Type headers on optional-body operations, and a widened MemoryJsonValue type. It runs as the second half of pnpm generate:api:

cd packages/api-core
pnpm generate:api

That script is openapi-ts -f openapi-ts.config.ts && tsx scripts/fix-generated-api-imports.ts, so the fixup always runs immediately after generation, never standalone against stale output.

1. Add .js extensions to relative imports#

@hey-api/openapi-ts emits extensionless relative imports (from "./types"), which fail under Node's ESM resolution. For every from "..." and dynamic import("...") specifier starting with ./ or ../:

• Leaves .js / .json specifiers untouched.
• If the specifier resolves to a directory containing index.ts, rewrites it to <specifier>/index.js.
• Otherwise rewrites it to <specifier>.js.

2. Guard optional-body Content-Type headers#

@hey-api/openapi-ts unconditionally emits:

headers: {
  'Content-Type': 'application/json',
  ...options.headers
}

on every operation with a request body in the spec, even when the body is optional. For the optional-body operations (testFunction, cli_logout, start_cli_login, search_emails), this sends the header with no payload when the caller omits the body, which is wrong on the wire. The fixup rewrites the pattern to:

headers: {
  ...(options.body !== undefined && { 'Content-Type': 'application/json' }),
  ...options.headers
}

so the header only appears when a body is actually present. Required-body operations are unaffected, since the type system guarantees body is always defined there. This is the same class of bug documented for the Go and Python generators; see Non-TypeScript Codegen: Go and Python Clients and Codegen Troubleshooting.

3. Repair the MemoryJsonValue type#

@hey-api/openapi-ts currently widens the OpenAPI 3.1 type: "null" branch of the recursive MemoryJsonValue JSON-value schema to unknown, which widens the entire generated type alias. The fixup detects export type MemoryJsonValue = ... in the generated output and replaces it with the exact type:

export type MemoryJsonValue = string | number | boolean | Array<MemoryJsonValue> | {
    [key: string]: MemoryJsonValue;
} | null;

If the generated file's shape ever changes enough that the replacement pattern no longer matches, the script throws loudly (Unable to repair generated MemoryJsonValue type in ${file}...) instead of silently leaving the broken type in place. That failure is the signal that fixMemoryJsonValueType needs updating before the next publish. See Memory Value Validation Helper for the runtime counterpart, isMemoryJsonValue.

When to re-run it#

Never run it standalone. It only makes sense immediately after openapi-ts regenerates packages/api-core/src/api, which is why generate:api chains both steps. If pnpm generate:api (or make node-generate) fails partway or you regenerate with a different openapi-ts version and start seeing raw unknown types on MemoryJsonValue or missing .js extensions in generated imports, re-run pnpm generate:api from packages/api-core rather than invoking the fixup script alone against stale generator output.

Running both together#

cd packages/api-core
pnpm generate

pnpm generate runs generate:openapi then generate:api in sequence, which is exactly what make node-generate invokes from the repo root. Always commit the regenerated files alongside the source spec/schema change, per Regenerating SDK Code from the OpenAPI Spec.