@heroku/sdk 0.6.2 → 0.6.4

package/dist/resources/data/database.d.ts

@@ -1,11 +1,8 @@
-import type { DatabaseInfoResult } from '@heroku/types/data';
+import type { DatabaseCancelUpgradeResult, DatabaseDryRunUpgradeOpts, DatabaseDryRunUpgradeResult, DatabaseInfoResult, DatabasePrepareUpgradeOpts, DatabasePrepareUpgradeResult, DatabaseRunUpgradeOpts, DatabaseRunUpgradeResult, DatabaseUpgradeWaitStatusResult } from '@heroku/types/data';
 import type { ResourceCtx } from '../../core/extend-resource.js';
 export type DatabaseOptions = {
     signal?: AbortSignal;
 };
-export type DatabaseUpgradeBody = {
-    version?: string;
-};
 export type DatabaseDescribeResult = DatabaseInfoResult & {
     following?: string;
     'hot_standby?'?: boolean;
@@ -14,41 +11,17 @@ export type DatabaseDescribeResult = DatabaseInfoResult & {
     postgres_version?: string;
     'standalone?'?: boolean;
 };
-export type DatabaseUpgradeWaitResult = {
-    'error?': boolean;
-    message: string;
-    step: string;
-    'waiting?': boolean;
-};
-export type DatabaseUpgradeResponse = {
-    message: string;
-};
-type DatabaseDataClient = {
-    database: {
-        cancelUpgrade(name: string): Promise<DatabaseUpgradeResponse>;
-        dryRunUpgrade(name: string, body: DatabaseUpgradeBody): Promise<DatabaseUpgradeResponse>;
-        info(name: string): Promise<DatabaseDescribeResult>;
-        prepareUpgrade(name: string, body: DatabaseUpgradeBody): Promise<DatabaseUpgradeResponse>;
-        runUpgrade(name: string, body: DatabaseUpgradeBody): Promise<DatabaseUpgradeResponse>;
-        upgradeWaitStatus(name: string): Promise<DatabaseUpgradeWaitResult>;
-    };
-};
-type DatabaseCtx = {
-    data: DatabaseDataClient;
-    platform: ResourceCtx['platform'];
-};
-export declare function describe(ctx: DatabaseCtx, appIdentity: string, addonIdentity?: string, options?: DatabaseOptions): Promise<DatabaseDescribeResult>;
-export declare function upgradeWaitStatus(ctx: DatabaseCtx, appIdentity: string, addonIdentity?: string, options?: DatabaseOptions): Promise<DatabaseUpgradeWaitResult>;
-export declare function dryRunUpgrade(ctx: DatabaseCtx, appIdentity: string, addonIdentity?: string, body?: DatabaseUpgradeBody, options?: DatabaseOptions): Promise<DatabaseUpgradeResponse>;
-export declare function runUpgrade(ctx: DatabaseCtx, appIdentity: string, addonIdentity?: string, body?: DatabaseUpgradeBody, options?: DatabaseOptions): Promise<DatabaseUpgradeResponse>;
-export declare function prepareUpgrade(ctx: DatabaseCtx, appIdentity: string, addonIdentity?: string, body?: DatabaseUpgradeBody, options?: DatabaseOptions): Promise<DatabaseUpgradeResponse>;
-export declare function cancelUpgrade(ctx: DatabaseCtx, appIdentity: string, addonIdentity?: string, options?: DatabaseOptions): Promise<DatabaseUpgradeResponse>;
+export declare function describe(ctx: Pick<ResourceCtx, 'data' | 'platform'>, appIdentity: string, addonIdentity?: string, options?: DatabaseOptions): Promise<DatabaseDescribeResult>;
+export declare function upgradeWaitStatus(ctx: Pick<ResourceCtx, 'data' | 'platform'>, appIdentity: string, addonIdentity?: string, options?: DatabaseOptions): Promise<DatabaseUpgradeWaitStatusResult>;
+export declare function dryRunUpgrade(ctx: Pick<ResourceCtx, 'data' | 'platform'>, appIdentity: string, addonIdentity?: string, body?: DatabaseDryRunUpgradeOpts, options?: DatabaseOptions): Promise<DatabaseDryRunUpgradeResult>;
+export declare function runUpgrade(ctx: Pick<ResourceCtx, 'data' | 'platform'>, appIdentity: string, addonIdentity?: string, body?: DatabaseRunUpgradeOpts, options?: DatabaseOptions): Promise<DatabaseRunUpgradeResult>;
+export declare function prepareUpgrade(ctx: Pick<ResourceCtx, 'data' | 'platform'>, appIdentity: string, addonIdentity?: string, body?: DatabasePrepareUpgradeOpts, options?: DatabaseOptions): Promise<DatabasePrepareUpgradeResult>;
+export declare function cancelUpgrade(ctx: Pick<ResourceCtx, 'data' | 'platform'>, appIdentity: string, addonIdentity?: string, options?: DatabaseOptions): Promise<DatabaseCancelUpgradeResult>;
 export declare const databaseExtensions: import("../../core/extend-resource.js").ResourceExtension<"data", "database", {
-    cancelUpgrade: (appIdentity: string, addonIdentity?: string, options?: DatabaseOptions) => Promise<DatabaseUpgradeResponse>;
+    cancelUpgrade: (appIdentity: string, addonIdentity?: string, options?: DatabaseOptions) => Promise<DatabaseCancelUpgradeResult>;
     describe: (appIdentity: string, addonIdentity?: string, options?: DatabaseOptions) => Promise<DatabaseDescribeResult>;
-    dryRunUpgrade: (appIdentity: string, addonIdentity?: string, body?: DatabaseUpgradeBody, options?: DatabaseOptions) => Promise<DatabaseUpgradeResponse>;
-    prepareUpgrade: (appIdentity: string, addonIdentity?: string, body?: DatabaseUpgradeBody, options?: DatabaseOptions) => Promise<DatabaseUpgradeResponse>;
-    runUpgrade: (appIdentity: string, addonIdentity?: string, body?: DatabaseUpgradeBody, options?: DatabaseOptions) => Promise<DatabaseUpgradeResponse>;
-    upgradeWaitStatus: (appIdentity: string, addonIdentity?: string, options?: DatabaseOptions) => Promise<DatabaseUpgradeWaitResult>;
+    dryRunUpgrade: (appIdentity: string, addonIdentity?: string, body?: DatabaseDryRunUpgradeOpts, options?: DatabaseOptions) => Promise<DatabaseDryRunUpgradeResult>;
+    prepareUpgrade: (appIdentity: string, addonIdentity?: string, body?: DatabasePrepareUpgradeOpts, options?: DatabaseOptions) => Promise<DatabasePrepareUpgradeResult>;
+    runUpgrade: (appIdentity: string, addonIdentity?: string, body?: DatabaseRunUpgradeOpts, options?: DatabaseOptions) => Promise<DatabaseRunUpgradeResult>;
+    upgradeWaitStatus: (appIdentity: string, addonIdentity?: string, options?: DatabaseOptions) => Promise<DatabaseUpgradeWaitStatusResult>;
 }>;
-export {};

package/dist/resources/data/database.js

@@ -30,15 +30,11 @@ export async function cancelUpgrade(ctx, appIdentity, addonIdentity, options = {
     const addon = await resolvePgDatabase(ctx, { appIdentity, input: addonIdentity, ...options });
     return ctx.data.database.cancelUpgrade(addon.id);
 }
-export const databaseExtensions = extendResource('data', 'database', rawCtx => {
-    // Bridge heroku-types' loose client types to the adapter's strongly-typed contract
-    const ctx = rawCtx;
-    return {
-        cancelUpgrade: (appIdentity, addonIdentity, options) => cancelUpgrade(ctx, appIdentity, addonIdentity, options),
-        describe: (appIdentity, addonIdentity, options) => describe(ctx, appIdentity, addonIdentity, options),
-        dryRunUpgrade: (appIdentity, addonIdentity, body, options) => dryRunUpgrade(ctx, appIdentity, addonIdentity, body, options),
-        prepareUpgrade: (appIdentity, addonIdentity, body, options) => prepareUpgrade(ctx, appIdentity, addonIdentity, body, options),
-        runUpgrade: (appIdentity, addonIdentity, body, options) => runUpgrade(ctx, appIdentity, addonIdentity, body, options),
-        upgradeWaitStatus: (appIdentity, addonIdentity, options) => upgradeWaitStatus(ctx, appIdentity, addonIdentity, options),
-    };
-});
+export const databaseExtensions = extendResource('data', 'database', ctx => ({
+    cancelUpgrade: (appIdentity, addonIdentity, options) => cancelUpgrade(ctx, appIdentity, addonIdentity, options),
+    describe: (appIdentity, addonIdentity, options) => describe(ctx, appIdentity, addonIdentity, options),
+    dryRunUpgrade: (appIdentity, addonIdentity, body, options) => dryRunUpgrade(ctx, appIdentity, addonIdentity, body, options),
+    prepareUpgrade: (appIdentity, addonIdentity, body, options) => prepareUpgrade(ctx, appIdentity, addonIdentity, body, options),
+    runUpgrade: (appIdentity, addonIdentity, body, options) => runUpgrade(ctx, appIdentity, addonIdentity, body, options),
+    upgradeWaitStatus: (appIdentity, addonIdentity, options) => upgradeWaitStatus(ctx, appIdentity, addonIdentity, options),
+}));

package/dist/resources/data/postgres-database.d.ts

@@ -16,17 +16,7 @@ export type CredentialInfo = {
     state: string;
     uuid: string;
 };
-type CredentialsDataClient = {
-    postgresDatabase: {
-        listCredentials(name: string): Promise<CredentialInfo[]>;
-    };
-};
-type CredentialsCtx = {
-    data: CredentialsDataClient;
-    platform: ResourceCtx['platform'];
-};
-export declare function listCredentials(ctx: CredentialsCtx, appIdentity: string, addonIdentity?: string, options?: ListCredentialsOptions): Promise<CredentialInfo[]>;
+export declare function listCredentials(ctx: Pick<ResourceCtx, 'data' | 'platform'>, appIdentity: string, addonIdentity?: string, options?: ListCredentialsOptions): Promise<CredentialInfo[]>;
 export declare const postgresDatabaseExtensions: import("../../core/extend-resource.js").ResourceExtension<"data", "postgresDatabase", {
     listCredentials: (appIdentity: string, addonIdentity?: string, options?: ListCredentialsOptions) => Promise<CredentialInfo[]>;
 }>;
-export {};

package/dist/resources/data/postgres-database.js

@@ -5,10 +5,6 @@ export async function listCredentials(ctx, appIdentity, addonIdentity, options =
     const addon = await resolvePgDatabase(ctx, { appIdentity, input: addonIdentity, ...options });
     return ctx.data.postgresDatabase.listCredentials(addon.id);
 }
-export const postgresDatabaseExtensions = extendResource('data', 'postgresDatabase', rawCtx => {
-    // Bridge heroku-types' loose client types to the adapter's strongly-typed contract
-    const ctx = rawCtx;
-    return {
-        listCredentials: (appIdentity, addonIdentity, options) => listCredentials(ctx, appIdentity, addonIdentity, options),
-    };
-});
+export const postgresDatabaseExtensions = extendResource('data', 'postgresDatabase', ctx => ({
+    listCredentials: (appIdentity, addonIdentity, options) => listCredentials(ctx, appIdentity, addonIdentity, options),
+}));

package/dist/resources/data/transfer.d.ts

@@ -1,49 +1,9 @@
+import type { TransferListByAppResult } from '@heroku/types/data';
 import type { ResourceCtx } from '../../core/extend-resource.js';
 export type TransferOptions = {
     signal?: AbortSignal;
 };
-export type BackupTransfer = {
-    canceled_at: string;
-    created_at: string;
-    deleted_at: string;
-    finished_at: string;
-    from_name: string;
-    from_type: string;
-    from_url: string;
-    logs: Array<{
-        created_at: string;
-        level: string;
-        message: string;
-    }>;
-    num: number;
-    num_keep: number;
-    options: Record<string, unknown>;
-    processed_bytes: number;
-    purged_at: string;
-    schedule?: {
-        uuid: string;
-    };
-    source_bytes: number;
-    started_at: string;
-    succeeded: boolean;
-    to_name: string;
-    to_type: string;
-    to_url: string;
-    updated_at: string;
-    uuid: string;
-    warnings: number;
-};
-type TransferDataClient = {
-    transfer: {
-        listByApp(name: string): Promise<BackupTransfer[]>;
-    };
-};
-type TransferCtx = {
-    data: TransferDataClient;
-    platform: ResourceCtx['platform'];
-};
-export declare function listByApp(ctx: TransferCtx, appIdentity: string, addonIdentity?: string, options?: TransferOptions): Promise<BackupTransfer[]>;
+export declare function listByApp(ctx: Pick<ResourceCtx, 'data' | 'platform'>, appIdentity: string, addonIdentity?: string, options?: TransferOptions): Promise<TransferListByAppResult>;
 export declare const transferExtensions: import("../../core/extend-resource.js").ResourceExtension<"data", "transfer", {
-    listByApp: (appIdentity: string, addonIdentity?: string, options?: TransferOptions) => Promise<BackupTransfer[]>;
+    listByApp: (appIdentity: string, addonIdentity?: string, options?: TransferOptions) => Promise<TransferListByAppResult>;
 }>;
-export {};

package/dist/resources/data/transfer.js

@@ -14,10 +14,6 @@ export async function listByApp(ctx, appIdentity, addonIdentity, options = {}) {
     }
     return ctx.data.transfer.listByApp(addon.id);
 }
-export const transferExtensions = extendResource('data', 'transfer', rawCtx => {
-    // Bridge heroku-types' loose client types to the adapter's strongly-typed contract
-    const ctx = rawCtx;
-    return {
-        listByApp: (appIdentity, addonIdentity, options) => listByApp(ctx, appIdentity, addonIdentity, options),
-    };
-});
+export const transferExtensions = extendResource('data', 'transfer', ctx => ({
+    listByApp: (appIdentity, addonIdentity, options) => listByApp(ctx, appIdentity, addonIdentity, options),
+}));

package/dist/resources/extensions/platform.d.ts

@@ -2,7 +2,7 @@ export { addOnExtensions } from '../platform/add-on/index.js';
 export { appExtensions, type AppInfo, type DiffAppsOptions, type DiffRow, type PipelineCouplingDetail, } from '../platform/app/index.js';
 export { containerExtensions, type DockerReleasesBatchUpdateOpts, NotAContainerAppError, type ReleaseDockerImagesResult, type RemoveProcessTypesOpts, } from '../platform/container/index.js';
 export { type CreateAndWaitOptions, domainExtensions, type DomainOptions, type WaitForReadyOptions, } from '../platform/domain/index.js';
-export { dynoExtensions, DynoNotReadyError, type DynoState, runDyno, type RunDynoOptions, waitForInfo, type WaitForInfoOptions, } from '../platform/dyno/index.js';
+export { DynoCrashedError, type DynoExtended, type DynoExtendedFields, dynoExtensions, DynoNotReadyError, type DynoState, enableExec, exchangeExecCredentials, type ExchangeExecCredentialsOptions, type ExecCredentials, type ExecOptions, type ExecPrereqs, execPrereqs, type ExecReservation, execStatus, type ExecStatusOptions, listExtended, type ListExtendedOptions, restartForExec, type RestartForExecOptions, runDyno, type RunDynoOptions, waitForInfo, type WaitForInfoOptions, waitForRelease, type WaitForReleaseOptions, type WaitForReleaseProgress, type WaitForReleaseResult, } from '../platform/dyno/index.js';
 export { type AttachmentAttachedEvent, type AttachmentDetachedEvent, type AttachmentUpdatedEvent, type HerokuLogEvent, logSessionExtensions, parseHerokuLogLine, type ProvisioningCompletedEvent, type ScaledToEntry, type ScaledToEvent, type StartingProcessEvent, type StateChangedEvent, } from '../platform/log-session/index.js';
 export { pipelineCouplingExtensions } from '../platform/pipeline/coupling.js';
 export { pipelineExtensions } from '../platform/pipeline/index.js';

package/dist/resources/extensions/platform.js

@@ -2,7 +2,7 @@ export { addOnExtensions } from '../platform/add-on/index.js';
 export { appExtensions, } from '../platform/app/index.js';
 export { containerExtensions, NotAContainerAppError, } from '../platform/container/index.js';
 export { domainExtensions, } from '../platform/domain/index.js';
-export { dynoExtensions, DynoNotReadyError, runDyno, waitForInfo, } from '../platform/dyno/index.js';
+export { DynoCrashedError, dynoExtensions, DynoNotReadyError, enableExec, exchangeExecCredentials, execPrereqs, execStatus, listExtended, restartForExec, runDyno, waitForInfo, waitForRelease, } from '../platform/dyno/index.js';
 export { logSessionExtensions, parseHerokuLogLine, } from '../platform/log-session/index.js';
 export { pipelineCouplingExtensions } from '../platform/pipeline/coupling.js';
 export { pipelineExtensions } from '../platform/pipeline/index.js';

package/dist/resources/platform/dyno/exec.d.ts

@@ -0,0 +1,134 @@
+import type { HerokuApiClientOptions } from '@heroku/heroku-fetch';
+import type { App, BuildpackInstallation, ConfigVar, Dyno } from '@heroku/types/3.sdk';
+import type { ResourceCtx } from '../../../core/extend-resource.js';
+import { type WaitForInfoOptions } from './wait-for-info.js';
+export type ExecOptions = {
+    signal?: AbortSignal;
+};
+/**
+ * Raw facts the CLI needs to decide whether — and how — Heroku Exec can
+ * be enabled for an app. This helper only gathers; every branch
+ * (Shield restriction, container-stack warning, missing-buildpack
+ * error, the deprecated `HEROKU_EXEC_URL` add-on notice) stays in the
+ * caller so the SDK owns no presentation or prompting.
+ */
+export type ExecPrereqs = {
+    /** Installed buildpacks, for the exec-buildpack presence check. */
+    buildpacks: BuildpackInstallation[];
+    /** `build_stack.name`, e.g. `'container'`. */
+    buildStack: string | undefined;
+    /** Full config-var map; the caller reads `HEROKU_EXEC_URL` off it. */
+    configVars: ConfigVar;
+    /** Whether the `runtime-heroku-exec` feature is already enabled. */
+    featureEnabled: boolean;
+    /** App generation; `'fir'` apps do not support exec. */
+    generation: string;
+    /** App's Private Space, if any (carries `shield`). */
+    space: App['space'];
+};
+/**
+ * Gather the app facts that gate Heroku Exec in one parallel round-trip:
+ * app info, buildpack installations, config vars, and the exec feature.
+ *
+ * Returns raw facts only — the caller branches on them. `configVars` is
+ * returned whole because the caller inspects `HEROKU_EXEC_URL` (the
+ * deprecated add-on) as well as passing config through to the exchange.
+ */
+export declare function execPrereqs(ctx: Pick<ResourceCtx, 'platform'>, appIdentity: string, options?: ExecOptions): Promise<ExecPrereqs>;
+/**
+ * Enable the `runtime-heroku-exec` feature on an app. Used both on the
+ * first-run restart path and on the Private-Space buildpack path, so it
+ * stays a bare enable — the caller decides whether a restart follows.
+ */
+export declare function enableExec(ctx: Pick<ResourceCtx, 'platform'>, appIdentity: string, options?: ExecOptions): Promise<void>;
+/**
+ * Thrown by {@link restartForExec} the moment the awaited dyno reports
+ * `crashed`, so the caller can surface the failure immediately rather
+ * than waiting out the remaining poll attempts.
+ */
+export declare class DynoCrashedError extends Error {
+    readonly dyno: Dyno;
+    readonly id = "dyno_crashed";
+    constructor(dyno: Dyno);
+}
+export type RestartForExecOptions = WaitForInfoOptions & {
+    /**
+     * Milliseconds to wait after enabling the feature before restarting,
+     * letting the enable propagate. Defaults to 2000, matching the
+     * historical CLI behavior.
+     */
+    settleMs?: number;
+};
+/**
+ * Restart all of an app's dynos and wait for the named dyno to come
+ * back `up`. Enabling Heroku Exec for the first time requires a dyno
+ * restart, so this bundles the settle delay, `dyno.restartAll`, and the
+ * wait-for-`up` poll into one step. A `crashed` dyno throws
+ * {@link DynoCrashedError} at once instead of exhausting the attempts.
+ *
+ * The wait is bounded by {@link WaitForInfoOptions.attempts} (default
+ * 20). Callers that need to tolerate a slow boot should raise it.
+ */
+export declare function restartForExec(ctx: Pick<ResourceCtx, 'platform'>, appIdentity: string, dynoIdentity: string, options?: RestartForExecOptions): Promise<Dyno>;
+/** Connection info the exec-manager returns for a client-key exchange. */
+export type ExecCredentials = {
+    client_user: string;
+    dyno_ip: string;
+    proxy_public_key: string;
+    tunnel_host: string;
+};
+export type ExchangeExecCredentialsOptions = {
+    /** API key used as the Basic-auth password (username is the app). */
+    apiKey: string;
+    /**
+     * Options forwarded to the raw `HerokuApiClient`. The exec-manager is
+     * not in the routes registry, so the call is issued via a bare client
+     * with `service: 'custom'`.
+     */
+    clientOptions?: Omit<HerokuApiClientOptions, 'baseUrl' | 'service' | 'token'>;
+    /**
+     * App config vars. When `HEROKU_EXEC_URL` is present (the deprecated
+     * add-on), its embedded credentials and the `/api/v1` prefix are used.
+     */
+    configVars?: ConfigVar;
+    /** Target dyno, e.g. `'web.1'`. */
+    dyno: string;
+    /** Extra request headers (e.g. from `HEROKU_HEADERS`). */
+    headers?: Record<string, string>;
+    /** OpenSSH-format public key generated by the caller. */
+    publicKey: string;
+    signal?: AbortSignal;
+};
+/**
+ * Exchange a client public key for exec connection info.
+ *
+ * Issues `PUT {execHost}{apiPath}/{dyno}` with `{client_key}` and Basic
+ * auth (`app:apiKey`, or the credentials embedded in `HEROKU_EXEC_URL`)
+ * via a bare `HerokuApiClient` — the exec-manager is a custom host with
+ * no routes entry and no bearer token (the empty `token` lets the Basic
+ * `Authorization` header survive). The caller feeds the returned info,
+ * plus the private key it holds, to its own SSH transport; the SDK does
+ * not open the connection.
+ */
+export declare function exchangeExecCredentials(appIdentity: string, options: ExchangeExecCredentialsOptions): Promise<ExecCredentials>;
+/** A running exec reservation, as reported by the exec-manager status endpoint. */
+export type ExecReservation = {
+    [key: string]: unknown;
+    dyno_name: string;
+};
+export type ExecStatusOptions = {
+    apiKey: string;
+    clientOptions?: Omit<HerokuApiClientOptions, 'baseUrl' | 'service' | 'token'>;
+    configVars?: ConfigVar;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+};
+/**
+ * List the app's running exec reservations.
+ *
+ * Issues `GET {execHost}{apiPath}` (no dyno segment) with the same
+ * custom-host Basic-auth setup as {@link exchangeExecCredentials}. The
+ * caller correlates each reservation's `dyno_name` with live dyno state
+ * for display.
+ */
+export declare function execStatus(appIdentity: string, options: ExecStatusOptions): Promise<ExecReservation[]>;

package/dist/resources/platform/dyno/exec.js

@@ -0,0 +1,187 @@
+import { HerokuApiClient, NotFoundError } from '@heroku/heroku-fetch';
+import { wait } from '../../../utils/wait.js';
+import { waitForInfo } from './wait-for-info.js';
+/** The app feature that gates Heroku Exec. */
+const EXEC_FEATURE = 'runtime-heroku-exec';
+/** Default exec-manager host used when no override is configured. */
+const DEFAULT_EXEC_HOST = 'https://exec-manager.heroku.com/';
+/** Exec-manager API prefixes. v1 is the legacy add-on path; v2 is current. */
+const EXEC_API_PATH_LEGACY = '/api/v1';
+const EXEC_API_PATH_CURRENT = '/api/v2';
+/** Milliseconds to let the feature-enable settle before restarting dynos. */
+const DEFAULT_SETTLE_MS = 2000;
+/**
+ * Gather the app facts that gate Heroku Exec in one parallel round-trip:
+ * app info, buildpack installations, config vars, and the exec feature.
+ *
+ * Returns raw facts only — the caller branches on them. `configVars` is
+ * returned whole because the caller inspects `HEROKU_EXEC_URL` (the
+ * deprecated add-on) as well as passing config through to the exchange.
+ */
+export async function execPrereqs(ctx, appIdentity, options = {}) {
+    options.signal?.throwIfAborted();
+    const platform = options.signal ? ctx.platform.withOptions({ signal: options.signal }) : ctx.platform;
+    const [app, buildpacks, configVars, feature] = await Promise.all([
+        platform.app.info(appIdentity),
+        platform.buildpackInstallation.list(appIdentity),
+        platform.configVar.infoForApp(appIdentity),
+        // fir apps have no runtime-heroku-exec feature, so this 404s there. A
+        // missing feature must not sink the whole gather — the caller reads
+        // `generation` to reject fir. Only a 404 degrades to disabled; other
+        // errors still propagate.
+        platform.appFeature.info(appIdentity, EXEC_FEATURE).catch((error) => {
+            if (error instanceof NotFoundError)
+                return { enabled: false };
+            throw error;
+        }),
+    ]);
+    return {
+        buildpacks,
+        buildStack: app.build_stack?.name,
+        configVars,
+        featureEnabled: Boolean(feature.enabled),
+        generation: app.generation,
+        space: app.space,
+    };
+}
+/**
+ * Enable the `runtime-heroku-exec` feature on an app. Used both on the
+ * first-run restart path and on the Private-Space buildpack path, so it
+ * stays a bare enable — the caller decides whether a restart follows.
+ */
+export async function enableExec(ctx, appIdentity, options = {}) {
+    options.signal?.throwIfAborted();
+    const platform = options.signal ? ctx.platform.withOptions({ signal: options.signal }) : ctx.platform;
+    await platform.appFeature.update(appIdentity, EXEC_FEATURE, { enabled: true });
+}
+/**
+ * Thrown by {@link restartForExec} the moment the awaited dyno reports
+ * `crashed`, so the caller can surface the failure immediately rather
+ * than waiting out the remaining poll attempts.
+ */
+export class DynoCrashedError extends Error {
+    dyno;
+    id = 'dyno_crashed';
+    constructor(dyno) {
+        super(`Dyno '${dyno.name}' crashed while waiting for Heroku Exec to start.`);
+        this.dyno = dyno;
+        this.name = 'DynoCrashedError';
+    }
+}
+/**
+ * Restart all of an app's dynos and wait for the named dyno to come
+ * back `up`. Enabling Heroku Exec for the first time requires a dyno
+ * restart, so this bundles the settle delay, `dyno.restartAll`, and the
+ * wait-for-`up` poll into one step. A `crashed` dyno throws
+ * {@link DynoCrashedError} at once instead of exhausting the attempts.
+ *
+ * The wait is bounded by {@link WaitForInfoOptions.attempts} (default
+ * 20). Callers that need to tolerate a slow boot should raise it.
+ */
+export async function restartForExec(ctx, appIdentity, dynoIdentity, options = {}) {
+    const { settleMs = DEFAULT_SETTLE_MS, ...waitOptions } = options;
+    const { signal } = waitOptions;
+    signal?.throwIfAborted();
+    const platform = signal ? ctx.platform.withOptions({ signal }) : ctx.platform;
+    await wait(settleMs, signal);
+    await platform.dyno.restartAll(appIdentity);
+    return waitForInfo(ctx, appIdentity, dynoIdentity, {
+        ...waitOptions,
+        onPoll(dyno) {
+            if (dyno.state === 'crashed') {
+                throw new DynoCrashedError(dyno);
+            }
+            waitOptions.onPoll?.(dyno);
+        },
+        states: ['up'],
+    });
+}
+/**
+ * Exchange a client public key for exec connection info.
+ *
+ * Issues `PUT {execHost}{apiPath}/{dyno}` with `{client_key}` and Basic
+ * auth (`app:apiKey`, or the credentials embedded in `HEROKU_EXEC_URL`)
+ * via a bare `HerokuApiClient` — the exec-manager is a custom host with
+ * no routes entry and no bearer token (the empty `token` lets the Basic
+ * `Authorization` header survive). The caller feeds the returned info,
+ * plus the private key it holds, to its own SSH transport; the SDK does
+ * not open the connection.
+ */
+export async function exchangeExecCredentials(appIdentity, options) {
+    options.signal?.throwIfAborted();
+    const endpoint = resolveExecEndpoint(appIdentity, options.apiKey, options.configVars);
+    const client = newExecClient(endpoint.baseUrl, options.clientOptions);
+    const path = `${endpoint.apiPath}/${encodeURIComponent(options.dyno)}`;
+    const response = await client.put(path, { client_key: options.publicKey }, {
+        headers: {
+            ...options.headers,
+            Authorization: endpoint.authorization,
+            'Content-Type': 'application/json',
+        },
+        signal: options.signal,
+    });
+    return parseExecBody(response);
+}
+/**
+ * List the app's running exec reservations.
+ *
+ * Issues `GET {execHost}{apiPath}` (no dyno segment) with the same
+ * custom-host Basic-auth setup as {@link exchangeExecCredentials}. The
+ * caller correlates each reservation's `dyno_name` with live dyno state
+ * for display.
+ */
+export async function execStatus(appIdentity, options) {
+    options.signal?.throwIfAborted();
+    const endpoint = resolveExecEndpoint(appIdentity, options.apiKey, options.configVars);
+    const client = newExecClient(endpoint.baseUrl, options.clientOptions);
+    const response = await client.get(endpoint.apiPath, {
+        headers: { ...options.headers, Authorization: endpoint.authorization },
+        signal: options.signal,
+    });
+    return parseExecBody(response);
+}
+/**
+ * Resolve the exec-manager base URL, API prefix, and Basic-auth header.
+ *
+ * When `HEROKU_EXEC_URL` is set as a config var (the deprecated add-on),
+ * that URL carries its own embedded credentials and uses the `/api/v1`
+ * prefix. Otherwise the host comes from the `HEROKU_EXEC_URL`
+ * environment override or the default exec-manager, authenticated as
+ * `app:apiKey` against `/api/v2`.
+ */
+function resolveExecEndpoint(appIdentity, apiKey, configVars) {
+    const configUrl = configVars?.HEROKU_EXEC_URL;
+    if (configUrl) {
+        const url = new URL(configUrl);
+        // URL.username/password are percent-encoded; decode before Basic auth so
+        // credentials with reserved characters (e.g. `p%40ss`) authenticate.
+        return {
+            apiPath: EXEC_API_PATH_LEGACY,
+            authorization: toBasicAuth(decodeURIComponent(url.username), decodeURIComponent(url.password)),
+            baseUrl: `${url.protocol}//${url.host}`,
+        };
+    }
+    const url = new URL(process.env.HEROKU_EXEC_URL ?? DEFAULT_EXEC_HOST);
+    return {
+        apiPath: EXEC_API_PATH_CURRENT,
+        authorization: toBasicAuth(appIdentity, apiKey),
+        baseUrl: `${url.protocol}//${url.host}`,
+    };
+}
+function newExecClient(baseUrl, clientOptions) {
+    return new HerokuApiClient({
+        ...clientOptions, baseUrl, service: 'custom', token: '',
+    });
+}
+function toBasicAuth(username, password) {
+    return `Basic ${Buffer.from(`${username}:${password}`).toString('base64')}`;
+}
+/**
+ * Parse an exec-manager response body, tolerating either a JSON value or
+ * a JSON string (double-encoded), so behavior matches the historical
+ * raw `JSON.parse` regardless of the response `Content-Type`.
+ */
+async function parseExecBody(response) {
+    const body = (await response.json());
+    return (typeof body === 'string' ? JSON.parse(body) : body);
+}

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

@@ -1,10 +1,16 @@
 import type { Formation } from '@heroku/types/3.sdk';
 import type { StickyRouteOptions } from '../../../core/create-client.js';
 import type { ResourceCtx } from '../../../core/extend-resource.js';
+import { type ExchangeExecCredentialsOptions, type ExecOptions, type ExecStatusOptions, type RestartForExecOptions } from './exec.js';
+import { type ListExtendedOptions } from './list-extended.js';
 import { type RunDynoOptions } from './run.js';
 import { type WaitForInfoOptions } from './wait-for-info.js';
+import { type WaitForReleaseOptions } from './wait-for-release.js';
+export { DynoCrashedError, enableExec, exchangeExecCredentials, type ExchangeExecCredentialsOptions, type ExecCredentials, type ExecOptions, type ExecPrereqs, execPrereqs, type ExecReservation, execStatus, type ExecStatusOptions, restartForExec, type RestartForExecOptions, } from './exec.js';
+export { type DynoExtended, type DynoExtendedFields, listExtended, type ListExtendedOptions, } from './list-extended.js';
 export { runDyno, type RunDynoOptions } from './run.js';
 export { DynoNotReadyError, type DynoState, waitForInfo, type WaitForInfoOptions, } from './wait-for-info.js';
+export { waitForRelease, type WaitForReleaseOptions, type WaitForReleaseProgress, type WaitForReleaseResult, } from './wait-for-release.js';
 export type DynoOptions = {
     signal?: AbortSignal;
 };
@@ -40,11 +46,18 @@ export declare function scaleDynos(ctx: {
 }, appIdentity: string, updates: ScaleDynosUpdate[], options?: DynoOptions): Promise<Formation[]>;
 export declare function restartDynos(ctx: Pick<ResourceCtx, 'platform'>, appIdentity: string, target?: RestartDynosTarget, options?: DynoOptions): Promise<void>;
 export declare const dynoExtensions: import("../../../core/extend-resource.js").ResourceExtension<"platform", "dyno", {
+    enableExec: (appIdentity: string, options?: ExecOptions) => Promise<void>;
+    exchangeExecCredentials: (appIdentity: string, options: ExchangeExecCredentialsOptions) => Promise<import("./exec.js").ExecCredentials>;
+    execPrereqs: (appIdentity: string, options?: ExecOptions) => Promise<import("./exec.js").ExecPrereqs>;
+    execStatus: (appIdentity: string, options: ExecStatusOptions) => Promise<import("./exec.js").ExecReservation[]>;
+    listExtended: (appIdentity: string, options?: ListExtendedOptions) => Promise<import("./list-extended.js").DynoExtended[]>;
     restart: (appIdentity: string, target?: RestartDynosTarget, options?: DynoOptions) => Promise<void>;
+    restartForExec: (appIdentity: string, dynoIdentity: string, options?: RestartForExecOptions) => Promise<import("@heroku/types/3.sdk").Dyno>;
     run: (appIdentity: string, command: string, options?: RunDynoOptions) => Promise<import("@heroku/types/3.sdk").Dyno>;
     scale: {
         (appIdentity: string, updates: ScaleDynosUpdate, options?: DynoOptions): Promise<Formation>;
         (appIdentity: string, updates: ScaleDynosUpdate[], options?: DynoOptions): Promise<Formation[]>;
     };
     waitForInfo: (appIdentity: string, dynoIdentity: string, options?: WaitForInfoOptions) => Promise<import("@heroku/types/3.sdk").Dyno>;
+    waitForRelease: (appIdentity: string, options?: WaitForReleaseOptions) => Promise<import("./wait-for-release.js").WaitForReleaseResult | undefined>;
 }>;

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

@@ -1,8 +1,14 @@
 import { extendResource } from '../../../core/extend-resource.js';
+import { enableExec, exchangeExecCredentials, execPrereqs, execStatus, restartForExec, } from './exec.js';
+import { listExtended } from './list-extended.js';
 import { runDyno } from './run.js';
 import { waitForInfo } from './wait-for-info.js';
+import { waitForRelease } from './wait-for-release.js';
+export { DynoCrashedError, enableExec, exchangeExecCredentials, execPrereqs, execStatus, restartForExec, } from './exec.js';
+export { listExtended, } from './list-extended.js';
 export { runDyno } from './run.js';
 export { DynoNotReadyError, waitForInfo, } from './wait-for-info.js';
+export { waitForRelease, } from './wait-for-release.js';
 export async function scaleDynos(ctx, appIdentity, updates, options = {}) {
     options.signal?.throwIfAborted();
     const platform = options.signal ? ctx.platform.withOptions({ signal: options.signal }) : ctx.platform;
@@ -25,8 +31,15 @@ export async function restartDynos(ctx, appIdentity, target, options = {}) {
     await ctx.platform.dyno.restartFormation(appIdentity, target.type);
 }
 export const dynoExtensions = extendResource('platform', 'dyno', ctx => ({
+    enableExec: (appIdentity, options) => (enableExec(ctx, appIdentity, options)),
+    exchangeExecCredentials: (appIdentity, options) => (exchangeExecCredentials(appIdentity, options)),
+    execPrereqs: (appIdentity, options) => (execPrereqs(ctx, appIdentity, options)),
+    execStatus: (appIdentity, options) => (execStatus(appIdentity, options)),
+    listExtended: (appIdentity, options) => (listExtended(appIdentity, options)),
     restart: (appIdentity, target, options) => (restartDynos(ctx, appIdentity, target, options)),
+    restartForExec: (appIdentity, dynoIdentity, options) => (restartForExec(ctx, appIdentity, dynoIdentity, options)),
     run: (appIdentity, command, options) => (runDyno(ctx, appIdentity, command, options)),
     scale: ((appIdentity, updates, options) => scaleDynos(ctx, appIdentity, updates, options)),
     waitForInfo: (appIdentity, dynoIdentity, options) => (waitForInfo(ctx, appIdentity, dynoIdentity, options)),
+    waitForRelease: (appIdentity, options) => (waitForRelease(ctx, appIdentity, options)),
 }));

package/dist/resources/platform/dyno/list-extended.d.ts

@@ -0,0 +1,50 @@
+import type { HerokuApiClientOptions } from '@heroku/heroku-fetch';
+import type { Dyno } from '@heroku/types/3.sdk';
+/**
+ * Operational detail the platform attaches to each dyno only when the
+ * `?extended=true` query is used with the `version=3.sdk` Accept
+ * variant. Every field is nullable — the platform omits values it
+ * cannot resolve for a given dyno (e.g. a `run` dyno has no `route`).
+ */
+export type DynoExtendedFields = {
+    az: null | string;
+    execution_plane: null | string;
+    fleet: null | string;
+    instance: null | string;
+    ip: null | string;
+    port: null | number;
+    region: null | string;
+    route: null | string;
+};
+/**
+ * A {@link Dyno} plus the optional {@link DynoExtendedFields} block
+ * returned by {@link listExtended}. `extended` is absent unless the
+ * request was made with sudo privileges against a supporting stack.
+ */
+export type DynoExtended = Dyno & {
+    extended?: DynoExtendedFields;
+};
+export type ListExtendedOptions = {
+    /**
+     * Options forwarded to the raw `HerokuApiClient`. The route registry
+     * has no entry for `GET /apps/{app}/dynos?extended=true`, so this
+     * call is issued via a bare client (like the exec-inside path in
+     * {@link runDyno}).
+     */
+    clientOptions?: HerokuApiClientOptions;
+    signal?: AbortSignal;
+};
+/**
+ * List an app's dynos with the extended operational detail block.
+ *
+ * Issues `GET /apps/{app}/dynos?extended=true` with
+ * `Accept: version=3.sdk` via a bare `HerokuApiClient`, because the
+ * routes registry has no entry for the `extended` query variant. The
+ * `extended` block is only populated for callers with sudo
+ * privileges; without them the platform returns ordinary dynos and
+ * `extended` is absent.
+ *
+ * Unlike the routes client, this does not auto-paginate — it issues a
+ * single GET, matching the historical CLI behavior.
+ */
+export declare function listExtended(appIdentity: string, options?: ListExtendedOptions): Promise<DynoExtended[]>;

package/dist/resources/platform/dyno/list-extended.js

@@ -0,0 +1,28 @@
+import { HerokuApiClient } from '@heroku/heroku-fetch';
+const ACCEPT_EXTENDED = 'application/vnd.heroku+json; version=3.sdk';
+/**
+ * List an app's dynos with the extended operational detail block.
+ *
+ * Issues `GET /apps/{app}/dynos?extended=true` with
+ * `Accept: version=3.sdk` via a bare `HerokuApiClient`, because the
+ * routes registry has no entry for the `extended` query variant. The
+ * `extended` block is only populated for callers with sudo
+ * privileges; without them the platform returns ordinary dynos and
+ * `extended` is absent.
+ *
+ * Unlike the routes client, this does not auto-paginate — it issues a
+ * single GET, matching the historical CLI behavior.
+ */
+export async function listExtended(appIdentity, options = {}) {
+    options.signal?.throwIfAborted();
+    const apiClient = new HerokuApiClient({
+        ...options.clientOptions,
+        service: 'platform',
+    });
+    const path = `/apps/${encodeURIComponent(appIdentity)}/dynos?extended=true`;
+    const response = await apiClient.get(path, {
+        headers: { Accept: ACCEPT_EXTENDED },
+        signal: options.signal,
+    });
+    return (await response.json());
+}

package/dist/resources/platform/dyno/wait-for-release.d.ts

@@ -0,0 +1,76 @@
+import type { ResourceCtx } from '../../../core/extend-resource.js';
+/**
+ * Progress reported on each poll where the fleet has NOT yet fully
+ * converged on the target release. `onLatest` of `total` relevant
+ * dynos are running a version `>= version`.
+ */
+export type WaitForReleaseProgress = {
+    onLatest: number;
+    total: number;
+    version: number;
+};
+export type WaitForReleaseOptions = {
+    /**
+     * Maximum number of polls before giving up with
+     * {@link ReleaseNotConvergedError}. Omitted (the default) means
+     * unbounded — the wait runs until the fleet converges or the
+     * caller's {@link WaitForReleaseOptions.signal} aborts, matching a
+     * long-running `ps:wait`.
+     */
+    attempts?: number;
+    /** Delay between polls in milliseconds. Defaults to 10000. */
+    delayMs?: number;
+    /**
+     * Fires after every poll where the fleet has NOT yet converged
+     * (i.e. `onLatest < total`), before the next wait. It never fires
+     * on the converged poll — a fleet already on the latest release
+     * when the first poll runs produces no `onPoll` calls at all. Use
+     * it to drive a live progress indicator; the converged result is
+     * the resolved value, not an `onPoll` call.
+     */
+    onPoll?: (progress: WaitForReleaseProgress) => void;
+    signal?: AbortSignal;
+    /** Only wait for dynos of this process type. */
+    type?: string;
+    /** Include one-off `run` dynos in the wait. Mutually exclusive with `type`. */
+    withRun?: boolean;
+};
+export type WaitForReleaseResult = {
+    total: number;
+    version: number;
+};
+/**
+ * Thrown by {@link waitForRelease} when {@link WaitForReleaseOptions.attempts}
+ * was set and the fleet did not converge on the target release within
+ * that many polls. Carries the last observed progress so callers can
+ * report how far the fleet got.
+ */
+export declare class ReleaseNotConvergedError extends Error {
+    readonly attempts: number;
+    readonly progress: undefined | WaitForReleaseProgress;
+    readonly id = "release_not_converged";
+    constructor(attempts: number, progress: undefined | WaitForReleaseProgress);
+}
+/**
+ * Poll an app's dynos until every relevant one is `up` and running a
+ * release version at least the app's latest, then resolve with the
+ * converged `{total, version}`.
+ *
+ * "Relevant" excludes `release` dynos always, and one-off `run` dynos
+ * unless {@link WaitForReleaseOptions.withRun} is set or
+ * {@link WaitForReleaseOptions.type} names `'run'`; when
+ * {@link WaitForReleaseOptions.type} is given, only that process type
+ * is considered.
+ *
+ * The latest release is resolved once up front via
+ * `GET /apps/{app}/releases` scoped to `Range: version ..; max=1,
+ * order=desc`. If the app has no releases (or the latest has no
+ * version), resolves `undefined` without polling — the caller should
+ * report "no releases" rather than wait forever.
+ *
+ * Polling is unbounded by default (runs until convergence or an
+ * aborted {@link WaitForReleaseOptions.signal}); pass
+ * {@link WaitForReleaseOptions.attempts} to cap it, after which it
+ * throws {@link ReleaseNotConvergedError}.
+ */
+export declare function waitForRelease(ctx: Pick<ResourceCtx, 'platform'>, appIdentity: string, options?: WaitForReleaseOptions): Promise<undefined | WaitForReleaseResult>;

package/dist/resources/platform/dyno/wait-for-release.js

@@ -0,0 +1,83 @@
+import { wait } from '../../../utils/wait.js';
+const DEFAULT_DELAY_MS = 10_000;
+const LATEST_RELEASE_RANGE = 'version ..; max=1, order=desc';
+/**
+ * Thrown by {@link waitForRelease} when {@link WaitForReleaseOptions.attempts}
+ * was set and the fleet did not converge on the target release within
+ * that many polls. Carries the last observed progress so callers can
+ * report how far the fleet got.
+ */
+export class ReleaseNotConvergedError extends Error {
+    attempts;
+    progress;
+    id = 'release_not_converged';
+    constructor(attempts, progress) {
+        super(`Fleet did not converge on release version ${progress?.version ?? '?'} `
+            + `within ${attempts} attempts`
+            + (progress ? ` (last: ${progress.onLatest}/${progress.total} on latest).` : '.'));
+        this.attempts = attempts;
+        this.progress = progress;
+        this.name = 'ReleaseNotConvergedError';
+    }
+}
+/**
+ * Poll an app's dynos until every relevant one is `up` and running a
+ * release version at least the app's latest, then resolve with the
+ * converged `{total, version}`.
+ *
+ * "Relevant" excludes `release` dynos always, and one-off `run` dynos
+ * unless {@link WaitForReleaseOptions.withRun} is set or
+ * {@link WaitForReleaseOptions.type} names `'run'`; when
+ * {@link WaitForReleaseOptions.type} is given, only that process type
+ * is considered.
+ *
+ * The latest release is resolved once up front via
+ * `GET /apps/{app}/releases` scoped to `Range: version ..; max=1,
+ * order=desc`. If the app has no releases (or the latest has no
+ * version), resolves `undefined` without polling — the caller should
+ * report "no releases" rather than wait forever.
+ *
+ * Polling is unbounded by default (runs until convergence or an
+ * aborted {@link WaitForReleaseOptions.signal}); pass
+ * {@link WaitForReleaseOptions.attempts} to cap it, after which it
+ * throws {@link ReleaseNotConvergedError}.
+ */
+export async function waitForRelease(ctx, appIdentity, options = {}) {
+    const { attempts, delayMs = DEFAULT_DELAY_MS, onPoll, signal, type, withRun, } = options;
+    signal?.throwIfAborted();
+    const platform = signal ? ctx.platform.withOptions({ signal }) : ctx.platform;
+    const releases = await platform
+        .withHeaders({ Range: LATEST_RELEASE_RANGE })
+        .release.list(appIdentity);
+    const version = releases[0]?.version;
+    if (version === undefined) {
+        return undefined;
+    }
+    let lastProgress;
+    let attempt = 0;
+    while (true) {
+        const dynos = await platform.dyno.list(appIdentity);
+        const relevant = dynos
+            .filter(dyno => dyno.type !== 'release')
+            // Keep run dynos only when explicitly requested — via withRun, or a
+            // type filter that names 'run'. Ordering matters: this must not drop
+            // run dynos before the type filter below can select them.
+            .filter(dyno => withRun || type === 'run' || dyno.type !== 'run')
+            .filter(dyno => !type || dyno.type === type);
+        const onLatest = relevant.filter(dyno => (dyno.state === 'up'
+            && dyno.release?.version !== undefined
+            && dyno.release.version >= version)).length;
+        if (onLatest === relevant.length) {
+            return { total: relevant.length, version };
+        }
+        lastProgress = { onLatest, total: relevant.length, version };
+        onPoll?.(lastProgress);
+        // Give up once the (opt-in) attempts cap is reached, before the next
+        // wait — an unbounded wait only exits on convergence or an aborted signal.
+        attempt++;
+        if (attempts !== undefined && attempt >= attempts) {
+            throw new ReleaseNotConvergedError(attempts, lastProgress);
+        }
+        await wait(delayMs, signal);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heroku/sdk",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "Heroku SDK",
   "author": "Heroku",
   "type": "module",
@@ -145,7 +145,7 @@
   },
   "dependencies": {
     "@heroku/heroku-fetch": "^0.1.4",
-    "@heroku/types": "^4.8.0",
+    "@heroku/types": "^5.0.0",
     "debug": "^4.4.0"
   }
 }