@heroku/sdk 0.5.2 → 0.5.3

package/dist/core/create-client.d.ts

@@ -7,7 +7,15 @@ type RoutesModule = Record<string, Record<string, RouteDefinition>>;
  * and `stream` are deliberately excluded — those belong on the
  * individual route call, not on the client wrapper.
  */
-export type StickyRouteOptions = Pick<RequestOptions, 'headers' | 'signal' | 'timeout'>;
+export type StickyRouteOptions = Pick<RequestOptions, 'headers' | 'signal' | 'timeout'> & {
+    /**
+     * Request body applied to write calls on the derived client. Primarily
+     * for methods whose route metadata lacks `hasRequestBody` (e.g. DELETE
+     * with a `force` payload) where the body cannot be passed positionally.
+     * The underlying client forwards this as the JSON payload.
+     */
+    body?: unknown;
+};
 /**
  * Methods available on every routes-generated client in addition to
  * the resources/methods generated from the routes registry.

package/dist/core/create-client.js

@@ -11,12 +11,14 @@ function mergeStickyOptions(base, next) {
     if (next.headers || base?.headers) {
         merged.headers = { ...base?.headers, ...next.headers };
     }
-    // signal and timeout are not additive — last wins, but only if the
-    // caller actually set them. Otherwise the previous value persists.
+    // signal, timeout, and body are not additive — last wins, but only if
+    // the caller actually set them. Otherwise the previous value persists.
     if (next.signal !== undefined)
         merged.signal = next.signal;
     if (next.timeout !== undefined)
         merged.timeout = next.timeout;
+    if (next.body !== undefined)
+        merged.body = next.body;
     return merged;
 }
 function buildClientProxy(httpClient, routes, inheritedOptions) {

package/dist/resources/data/redis/errors.d.ts

@@ -0,0 +1,8 @@
+import type { AddOn } from '@heroku/types/3.sdk';
+import { AddonAmbiguousError, AddonNotFoundError } from '../../platform/add-on/index.js';
+export declare class RedisAddonNotFoundError extends AddonNotFoundError {
+    constructor();
+}
+export declare class RedisAddonAmbiguousError extends AddonAmbiguousError {
+    constructor(matches: AddOn[]);
+}

package/dist/resources/data/redis/errors.js

@@ -0,0 +1,15 @@
+import { AddonAmbiguousError, AddonNotFoundError } from '../../platform/add-on/index.js';
+export class RedisAddonNotFoundError extends AddonNotFoundError {
+    constructor() {
+        super('redis instance');
+        this.message = 'No Redis instances found.';
+        this.name = 'RedisAddonNotFoundError';
+    }
+}
+export class RedisAddonAmbiguousError extends AddonAmbiguousError {
+    constructor(matches) {
+        super(matches);
+        this.message = `Please specify a single instance. Found: ${matches.map(m => m.name).join(', ')}`;
+        this.name = 'RedisAddonAmbiguousError';
+    }
+}

package/dist/resources/data/redis/index.d.ts

@@ -0,0 +1,9 @@
+import type { ResolveRedisByAppOptions } from './resolve-by-app.js';
+import type { WaitForRedisReadyOptions } from './wait-for-ready.js';
+export { RedisAddonAmbiguousError, RedisAddonNotFoundError } from './errors.js';
+export { resolveRedisByApp, type ResolveRedisByAppOptions } from './resolve-by-app.js';
+export { waitForRedisReady, type WaitForRedisReadyOptions } from './wait-for-ready.js';
+export declare const redisExtensions: import("../../../core/extend-resource.js").ResourceExtension<"data", "redis", {
+    resolveByApp: (appIdentity: string, options?: ResolveRedisByAppOptions) => Promise<import("../../platform/add-on/types.js").ResolvedAddOn>;
+    waitForReady: (nameOrId: string, options?: WaitForRedisReadyOptions) => Promise<import("@heroku/types/data").RedisWaitResult>;
+}>;

package/dist/resources/data/redis/index.js

@@ -0,0 +1,10 @@
+import { extendResource } from '../../../core/extend-resource.js';
+import { resolveRedisByApp } from './resolve-by-app.js';
+import { waitForRedisReady } from './wait-for-ready.js';
+export { RedisAddonAmbiguousError, RedisAddonNotFoundError } from './errors.js';
+export { resolveRedisByApp } from './resolve-by-app.js';
+export { waitForRedisReady } from './wait-for-ready.js';
+export const redisExtensions = extendResource('data', 'redis', ctx => ({
+    resolveByApp: (appIdentity, options) => resolveRedisByApp(ctx, appIdentity, options),
+    waitForReady: (nameOrId, options) => waitForRedisReady(ctx, nameOrId, options),
+}));

package/dist/resources/data/redis/resolve-by-app.d.ts

@@ -0,0 +1,35 @@
+import type { ResourceCtx } from '../../../core/extend-resource.js';
+import type { ResolvedAddOn } from '../../platform/add-on/index.js';
+export type ResolveRedisByAppOptions = {
+    /**
+     * Override the add-on service prefix used to identify a redis add-on
+     * on the app. Defaults to `heroku-redis`. The match is a prefix
+     * (`startsWith`) on `addon_service.name`, matching the CLI's existing
+     * `makeAddonsFilter` semantics.
+     */
+    addonServiceName?: string;
+    /**
+     * Optional filter narrowing the app's redis add-ons to a single
+     * database. Matched case-insensitively against the add-on's `name`
+     * and each of its `config_vars`, using substring containment. This
+     * mirrors the CLI's `makeAddonsFilter` behavior so migrating callers
+     * observe identical resolution semantics.
+     */
+    database?: string;
+    signal?: AbortSignal;
+};
+/**
+ * Resolve a redis add-on attached to `appIdentity`.
+ *
+ * Lists the app's add-ons, filters them to those whose
+ * `addon_service.name` starts with `heroku-redis` (or the caller's
+ * `addonServiceName`), and further narrows by the optional `database`
+ * filter using the same case-insensitive substring match the CLI has
+ * always used.
+ *
+ * Throws `RedisAddonNotFoundError` if no add-ons remain after filtering,
+ * `RedisAddonAmbiguousError` if more than one remains. Both subclass the
+ * generic add-on errors so callers doing `instanceof AddonNotFoundError`
+ * still match.
+ */
+export declare function resolveRedisByApp(ctx: Pick<ResourceCtx, 'platform'>, appIdentity: string, options?: ResolveRedisByAppOptions): Promise<ResolvedAddOn>;

package/dist/resources/data/redis/resolve-by-app.js

@@ -0,0 +1,56 @@
+import createDebug from 'debug';
+import { RedisAddonAmbiguousError, RedisAddonNotFoundError } from './errors.js';
+const debug = createDebug('heroku:sdk:resources:redis');
+const DEFAULT_REDIS_ADDON_SERVICE_PREFIX = 'heroku-redis';
+/**
+ * Resolve a redis add-on attached to `appIdentity`.
+ *
+ * Lists the app's add-ons, filters them to those whose
+ * `addon_service.name` starts with `heroku-redis` (or the caller's
+ * `addonServiceName`), and further narrows by the optional `database`
+ * filter using the same case-insensitive substring match the CLI has
+ * always used.
+ *
+ * Throws `RedisAddonNotFoundError` if no add-ons remain after filtering,
+ * `RedisAddonAmbiguousError` if more than one remains. Both subclass the
+ * generic add-on errors so callers doing `instanceof AddonNotFoundError`
+ * still match.
+ */
+export async function resolveRedisByApp(ctx, appIdentity, options = {}) {
+    options.signal?.throwIfAborted();
+    const { addonServiceName = DEFAULT_REDIS_ADDON_SERVICE_PREFIX, database } = options;
+    const platform = options.signal ? ctx.platform.withOptions({ signal: options.signal }) : ctx.platform;
+    debug('resolveByApp app=%s service-prefix=%s database=%s', appIdentity, addonServiceName, database ?? '<any>');
+    const addons = await platform.addOn.listByApp(appIdentity);
+    const filter = database?.toUpperCase();
+    const matches = addons.filter(addon => {
+        const service = addon.addon_service?.name;
+        if (!service || !service.startsWith(addonServiceName))
+            return false;
+        if (!filter)
+            return true;
+        return matchesDatabaseFilter(addon, filter);
+    });
+    debug('resolveByApp app=%s candidates=%d matches=%d', appIdentity, addons.length, matches.length);
+    if (matches.length === 0) {
+        throw new RedisAddonNotFoundError();
+    }
+    if (matches.length > 1) {
+        throw new RedisAddonAmbiguousError(matches);
+    }
+    const match = matches[0];
+    if (!match.id || !match.app?.id) {
+        throw new Error(`Resolved redis add-on is missing required fields (id=${match.id}, app.id=${match.app?.id})`);
+    }
+    return match;
+}
+function matchesDatabaseFilter(addon, filter) {
+    const configVars = addon.config_vars ?? [];
+    for (const configVar of configVars) {
+        if (configVar.toUpperCase().includes(filter))
+            return true;
+    }
+    if (addon.name && addon.name.toUpperCase().includes(filter))
+        return true;
+    return false;
+}

package/dist/resources/data/redis/wait-for-ready.d.ts

@@ -0,0 +1,32 @@
+import type { RedisWaitResult } from '@heroku/types/data';
+import type { ResourceCtx } from '../../../core/extend-resource.js';
+export type WaitForRedisReadyOptions = {
+    /**
+     * Polling interval in milliseconds. Defaults to 5000 (5s), matching
+     * the CLI's historical `--wait-interval` default.
+     */
+    intervalMs?: number;
+    /**
+     * Aborts the in-flight request and any pending poll delay.
+     */
+    signal?: AbortSignal;
+    /**
+     * Maximum total time to wait before throwing. If omitted, polls until
+     * the database reports ready or `signal` aborts.
+     */
+    timeoutMs?: number;
+};
+/**
+ * Poll `data.redis.wait` until the redis database reports ready
+ * (`waiting?: false`).
+ *
+ * A 404 from the wait endpoint during the initial provisioning window
+ * is treated as "still waiting" — the platform briefly returns 404 for
+ * a database whose row has not yet been created after the addon
+ * provision call resolves.
+ *
+ * Cancellation: the caller's `signal` is threaded into both the
+ * in-flight request (via `withOptions`) and the poll-delay `wait()`,
+ * so aborting takes effect during either phase.
+ */
+export declare function waitForRedisReady(ctx: Pick<ResourceCtx, 'data'>, nameOrId: string, options?: WaitForRedisReadyOptions): Promise<RedisWaitResult>;

package/dist/resources/data/redis/wait-for-ready.js

@@ -0,0 +1,46 @@
+import { NotFoundError } from '@heroku/heroku-fetch';
+import createDebug from 'debug';
+import { wait } from '../../../utils/wait.js';
+const debug = createDebug('heroku:sdk:resources:redis');
+const DEFAULT_INTERVAL_MS = 5000;
+/**
+ * Poll `data.redis.wait` until the redis database reports ready
+ * (`waiting?: false`).
+ *
+ * A 404 from the wait endpoint during the initial provisioning window
+ * is treated as "still waiting" — the platform briefly returns 404 for
+ * a database whose row has not yet been created after the addon
+ * provision call resolves.
+ *
+ * Cancellation: the caller's `signal` is threaded into both the
+ * in-flight request (via `withOptions`) and the poll-delay `wait()`,
+ * so aborting takes effect during either phase.
+ */
+export async function waitForRedisReady(ctx, nameOrId, options = {}) {
+    const { intervalMs = DEFAULT_INTERVAL_MS, signal, timeoutMs } = options;
+    signal?.throwIfAborted();
+    const data = signal ? ctx.data.withOptions({ signal }) : ctx.data;
+    const deadline = timeoutMs === undefined ? undefined : Date.now() + timeoutMs;
+    debug('waitForReady name=%s intervalMs=%d timeoutMs=%s', nameOrId, intervalMs, timeoutMs ?? '<none>');
+    while (true) {
+        signal?.throwIfAborted();
+        let status;
+        try {
+            status = await data.redis.wait(nameOrId);
+        }
+        catch (error) {
+            if (!(error instanceof NotFoundError))
+                throw error;
+            debug('waitForReady name=%s 404 during provisioning window', nameOrId);
+            status = { message: 'not found', 'waiting?': true };
+        }
+        if (!status['waiting?']) {
+            debug('waitForReady name=%s ready', nameOrId);
+            return status;
+        }
+        if (deadline !== undefined && Date.now() >= deadline) {
+            throw new Error(`Redis database '${nameOrId}' did not become ready within ${timeoutMs}ms`);
+        }
+        await wait(intervalMs, signal);
+    }
+}

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

@@ -1,4 +1,5 @@
 export { databaseExtensions } from '../data/database.js';
 export { maintenanceExtensions } from '../data/maintenance.js';
 export { postgresDatabaseExtensions } from '../data/postgres-database.js';
+export { redisExtensions } from '../data/redis/index.js';
 export { transferExtensions } from '../data/transfer.js';

package/dist/resources/extensions/data.js

@@ -1,4 +1,5 @@
 export { databaseExtensions } from '../data/database.js';
 export { maintenanceExtensions } from '../data/maintenance.js';
 export { postgresDatabaseExtensions } from '../data/postgres-database.js';
+export { redisExtensions } from '../data/redis/index.js';
 export { transferExtensions } from '../data/transfer.js';

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

@@ -1,9 +1,13 @@
 export { addOnExtensions } from '../platform/add-on/index.js';
 export { appExtensions, type AppInfo, 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, waitForInfo, type WaitForInfoOptions, } from '../platform/dyno/index.js';
+export { dynoExtensions, DynoNotReadyError, type DynoState, runDyno, type RunDynoOptions, waitForInfo, type WaitForInfoOptions, } 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';
 export { pipelinePromotionExtensions } from '../platform/pipeline/promotion.js';
 export { privateToShield, shieldToPrivate } from '../platform/shield.js';
+export { createAndAssociate, type CreateAndAssociateOptions, sniEndpointExtensions } from '../platform/sni-endpoint/index.js';
+export { telemetryDrainExtensions, type TelemetryDrainOptions, type TelemetryDrainTarget } from '../platform/telemetry-drain/index.js';
+export { testRunExtensions, TestRunNotReadyError, type TestRunStatus, waitForState, type WaitForStateOptions, } from '../platform/test-run/index.js';

package/dist/resources/extensions/platform.js

@@ -1,9 +1,13 @@
 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, waitForInfo, } from '../platform/dyno/index.js';
+export { dynoExtensions, DynoNotReadyError, runDyno, waitForInfo, } 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';
 export { pipelinePromotionExtensions } from '../platform/pipeline/promotion.js';
 export { privateToShield, shieldToPrivate } from '../platform/shield.js';
+export { createAndAssociate, sniEndpointExtensions } from '../platform/sni-endpoint/index.js';
+export { telemetryDrainExtensions } from '../platform/telemetry-drain/index.js';
+export { testRunExtensions, TestRunNotReadyError, waitForState, } from '../platform/test-run/index.js';

package/dist/resources/platform/add-on/destroy-and-wait.d.ts

@@ -0,0 +1,22 @@
+import type { AddOn } from '@heroku/types/3.sdk';
+import type { ResourceCtx } from '../../../core/extend-resource.js';
+import type { DestroyAndWaitOptions } from './types.js';
+/**
+ * Delete an add-on and optionally wait for deprovisioning to complete.
+ *
+ * Wraps `addOn.delete` with two pieces of orchestration:
+ *
+ *   - When `wait: true` is set, polls `addOn.infoByApp` on a
+ *     `waitIntervalMs` cadence until the add-on's `state` is no longer
+ *     `deprovisioning`. A 404 response during polling is treated as
+ *     successful deprovisioning (the platform deletes the record).
+ *   - `options.onDeprovisioning` fires once after the delete response
+ *     when polling is about to begin, letting callers surface a
+ *     two-phase status display.
+ *
+ * When `options.force` is set, the delete request sends `{force: true}`
+ * as its body (scoped to the delete call only, not the poll requests).
+ *
+ * Both the delete and the poll requests send `Accept-Expansion: plan`.
+ */
+export declare function destroyAndWait(ctx: Pick<ResourceCtx, 'platform'>, appIdentity: string, addonIdentity: string, options?: DestroyAndWaitOptions): Promise<AddOn>;

package/dist/resources/platform/add-on/destroy-and-wait.js

@@ -0,0 +1,62 @@
+import { wait } from '../../../utils/wait.js';
+import { AddonProvisioningFailedError } from './errors.js';
+const DEFAULT_DESTROY_WAIT_INTERVAL_MS = 5000;
+/**
+ * Delete an add-on and optionally wait for deprovisioning to complete.
+ *
+ * Wraps `addOn.delete` with two pieces of orchestration:
+ *
+ *   - When `wait: true` is set, polls `addOn.infoByApp` on a
+ *     `waitIntervalMs` cadence until the add-on's `state` is no longer
+ *     `deprovisioning`. A 404 response during polling is treated as
+ *     successful deprovisioning (the platform deletes the record).
+ *   - `options.onDeprovisioning` fires once after the delete response
+ *     when polling is about to begin, letting callers surface a
+ *     two-phase status display.
+ *
+ * When `options.force` is set, the delete request sends `{force: true}`
+ * as its body (scoped to the delete call only, not the poll requests).
+ *
+ * Both the delete and the poll requests send `Accept-Expansion: plan`.
+ */
+export async function destroyAndWait(ctx, appIdentity, addonIdentity, options = {}) {
+    options.signal?.throwIfAborted();
+    const platform = ctx.platform
+        .withHeaders({ 'Accept-Expansion': 'plan' })
+        .withOptions({ signal: options.signal });
+    // The force body is scoped to the delete call only — a sticky body on the
+    // shared client would leak onto the GET poll requests below.
+    const deleteClient = options.force
+        ? platform.withOptions({ body: { force: true } })
+        : platform;
+    const deleted = await deleteClient.addOn.delete(appIdentity, addonIdentity);
+    let addon = deleted ?? {};
+    if (!options.wait || (addon.state !== 'deprovisioning' && addon.state !== 'provisioning')) {
+        return addon;
+    }
+    await options.onDeprovisioning?.(addon);
+    const intervalMs = options.waitIntervalMs ?? DEFAULT_DESTROY_WAIT_INTERVAL_MS;
+    /* eslint-disable no-await-in-loop */
+    while (addon.state === 'deprovisioning' || addon.state === 'provisioning') {
+        options.signal?.throwIfAborted();
+        await wait(intervalMs, options.signal);
+        addon = await platform.addOn.infoByApp(appIdentity, addonIdentity).catch((error) => {
+            // Platform deletes the record on successful deprovisioning — a 404 is success.
+            if (isNotFound(error)) {
+                return { ...addon, state: 'deprovisioned' };
+            }
+            throw error;
+        });
+    }
+    /* eslint-enable no-await-in-loop */
+    if (addon.state !== 'deprovisioned') {
+        throw new AddonProvisioningFailedError(addon);
+    }
+    return addon;
+}
+function isNotFound(error) {
+    return (typeof error === 'object'
+        && error !== null
+        && 'statusCode' in error
+        && error.statusCode === 404);
+}

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

@@ -1,23 +1,27 @@
-import type { AddOnCreateOpts } from '@heroku/types/3.sdk';
+import type { AddOn, AddOnCreateOpts } from '@heroku/types/3.sdk';
 import type { ListPlansForAddonOptions } from './list-plans.js';
-import type { AddOnOptions, CreateAndWaitOptions, ResolveAddonOptions, UpgradeAddOnOptions } from './types.js';
+import type { AddOnOptions, CreateAndWaitOptions, DestroyAndWaitOptions, ResolveAddonOptions, UpgradeAddOnOptions, WaitForProvisioningOptions } from './types.js';
 import { formatPlanPriceLabel, priceForPlan } from './pricing.js';
 export { createAndWait } from './create-and-wait.js';
 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, ResolveAddonOptions, ResolvedAddOn, UpgradeAddOnOptions, } from './types.js';
+export type { AddOnOptions, CreateAndWaitOptions, DescribedAddOn, DestroyAndWaitOptions, ResolveAddonOptions, ResolvedAddOn, 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<import("@heroku/types/3.sdk").AddOn>;
+    createAndWait: (appIdentity: string, body: AddOnCreateOpts, options?: CreateAndWaitOptions) => Promise<AddOn>;
     describe: (addonIdentity: string, options?: ResolveAddonOptions) => Promise<import("./types.js").DescribedAddOn>;
+    destroyAndWait: (appIdentity: string, addonIdentity: string, options?: DestroyAndWaitOptions) => Promise<AddOn>;
     formatPlanPriceLabel: typeof formatPlanPriceLabel;
     listPlans: (serviceIdentity: string, options?: AddOnOptions) => Promise<import("@heroku/types/3.sdk").Plan[]>;
     listPlansForAddon: (addonIdentity: string, options?: ListPlansForAddonOptions) => Promise<import("@heroku/types/3.sdk").Plan[]>;
     priceForPlan: typeof priceForPlan;
     resolve: (addonIdentity: string, options?: ResolveAddonOptions) => Promise<import("./types.js").ResolvedAddOn>;
     resolveByAttachment: (appIdentity: string, attachmentName: string, options?: AddOnOptions) => Promise<import("./types.js").ResolvedAddOn>;
-    upgrade: (addonIdentity: string, plan: string, options?: UpgradeAddOnOptions) => Promise<import("@heroku/types/3.sdk").AddOn>;
+    upgrade: (addonIdentity: string, plan: string, options?: UpgradeAddOnOptions) => Promise<AddOn>;
+    waitForProvisioning: (addon: AddOn, options?: WaitForProvisioningOptions) => Promise<AddOn>;
 }>;

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

@@ -1,20 +1,25 @@
 import { extendResource } from '../../../core/extend-resource.js';
 import { createAndWait } from './create-and-wait.js';
 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 { upgrade } from './upgrade.js';
+import { waitForProvisioning } from './wait-for-provisioning.js';
 export { createAndWait } from './create-and-wait.js';
 export { describeAddon } from './describe.js';
+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 { 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),
+    destroyAndWait: (appIdentity, addonIdentity, options) => destroyAndWait(ctx, appIdentity, addonIdentity, options),
     formatPlanPriceLabel,
     listPlans: (serviceIdentity, options) => listPlans(ctx, serviceIdentity, options),
     listPlansForAddon: (addonIdentity, options) => listPlansForAddon(ctx, addonIdentity, options),
@@ -22,4 +27,5 @@ export const addOnExtensions = extendResource('platform', 'addOn', ctx => ({
     resolve: (addonIdentity, options) => resolveAddon(ctx, addonIdentity, options),
     resolveByAttachment: (appIdentity, attachmentName, options) => resolveAddonByAttachment(ctx, appIdentity, attachmentName, options),
     upgrade: (addonIdentity, plan, options) => upgrade(ctx, addonIdentity, plan, options),
+    waitForProvisioning: (addon, options) => waitForProvisioning(ctx, addon, options),
 }));

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

@@ -24,6 +24,41 @@ export type DescribedAddOn = ResolvedAddOn & {
 export type UpgradeAddOnOptions = ResolveAddonOptions & {
     onResolved?: (addon: ResolvedAddOn) => Promise<void> | void;
 };
+export type DestroyAndWaitOptions = {
+    /**
+     * When true, sends `{force: true}` as the delete body — allows
+     * destruction even if the add-on is attached to other apps. Mirrors
+     * the CLI's `--force` flag. Defaults to false.
+     */
+    force?: boolean;
+    /**
+     * Fires once after the initial delete returns and the add-on is still
+     * deprovisioning, before the first poll. Useful for two-phase UX:
+     * e.g. "Destroying…" followed by "Waiting for deprovisioning…".
+     *
+     * Only invoked when `wait: true` and the delete response state is
+     * `deprovisioning`.
+     */
+    onDeprovisioning?: (addon: AddOn) => Promise<void> | void;
+    /**
+     * If true, poll until the add-on leaves `deprovisioning`. If the
+     * terminal state is not `deprovisioned`, throws `AddonProvisioningFailedError`.
+     *
+     * If false (the default), returns immediately after the delete call.
+     */
+    wait?: boolean;
+    /** Polling interval in milliseconds. Defaults to 5000. */
+    waitIntervalMs?: number;
+} & AddOnOptions;
+export type WaitForProvisioningOptions = AddOnOptions & {
+    /**
+     * When provided, polls `GET /apps/:app/addons/:addon` (app-scoped).
+     * Without it, polls `GET /addons/:addon` (global).
+     */
+    appIdentity?: string;
+    /** Polling interval in milliseconds. Defaults to 5000. */
+    waitIntervalMs?: number;
+};
 export type CreateAndWaitOptions = {
     /**
      * Fires once after the initial create returns and the add-on is

package/dist/resources/platform/add-on/wait-for-provisioning.d.ts

@@ -0,0 +1,19 @@
+import type { AddOn } from '@heroku/types/3.sdk';
+import type { ResourceCtx } from '../../../core/extend-resource.js';
+import type { WaitForProvisioningOptions } from './types.js';
+/**
+ * Poll add-on state until it leaves a non-terminal state.
+ *
+ * When `appIdentity` is provided, polls `GET /apps/:app/addons/:addon`
+ * (app-scoped). Without it, polls `GET /addons/:addon` (global).
+ *
+ * Terminal states: `provisioned`, `deprovisioned`. Polling continues
+ * while the add-on is in `provisioning` or `deprovisioning`.
+ *
+ * Throws `AddonProvisioningFailedError` if the terminal state is
+ * `deprovisioned`.
+ *
+ * The `Accept-Expansion: addon_service,plan` header is included on
+ * each poll to match the existing CLI behaviour.
+ */
+export declare function waitForProvisioning(ctx: Pick<ResourceCtx, 'platform'>, addon: AddOn, options?: WaitForProvisioningOptions): Promise<AddOn>;

package/dist/resources/platform/add-on/wait-for-provisioning.js

@@ -0,0 +1,37 @@
+import { wait } from '../../../utils/wait.js';
+import { AddonProvisioningFailedError } from './errors.js';
+const DEFAULT_WAIT_INTERVAL_MS = 5000;
+/**
+ * Poll add-on state until it leaves a non-terminal state.
+ *
+ * When `appIdentity` is provided, polls `GET /apps/:app/addons/:addon`
+ * (app-scoped). Without it, polls `GET /addons/:addon` (global).
+ *
+ * Terminal states: `provisioned`, `deprovisioned`. Polling continues
+ * while the add-on is in `provisioning` or `deprovisioning`.
+ *
+ * Throws `AddonProvisioningFailedError` if the terminal state is
+ * `deprovisioned`.
+ *
+ * The `Accept-Expansion: addon_service,plan` header is included on
+ * each poll to match the existing CLI behaviour.
+ */
+export async function waitForProvisioning(ctx, addon, options = {}) {
+    options.signal?.throwIfAborted();
+    const intervalMs = options.waitIntervalMs ?? DEFAULT_WAIT_INTERVAL_MS;
+    const platform = ctx.platform.withHeaders({ 'Accept-Expansion': 'addon_service,plan' });
+    let current = addon;
+    /* eslint-disable no-await-in-loop */
+    while (current.state === 'provisioning' || current.state === 'deprovisioning') {
+        options.signal?.throwIfAborted();
+        await wait(intervalMs, options.signal);
+        current = options.appIdentity
+            ? await platform.addOn.infoByApp(options.appIdentity, current.name)
+            : await platform.addOn.info(current.name);
+    }
+    /* eslint-enable no-await-in-loop */
+    if (current.state === 'deprovisioned') {
+        throw new AddonProvisioningFailedError(current);
+    }
+    return current;
+}

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

@@ -1,7 +1,9 @@
 import type { App } from '@heroku/types/3.sdk';
 import type { ResourceCtx } from '../../../core/extend-resource.js';
 import type { DescribeAppOptions } from './info.js';
+import type { WaitForACMCertificatesOptions } from './wait-for-acm-certificates.js';
 export { type AppInfo, describeApp, type DescribeAppOptions, type PipelineCouplingDetail, } from './info.js';
+export { waitForACMCertificates, type WaitForACMCertificatesOptions } from './wait-for-acm-certificates.js';
 export type AppMaintenanceOptions = {
     signal?: AbortSignal;
 };
@@ -55,4 +57,5 @@ export declare const appExtensions: import("../../../core/extend-resource.js").R
     getGeneration: (appIdentity: string, options?: GetGenerationOptions) => Promise<GenerationKind | undefined>;
     getProcessTier: (appIdentity: string, options?: GetProcessTierOptions) => Promise<ProcessTier | undefined>;
     isShielded: (appIdentity: string, options?: IsShieldedOptions) => Promise<boolean>;
+    waitForACMCertificates: (appIdentity: string, options?: WaitForACMCertificatesOptions) => Promise<import("@heroku/types/3.sdk").Domain[]>;
 }>;

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

@@ -1,6 +1,8 @@
 import { extendResource } from '../../../core/extend-resource.js';
 import { describeApp } from './info.js';
+import { waitForACMCertificates } from './wait-for-acm-certificates.js';
 export { describeApp, } from './info.js';
+export { waitForACMCertificates } from './wait-for-acm-certificates.js';
 export async function enableMaintenance(ctx, appIdentity, options = {}) {
     options.signal?.throwIfAborted();
     return ctx.platform.app.update(appIdentity, { maintenance: true });
@@ -50,4 +52,5 @@ export const appExtensions = extendResource('platform', 'app', ctx => ({
     getGeneration: (appIdentity, options) => getGeneration(ctx, appIdentity, options),
     getProcessTier: (appIdentity, options) => getProcessTier(ctx, appIdentity, options),
     isShielded: (appIdentity, options) => isShielded(ctx, appIdentity, options),
+    waitForACMCertificates: (appIdentity, options) => waitForACMCertificates(ctx, appIdentity, options),
 }));

package/dist/resources/platform/app/wait-for-acm-certificates.d.ts

@@ -0,0 +1,34 @@
+import type { Domain } from '@heroku/types/3.sdk';
+import type { ResourceCtx } from '../../../core/extend-resource.js';
+export type WaitForACMCertificatesOptions = {
+    /**
+     * Base polling interval in milliseconds. Defaults to 15000 (the
+     * CLI's 15s base). The effective delay grows with the CLI's backoff
+     * formula, scaled off this value.
+     */
+    intervalMs?: number;
+    /**
+     * Abort signal to cancel the operation.
+     */
+    signal?: AbortSignal;
+    /**
+     * Maximum time in milliseconds to wait before giving up.
+     * If undefined, waits indefinitely (preserving the CLI's
+     * poll-forever behavior) until the signal aborts.
+     */
+    timeoutMs?: number;
+};
+/**
+ * Waits for ACM (Automated Certificate Management) certificates to be
+ * issued on all custom domains of an app.
+ *
+ * Polls the app's domains until every `custom` domain reaches a
+ * terminal `acm_status` of `'cert issued'` or `'failed'`, then returns
+ * the custom domains. `heroku` domains are ignored and never block
+ * termination.
+ *
+ * @throws if any custom domain finishes with `acm_status: 'failed'`
+ * (`'ACM not enabled for some domains'`), or if `timeoutMs` elapses
+ * before all custom domains reach a terminal status.
+ */
+export declare function waitForACMCertificates(ctx: Pick<ResourceCtx, 'platform'>, appIdentity: string, options?: WaitForACMCertificatesOptions): Promise<Domain[]>;