@heroku/sdk 0.5.5 → 0.5.7

package/README.md

@@ -1,6 +1,6 @@
 # Heroku SDK
 
-A TypeScript SDK for the [Heroku Platform API](https://devcenter.heroku.com/articles/platform-api-reference) and [Heroku Data API](https://devcenter.heroku.com/articles/heroku-postgres-api-reference). It generates fully-typed clients at runtime from route definitions — no hand-written method per endpoint.
+A TypeScript SDK for the [Heroku Platform API](https://devcenter.heroku.com/articles/platform-api-reference), [Heroku Data API](https://devcenter.heroku.com/articles/heroku-postgres-api-reference), and the Heroku Metrics API. It generates fully-typed clients at runtime from route definitions — no hand-written method per endpoint.
 
 ## Installation
 
@@ -40,9 +40,11 @@ If you only need one service (and want the smallest possible bundle), import the
 ```ts
 import { createPlatformClient } from '@heroku/sdk/platform'
 import { createDataClient }     from '@heroku/sdk/data'
+import { createMetricsClient }  from '@heroku/sdk/metrics'
 
 const platform = createPlatformClient()
 const data     = createDataClient()
+const metrics  = createMetricsClient()
 
 const apps = await platform.app.list()
 ```
@@ -54,6 +56,7 @@ const apps = await platform.app.list()
 | `HerokuSDK`, `extendResource`, types     | `@heroku/sdk`                     |
 | `createPlatformClient`, `PlatformClient` | `@heroku/sdk/platform`            |
 | `createDataClient`, `DataClient`         | `@heroku/sdk/data`                |
+| `createMetricsClient`, `MetricsClient`   | `@heroku/sdk/metrics`             |
 | `appExtensions`, `dynoExtensions`, …     | `@heroku/sdk/extensions/platform` |
 | `databaseExtensions`, …                  | `@heroku/sdk/extensions/data`     |
 

package/dist/core/dispatcher.js

@@ -16,8 +16,22 @@ export async function dispatch(client, route, args, invocation, requestOptions)
     if (route.hasRequestBody && remaining.length > 0) {
         body = remaining[0];
     }
+    let effectiveOptions = requestOptions;
+    if (route.query && route.query.length > 0 && remaining.length > 0) {
+        const raw = remaining[0];
+        if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+            const searchParams = {};
+            for (const key of route.query) {
+                const value = raw[key];
+                if (value !== undefined && value !== null) {
+                    searchParams[key] = value;
+                }
+            }
+            effectiveOptions = { ...requestOptions, searchParams };
+        }
+    }
     debug('%s %s %s -> %s hasBody=%s', invocation ?? 'dispatch', route.method, route.path, path, body !== undefined);
-    const response = await callMethod(client, route.method, path, body, requestOptions);
+    const response = await callMethod(client, route.method, path, body, effectiveOptions);
     const contentLength = response.headers.get('content-length');
     if (response.status === 204 || contentLength === '0') {
         debug('%s empty response status=%d content-length=%s', invocation ?? 'dispatch', response.status, contentLength ?? '');
@@ -30,7 +44,7 @@ export async function dispatch(client, route, args, invocation, requestOptions)
     const nextRange = response.headers.get('next-range');
     if (!nextRange)
         return result;
-    return followPages(client, path, result, nextRange, invocation, requestOptions);
+    return followPages(client, path, result, nextRange, invocation, effectiveOptions);
 }
 /* eslint-disable no-await-in-loop -- pagination is inherently sequential; each page depends on the previous next-range header */
 async function followPages(client, path, firstPage, initialRange, invocation, requestOptions) {

package/dist/core/extend-resource.d.ts

@@ -1,8 +1,10 @@
 import type { DataClient } from '../services/data.js';
+import type { MetricsClient } from '../services/metrics.js';
 import type { PlatformClient } from '../services/platform.js';
-export type ServiceName = 'data' | 'platform';
+export type ServiceName = 'data' | 'metrics' | 'platform';
 export type ResourceCtx = {
     data: DataClient;
+    metrics: MetricsClient;
     platform: PlatformClient;
 };
 export type ResourceMethods = Record<string, (...args: any[]) => any>;

package/dist/core/heroku-sdk.d.ts

@@ -1,5 +1,6 @@
 import type { HerokuApiClientOptions } from '@heroku/heroku-fetch';
 import type { DataClient } from '../services/data.js';
+import type { MetricsClient } from '../services/metrics.js';
 import type { PlatformClient } from '../services/platform.js';
 import type { ApplyExtensions, ExtensionsFor, ResourceExtension } from './extend-resource.js';
 export type HerokuSDKOptions<Exts extends readonly ResourceExtension[]> = {
@@ -10,5 +11,6 @@ export declare class HerokuSDK<const Exts extends readonly ResourceExtension[] =
     #private;
     constructor(options?: HerokuSDKOptions<Exts>);
     get data(): ApplyExtensions<DataClient, ExtensionsFor<Exts, 'data'>>;
+    get metrics(): ApplyExtensions<MetricsClient, ExtensionsFor<Exts, 'metrics'>>;
     get platform(): ApplyExtensions<PlatformClient, ExtensionsFor<Exts, 'platform'>>;
 }

package/dist/core/heroku-sdk.js

@@ -1,4 +1,5 @@
 import { createDataClient } from '../services/data.js';
+import { createMetricsClient } from '../services/metrics.js';
 import { createPlatformClient } from '../services/platform.js';
 import { mergeExtensions } from './extensions-proxy.js';
 function partitionByService(extensions) {
@@ -15,8 +16,10 @@ export class HerokuSDK {
     #ctx;
     #data;
     #extensionsByService;
+    #metrics;
     #platform;
     #rawData;
+    #rawMetrics;
     #rawPlatform;
     constructor(options = {}) {
         this.#clientOptions = options.clientOptions ?? {};
@@ -26,6 +29,10 @@ export class HerokuSDK {
         this.#data ??= mergeExtensions(this.#getRawData(), this.#extensionsByService.get('data') ?? [], this.#getCtx());
         return this.#data;
     }
+    get metrics() {
+        this.#metrics ??= mergeExtensions(this.#getRawMetrics(), this.#extensionsByService.get('metrics') ?? [], this.#getCtx());
+        return this.#metrics;
+    }
     get platform() {
         this.#platform ??= mergeExtensions(this.#getRawPlatform(), this.#extensionsByService.get('platform') ?? [], this.#getCtx());
         return this.#platform;
@@ -36,6 +43,10 @@ export class HerokuSDK {
                 enumerable: true,
                 get: () => this.#getRawData(),
             },
+            metrics: {
+                enumerable: true,
+                get: () => this.#getRawMetrics(),
+            },
             platform: {
                 enumerable: true,
                 get: () => this.#getRawPlatform(),
@@ -47,6 +58,10 @@ export class HerokuSDK {
         this.#rawData ??= createDataClient(this.#clientOptions);
         return this.#rawData;
     }
+    #getRawMetrics() {
+        this.#rawMetrics ??= createMetricsClient(this.#clientOptions);
+        return this.#rawMetrics;
+    }
     #getRawPlatform() {
         this.#rawPlatform ??= createPlatformClient(this.#clientOptions);
         return this.#rawPlatform;

package/dist/resources/platform/app/create-and-setup.d.ts

@@ -0,0 +1,50 @@
+import type { App, ConfigVarUpdateOpts } from '@heroku/types/3.sdk';
+import type { ResourceCtx } from '../../../core/extend-resource.js';
+export type SetupStep = {
+    kind: 'addon' | 'buildpack' | 'config-vars' | 'setup';
+    label?: string;
+};
+export type CreateAndSetupOptions = {
+    poller?: {
+        onStart?: (step: SetupStep) => void;
+        onStop?: (step?: SetupStep) => void;
+    };
+    signal?: AbortSignal;
+};
+export type CreateAndSetupInput = {
+    addons?: Array<{
+        as?: string;
+        plan: string;
+    }>;
+    buildpack?: string;
+    configVars?: ConfigVarUpdateOpts;
+    name?: string;
+    region?: string;
+    space?: string;
+    stack?: string;
+    team?: string;
+};
+/**
+ * Create an app and run its post-create setup in one call.
+ *
+ * Creates the app (team/space → `teamApp.create`, otherwise `app.create`),
+ * then fans out the optional setup steps in parallel: add-ons
+ * (`addOn.create` per plan), config vars (`configVar.update`), and buildpack
+ * (`buildpackInstallation.update`). Returns the created `App`.
+ *
+ * Progress is reported via the `poller` convention. Because the steps run in
+ * parallel and a caller's progress indicator is typically a single global
+ * spinner, this method fires a single `onStart`/`onStop` pair around the whole
+ * setup batch rather than one per step, so parallel steps don't clobber the
+ * spinner. Per the poller contract, `onStart` fires BEFORE any request is
+ * dispatched, and `onStop` fires ONLY on success — if a step rejects, the
+ * error propagates and `onStop` is never called (there is no try/finally, so
+ * the caller's error path stops the spinner). Signal threading uses the
+ * standard `withOptions({signal})`
+ * scoped-client idiom so an abort cancels in-flight requests, not just the
+ * pre-flight `throwIfAborted()`.
+ *
+ * The CLI parses flags / heroku.yml into `input` and owns git-remote setup
+ * and rendering; this method owns the API orchestration only.
+ */
+export declare function createAndSetup(ctx: Pick<ResourceCtx, 'platform'>, input: CreateAndSetupInput, options?: CreateAndSetupOptions): Promise<App>;

package/dist/resources/platform/app/create-and-setup.js

@@ -0,0 +1,60 @@
+/**
+ * Create an app and run its post-create setup in one call.
+ *
+ * Creates the app (team/space → `teamApp.create`, otherwise `app.create`),
+ * then fans out the optional setup steps in parallel: add-ons
+ * (`addOn.create` per plan), config vars (`configVar.update`), and buildpack
+ * (`buildpackInstallation.update`). Returns the created `App`.
+ *
+ * Progress is reported via the `poller` convention. Because the steps run in
+ * parallel and a caller's progress indicator is typically a single global
+ * spinner, this method fires a single `onStart`/`onStop` pair around the whole
+ * setup batch rather than one per step, so parallel steps don't clobber the
+ * spinner. Per the poller contract, `onStart` fires BEFORE any request is
+ * dispatched, and `onStop` fires ONLY on success — if a step rejects, the
+ * error propagates and `onStop` is never called (there is no try/finally, so
+ * the caller's error path stops the spinner). Signal threading uses the
+ * standard `withOptions({signal})`
+ * scoped-client idiom so an abort cancels in-flight requests, not just the
+ * pre-flight `throwIfAborted()`.
+ *
+ * The CLI parses flags / heroku.yml into `input` and owns git-remote setup
+ * and rendering; this method owns the API orchestration only.
+ */
+export async function createAndSetup(ctx, input, options = {}) {
+    options.signal?.throwIfAborted();
+    const platform = options.signal ? ctx.platform.withOptions({ signal: options.signal }) : ctx.platform;
+    const { addons, buildpack, configVars, ...createParams } = input;
+    const app = (createParams.space || createParams.team)
+        ? (await platform.teamApp.create(createParams))
+        : await platform.app.create(createParams);
+    if (!app.name)
+        throw new Error('createAndSetup: created app has no name');
+    const appName = app.name;
+    // Deferred thunks: nothing is dispatched until the batch is launched below,
+    // so `onStart` reliably fires before the first request.
+    const steps = [];
+    if (addons?.length) {
+        for (const addon of addons) {
+            steps.push(() => platform.addOn.create(appName, {
+                attachment: addon.as ? { name: addon.as } : undefined,
+                plan: addon.plan,
+            }));
+        }
+    }
+    if (configVars && Object.keys(configVars).length > 0) {
+        steps.push(() => platform.configVar.update(appName, configVars));
+    }
+    if (buildpack) {
+        steps.push(() => platform.buildpackInstallation.update(appName, { updates: [{ buildpack }] }));
+    }
+    if (steps.length > 0) {
+        // Single combined progress window — one spinner for the whole parallel
+        // setup batch, not one per step. onStart before dispatch; onStop only on
+        // success (no try/finally — a rejection skips onStop per contract).
+        options.poller?.onStart?.({ kind: 'setup', label: 'setup' });
+        await Promise.all(steps.map(step => step()));
+        options.poller?.onStop?.();
+    }
+    return app;
+}

package/dist/resources/platform/app/index.d.ts

@@ -1,8 +1,12 @@
 import type { App } from '@heroku/types/3.sdk';
 import type { ResourceCtx } from '../../../core/extend-resource.js';
+import type { CreateAndSetupInput, CreateAndSetupOptions } from './create-and-setup.js';
 import type { DescribeAppOptions } from './info.js';
+import type { TransferOptions } from './transfer.js';
 import type { WaitForACMCertificatesOptions } from './wait-for-acm-certificates.js';
+export { createAndSetup, type CreateAndSetupInput, type CreateAndSetupOptions, type SetupStep, } from './create-and-setup.js';
 export { type AppInfo, describeApp, type DescribeAppOptions, type PipelineCouplingDetail, } from './info.js';
+export { transferApp, type TransferOptions } from './transfer.js';
 export { waitForACMCertificates, type WaitForACMCertificatesOptions } from './wait-for-acm-certificates.js';
 export type AppMaintenanceOptions = {
     signal?: AbortSignal;
@@ -51,11 +55,13 @@ export declare function getProcessTier(ctx: {
     platform: AppInfoPlatform;
 }, appIdentity: string, options?: GetProcessTierOptions): Promise<ProcessTier | undefined>;
 export declare const appExtensions: import("../../../core/extend-resource.js").ResourceExtension<"platform", "app", {
+    createAndSetup: (input: CreateAndSetupInput, options?: CreateAndSetupOptions) => Promise<App>;
     describe: (appIdentity: string, options?: DescribeAppOptions) => Promise<import("./info.js").AppInfo>;
     disableMaintenance: (appIdentity: string, options?: AppMaintenanceOptions) => Promise<App>;
     enableMaintenance: (appIdentity: string, options?: AppMaintenanceOptions) => Promise<App>;
     getGeneration: (appIdentity: string, options?: GetGenerationOptions) => Promise<GenerationKind | undefined>;
     getProcessTier: (appIdentity: string, options?: GetProcessTierOptions) => Promise<ProcessTier | undefined>;
     isShielded: (appIdentity: string, options?: IsShieldedOptions) => Promise<boolean>;
+    transfer: (appIdentity: string, recipient: string, options?: TransferOptions) => Promise<import("@heroku/types/3.sdk").TeamApp | import("@heroku/types/3.sdk").AppTransfer>;
     waitForACMCertificates: (appIdentity: string, options?: WaitForACMCertificatesOptions) => Promise<import("@heroku/types/3.sdk").Domain[]>;
 }>;

package/dist/resources/platform/app/index.js

@@ -1,7 +1,11 @@
 import { extendResource } from '../../../core/extend-resource.js';
+import { createAndSetup } from './create-and-setup.js';
 import { describeApp } from './info.js';
+import { transferApp } from './transfer.js';
 import { waitForACMCertificates } from './wait-for-acm-certificates.js';
+export { createAndSetup, } from './create-and-setup.js';
 export { describeApp, } from './info.js';
+export { transferApp } from './transfer.js';
 export { waitForACMCertificates } from './wait-for-acm-certificates.js';
 export async function enableMaintenance(ctx, appIdentity, options = {}) {
     options.signal?.throwIfAborted();
@@ -46,11 +50,13 @@ export async function getProcessTier(ctx, appIdentity, options = {}) {
     return app.process_tier;
 }
 export const appExtensions = extendResource('platform', 'app', ctx => ({
+    createAndSetup: (input, options) => createAndSetup(ctx, input, options),
     describe: (appIdentity, options) => describeApp(ctx, appIdentity, options),
     disableMaintenance: (appIdentity, options) => disableMaintenance(ctx, appIdentity, options),
     enableMaintenance: (appIdentity, options) => enableMaintenance(ctx, appIdentity, options),
     getGeneration: (appIdentity, options) => getGeneration(ctx, appIdentity, options),
     getProcessTier: (appIdentity, options) => getProcessTier(ctx, appIdentity, options),
     isShielded: (appIdentity, options) => isShielded(ctx, appIdentity, options),
+    transfer: (appIdentity, recipient, options) => transferApp(ctx, appIdentity, recipient, options),
     waitForACMCertificates: (appIdentity, options) => waitForACMCertificates(ctx, appIdentity, options),
 }));

package/dist/resources/platform/app/transfer.d.ts

@@ -0,0 +1,23 @@
+import type { AppTransfer, TeamApp } from '@heroku/types/3.sdk';
+import type { ResourceCtx } from '../../../core/extend-resource.js';
+export type TransferOptions = {
+    personalToPersonal?: boolean;
+    signal?: AbortSignal;
+    silent?: boolean;
+};
+/**
+ * Transfer an app to another user or team.
+ *
+ * Route selection mirrors the platform's two transfer surfaces:
+ *   - personal-to-personal transfers go through `POST /account/app-transfers`
+ *     (`appTransfer.create`), which emails the recipient for acceptance
+ *     (response `state: 'pending'`).
+ *   - team-involved transfers go through `PATCH /teams/apps/{name}`
+ *     (`teamApp.transferToTeam` / `transferToAccount`), differing only by body.
+ *
+ * The caller (CLI) decides `personalToPersonal` and interprets the returned
+ * `state` for presentation. `personalToPersonal` defaults falsy → the team
+ * route, so a caller who forgets the flag on a genuine personal transfer
+ * silently hits the team path (a caller-owned footgun the SDK can't detect).
+ */
+export declare function transferApp(ctx: Pick<ResourceCtx, 'platform'>, appIdentity: string, recipient: string, options?: TransferOptions): Promise<AppTransfer | TeamApp>;

package/dist/resources/platform/app/transfer.js

@@ -0,0 +1,35 @@
+/**
+ * Transfer an app to another user or team.
+ *
+ * Route selection mirrors the platform's two transfer surfaces:
+ *   - personal-to-personal transfers go through `POST /account/app-transfers`
+ *     (`appTransfer.create`), which emails the recipient for acceptance
+ *     (response `state: 'pending'`).
+ *   - team-involved transfers go through `PATCH /teams/apps/{name}`
+ *     (`teamApp.transferToTeam` / `transferToAccount`), differing only by body.
+ *
+ * The caller (CLI) decides `personalToPersonal` and interprets the returned
+ * `state` for presentation. `personalToPersonal` defaults falsy → the team
+ * route, so a caller who forgets the flag on a genuine personal transfer
+ * silently hits the team path (a caller-owned footgun the SDK can't detect).
+ */
+export async function transferApp(ctx, appIdentity, recipient, options = {}) {
+    options.signal?.throwIfAborted();
+    const platform = options.signal ? ctx.platform.withOptions({ signal: options.signal }) : ctx.platform;
+    if (options.personalToPersonal) {
+        const body = { app: appIdentity, recipient };
+        if (options.silent !== undefined)
+            body.silent = options.silent;
+        return platform.appTransfer.create(body);
+    }
+    // Team-involved (personalToPersonal=false): both routes are PATCH /teams/apps/{name}
+    // with body {owner}, differing only by semantics. Split by recipient shape: an
+    // email recipient transfers ownership to a personal ACCOUNT; anything else is a
+    // TEAM name. Both produce a byte-identical wire request to the legacy
+    // app-transfer.ts (a single PATCH with {owner: recipient}), so this is a
+    // spec-faithful split with no functional regression.
+    const looksLikeEmail = recipient.includes('@');
+    return looksLikeEmail
+        ? platform.teamApp.transferToAccount(appIdentity, { owner: recipient })
+        : platform.teamApp.transferToTeam(appIdentity, { owner: recipient });
+}

package/dist/resources/platform/domain/test-utils.js

@@ -17,6 +17,7 @@ export function buildCtx(stubs = {}) {
     platform.withOptions.mockReturnValue(platform);
     return {
         data: {},
+        metrics: {},
         platform: platform,
     };
 }

package/dist/services/metrics.d.ts

@@ -0,0 +1,5 @@
+import type { HerokuApiClientOptions } from '@heroku/heroku-fetch';
+import type { HerokuClient } from '@heroku/types/metrics';
+import type { RoutesClientExtras } from '../core/create-client.js';
+export type MetricsClient = HerokuClient & RoutesClientExtras<HerokuClient>;
+export declare function createMetricsClient(options?: HerokuApiClientOptions): MetricsClient;

package/dist/services/metrics.js

@@ -0,0 +1,23 @@
+import * as routes from '@heroku/types/metrics/routes';
+import { createClient } from '../core/create-client.js';
+const DEFAULT_METRICS_BASE_URL = 'https://api.metrics.heroku.com';
+export function createMetricsClient(options = {}) {
+    const baseUrl = process.env.HEROKU_METRICS_HOST ?? DEFAULT_METRICS_BASE_URL;
+    // Metrics is a distinct host that heroku-fetch does not model as a first-class
+    // service, so we use `service: 'custom'` with an explicit base URL. Auth (bearer
+    // token) is resolved by heroku-fetch exactly as for platform/data — same
+    // HEROKU_API_KEY / netrc source, shared across services on one SDK instance.
+    //
+    // Unlike platform/data, `service: 'custom'` sends no default Accept header, so we
+    // set `application/vnd.heroku+json; version=3` explicitly to match what meetas
+    // expects — the same versioned vendor type platform/data get automatically via
+    // heroku-fetch's `defaultAccept`. A caller can still override it via `headers`:
+    // `...options` first, then an explicit `headers` key whose `...options.headers`
+    // spread lands AFTER the literal Accept, so caller headers win for any key they set.
+    return createClient(routes, {
+        baseUrl,
+        service: 'custom',
+        ...options,
+        headers: { Accept: 'application/vnd.heroku+json; version=3', ...options.headers },
+    });
+}

package/dist/services/platform.js

@@ -1,5 +1,19 @@
 import * as routes from '@heroku/types/3.sdk/routes';
 import { createClient } from '../core/create-client.js';
+/**
+ * The Platform API variant this client's routes and types are generated from
+ * (`@heroku/types/3.sdk`). Dispatch at the same variant so the wire matches the
+ * shipped types — otherwise `3.sdk`-only routes (e.g. `buildMetadata.info`) 404
+ * under heroku-fetch's shared `version=3` default, and fields the types describe
+ * in their `3.sdk` shape (e.g. `App.generation: string`) arrive in the older
+ * `version=3` shape. A caller can still override per request via `withHeaders`,
+ * or per client by passing their own `defaultAccept`.
+ */
+const PLATFORM_SDK_ACCEPT = 'application/vnd.heroku+json; version=3.sdk';
 export function createPlatformClient(options = {}) {
-    return createClient(routes, { service: 'platform', ...options });
+    return createClient(routes, {
+        defaultAccept: PLATFORM_SDK_ACCEPT,
+        service: 'platform',
+        ...options,
+    });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heroku/sdk",
-  "version": "0.5.5",
+  "version": "0.5.7",
   "description": "Heroku SDK",
   "author": "Heroku",
   "type": "module",
@@ -18,6 +18,10 @@
       "types": "./dist/services/data.d.ts",
       "default": "./dist/services/data.js"
     },
+    "./metrics": {
+      "types": "./dist/services/metrics.d.ts",
+      "default": "./dist/services/metrics.js"
+    },
     "./extensions/platform": {
       "types": "./dist/resources/extensions/platform.d.ts",
       "default": "./dist/resources/extensions/platform.js"
@@ -99,8 +103,8 @@
     "vitest": "^4.1.4"
   },
   "dependencies": {
-    "@heroku/heroku-fetch": "^0.1.3",
-    "@heroku/types": "^4.0.1",
+    "@heroku/heroku-fetch": "^0.1.4",
+    "@heroku/types": "^4.1.0",
     "debug": "^4.4.0"
   }
 }