@heroku/types

This package provides TypeScript types and a runtime route registry, generated from the Heroku API Hyperschema. Generated files are organized by API variant. For example, the 3.sdk variant outputs to dist/3.sdk/types.d.ts and dist/3.sdk/routes.js.

NOTE: This package currently provides two variants: 3.sdk (Heroku Platform API, fully generated from the hyperschema) and data (Heroku's data services control plane / Shogun, where types are generated from spec-captured payloads against a hand-curated resource grouping).

Installation

npm install @heroku/types

Types are available under the variant subpath:

import type { Account, Addon } from '@heroku/types/3.sdk'

A runtime route registry is also available, providing method, path, and request-body metadata for each API endpoint:

import { app, dyno } from '@heroku/types/3.sdk/routes'

console.log(app.create) // { method: 'POST', path: '/apps', hasRequestBody: true }
console.log(dyno.list)  // { method: 'GET', path: '/apps/{appId}/dynos' }

Generating Type Definitions

The package includes a CLI that fetches the live Heroku API hyperschema and generates type definitions and a route registry. Before writing files to the file system, the type output is verified against the TypeScript type checker to ensure we're only writing valid definitions.

Run the CLI

npm run generate

This fetches the schema from https://api.heroku.com/schema and writes the generated files into dist/<variant>/ (e.g. dist/3.sdk/). It also updates package.json exports automatically. The CLI is executed directly from TypeScript via tsx — no separate build step is required.

CLI Options

Usage: heroku-types [options]

Options:
  --variant <variant>   Schema variant (default: 3.sdk)
  --base-url <url>      Schema endpoint (default: https://api.heroku.com/schema)
  --help                Show this help message

For example, to generate types for a different schema variant:

npm run generate -- --variant 3.webhooks

The data variant (Shogun)

The data variant covers Heroku's data services control plane (Shogun). Unlike 3.sdk, Shogun does not publish a hyperschema, so the resource grouping in src/data/routes.ts is curated by hand. The body of dist/data/types.d.ts — every *Opts and *Result interface, plus the HerokuClient method signatures — is generated from request/response payloads captured during Shogun's spec suite. The runtime route registry at dist/data/routes.{js,d.ts} is compiled from src/data/routes.ts by the same pipeline. Given the Shogun spec artifact, dist/ is fully reproducible from source.

Pipeline

1. Capture payloads in Shogun. From a Shogun checkout, with the spec DB running:

   bundle exec rspec spec/shogun/endpoints
   bundle exec rake api_schemas:build

   This writes tmp/api_schemas.json (schemas keyed by "VERB /path").

2. Generate types in this repo. Point the generator at the artifact:

   SHOGUN_SCHEMA_PATH=/path/to/shogun/tmp/api_schemas.json npm run generate:data

   This reads src/data/routes.ts for the curated resource grouping, emits dist/data/types.d.ts, and emits dist/data/routes.{js,d.ts} from the same source. Methods with no schema coverage are typed as Promise<unknown> and annotated with a // TODO: no spec coverage comment.

What the generator preserves

The grouping in src/data/routes.ts is the source of truth. The generator never invents new resources or moves methods between resources — it only fills in Opts/Result types from the schema artifact. To add or rename a resource, edit src/data/routes.ts and re-run the generator. Do not edit dist/data/routes.{js,d.ts} directly — those files are regenerated on every npm run generate:data invocation.

Running Tests

npm test

This runs the test suite via Vitest.

To run tests in watch mode during development:

npm run test:watch

Contributing

See CONTRIBUTING.md. Security issues should be reported per SECURITY.

License

MIT — see LICENSE.