@heroku/sdk 0.3.0-beta.0 → 0.4.0-beta.0

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

@@ -1,6 +1,6 @@
 export { addOnExtensions } from '../platform/add-on/index.js';
 export { appExtensions, type AppInfo, type PipelineCouplingDetail } from '../platform/app/index.js';
-export { dynoExtensions } from '../platform/dyno/index.js';
+export { dynoExtensions, DynoNotReadyError, type DynoState, 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';

package/dist/resources/extensions/platform.js

@@ -1,6 +1,6 @@
 export { addOnExtensions } from '../platform/add-on/index.js';
 export { appExtensions } from '../platform/app/index.js';
-export { dynoExtensions } from '../platform/dyno/index.js';
+export { dynoExtensions, DynoNotReadyError, 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';

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

@@ -1,6 +1,8 @@
 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 WaitForInfoOptions } from './wait-for-info.js';
+export { DynoNotReadyError, type DynoState, waitForInfo, type WaitForInfoOptions, } from './wait-for-info.js';
 export type DynoOptions = {
     signal?: AbortSignal;
 };
@@ -41,5 +43,5 @@ export declare const dynoExtensions: import("../../../core/extend-resource.js").
         (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>;
 }>;
-export {};

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

@@ -1,4 +1,6 @@
 import { extendResource } from '../../../core/extend-resource.js';
+import { waitForInfo } from './wait-for-info.js';
+export { DynoNotReadyError, waitForInfo, } from './wait-for-info.js';
 export async function scaleDynos(ctx, appIdentity, updates, options = {}) {
     options.signal?.throwIfAborted();
     const platform = options.signal ? ctx.platform.withOptions({ signal: options.signal }) : ctx.platform;
@@ -23,4 +25,5 @@ export async function restartDynos(ctx, appIdentity, target, options = {}) {
 export const dynoExtensions = extendResource('platform', 'dyno', ctx => ({
     restart: (appIdentity, target, options) => (restartDynos(ctx, appIdentity, target, options)),
     scale: ((appIdentity, updates, options) => scaleDynos(ctx, appIdentity, updates, options)),
+    waitForInfo: (appIdentity, dynoIdentity, options) => (waitForInfo(ctx, appIdentity, dynoIdentity, options)),
 }));

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

@@ -0,0 +1,95 @@
+import type { Dyno } from '@heroku/types/3.sdk';
+import type { ResourceCtx } from '../../../core/extend-resource.js';
+/**
+ * Documented dyno states from the Platform API:
+ * https://devcenter.heroku.com/articles/platform-api-reference#dyno
+ *
+ * Recommended for autocomplete in {@link WaitForInfoOptions.states},
+ * which accepts any string at runtime — the platform does not commit
+ * to a closed set, so the comparison is plain string equality.
+ */
+export type DynoState = 'crashed' | 'down' | 'idle' | 'starting' | 'up';
+/**
+ * Thrown by {@link waitForInfo} when `states` was set, the dyno was
+ * reachable, but its `state` never matched within the configured
+ * number of attempts. Carries the last observed dyno so callers can
+ * branch on its state (e.g. distinguish a `crashed` dyno from one
+ * stuck in `starting`).
+ */
+export declare class DynoNotReadyError extends Error {
+    readonly dyno: Dyno;
+    readonly expectedStates: ReadonlyArray<string>;
+    readonly attempts: number;
+    readonly id = "dyno_not_ready";
+    constructor(dyno: Dyno, expectedStates: ReadonlyArray<string>, attempts: number);
+}
+export type WaitForInfoOptions = {
+    /**
+     * Maximum total number of `dyno.info` calls before giving up.
+     * Defaults to 20. Each attempt is one info call; the delay
+     * between attempts is {@link WaitForInfoOptions.delayMs}.
+     */
+    attempts?: number;
+    /**
+     * Delay between attempts in milliseconds. Defaults to 1000.
+     * On a 429 response, the platform's `Retry-After` header takes
+     * precedence over this value for the next wait.
+     */
+    delayMs?: number;
+    /**
+     * Fires after every successful `dyno.info` call, including ones
+     * whose `state` does not yet match {@link WaitForInfoOptions.states}
+     * and trigger another retry, AND for the final matching dyno
+     * before it is returned. Use this to surface live state
+     * transitions in a UI (e.g. a CLI spinner that updates
+     * `starting → up`). Not called when an attempt errors (404, 429,
+     * 503). Exceptions thrown from this callback propagate and end
+     * the wait — there is no implicit catch.
+     */
+    onPoll?: (dyno: Dyno) => void;
+    signal?: AbortSignal;
+    /**
+     * If set, only return when the dyno's `state` is one of these.
+     * If omitted, the call returns on the first 2xx response
+     * regardless of state — useful for racing past the post-creation
+     * 404 window without waiting for the dyno to be runnable. The
+     * recommended values are documented as {@link DynoState}; any
+     * string is accepted.
+     */
+    states?: ReadonlyArray<DynoState | string>;
+};
+/**
+ * Poll `dyno.info` until the dyno exists and (optionally) reaches a
+ * caller-specified state. Absorbs two distinct races:
+ *
+ *   - **Post-creation 404.** The platform briefly returns 404 for a
+ *     newly-provisioning dyno even after `dyno.create` resolves
+ *     (also observable from log events emitting "Starting process"
+ *     before the dyno row is queryable). Callers that just need the
+ *     row to exist should omit `states` and accept the first 2xx —
+ *     the dyno's `state` value does not gate the return.
+ *   - **Wait for runnable.** Callers that need to act on the dyno
+ *     (open an SSH connection, exec a one-off command) need it in
+ *     `starting` or `up` first. Pass `{states: ['starting', 'up']}`
+ *     and the helper polls until the dyno reports one of those
+ *     states.
+ *
+ * Retry policy: 404, 429, and 503 are treated as transient and
+ * trigger another attempt. 429 responses honor `Retry-After` for
+ * the next wait. Any other error throws immediately.
+ *
+ * After {@link WaitForInfoOptions.attempts} attempts:
+ *   - If state-filtered, throws {@link DynoNotReadyError} carrying
+ *     the last observed dyno.
+ *   - Otherwise rethrows the last transient error.
+ *
+ * @example
+ * ```ts
+ * // Race past the post-creation 404; return on first 2xx regardless of state.
+ * await platform.dyno.waitForInfo(app, name)
+ *
+ * // Wait for the dyno to be ready to accept connections.
+ * await platform.dyno.waitForInfo(app, name, {states: ['starting', 'up']})
+ * ```
+ */
+export declare function waitForInfo(ctx: Pick<ResourceCtx, 'platform'>, appIdentity: string, dynoIdentity: string, options?: WaitForInfoOptions): Promise<Dyno>;

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

@@ -0,0 +1,108 @@
+import { HerokuApiError, NotFoundError, RateLimitError } from '@heroku/heroku-fetch';
+import { wait } from '../../../utils/wait.js';
+const DEFAULT_ATTEMPTS = 20;
+const DEFAULT_DELAY_MS = 1000;
+/**
+ * Thrown by {@link waitForInfo} when `states` was set, the dyno was
+ * reachable, but its `state` never matched within the configured
+ * number of attempts. Carries the last observed dyno so callers can
+ * branch on its state (e.g. distinguish a `crashed` dyno from one
+ * stuck in `starting`).
+ */
+export class DynoNotReadyError extends Error {
+    dyno;
+    expectedStates;
+    attempts;
+    id = 'dyno_not_ready';
+    constructor(dyno, expectedStates, attempts) {
+        super(`Dyno '${dyno.name}' did not reach state ${expectedStates.join('/')} `
+            + `within ${attempts} attempts (last state: ${dyno.state}).`);
+        this.dyno = dyno;
+        this.expectedStates = expectedStates;
+        this.attempts = attempts;
+        this.name = 'DynoNotReadyError';
+    }
+}
+/**
+ * Poll `dyno.info` until the dyno exists and (optionally) reaches a
+ * caller-specified state. Absorbs two distinct races:
+ *
+ *   - **Post-creation 404.** The platform briefly returns 404 for a
+ *     newly-provisioning dyno even after `dyno.create` resolves
+ *     (also observable from log events emitting "Starting process"
+ *     before the dyno row is queryable). Callers that just need the
+ *     row to exist should omit `states` and accept the first 2xx —
+ *     the dyno's `state` value does not gate the return.
+ *   - **Wait for runnable.** Callers that need to act on the dyno
+ *     (open an SSH connection, exec a one-off command) need it in
+ *     `starting` or `up` first. Pass `{states: ['starting', 'up']}`
+ *     and the helper polls until the dyno reports one of those
+ *     states.
+ *
+ * Retry policy: 404, 429, and 503 are treated as transient and
+ * trigger another attempt. 429 responses honor `Retry-After` for
+ * the next wait. Any other error throws immediately.
+ *
+ * After {@link WaitForInfoOptions.attempts} attempts:
+ *   - If state-filtered, throws {@link DynoNotReadyError} carrying
+ *     the last observed dyno.
+ *   - Otherwise rethrows the last transient error.
+ *
+ * @example
+ * ```ts
+ * // Race past the post-creation 404; return on first 2xx regardless of state.
+ * await platform.dyno.waitForInfo(app, name)
+ *
+ * // Wait for the dyno to be ready to accept connections.
+ * await platform.dyno.waitForInfo(app, name, {states: ['starting', 'up']})
+ * ```
+ */
+export async function waitForInfo(ctx, appIdentity, dynoIdentity, options = {}) {
+    const { attempts = DEFAULT_ATTEMPTS, delayMs = DEFAULT_DELAY_MS, onPoll, signal, states, } = options;
+    signal?.throwIfAborted();
+    // Scope the in-flight info call to the caller's signal so an abort
+    // takes effect during the API call, not just during the backoff.
+    const platform = signal ? ctx.platform.withOptions({ signal }) : ctx.platform;
+    let lastError;
+    let lastDyno;
+    for (let attempt = 0; attempt < attempts; attempt++) {
+        let nextDelayMs = delayMs;
+        try {
+            const dyno = await platform.dyno.info(appIdentity, dynoIdentity);
+            onPoll?.(dyno);
+            if (!states || states.includes(dyno.state)) {
+                return dyno;
+            }
+            lastDyno = dyno;
+        }
+        catch (error) {
+            if (!isTransient(error))
+                throw error;
+            lastError = error;
+            if (error instanceof RateLimitError && typeof error.retryAfter === 'number') {
+                nextDelayMs = Math.max(delayMs, error.retryAfter * 1000);
+            }
+        }
+        if (attempt < attempts - 1) {
+            await wait(nextDelayMs, signal);
+        }
+    }
+    if (states && lastDyno) {
+        throw new DynoNotReadyError(lastDyno, states, attempts);
+    }
+    throw lastError ?? new Error(`Dyno '${dynoIdentity}' on app '${appIdentity}' was not available within ${attempts} attempts.`);
+}
+/**
+ * Errors the platform commonly returns transiently during a dyno's
+ * provisioning window. Anything else propagates so callers see real
+ * failures (auth, app-not-found-permanently, 5xx that aren't 503).
+ */
+function isTransient(error) {
+    if (error instanceof NotFoundError)
+        return true;
+    if (error instanceof RateLimitError)
+        return true;
+    if (error instanceof HerokuApiError && error.statusCode === 503)
+        return true;
+    return false;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heroku/sdk",
-  "version": "0.3.0-beta.0",
+  "version": "0.4.0-beta.0",
   "description": "Heroku SDK",
   "author": "Heroku",
   "type": "module",
@@ -26,6 +26,30 @@
       "types": "./dist/resources/extensions/data.d.ts",
       "default": "./dist/resources/extensions/data.js"
     },
+    "./resources/platform/add-on": {
+      "types": "./dist/resources/platform/add-on/index.d.ts",
+      "default": "./dist/resources/platform/add-on/index.js"
+    },
+    "./resources/platform/app": {
+      "types": "./dist/resources/platform/app/index.d.ts",
+      "default": "./dist/resources/platform/app/index.js"
+    },
+    "./resources/platform/dyno": {
+      "types": "./dist/resources/platform/dyno/index.d.ts",
+      "default": "./dist/resources/platform/dyno/index.js"
+    },
+    "./resources/platform/log-session": {
+      "types": "./dist/resources/platform/log-session/index.d.ts",
+      "default": "./dist/resources/platform/log-session/index.js"
+    },
+    "./resources/platform/pipeline": {
+      "types": "./dist/resources/platform/pipeline/index.d.ts",
+      "default": "./dist/resources/platform/pipeline/index.js"
+    },
+    "./resources/platform/pipeline/*": {
+      "types": "./dist/resources/platform/pipeline/*.d.ts",
+      "default": "./dist/resources/platform/pipeline/*.js"
+    },
     "./resources/*": {
       "types": "./dist/resources/*.d.ts",
       "default": "./dist/resources/*.js"
@@ -42,6 +66,7 @@
     "example": "tsx",
     "lint": "eslint",
     "lint:fix": "eslint --fix",
+    "prebuild": "rimraf dist",
     "prepare": "npm run build",
     "test": "vitest --run"
   },
@@ -60,6 +85,7 @@
     "eslint": "^9.39.4",
     "eslint-config-oclif": "^6.0.167",
     "eslint-plugin-vitest": "0.5.4",
+    "rimraf": "^6.1.3",
     "tsx": "^4.22.4",
     "typescript": "^6.0.2",
     "vitest": "^4.1.4"