Heroku SDK

A TypeScript SDK for the Heroku Platform API and Heroku Data API. It generates fully-typed clients at runtime from route definitions — no hand-written method per endpoint.

Installation

npm install @heroku/sdk

Usage

The simplest entry point is the HerokuSDK class. It exposes both the Platform and Data clients on a single object, plus an extension mechanism for hand-written helpers.

import { HerokuSDK } from '@heroku/sdk'
import { appExtensions } from '@heroku/sdk/extensions/platform'

// Reads token from HEROKU_API_KEY or ~/.netrc
const sdk = new HerokuSDK({ extensions: [appExtensions] })

// Upstream route (auto-generated from the API spec)
const apps = await sdk.platform.app.list()
const app  = await sdk.platform.app.info('my-app')

// Hand-written extension method (provided by appExtensions)
await sdk.platform.app.enableMaintenance('my-app')

You can also pass options directly:

const sdk = new HerokuSDK({ clientOptions: { token: 'your-api-token' } })

Per-service clients

If you only need one service (and want the smallest possible bundle), import the factory directly. These return the same typed client the SDK class wraps internally.

import { createPlatformClient } from '@heroku/sdk/platform'
import { createDataClient }     from '@heroku/sdk/data'

const platform = createPlatformClient()
const data     = createDataClient()

const apps = await platform.app.list()

Imports

| Symbol | Import from | | ---------------------------------------- | --------------------------------- | | HerokuSDK, extendResource, types | @heroku/sdk | | createPlatformClient, PlatformClient | @heroku/sdk/platform | | createDataClient, DataClient | @heroku/sdk/data | | appExtensions, dynoExtensions, … | @heroku/sdk/extensions/platform | | databaseExtensions, … | @heroku/sdk/extensions/data |

Development

Prerequisites

• Node.js 22 (see .tool-versions)

Install dependencies

npm install

Build

npm run build

Run tests

npm test

Run a single test file:

npm test -- src/core/dispatcher.test.ts

Run examples

npm run example -- examples/basic-usage.ts