@heroku/sdk 0.5.4 → 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/add-on/index.d.ts

@@ -7,14 +7,15 @@ export { describeAddon } from './describe.js';
 export { destroyAndWait } from './destroy-and-wait.js';
 export { AddonAmbiguousError, AddonConfirmationRequiredError, AddonNotFoundError, AddonProvisioningFailedError, } from './errors.js';
 export { listPlans, listPlansForAddon, type ListPlansForAddonOptions } from './list-plans.js';
-export { formatPlanPriceLabel, type FormatPlanPriceLabelOptions, type PlanPriceBreakdown, priceForPlan, } from './pricing.js';
-export { resolveAddon, resolveAddonByAttachment } from './resolve.js';
-export type { AddOnOptions, CreateAndWaitOptions, DescribedAddOn, DestroyAndWaitOptions, ResolveAddonOptions, ResolvedAddOn, UpgradeAddOnOptions, WaitForProvisioningOptions, } from './types.js';
+export { formatPlanPriceLabel, type FormatPlanPriceLabelOptions, type PlanPriceBreakdown, type PlanPriceKind, priceForPlan, } from './pricing.js';
+export { describeAttachment, resolveAddon, resolveAddonByAttachment } from './resolve.js';
+export type { AddOnOptions, CreateAndWaitOptions, DescribedAddOn, DestroyAndWaitOptions, ResolveAddonOptions, ResolvedAddOn, ResolvedAddOnAttachment, UpgradeAddOnOptions, WaitForProvisioningOptions, } from './types.js';
 export { upgrade } from './upgrade.js';
 export { waitForProvisioning } from './wait-for-provisioning.js';
 export declare const addOnExtensions: import("../../../core/extend-resource.js").ResourceExtension<"platform", "addOn", {
     createAndWait: (appIdentity: string, body: AddOnCreateOpts, options?: CreateAndWaitOptions) => Promise<AddOn>;
     describe: (addonIdentity: string, options?: ResolveAddonOptions) => Promise<import("./types.js").DescribedAddOn>;
+    describeAttachment: (appIdentity: string, attachmentName: string, options?: AddOnOptions) => Promise<import("./types.js").ResolvedAddOnAttachment>;
     destroyAndWait: (appIdentity: string, addonIdentity: string, options?: DestroyAndWaitOptions) => Promise<AddOn>;
     formatPlanPriceLabel: typeof formatPlanPriceLabel;
     listPlans: (serviceIdentity: string, options?: AddOnOptions) => Promise<import("@heroku/types/3.sdk").Plan[]>;

package/dist/resources/platform/add-on/index.js

@@ -4,7 +4,7 @@ import { describeAddon } from './describe.js';
 import { destroyAndWait } from './destroy-and-wait.js';
 import { listPlans, listPlansForAddon } from './list-plans.js';
 import { formatPlanPriceLabel, priceForPlan } from './pricing.js';
-import { resolveAddon, resolveAddonByAttachment } from './resolve.js';
+import { describeAttachment, resolveAddon, resolveAddonByAttachment } from './resolve.js';
 import { upgrade } from './upgrade.js';
 import { waitForProvisioning } from './wait-for-provisioning.js';
 export { createAndWait } from './create-and-wait.js';
@@ -13,12 +13,13 @@ export { destroyAndWait } from './destroy-and-wait.js';
 export { AddonAmbiguousError, AddonConfirmationRequiredError, AddonNotFoundError, AddonProvisioningFailedError, } from './errors.js';
 export { listPlans, listPlansForAddon } from './list-plans.js';
 export { formatPlanPriceLabel, priceForPlan, } from './pricing.js';
-export { resolveAddon, resolveAddonByAttachment } from './resolve.js';
+export { describeAttachment, resolveAddon, resolveAddonByAttachment } from './resolve.js';
 export { upgrade } from './upgrade.js';
 export { waitForProvisioning } from './wait-for-provisioning.js';
 export const addOnExtensions = extendResource('platform', 'addOn', ctx => ({
     createAndWait: (appIdentity, body, options) => createAndWait(ctx, appIdentity, body, options),
     describe: (addonIdentity, options) => describeAddon(ctx, addonIdentity, options),
+    describeAttachment: (appIdentity, attachmentName, options) => describeAttachment(ctx, appIdentity, attachmentName, options),
     destroyAndWait: (appIdentity, addonIdentity, options) => destroyAndWait(ctx, appIdentity, addonIdentity, options),
     formatPlanPriceLabel,
     listPlans: (serviceIdentity, options) => listPlans(ctx, serviceIdentity, options),

package/dist/resources/platform/add-on/pricing.d.ts

@@ -1,9 +1,36 @@
 import type { Plan } from '@heroku/types/3.sdk';
+/**
+ * How a plan is priced, classified once so every consumer agrees. The
+ * classification — not the raw `cents`/`contract`/`metered` fields — is what
+ * a caller should branch on to decide how to present a plan:
+ *
+ * - `'contract'` — negotiated outside monthly add-on billing. `cents` is not a
+ *   meaningful price and may be absent.
+ * - `'metered'`  — billed per use. A flat `cents` (often `0`) does NOT reflect
+ *   real cost; per-use rates live on the plan's meters (fetched separately).
+ * - `'free'`     — a flat plan that genuinely costs nothing (`cents === 0`).
+ * - `'flat'`     — a fixed recurring price of `cents` per `unit`.
+ *
+ * The precedence (contract, then metered, then free, then flat) matches the
+ * Heroku CLI's long-standing production behavior: a contract- or metered-billed
+ * plan is reported as such even when its flat `cents` reads `0`, so a `cents: 0`
+ * metered/contract plan is never mistaken for free.
+ */
+export type PlanPriceKind = 'contract' | 'flat' | 'free' | 'metered';
 export type PlanPriceBreakdown = {
-    /** raw price as reported by the API, in cents */
-    cents: number;
+    /**
+     * Raw price as reported by the API, in cents. `undefined` for a contract
+     * plan that reports no `cents` (the price is negotiated elsewhere).
+     */
+    cents: number | undefined;
     /** True when the price is negotiated outside monthly add-on billing */
     contract: boolean;
+    /**
+     * The price classification. Branch on this rather than re-deriving it from
+     * `cents`/`contract`/`metered` at each call site — that re-derivation is the
+     * source of the "0 cents ⇒ free" bug this field exists to prevent.
+     */
+    kind: PlanPriceKind;
     /** True when the price is billed per use rather than at a fixed cadence */
     metered: boolean;
     /**
@@ -31,15 +58,17 @@ export type PlanPriceBreakdown = {
  * keeps the 30-day-month assumption (Heroku's documented convention)
  * in one place.
  *
- * Returns `undefined` if the plan has no usable `price.cents` value.
- * `Plan.price` is typed as optional in `@heroku/types`, and consumers
- * occasionally receive partial responses depending on the Accept
- * variant.
+ * Returns `undefined` only when the plan carries no pricing signal at
+ * all — no `price`, and no `cents`/`contract`/`metered` to classify
+ * from. A contract- or metered-billed plan still classifies (its flag
+ * is the signal) even when `cents` is absent. `Plan.price` is typed as
+ * optional in `@heroku/types`, and consumers occasionally receive
+ * partial responses depending on the Accept variant.
  *
- * `perMonthCents` and `perHourCents` are themselves `undefined` when
- * the API reports a unit other than `'month'` or `'hour'` — callers
- * should omit those parts of their label rather than show fabricated
- * numbers.
+ * `perMonthCents` and `perHourCents` are populated only for a flat or
+ * free plan on a `'month'`/`'hour'` cadence; they are `undefined` for
+ * metered/contract plans and for unknown units, so callers omit those
+ * parts of their label rather than show fabricated numbers.
  *
  * @param plan The plan to break down. Pass the whole `Plan` rather
  *   than just `plan.price` so the helper can pick up future fields

package/dist/resources/platform/add-on/pricing.js

@@ -13,15 +13,17 @@ const HOURS_PER_MONTH = 24 * 30;
  * keeps the 30-day-month assumption (Heroku's documented convention)
  * in one place.
  *
- * Returns `undefined` if the plan has no usable `price.cents` value.
- * `Plan.price` is typed as optional in `@heroku/types`, and consumers
- * occasionally receive partial responses depending on the Accept
- * variant.
+ * Returns `undefined` only when the plan carries no pricing signal at
+ * all — no `price`, and no `cents`/`contract`/`metered` to classify
+ * from. A contract- or metered-billed plan still classifies (its flag
+ * is the signal) even when `cents` is absent. `Plan.price` is typed as
+ * optional in `@heroku/types`, and consumers occasionally receive
+ * partial responses depending on the Accept variant.
  *
- * `perMonthCents` and `perHourCents` are themselves `undefined` when
- * the API reports a unit other than `'month'` or `'hour'` — callers
- * should omit those parts of their label rather than show fabricated
- * numbers.
+ * `perMonthCents` and `perHourCents` are populated only for a flat or
+ * free plan on a `'month'`/`'hour'` cadence; they are `undefined` for
+ * metered/contract plans and for unknown units, so callers omit those
+ * parts of their label rather than show fabricated numbers.
  *
  * @param plan The plan to break down. Pass the whole `Plan` rather
  *   than just `plan.price` so the helper can pick up future fields
@@ -29,35 +31,60 @@ const HOURS_PER_MONTH = 24 * 30;
  */
 export function priceForPlan(plan) {
     const { price } = plan;
-    if (!price || typeof price.cents !== 'number')
+    if (!price)
         return undefined;
-    const { cents } = price;
+    const contract = Boolean(price.contract);
+    const metered = Boolean(price.metered);
+    const hasCents = typeof price.cents === 'number';
+    // A plan with no `cents` and no contract/metered flag carries no usable
+    // pricing signal at all — treat it as unknown (undefined) rather than
+    // guessing. Contract/metered plans, by contrast, are fully classifiable
+    // without a `cents` value: the flag IS the price signal.
+    if (!hasCents && !contract && !metered)
+        return undefined;
+    const cents = hasCents ? price.cents : undefined;
     const unit = price.unit ?? '';
+    // Precedence matches the CLI's production formatter: contract and metered
+    // win over the raw cents, so a `cents: 0` contract/metered plan is never
+    // classified as free. `free` is a flat plan that genuinely costs nothing.
+    let kind;
+    if (contract)
+        kind = 'contract';
+    else if (metered)
+        kind = 'metered';
+    else if (cents === 0)
+        kind = 'free';
+    else
+        kind = 'flat';
+    // Per-month / per-hour equivalents are only meaningful for a flat recurring
+    // price on a known cadence. Metered/contract plans (and unknown units) leave
+    // them undefined so callers omit those labels instead of rendering
+    // fabricated numbers.
     let perMonthCents;
     let perHourCents;
-    switch (unit) {
-        case 'hour': {
-            perHourCents = cents;
-            perMonthCents = cents * HOURS_PER_MONTH;
-            break;
-        }
-        case 'month': {
-            perMonthCents = cents;
-            perHourCents = cents / HOURS_PER_MONTH;
-            break;
-        }
-        default: {
-            // Unknown billing unit — leave per-month / per-hour undefined
-            // so callers can omit those labels instead of rendering
-            // fabricated numbers.
-            perMonthCents = undefined;
-            perHourCents = undefined;
+    if ((kind === 'flat' || kind === 'free') && cents !== undefined) {
+        switch (unit) {
+            case 'hour': {
+                perHourCents = cents;
+                perMonthCents = cents * HOURS_PER_MONTH;
+                break;
+            }
+            case 'month': {
+                perMonthCents = cents;
+                perHourCents = cents / HOURS_PER_MONTH;
+                break;
+            }
+            default: {
+                perMonthCents = undefined;
+                perHourCents = undefined;
+            }
         }
     }
     return {
         cents,
-        contract: Boolean(price.contract),
-        metered: Boolean(price.metered),
+        contract,
+        kind,
+        metered,
         perHourCents,
         perMonthCents,
         unit,

package/dist/resources/platform/add-on/resolve.d.ts

@@ -1,6 +1,6 @@
 import type { ResourceCtx } from '../../../core/extend-resource.js';
 import type { PlatformClient } from '../../../services/platform.js';
-import type { AddOnOptions, ResolveAddonOptions, ResolvedAddOn } from './types.js';
+import type { AddOnOptions, ResolveAddonOptions, ResolvedAddOn, ResolvedAddOnAttachment } from './types.js';
 /**
  * Resolve a Platform add-on by identity.
  *
@@ -27,14 +27,30 @@ import type { AddOnOptions, ResolveAddonOptions, ResolvedAddOn } from './types.j
  */
 export declare function resolveAddon(ctx: Pick<ResourceCtx, 'platform'>, addonIdentity: string, options?: ResolveAddonOptions): Promise<ResolvedAddOn>;
 /**
- * Resolve a Platform add-on via one of its attachments on a given app.
+ * Describe an add-on *attachment* via its name on a given app.
  *
  * Use this when you have an attachment name (e.g. `DATABASE_URL`,
- * `HEROKU_POSTGRESQL_GREEN`) on a known app, rather than an add-on
- * identity. Calls `addOnAttachment.resolution` and returns the add-on
- * the matched attachment points to.
+ * `HEROKU_POSTGRESQL_GREEN`) on a known app and need the attachment
+ * itself — including its context-scoped `web_url` (the dashboard URL for
+ * opening the add-on *from this app*, which differs from the add-on's own
+ * billing-app `web_url`). Calls `addOnAttachment.resolution` and returns
+ * the matched attachment with its resolved add-on.
  *
- * For resolving by add-on identity, use `resolveAddon`.
+ * `web_url` is `string | null` by design: it is `null` for add-ons that
+ * expose no web dashboard. A `null` here is a valid result, not a
+ * not-found — callers who need a URL must handle it (e.g. fall back to
+ * the add-on's own `web_url` via `resolveAddon`).
+ *
+ * To resolve just the add-on the attachment points to, use
+ * `resolveAddonByAttachment`. For resolving by add-on identity, use
+ * `resolveAddon`.
+ */
+export declare function describeAttachment(ctx: Pick<ResourceCtx, 'platform'>, appIdentity: string, attachmentName: string, options?: AddOnOptions): Promise<ResolvedAddOnAttachment>;
+/**
+ * Resolve the add-on that an attachment points to, by attachment name on a
+ * given app. A thin wrapper over `describeAttachment` that returns only the
+ * resolved add-on (not the attachment). Use `describeAttachment` when you
+ * need the attachment's context-scoped `web_url`.
  */
 export declare function resolveAddonByAttachment(ctx: Pick<ResourceCtx, 'platform'>, appIdentity: string, attachmentName: string, options?: AddOnOptions): Promise<ResolvedAddOn>;
 export declare function resolveAddonInternal(platform: PlatformClient, addonIdentity: string, options?: {

package/dist/resources/platform/add-on/resolve.js

@@ -30,31 +30,51 @@ export async function resolveAddon(ctx, addonIdentity, options = {}) {
     return resolveAddonInternal(ctx.platform, addonIdentity, options);
 }
 /**
- * Resolve a Platform add-on via one of its attachments on a given app.
+ * Describe an add-on *attachment* via its name on a given app.
  *
  * Use this when you have an attachment name (e.g. `DATABASE_URL`,
- * `HEROKU_POSTGRESQL_GREEN`) on a known app, rather than an add-on
- * identity. Calls `addOnAttachment.resolution` and returns the add-on
- * the matched attachment points to.
+ * `HEROKU_POSTGRESQL_GREEN`) on a known app and need the attachment
+ * itself — including its context-scoped `web_url` (the dashboard URL for
+ * opening the add-on *from this app*, which differs from the add-on's own
+ * billing-app `web_url`). Calls `addOnAttachment.resolution` and returns
+ * the matched attachment with its resolved add-on.
  *
- * For resolving by add-on identity, use `resolveAddon`.
+ * `web_url` is `string | null` by design: it is `null` for add-ons that
+ * expose no web dashboard. A `null` here is a valid result, not a
+ * not-found — callers who need a URL must handle it (e.g. fall back to
+ * the add-on's own `web_url` via `resolveAddon`).
+ *
+ * To resolve just the add-on the attachment points to, use
+ * `resolveAddonByAttachment`. For resolving by add-on identity, use
+ * `resolveAddon`.
  */
-export async function resolveAddonByAttachment(ctx, appIdentity, attachmentName, options = {}) {
+export async function describeAttachment(ctx, appIdentity, attachmentName, options = {}) {
     options.signal?.throwIfAborted();
-    debug('resolveByAttachment app=%s attachment=%s', appIdentity, attachmentName);
-    const matches = await ctx.platform.addOnAttachment.resolution({
+    debug('describeAttachment app=%s attachment=%s', appIdentity, attachmentName);
+    // Scope the in-flight resolution call to the caller's signal so an abort
+    // mid-request is honored, not just before it starts.
+    const platform = options.signal ? ctx.platform.withOptions({ signal: options.signal }) : ctx.platform;
+    const matches = await platform.addOnAttachment.resolution({
         // eslint-disable-next-line camelcase
         addon_attachment: attachmentName,
         app: appIdentity,
     });
     const attachment = matches[0];
-    const addon = attachment?.addon;
-    if (!addon?.id || !addon.app?.id) {
-        debug('resolveByAttachment matches=%d (no usable add-on returned)', matches.length);
+    if (!attachment?.addon?.id || !attachment.addon.app?.id) {
+        debug('describeAttachment matches=%d (no usable add-on returned)', matches.length);
         throw new AddonNotFoundError();
     }
-    debug('resolveByAttachment resolved addon=%s app=%s', addon.id, addon.app.id);
-    return addon;
+    debug('describeAttachment resolved addon=%s app=%s', attachment.addon.id, attachment.addon.app.id);
+    return attachment;
+}
+/**
+ * Resolve the add-on that an attachment points to, by attachment name on a
+ * given app. A thin wrapper over `describeAttachment` that returns only the
+ * resolved add-on (not the attachment). Use `describeAttachment` when you
+ * need the attachment's context-scoped `web_url`.
+ */
+export async function resolveAddonByAttachment(ctx, appIdentity, attachmentName, options = {}) {
+    return (await describeAttachment(ctx, appIdentity, attachmentName, options)).addon;
 }
 export async function resolveAddonInternal(platform, addonIdentity, options = {}) {
     const { addonService, appIdentity } = options;

package/dist/resources/platform/add-on/types.d.ts

@@ -18,6 +18,24 @@ export type ResolvedAddOn = AddOn & {
     };
     id: string;
 };
+/**
+ * An attachment whose add-on `id`/`app.id` are guaranteed non-null (as the
+ * resolver enforces at runtime). `web_url` is scoped to the attached app's
+ * context — the dashboard URL for opening this add-on *from this app*, which
+ * differs from the add-on's own (billing-app) `web_url`.
+ *
+ * `web_url` remains `string | null` by design (inherited from
+ * `AddOnAttachment`): it is `null` for add-ons that expose no web dashboard.
+ * The resolver does not guarantee a URL — callers must handle the `null` case.
+ */
+export type ResolvedAddOnAttachment = AddOnAttachment & {
+    addon: NonNullable<AddOnAttachment['addon']> & {
+        app: {
+            id: string;
+        };
+        id: string;
+    };
+};
 export type DescribedAddOn = ResolvedAddOn & {
     attachments: AddOnAttachment[];
 };

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/container/remove-process-types.d.ts

@@ -1,20 +1,18 @@
 import type { Formation } from '@heroku/types/3.sdk';
 import type { ResourceCtx } from '../../../core/extend-resource.js';
+import type { Poller } from '../../../utils/poller.js';
 import type { ContainerOptions } from './index.js';
 export type RemoveProcessTypesOpts = {
     /**
-     * Fires `onStart` immediately before, and `onStop` immediately after,
-     * each process type's `formation.update` call. Process types are
-     * removed one at a time (not concurrently) so a caller can drive a
-     * single shared UI element (e.g. a CLI spinner) across the whole
+     * Fires `poller.onStart` immediately before, and `poller.onStop`
+     * immediately after, each process type's `formation.update` call. Process
+     * types are removed one at a time (not concurrently) so a caller can
+     * drive a single shared UI element (e.g. a CLI spinner) across the whole
      * batch. If an update rejects, its `onStart` has already fired but
      * `onStop` never will — the rejection propagates immediately and any
      * remaining process types are not attempted.
      */
-    onProgress?: {
-        onStart?: (processType: string) => void;
-        onStop?: (processType: string) => void;
-    };
+    poller?: Poller<string>;
 } & ContainerOptions;
 /**
  * Remove one or more process types from a container app

package/dist/resources/platform/container/remove-process-types.js

@@ -9,11 +9,11 @@ export async function removeProcessTypes(ctx, appIdentity, processTypes, options
     const requestBody = { docker_image: null };
     const updatedFormations = [];
     for (const processType of processTypes) {
-        options.onProgress?.onStart?.(processType);
+        options.poller?.onStart?.(processType);
         const formation = await platform
             .withHeaders({ Accept: 'application/vnd.heroku+json; version=3.docker-releases' })
             .formation.update(appIdentity, processType, requestBody);
-        options.onProgress?.onStop?.(processType);
+        options.poller?.onStop?.(processType);
         updatedFormations.push(formation);
     }
     return updatedFormations;

package/dist/resources/platform/domain/create-and-wait.js

@@ -9,7 +9,7 @@ import { waitForReady } from './wait-for-ready.js';
  * 4. If wait: true, poll until domain reaches ready status
  */
 export async function createAndWait(ctx, appIdentity, hostname, options = {}) {
-    const { resolveSniEndpoint, signal, sniEndpoint, timeoutMs, wait: shouldWait, waitIntervalMs, } = options;
+    const { poller, resolveSniEndpoint, signal, sniEndpoint, timeoutMs, wait: shouldWait, waitIntervalMs, } = options;
     signal?.throwIfAborted();
     const platform = signal ? ctx.platform.withOptions({ signal }) : ctx.platform;
     let resolvedSniEndpoint = null;
@@ -33,9 +33,10 @@ export async function createAndWait(ctx, appIdentity, hostname, options = {}) {
         // eslint-disable-next-line camelcase
         sni_endpoint: resolvedSniEndpoint,
     });
-    if (shouldWait && domain.status !== 'succeeded' && domain.status !== 'none') {
+    if (shouldWait && domain.status !== 'none') {
         const [readyDomain] = await waitForReady(ctx, appIdentity, {
             domain,
+            poller,
             signal,
             timeoutMs,
             waitIntervalMs,

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/resources/platform/domain/types.d.ts

@@ -1,4 +1,5 @@
 import type { Domain, SniEndpoint } from '@heroku/types/3.sdk';
+import type { Poller } from '../../../utils/poller.js';
 export type DomainOptions = {
     /**
      * Abort signal to cancel the operation.
@@ -14,6 +15,12 @@ export type WaitForReadyOptions = DomainOptions & {
      * Hostname of the domain to wait for.
      */
     hostname?: string;
+    /**
+     * Progress hooks fired once per domain being waited for:
+     * `poller.onStart(domain)` before polling begins, `poller.onStop(domain)`
+     * after the domain becomes ready.
+     */
+    poller?: Poller<Domain>;
     /**
      * Maximum time in milliseconds to wait before giving up.
      * If undefined, waits indefinitely (until signal aborted).
@@ -25,6 +32,12 @@ export type WaitForReadyOptions = DomainOptions & {
     waitIntervalMs?: number;
 };
 export type CreateAndWaitOptions = DomainOptions & {
+    /**
+     * Progress hooks fired once per domain being waited for:
+     * `poller.onStart(domain)` before polling begins, `poller.onStop(domain)`
+     * after the domain becomes ready.
+     */
+    poller?: Poller<Domain>;
     /**
      * Callback to resolve which SNI endpoint to use
      * when one is not provided.

package/dist/resources/platform/domain/wait-for-ready.js

@@ -9,7 +9,7 @@ const DEFAULT_WAIT_INTERVAL_MS = 5000;
  * @throws if the domain reaches a non-ready status (e.g., 'failed').
  */
 export async function waitForReady(ctx, appIdentity, options = {}) {
-    const { domain, hostname, signal, timeoutMs, waitIntervalMs = DEFAULT_WAIT_INTERVAL_MS } = options;
+    const { domain, hostname, poller, signal, timeoutMs, waitIntervalMs = DEFAULT_WAIT_INTERVAL_MS, } = options;
     signal?.throwIfAborted();
     const platform = signal ? ctx.platform.withOptions({ signal }) : ctx.platform;
     let domains;
@@ -24,10 +24,14 @@ export async function waitForReady(ctx, appIdentity, options = {}) {
         const apiDomains = await platform.domain.list(appIdentity);
         domains = apiDomains.filter(domain => domain.status === 'pending');
     }
-    for (let i = 0; i < domains.length; i++) {
-        domains[i] = await waitForDomain(platform, appIdentity, domains[i], waitIntervalMs, timeoutMs, signal);
+    const readyDomains = [];
+    for (const domain of domains) {
+        poller?.onStart?.(domain);
+        const readyDomain = await waitForDomain(platform, appIdentity, domain, waitIntervalMs, timeoutMs, signal);
+        poller?.onStop?.(domain);
+        readyDomains.push(readyDomain);
     }
-    return domains;
+    return readyDomains;
 }
 async function waitForDomain(platform, appIdentity, domain, waitIntervalMs, timeoutMs, signal) {
     const deadline = timeoutMs === undefined ? undefined : Date.now() + timeoutMs;
@@ -35,7 +39,7 @@ async function waitForDomain(platform, appIdentity, domain, waitIntervalMs, time
         await wait(waitIntervalMs, signal);
         const updatedDomain = await platform.domain.info(appIdentity, domain.id);
         domain = updatedDomain;
-        if (deadline !== undefined && Date.now() >= deadline) {
+        if (domain.status === 'pending' && deadline !== undefined && Date.now() >= deadline) {
             throw new Error(`Timed out waiting for domain ${domain.hostname}`);
         }
     }

package/dist/resources/platform/sni-endpoint/create-and-associate.d.ts

@@ -1,6 +1,13 @@
 import type { SniEndpoint } from '@heroku/types/3.sdk';
 import type { ResourceCtx } from '../../../core/extend-resource.js';
+import type { Poller } from '../../../utils/poller.js';
 export type CreateAndAssociateOptions = {
+    /**
+     * Progress hooks for the domain readiness wait:
+     * `domainPoller.onStart()` before polling begins, `domainPoller.onStop()`
+     * once the app's domains reach ready status.
+     */
+    domainPoller?: Poller;
     intervalMs?: number;
     /** Required. Given the wildcard-matched candidate hostnames, returns the subset to associate. */
     resolveDomains: (candidates: string[]) => Promise<string[]>;

package/dist/resources/platform/sni-endpoint/create-and-associate.js

@@ -33,14 +33,16 @@ const DEFAULT_TIMEOUT_MS = 30_000;
 // createAndAssociate(app, certChain, privateKey, {resolveDomains}).
 // eslint-disable-next-line max-params
 export async function createAndAssociate(ctx, appIdentity, certificateChain, privateKey, options) {
-    const { intervalMs = DEFAULT_WAIT_INTERVAL_MS, resolveDomains, signal, timeoutMs = DEFAULT_TIMEOUT_MS, } = options;
+    const { domainPoller, intervalMs = DEFAULT_WAIT_INTERVAL_MS, resolveDomains, signal, timeoutMs = DEFAULT_TIMEOUT_MS, } = options;
     signal?.throwIfAborted();
     const platform = signal ? ctx.platform.withOptions({ signal }) : ctx.platform;
     const sniEndpoint = await platform.sniEndpoint.create(appIdentity, {
         certificate_chain: certificateChain,
         private_key: privateKey,
     });
+    domainPoller?.onStart?.();
     await waitForReady(ctx, appIdentity, { signal, timeoutMs, waitIntervalMs: intervalMs });
+    domainPoller?.onStop?.();
     const apiDomains = await platform.domain.list(appIdentity);
     const appDomains = apiDomains.map(d => d.hostname);
     const certDomains = (sniEndpoint.ssl_cert.cert_domains ?? []);

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/dist/utils/poller.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Progress hooks for a polling loop, so a caller can drive UI (e.g. a CLI
+ * spinner) around each unit of work without reaching into the loop itself.
+ *
+ * `onStart` fires immediately before polling a unit begins; `onStop` fires
+ * once it settles into a terminal state. If polling that unit throws,
+ * `onStart` has already fired but `onStop` never will.
+ */
+export type Poller<T = void> = {
+    onStart?: (arg: T) => void;
+    onStop?: (arg: T) => void;
+};

package/dist/utils/poller.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heroku/sdk",
-  "version": "0.5.4",
+  "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"
   }
 }