@heroku/sdk 0.5.4 → 0.5.5

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/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/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/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.5",
   "description": "Heroku SDK",
   "author": "Heroku",
   "type": "module",