@heroku/sdk 0.12.3 → 0.12.4

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

@@ -0,0 +1,313 @@
+import { NotFoundError } from '@heroku/heroku-fetch';
+import { extendResource } from '../../core/extend-resource.js';
+import { withSignal } from '../../core/with-signal.js';
+import { isAdvancedDatabase, isEssentialDatabase, isLegacyDatabase, isPostgresAddon, } from './internal/postgres-utils.js';
+/**
+ * Thrown by `create` when the migration inputs are invalid before any request
+ * fires. Carries a machine `reason` so callers can branch without string
+ * matching.
+ */
+export class MigrationInvalidError extends Error {
+    reason;
+    id = 'migration_invalid';
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+        this.name = 'MigrationInvalidError';
+    }
+    get body() {
+        return { id: this.id, message: this.message, reason: this.reason };
+    }
+}
+/**
+ * Thrown by `run` when the migration isn't in a startable state. Carries the
+ * migration (and thus its `status`) so callers can report the drift without
+ * re-fetching.
+ */
+export class MigrationNotRunnableError extends Error {
+    migration;
+    id = 'migration_not_runnable';
+    constructor(migration) {
+        super(`Migration ${migration.id} can't be started from status '${migration.status}'. Only migrations in the 'ready' status can be started.`);
+        this.migration = migration;
+        this.name = 'MigrationNotRunnableError';
+    }
+    get body() {
+        return { id: this.id, message: this.message, status: this.migrationStatus };
+    }
+    /**
+     * The migration's status. Named `migrationStatus` (not `status`) to avoid
+     * shadowing the HTTP-status convention other `Error` subclasses in the SDK
+     * carry.
+     */
+    get migrationStatus() {
+        return this.migration.status;
+    }
+}
+/**
+ * Thrown by `cancel` when the migration isn't in a cancellable state. Carries
+ * the migration (and thus its `status`).
+ */
+export class MigrationNotCancellableError extends Error {
+    migration;
+    id = 'migration_not_cancellable';
+    constructor(migration) {
+        super(`Migration ${migration.id} can't be canceled from status '${migration.status}'. Only migrations in the 'ready' status can be canceled.`);
+        this.migration = migration;
+        this.name = 'MigrationNotCancellableError';
+    }
+    get body() {
+        return { id: this.id, message: this.message, status: this.migrationStatus };
+    }
+    /**
+     * The migration's status. Named `migrationStatus` (not `status`) to avoid
+     * shadowing the HTTP-status convention other `Error` subclasses in the SDK
+     * carry.
+     */
+    get migrationStatus() {
+        return this.migration.status;
+    }
+}
+/**
+ * Compile-time exhaustiveness guard with a safe runtime fallback. A newly
+ * generated `MigrationStatus` that isn't handled above is a type error here
+ * (the `never` parameter), but if one reaches this at runtime — e.g. the API
+ * returns a status the type doesn't yet know about — we return `fallback`
+ * rather than throwing, so `run`/`cancel` fail closed (treat it as not
+ * runnable/cancellable) instead of crashing.
+ */
+function exhaustiveFallback(_status, fallback) {
+    return fallback;
+}
+/**
+ * Whether a migration can be started. Only `ready` migrations are runnable,
+ * matching the CLI's menu gate. The exhaustive `switch` makes a newly
+ * generated status a compile error until its policy is decided here, rather
+ * than silently defaulting to runnable or not.
+ */
+export function isRunnable(status) {
+    switch (status) {
+        case 'cancelled':
+        case 'completed':
+        case 'creating_target':
+        case 'failed':
+        case 'migrating':
+        case 'preparing':
+        case 'promoting':
+        case 'unknown': {
+            return false;
+        }
+        case 'ready': {
+            return true;
+        }
+        default: {
+            return exhaustiveFallback(status, false);
+        }
+    }
+}
+/**
+ * Whether a migration can be canceled. Only `ready` migrations are
+ * cancellable, matching the CLI's menu gate. Exhaustive for the same reason as
+ * {@link isRunnable}.
+ */
+export function isCancellable(status) {
+    switch (status) {
+        case 'cancelled':
+        case 'completed':
+        case 'creating_target':
+        case 'failed':
+        case 'migrating':
+        case 'preparing':
+        case 'promoting':
+        case 'unknown': {
+            return false;
+        }
+        case 'ready': {
+            return true;
+        }
+        default: {
+            return exhaustiveFallback(status, false);
+        }
+    }
+}
+/**
+ * Fetches the migration currently targeting `targetAddonId`.
+ *
+ * The data API's migration endpoint is a single-object `GET` (not a list);
+ * when no migration exists it 404s, which this surfaces as `undefined` rather
+ * than throwing, so callers can treat "no migration" as a normal state.
+ */
+export async function info(ctx, targetAddonId, options = {}) {
+    const { signal } = options;
+    signal?.throwIfAborted();
+    try {
+        return await withSignal(ctx.data, signal).postgresMigration.info(targetAddonId);
+    }
+    catch (error) {
+        if (error instanceof NotFoundError)
+            return undefined;
+        throw error;
+    }
+}
+/**
+ * Configures a new migration *to* `targetAddonId` *from* the database named in
+ * `body.source_id`.
+ *
+ * The URL identifies the **target**; the body's `source_id` identifies the
+ * **source** — both are add-on ids, so the two are easy to swap. A
+ * client-side guard rejects a source that equals the target before any request
+ * fires.
+ */
+export async function create(ctx, targetAddonId, body, options = {}) {
+    const { signal } = options;
+    signal?.throwIfAborted();
+    if (body.source_id === targetAddonId) {
+        throw new MigrationInvalidError('source_equals_target', `A migration's source and target must differ, but both are '${targetAddonId}'.`);
+    }
+    return withSignal(ctx.data, signal).postgresMigration.create(targetAddonId, body);
+}
+/**
+ * Best-effort re-fetch of a migration after a successful `run`/`cancel` POST so
+ * the returned status reflects the transition the action kicked off.
+ *
+ * The POST already succeeded by the time this runs, so the re-fetch must never
+ * turn a completed action into a thrown error: the caller's `signal` is
+ * deliberately *not* threaded in (a post-POST abort shouldn't surface as a
+ * failure of an action that already happened), and any re-fetch error is
+ * swallowed. When the migration can't be re-read — it 404s (already gone) or
+ * the re-fetch fails for any other reason — we fall back to the gated record
+ * with its status forced to `'unknown'` rather than returning the stale
+ * `'ready'` the gate observed, which would wrongly imply the action never ran.
+ */
+async function refetchAfterAction(ctx, targetAddonId, gated) {
+    try {
+        const refreshed = await info(ctx, targetAddonId);
+        return refreshed ?? { ...gated, status: 'unknown' };
+    }
+    catch {
+        return { ...gated, status: 'unknown' };
+    }
+}
+/**
+ * Starts the migration targeting `targetAddonId`.
+ *
+ * Fetches the migration first and gates on its status — a defensive backstop
+ * against state drift between listing and action: throws
+ * `MigrationNotRunnableError` (carrying the migration) if it's no longer
+ * `ready`, and lets a `NotFoundError` propagate if the migration is already
+ * gone. Once the run POST succeeds, returns the migration's post-action state
+ * via a best-effort re-fetch (see {@link refetchAfterAction}); never throws
+ * after the action has fired.
+ */
+export async function run(ctx, targetAddonId, options = {}) {
+    const { signal } = options;
+    signal?.throwIfAborted();
+    const data = withSignal(ctx.data, signal);
+    const migration = await data.postgresMigration.info(targetAddonId);
+    if (!isRunnable(migration.status)) {
+        throw new MigrationNotRunnableError(migration);
+    }
+    signal?.throwIfAborted();
+    await data.postgresMigration.run(targetAddonId);
+    return refetchAfterAction(ctx, targetAddonId, migration);
+}
+/**
+ * Cancels the migration targeting `targetAddonId`.
+ *
+ * Gates on status like {@link run}: throws `MigrationNotCancellableError`
+ * (carrying the migration) if it's not `ready`, and lets a `NotFoundError`
+ * propagate if the migration is already gone. Once the cancel POST succeeds,
+ * returns the migration's post-action state via a best-effort re-fetch (see
+ * {@link refetchAfterAction}); never throws after the action has fired.
+ */
+export async function cancel(ctx, targetAddonId, options = {}) {
+    const { signal } = options;
+    signal?.throwIfAborted();
+    const data = withSignal(ctx.data, signal);
+    const migration = await data.postgresMigration.info(targetAddonId);
+    if (!isCancellable(migration.status)) {
+        throw new MigrationNotCancellableError(migration);
+    }
+    signal?.throwIfAborted();
+    await data.postgresMigration.cancel(targetAddonId);
+    return refetchAfterAction(ctx, targetAddonId, migration);
+}
+/**
+ * Lists everything the migration UI needs for an app in one pass: the classic
+ * databases that can be sources, the Advanced databases that can be targets
+ * (each with its `info` and any migration targeting it), and the flat list of
+ * configured migrations.
+ *
+ * Replaces the CLI's `getAppDatabases` + `getMigrationTargetsAndInfo`: resolves
+ * the app's add-on attachments (with `addon:plan,config_vars` inclusions so
+ * plans are present for tier classification), keeps only Postgres databases
+ * the app owns, dedupes to unique add-ons with their attachment names, then
+ * fans out `/migrations` and `/info` per Advanced database. A per-database 404
+ * is tolerated (that database simply isn't a migration target yet); the first
+ * non-404 rejection is rethrown.
+ */
+export async function listMigrationContext(ctx, appIdentity, options = {}) {
+    const { signal } = options;
+    signal?.throwIfAborted();
+    const platform = withSignal(ctx.platform.withHeaders({ 'Accept-Inclusion': 'addon:plan,config_vars' }), signal);
+    const data = withSignal(ctx.data, signal);
+    const attachments = await platform.addOnAttachment.listByApp(appIdentity);
+    // Keep only Postgres databases this app *owns* (attachments to databases
+    // owned by other apps are excluded), then dedupe to unique add-ons while
+    // collecting the names each is attached under (insertion order preserved).
+    const byAddonId = new Map();
+    for (const attachment of attachments) {
+        const { addon } = attachment;
+        if (!isPostgresAddon(addon) || (addon.app?.name !== appIdentity && addon.app?.id !== appIdentity))
+            continue;
+        const existing = byAddonId.get(addon.id);
+        if (existing) {
+            existing.attachmentNames.push(attachment.name);
+        }
+        else {
+            byAddonId.set(addon.id, { ...addon, attachmentNames: [attachment.name] });
+        }
+    }
+    const databases = [...byAddonId.values()];
+    const sources = databases.filter(db => isLegacyDatabase(db) && !isEssentialDatabase(db));
+    const advanced = databases.filter(db => isAdvancedDatabase(db));
+    const [migrationResults, infoResults] = await Promise.all([
+        Promise.allSettled(advanced.map(db => data.postgresMigration.info(db.id))),
+        Promise.allSettled(advanced.map(db => data.postgres.info(db.id))),
+    ]);
+    // A 404 means the database isn't a migration target yet (or has no info) —
+    // expected. Anything else is a real failure; rethrow the first one.
+    const unexpected = [...migrationResults, ...infoResults].find((result) => result.status === 'rejected' && !(result.reason instanceof NotFoundError));
+    if (unexpected)
+        throw unexpected.reason;
+    const targets = advanced.map((db, index) => {
+        const migrationResult = migrationResults[index];
+        const infoResult = infoResults[index];
+        return {
+            ...db,
+            info: infoResult.status === 'fulfilled' ? infoResult.value : undefined,
+            migration: migrationResult.status === 'fulfilled' ? migrationResult.value : undefined,
+        };
+    });
+    const migrations = targets
+        .map(target => target.migration)
+        .filter((migration) => migration !== undefined);
+    return { migrations, sources, targets };
+}
+// These extension keys are intentionally named distinctly from the generated
+// `postgresMigration` routes (`info`/`create`/`run`/`cancel`) they wrap.
+// Registering an extension under a generated route's own name silently replaces
+// that route (the replacement is only debug-logged), which both hides the
+// orchestration behind a familiar-looking name and leaves no way to reach the
+// raw route. The verbs here also describe the guarded behavior the raw routes
+// lack: `find` returns undefined instead of throwing on 404; `prepare`
+// configures (and validates) a migration without starting it; `startWhenReady`
+// and `abortBeforeRun` gate on the migration still being in its pre-run `ready`
+// state before acting, then re-fetch the post-action status.
+export const postgresMigrationExtensions = extendResource('data', 'postgresMigration', ctx => ({
+    abortBeforeRun: (targetAddonId, options) => cancel(ctx, targetAddonId, options),
+    find: (targetAddonId, options) => info(ctx, targetAddonId, options),
+    listMigrationContext: (appIdentity, options) => listMigrationContext(ctx, appIdentity, options),
+    prepare: (targetAddonId, body, options) => create(ctx, targetAddonId, body, options),
+    startWhenReady: (targetAddonId, options) => run(ctx, targetAddonId, options),
+}));

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

@@ -0,0 +1,77 @@
+import type { PostgresLevelInfoResult, PostgresPoolInfoResult } from '@heroku/types/data';
+/** The maximum number of follower-pool instances a database cluster can hold. */
+export declare const MAX_POOL_INSTANCES = 13;
+/** The name the leader pool always carries; any other name is a follower pool. */
+export declare const LEADER_POOL_NAME = "leader";
+/** A single compute level from `postgresLevel.info`. */
+export type LevelItem = PostgresLevelInfoResult['items'][number];
+/**
+ * A level paired with whether it's selectable for a given pool. The level a
+ * pool is already at is reported unavailable (`reason: 'current_level'`),
+ * mirroring the CLI's "current level" disabling; every other level is
+ * available. Callers get the full `LevelItem` (vcpu/memory/connection_limit),
+ * not just a name, so they can render without a second lookup.
+ */
+export type AvailableLevel = {
+    level: LevelItem;
+} & ({
+    available: false;
+    reason: 'current_level';
+} | {
+    available: true;
+});
+/**
+ * An action that can be taken on a pool. A discriminated union on `type`:
+ * `change_level` applies to any pool; `add_ha`/`remove_ha` are the leader's
+ * HA toggle (carrying the instance `count` the mutation sets); `update_count`
+ * (carrying the selectable `min`/`max`) and `destroy` apply to follower pools.
+ */
+export type PoolAction = {
+    count: 1;
+    type: 'remove_ha';
+} | {
+    count: 2;
+    type: 'add_ha';
+} | {
+    max: number;
+    min: number;
+    type: 'update_count';
+} | {
+    type: 'change_level';
+} | {
+    type: 'destroy';
+};
+export type ListAvailableActionsOptions = {
+    /**
+     * Total instances across *all* follower pools in the cluster, *including*
+     * the pool being queried. Used to bound a follower's `update_count` range:
+     * the edited pool's own instances are excluded so it can grow back into the
+     * budget they occupy (`max = MAX_POOL_INSTANCES - (count - pool.expected_count)`,
+     * floored at 1). Required so an omitted count can't silently widen the range
+     * to the full budget. Ignored for the leader pool.
+     */
+    followerInstanceCount: number;
+};
+/**
+ * Derives the selectable compute levels for a pool. Pure — no request.
+ *
+ * Returns every level from `levels`, marking the pool's current
+ * `expected_level` unavailable (`reason: 'current_level'`) so the UI can
+ * disable it. With no `pool`, every level is available (e.g. choosing the
+ * level for a brand-new pool).
+ */
+export declare function listAvailableLevels(levels: PostgresLevelInfoResult, pool?: Pick<PostgresPoolInfoResult, 'expected_level'>): AvailableLevel[];
+/**
+ * Derives the actions available on a pool. Pure — no request.
+ *
+ * The leader pool can always change level and can toggle high availability:
+ * `remove_ha` (down to a single instance) when it currently runs a standby
+ * (`expected_count > 1`), otherwise `add_ha` (up to two instances). A follower
+ * pool can change level, update its instance count (bounded by the cluster's
+ * remaining instance budget), or be destroyed.
+ */
+export declare function listAvailableActions(pool: Pick<PostgresPoolInfoResult, 'expected_count' | 'name'>, options: ListAvailableActionsOptions): PoolAction[];
+export declare const postgresPoolExtensions: import("../../core/extend-resource.js").ResourceExtension<"data", "postgresPool", {
+    listAvailableActions: typeof listAvailableActions;
+    listAvailableLevels: typeof listAvailableLevels;
+}>;

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

@@ -0,0 +1,50 @@
+import { extendResource } from '../../core/extend-resource.js';
+/** The maximum number of follower-pool instances a database cluster can hold. */
+export const MAX_POOL_INSTANCES = 13;
+/** The name the leader pool always carries; any other name is a follower pool. */
+export const LEADER_POOL_NAME = 'leader';
+/**
+ * Derives the selectable compute levels for a pool. Pure — no request.
+ *
+ * Returns every level from `levels`, marking the pool's current
+ * `expected_level` unavailable (`reason: 'current_level'`) so the UI can
+ * disable it. With no `pool`, every level is available (e.g. choosing the
+ * level for a brand-new pool).
+ */
+export function listAvailableLevels(levels, pool) {
+    return levels.items.map(level => level.name === pool?.expected_level
+        ? { available: false, level, reason: 'current_level' }
+        : { available: true, level });
+}
+/**
+ * Derives the actions available on a pool. Pure — no request.
+ *
+ * The leader pool can always change level and can toggle high availability:
+ * `remove_ha` (down to a single instance) when it currently runs a standby
+ * (`expected_count > 1`), otherwise `add_ha` (up to two instances). A follower
+ * pool can change level, update its instance count (bounded by the cluster's
+ * remaining instance budget), or be destroyed.
+ */
+export function listAvailableActions(pool, options) {
+    if (pool.name === LEADER_POOL_NAME) {
+        return [
+            { type: 'change_level' },
+            pool.expected_count > 1 ? { count: 1, type: 'remove_ha' } : { count: 2, type: 'add_ha' },
+        ];
+    }
+    const { followerInstanceCount } = options;
+    // `followerInstanceCount` includes this pool's own instances; exclude them so
+    // the pool can grow back into the budget it already occupies. Floor at 1 so
+    // the range never collapses below `min` even if the counts are inconsistent.
+    const otherInstances = Math.max(0, followerInstanceCount - pool.expected_count);
+    const max = Math.max(1, MAX_POOL_INSTANCES - otherInstances);
+    return [
+        { type: 'change_level' },
+        { max, min: 1, type: 'update_count' },
+        { type: 'destroy' },
+    ];
+}
+export const postgresPoolExtensions = extendResource('data', 'postgresPool', () => ({
+    listAvailableActions,
+    listAvailableLevels,
+}));

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

@@ -0,0 +1,33 @@
+import type { PostgresSettingsInfoResult, PostgresSettingsUpdateOpts, PostgresSettingsUpdateResult } from '@heroku/types/data';
+import type { ResourceCtx } from '../../core/extend-resource.js';
+import type { ResolvedAddOn } from '../platform/add-on/types.js';
+export type PostgresSettingsOptions = {
+    appIdentity?: string;
+    signal?: AbortSignal;
+};
+export type GetPostgresSettingsResult = {
+    addon: ResolvedAddOn;
+    settings: PostgresSettingsInfoResult;
+};
+export type UpdatePostgresSettingsResult = {
+    addon: ResolvedAddOn;
+    settings: PostgresSettingsUpdateResult;
+};
+/**
+ * Reads the settings of an Advanced-tier Postgres database.
+ *
+ * Throws `NotAdvancedDatabaseError` (carrying the resolved addon) if
+ * `addonIdentity` doesn't resolve to an Advanced-tier database.
+ */
+export declare function info(ctx: Pick<ResourceCtx, 'data' | 'platform'>, addonIdentity: string, options?: PostgresSettingsOptions): Promise<GetPostgresSettingsResult>;
+/**
+ * Updates the settings of an Advanced-tier Postgres database.
+ *
+ * Throws `NotAdvancedDatabaseError` (carrying the resolved addon) if
+ * `addonIdentity` doesn't resolve to an Advanced-tier database.
+ */
+export declare function update(ctx: Pick<ResourceCtx, 'data' | 'platform'>, addonIdentity: string, body: PostgresSettingsUpdateOpts, options?: PostgresSettingsOptions): Promise<UpdatePostgresSettingsResult>;
+export declare const postgresSettingsExtensions: import("../../core/extend-resource.js").ResourceExtension<"data", "postgresSettings", {
+    info: (addonIdentity: string, options?: PostgresSettingsOptions) => Promise<GetPostgresSettingsResult>;
+    update: (addonIdentity: string, body: PostgresSettingsUpdateOpts, options?: PostgresSettingsOptions) => Promise<UpdatePostgresSettingsResult>;
+}>;

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

@@ -0,0 +1,47 @@
+import { extendResource } from '../../core/extend-resource.js';
+import { withSignal } from '../../core/with-signal.js';
+import { resolveAddonInternal } from '../platform/add-on/resolve.js';
+import { getPostgresServiceName, isAdvancedDatabase, NotAdvancedDatabaseError } from './internal/postgres-utils.js';
+async function resolveTieredAddon(ctx, addonIdentity, options) {
+    const { appIdentity, signal } = options;
+    signal?.throwIfAborted();
+    // Bind the signal so the resolve request aborts in flight.
+    const platform = withSignal(ctx.platform, signal);
+    const addon = await resolveAddonInternal(platform, addonIdentity, {
+        addonService: getPostgresServiceName(), appIdentity,
+    });
+    if (!isAdvancedDatabase(addon)) {
+        throw new NotAdvancedDatabaseError(addon, `You can only manage settings on Advanced-tier databases. ${addon.name} isn't an Advanced-tier database.`);
+    }
+    return addon;
+}
+/**
+ * Reads the settings of an Advanced-tier Postgres database.
+ *
+ * Throws `NotAdvancedDatabaseError` (carrying the resolved addon) if
+ * `addonIdentity` doesn't resolve to an Advanced-tier database.
+ */
+export async function info(ctx, addonIdentity, options = {}) {
+    const addon = await resolveTieredAddon(ctx, addonIdentity, options);
+    // Bind the signal so the info request aborts in flight.
+    const data = withSignal(ctx.data, options.signal);
+    const settings = await data.postgresSettings.info(addon.id);
+    return { addon, settings };
+}
+/**
+ * Updates the settings of an Advanced-tier Postgres database.
+ *
+ * Throws `NotAdvancedDatabaseError` (carrying the resolved addon) if
+ * `addonIdentity` doesn't resolve to an Advanced-tier database.
+ */
+export async function update(ctx, addonIdentity, body, options = {}) {
+    const addon = await resolveTieredAddon(ctx, addonIdentity, options);
+    // Bind the signal so the update request aborts in flight.
+    const data = withSignal(ctx.data, options.signal);
+    const settings = await data.postgresSettings.update(addon.id, body);
+    return { addon, settings };
+}
+export const postgresSettingsExtensions = extendResource('data', 'postgresSettings', ctx => ({
+    info: (addonIdentity, options) => info(ctx, addonIdentity, options),
+    update: (addonIdentity, body, options) => update(ctx, addonIdentity, body, options),
+}));