@heroku/sdk 0.12.3 → 0.12.4

package/dist/resources/data/internal/postgres-utils.d.ts

@@ -3,14 +3,21 @@ import { PostgresCredentialInfoResult as AdvancedCredentialInfo } from '@heroku/
 import type { ResourceCtx } from '../../../core/extend-resource.js';
 import type { ResolvedAddOnAttachment } from '../../platform/add-on-attachment/resolve.js';
 import { CredentialInfo as NonAdvancedCredentialInfo } from '../postgres-database.js';
+/**
+ * The add-on shapes the Postgres tier predicates accept: either a full
+ * platform `AddOn` or the lighter add-on carried on a resolved attachment.
+ * Both expose the `plan.name` these checks read, so they're interchangeable
+ * here.
+ */
+export type PostgresAddonLike = AddOn | ResolvedAddOnAttachment['addon'];
 /**
  * Thrown when an add-on is not an Advanced-tier database. Carries the add-on
  * so callers that need its identity don't need a second resolve call.
  */
 export declare class NotAdvancedDatabaseError extends Error {
-    readonly addon: AddOn | ResolvedAddOnAttachment['addon'];
+    readonly addon: PostgresAddonLike;
     readonly id = "not_advanced_database";
-    constructor(addon: AddOn | ResolvedAddOnAttachment['addon'], message: string);
+    constructor(addon: PostgresAddonLike, message: string);
     get body(): {
         id: string;
         message: string;
@@ -22,9 +29,9 @@ export declare class NotAdvancedDatabaseError extends Error {
 export declare function findLegacyDatabase(ctx: Pick<ResourceCtx, 'platform'>, appIdentity: string): Promise<AddOn>;
 export declare function isAdvancedCredential(credential: AdvancedCredentialInfo | NonAdvancedCredentialInfo): credential is AdvancedCredentialInfo;
 export declare const getPostgresServiceName: () => string;
-export declare const isPostgresAddon: (addon: AddOn | ResolvedAddOnAttachment["addon"]) => boolean;
-export declare const isAdvancedDatabase: (addon: AddOn | ResolvedAddOnAttachment["addon"]) => boolean;
-export declare const isLegacyDatabase: (addon: AddOn) => boolean;
-export declare const isLegacyEssentialDatabase: (addon: AddOn) => boolean;
-export declare const isEssentialDatabase: (addon: AddOn) => boolean;
-export declare const isEssentialTier: (addon: AddOn) => boolean;
+export declare const isPostgresAddon: (addon: PostgresAddonLike) => boolean;
+export declare const isAdvancedDatabase: (addon: PostgresAddonLike) => boolean;
+export declare const isLegacyDatabase: (addon: PostgresAddonLike) => boolean;
+export declare const isLegacyEssentialDatabase: (addon: PostgresAddonLike) => boolean;
+export declare const isEssentialDatabase: (addon: PostgresAddonLike) => boolean;
+export declare const isEssentialTier: (addon: PostgresAddonLike) => boolean;

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

@@ -1,6 +1,7 @@
 import type { AddOnAttachment, AddOnAttachmentCreateOpts } from '@heroku/types/3.sdk';
+import type { PostgresCredentialListResult } from '@heroku/types/data';
 import type { ResourceCtx } from '../../core/extend-resource.js';
-import type { ResolvedAddOn } from '../platform/add-on/types.js';
+import type { DeprovisioningAddOn, ResolvedAddOn } from '../platform/add-on/types.js';
 export type ListCredentialsOptions = {
     signal?: AbortSignal;
 };
@@ -9,11 +10,23 @@ export type DeleteAttachmentOptions = {
         addon: ResolvedAddOn;
         attachment: AddOnAttachment;
     }) => Promise<void> | void;
+    onDetached?: (attachment: AddOnAttachment) => Promise<void> | void;
     signal?: AbortSignal;
 };
 export type DeleteAttachmentResult = {
     addon: ResolvedAddOn;
     attachment: AddOnAttachment;
+    releaseVersion?: number;
+};
+export type PostgresCredential = PostgresCredentialListResult['items'][number];
+export type ListAttachmentsOptions = {
+    appIdentity?: string;
+    signal?: AbortSignal;
+};
+export type ListAttachmentsResult = {
+    addon: ResolvedAddOn;
+    attachments: AddOnAttachment[];
+    credentials: PostgresCredential[];
 };
 export type CreateAttachmentBody = Omit<AddOnAttachmentCreateOpts, 'addon' | 'app'>;
 export type CreateAttachmentOptions = {
@@ -25,6 +38,26 @@ export type CreateAttachmentResult = {
     attachment: AddOnAttachment;
     releaseVersion?: number;
 };
+export type DestroyOptions = {
+    appIdentity?: string;
+    /**
+     * Runs after the database is resolved but before the delete request fires.
+     * An abort (or throw) during the hook prevents the delete — use it to
+     * confirm destruction against the resolved add-on.
+     */
+    beforeDestroy?: (preview: {
+        addon: ResolvedAddOn;
+    }) => Promise<void> | void;
+    force?: boolean;
+    onDeprovisioning?: (addon: DeprovisioningAddOn) => Promise<void> | void;
+    signal?: AbortSignal;
+    wait?: boolean;
+    waitIntervalMs?: number;
+};
+export type DestroyResult = {
+    addon: ResolvedAddOn;
+    result: DeprovisioningAddOn;
+};
 export type CredentialInfo = {
     credentials: Array<{
         connections?: null | number;
@@ -48,9 +81,21 @@ export declare function listCredentials(ctx: Pick<ResourceCtx, 'data' | 'platfor
  * attachment's database isn't an Advanced-tier database.
  *
  * If provided, `beforeDelete` runs after resolution/tier-checking but before
- * the delete request fires. An abort during the hook prevents the delete.
+ * the delete request fires (an abort during the hook prevents the delete), and
+ * `onDetached` runs once the attachment is deleted but before the release
+ * version fetch. The returned `releaseVersion` is the latest release created by
+ * unsetting the attachment's config vars.
  */
 export declare function deleteAttachment(ctx: Pick<ResourceCtx, 'platform'>, appIdentity: string, attachmentName: string, options?: DeleteAttachmentOptions): Promise<DeleteAttachmentResult>;
+/**
+ * Resolves a Postgres database by add-on identity and lists its attachments
+ * alongside its credentials, fanning the two requests out in parallel.
+ *
+ * Resolution is scoped by `appIdentity` when given. Throws
+ * `NotAdvancedDatabaseError` (carrying the resolved add-on) if the database
+ * isn't an Advanced-tier database.
+ */
+export declare function listAttachments(ctx: Pick<ResourceCtx, 'data' | 'platform'>, addonIdentity: string, options?: ListAttachmentsOptions): Promise<ListAttachmentsResult>;
 /**
  * Resolves a source Postgres database by add-on identity, attaches it
  * to an app, and fetches the latest release version.
@@ -62,10 +107,24 @@ export declare function deleteAttachment(ctx: Pick<ResourceCtx, 'platform'>, app
  * the release version fetch.
  */
 export declare function createAttachment(ctx: Pick<ResourceCtx, 'platform'>, appIdentity: string, addonIdentity: string, body?: CreateAttachmentBody, options?: CreateAttachmentOptions): Promise<CreateAttachmentResult>;
+/**
+ * Resolves a Postgres database by add-on identity and destroys it.
+ *
+ * Resolution is scoped by `appIdentity` when given. If provided,
+ * `beforeDestroy` runs after resolution but before the delete request fires,
+ * so callers can confirm against the resolved add-on; an abort or throw in
+ * the hook prevents the delete. Delegates the delete (and optional
+ * deprovisioning poll when `wait` is set) to `addOn.destroyAndWait`.
+ */
+export declare function destroy(ctx: Pick<ResourceCtx, 'platform'>, addonIdentity: string, options?: DestroyOptions): Promise<DestroyResult>;
 export declare const postgresDatabaseExtensions: import("../../core/extend-resource.js").ResourceExtension<"data", "postgresDatabase", {
     createAttachment: (appIdentity: string, addonIdentity: string, body?: CreateAttachmentBody, options?: CreateAttachmentOptions) => Promise<CreateAttachmentResult>;
     deleteAttachment: (appIdentity: string, attachmentName: string, options?: DeleteAttachmentOptions) => Promise<DeleteAttachmentResult>;
+    destroy: (addonIdentity: string, options?: DestroyOptions) => Promise<DestroyResult>;
+    listAttachments: (addonIdentity: string, options?: ListAttachmentsOptions) => Promise<ListAttachmentsResult>;
     listCredentials: (appIdentity: string, addonIdentity?: string, options?: ListCredentialsOptions) => Promise<CredentialInfo[]>;
 }>;
+export { AddonAppMismatchError, AddonConfirmationRequiredError, AddonDestroyFailedError, AddonNotFoundError, } from '../platform/add-on/errors.js';
+export type { DeprovisioningAddOn, ResolvedAddOn } from '../platform/add-on/types.js';
 export { type AttachmentFactors, parseAttachmentFactors, } from './internal/parse-attachment-factors.js';
 export { findLegacyDatabase, getPostgresServiceName, isAdvancedCredential, isAdvancedDatabase, isEssentialDatabase, isEssentialTier, isLegacyDatabase, isLegacyEssentialDatabase, isPostgresAddon, NotAdvancedDatabaseError, } from './internal/postgres-utils.js';

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

@@ -1,7 +1,8 @@
-import { HerokuApiError } from '@heroku/heroku-fetch';
+import { HerokuApiError, NotFoundError } from '@heroku/heroku-fetch';
 import { extendResource } from '../../core/extend-resource.js';
 import { withSignal } from '../../core/with-signal.js';
-import { AddonConfirmationRequiredError, AddonNotFoundError } from '../platform/add-on/errors.js';
+import { destroyAndWait } from '../platform/add-on/destroy-and-wait.js';
+import { AddonAppMismatchError, AddonConfirmationRequiredError, AddonDestroyFailedError, AddonNotFoundError, } from '../platform/add-on/errors.js';
 import { resolveAddonInternal } from '../platform/add-on/resolve.js';
 import { getPostgresServiceName, isAdvancedDatabase, NotAdvancedDatabaseError } from './internal/postgres-utils.js';
 import { resolvePgDatabase } from './internal/resolve-pg-database.js';
@@ -20,12 +21,15 @@ export async function listCredentials(ctx, appIdentity, addonIdentity, options =
  * attachment's database isn't an Advanced-tier database.
  *
  * If provided, `beforeDelete` runs after resolution/tier-checking but before
- * the delete request fires. An abort during the hook prevents the delete.
+ * the delete request fires (an abort during the hook prevents the delete), and
+ * `onDetached` runs once the attachment is deleted but before the release
+ * version fetch. The returned `releaseVersion` is the latest release created by
+ * unsetting the attachment's config vars.
  */
 export async function deleteAttachment(ctx, appIdentity, attachmentName, options = {}) {
-    const { beforeDelete, signal } = options;
+    const { beforeDelete, onDetached, signal } = options;
     signal?.throwIfAborted();
-    // Bind the signal so the lookup and delete requests abort in flight.
+    // Bind the signal so the lookup, delete, and release-list requests abort in flight.
     const platform = withSignal(ctx.platform, signal);
     const attachment = await platform.addOnAttachment.infoByApp(appIdentity, attachmentName);
     const addon = await resolveAddonInternal(platform, attachment.addon.name, { addonService: getPostgresServiceName() });
@@ -35,7 +39,48 @@ export async function deleteAttachment(ctx, appIdentity, attachmentName, options
     await beforeDelete?.({ addon, attachment });
     signal?.throwIfAborted();
     const deletedAttachment = await platform.addOnAttachment.delete(attachment.id);
-    return { addon, attachment: deletedAttachment };
+    await onDetached?.(deletedAttachment);
+    signal?.throwIfAborted();
+    // The detach already succeeded; a failed release lookup shouldn't fail the
+    // whole operation. Preserve aborts, otherwise report an unknown version.
+    let releaseVersion;
+    try {
+        const releases = await platform
+            .withHeaders({ Range: 'version ..; max=1, order=desc' })
+            .release.list(appIdentity);
+        releaseVersion = releases[0]?.version;
+    }
+    catch (error) {
+        // Preserve aborts; otherwise leave releaseVersion undefined (best-effort).
+        if (signal?.aborted) {
+            throw error;
+        }
+    }
+    return { addon, attachment: deletedAttachment, releaseVersion };
+}
+/**
+ * Resolves a Postgres database by add-on identity and lists its attachments
+ * alongside its credentials, fanning the two requests out in parallel.
+ *
+ * Resolution is scoped by `appIdentity` when given. Throws
+ * `NotAdvancedDatabaseError` (carrying the resolved add-on) if the database
+ * isn't an Advanced-tier database.
+ */
+export async function listAttachments(ctx, addonIdentity, options = {}) {
+    const { appIdentity, signal } = options;
+    signal?.throwIfAborted();
+    // Bind the signal so the resolve and fan-out requests abort in flight.
+    const platform = withSignal(ctx.platform, signal);
+    const data = withSignal(ctx.data, signal);
+    const addon = await resolveAddonInternal(platform, addonIdentity, { addonService: getPostgresServiceName(), appIdentity });
+    if (!isAdvancedDatabase(addon)) {
+        throw new NotAdvancedDatabaseError(addon, `You can only list attachments on Advanced-tier databases with postgresDatabase.listAttachments(). ${addon.name} isn't an Advanced-tier database.`);
+    }
+    const [{ items: credentials }, attachments] = await Promise.all([
+        data.postgresCredential.list(addon.id),
+        platform.addOnAttachment.listByAddOn(addon.id),
+    ]);
+    return { addon, attachments, credentials };
 }
 /**
  * Resolves a source Postgres database by add-on identity, attaches it
@@ -60,7 +105,7 @@ export async function createAttachment(ctx, appIdentity, addonIdentity, body = {
         addon = await resolveAddonInternal(platform, addonIdentity, { addonService: getPostgresServiceName(), appIdentity });
     }
     catch (error) {
-        if (!(error instanceof AddonNotFoundError)) {
+        if (!(error instanceof NotFoundError)) {
             throw error;
         }
         addon = await resolveAddonInternal(platform, addonIdentity, { addonService: getPostgresServiceName() });
@@ -89,10 +134,88 @@ export async function createAttachment(ctx, appIdentity, addonIdentity, body = {
         .release.list(appIdentity);
     return { addon, attachment, releaseVersion: releases[0]?.version };
 }
+/**
+ * Resolves a Postgres database by add-on identity and destroys it.
+ *
+ * Resolution is scoped by `appIdentity` when given. If provided,
+ * `beforeDestroy` runs after resolution but before the delete request fires,
+ * so callers can confirm against the resolved add-on; an abort or throw in
+ * the hook prevents the delete. Delegates the delete (and optional
+ * deprovisioning poll when `wait` is set) to `addOn.destroyAndWait`.
+ */
+export async function destroy(ctx, addonIdentity, options = {}) {
+    const { appIdentity, beforeDestroy, force, onDeprovisioning, signal, wait, waitIntervalMs, } = options;
+    signal?.throwIfAborted();
+    // Bind the signal so the resolve request aborts in flight.
+    const platform = withSignal(ctx.platform, signal);
+    let addon;
+    try {
+        addon = await resolveAddonInternal(platform, addonIdentity, {
+            addonService: getPostgresServiceName(), appIdentity,
+        });
+    }
+    catch (error) {
+        // When scoped resolution misses, check whether the database exists under a
+        // different app so we can surface a targeted mismatch error instead of a
+        // bare not-found. Skip the probe for `::`-qualified identities: those name
+        // their app inline, so `resolveAddonInternal` ignores `appIdentity` and the
+        // unscoped retry would just repeat the same failing request.
+        if (appIdentity && !addonIdentity.includes('::') && error instanceof AddonNotFoundError) {
+            let elsewhere;
+            try {
+                elsewhere = await resolveAddonInternal(platform, addonIdentity, {
+                    addonService: getPostgresServiceName(),
+                });
+            }
+            catch (retryError) {
+                // Preserve aborts; an ambiguous/other failure here can't produce a
+                // clean mismatch message, so fall through to the original not-found.
+                if (signal?.aborted) {
+                    throw retryError;
+                }
+            }
+            // `appIdentity` may be an app name or UUID; compare against both so a
+            // UUID-scoped caller isn't always flagged as a mismatch (and doesn't get
+            // a raw UUID echoed back in the error message).
+            if (elsewhere && elsewhere.app.id !== appIdentity && elsewhere.app.name !== appIdentity) {
+                throw new AddonAppMismatchError(elsewhere, appIdentity);
+            }
+        }
+        throw error;
+    }
+    await beforeDestroy?.({ addon });
+    signal?.throwIfAborted();
+    // Resolution and beforeDestroy aborts already happened above; a failure here
+    // is the delete request (or wait poll) itself. Preserve aborts, but wrap other
+    // failures so callers get the resolved add-on (and thus tier) without
+    // re-resolving.
+    try {
+        const result = await destroyAndWait(ctx, addon.app.id, addon.id, {
+            force, onDeprovisioning, signal, wait, waitIntervalMs,
+        });
+        return { addon, result };
+    }
+    catch (error) {
+        if (signal?.aborted) {
+            throw error;
+        }
+        // A platform `confirmation_required` (e.g. destroying a database attached
+        // to other apps without `force`) is a distinct, recoverable condition —
+        // surface it as the typed error so callers can prompt and retry, matching
+        // `createAttachment`, rather than collapsing it into a generic failure.
+        if (error instanceof HerokuApiError && error.id === 'confirmation_required') {
+            throw new AddonConfirmationRequiredError(error.message);
+        }
+        throw new AddonDestroyFailedError(addon, error);
+    }
+}
 export const postgresDatabaseExtensions = extendResource('data', 'postgresDatabase', ctx => ({
     createAttachment: (appIdentity, addonIdentity, body, options) => createAttachment(ctx, appIdentity, addonIdentity, body, options),
     deleteAttachment: (appIdentity, attachmentName, options) => deleteAttachment(ctx, appIdentity, attachmentName, options),
+    destroy: (addonIdentity, options) => destroy(ctx, addonIdentity, options),
+    listAttachments: (addonIdentity, options) => listAttachments(ctx, addonIdentity, options),
     listCredentials: (appIdentity, addonIdentity, options) => listCredentials(ctx, appIdentity, addonIdentity, options),
 }));
+export { AddonAppMismatchError, AddonConfirmationRequiredError, AddonDestroyFailedError, AddonNotFoundError, } from '../platform/add-on/errors.js';
 export { parseAttachmentFactors, } from './internal/parse-attachment-factors.js';
 export { findLegacyDatabase, getPostgresServiceName, isAdvancedCredential, isAdvancedDatabase, isEssentialDatabase, isEssentialTier, isLegacyDatabase, isLegacyEssentialDatabase, isPostgresAddon, NotAdvancedDatabaseError, } from './internal/postgres-utils.js';

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

@@ -0,0 +1,182 @@
+import type { PostgresInfoResult, PostgresMigrationCreateOpts, PostgresMigrationCreateResult, PostgresMigrationInfoResult } from '@heroku/types/data';
+import type { ResourceCtx } from '../../core/extend-resource.js';
+import type { AddOnAttachmentWithInclusions } from '../platform/add-on-attachment/resolve.js';
+/**
+ * A database migration record, as returned by `find`, `startWhenReady`, and
+ * `abortBeforeRun`. The create/prepare response
+ * (`PostgresMigrationCreateResult`) is structurally identical today — same
+ * fields, same closed `status` union — but keeps its own generated type rather
+ * than sharing this alias.
+ */
+export type Migration = PostgresMigrationInfoResult;
+/** The closed migration-status union, re-derived so callers don't restate it. */
+export type MigrationStatus = Migration['status'];
+/** Request body for configuring a migration (the generated create opts). */
+export type MigrationCreateBody = PostgresMigrationCreateOpts;
+export type MigrationOptions = {
+    signal?: AbortSignal;
+};
+/**
+ * The reason a migration create request was rejected client-side. A
+ * single-member discriminated union today; new guards add members here so
+ * callers keep exhaustive handling. Server-side validation rejections are not
+ * yet mapped onto this type — they surface as the raw API error.
+ */
+export type MigrationInvalidReason = 'source_equals_target';
+/**
+ * A classic Postgres database eligible to be migrated *from*, with the names
+ * it's attached under on the app.
+ */
+export type MigrationSource = AddOnAttachmentWithInclusions['addon'] & {
+    attachmentNames: string[];
+};
+/**
+ * An Advanced Postgres database eligible to be migrated *to*, with its
+ * attachment names, its current `info` (for availability gating), and any
+ * migration currently targeting it. `info`/`migration` are absent when the
+ * database's `/info` or `/migrations` endpoint 404s (not yet a target).
+ */
+export type MigrationTarget = AddOnAttachmentWithInclusions['addon'] & {
+    attachmentNames: string[];
+    info?: PostgresInfoResult;
+    migration?: Migration;
+};
+export type MigrationContext = {
+    /** All migration records currently configured on the app's Advanced databases. */
+    migrations: Migration[];
+    /** Classic (non-Essential) databases that can be migration sources. */
+    sources: MigrationSource[];
+    /** Advanced databases that can be migration targets. */
+    targets: MigrationTarget[];
+};
+/**
+ * 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 declare class MigrationInvalidError extends Error {
+    readonly reason: MigrationInvalidReason;
+    readonly id = "migration_invalid";
+    constructor(reason: MigrationInvalidReason, message: string);
+    get body(): {
+        id: string;
+        message: string;
+        reason: "source_equals_target";
+    };
+}
+/**
+ * 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 declare class MigrationNotRunnableError extends Error {
+    readonly migration: Migration;
+    readonly id = "migration_not_runnable";
+    constructor(migration: Migration);
+    get body(): {
+        id: string;
+        message: string;
+        status: "creating_target" | "preparing" | "migrating" | "completed" | "failed" | "cancelled" | "ready" | "promoting" | "unknown";
+    };
+    /**
+     * The migration's status. Named `migrationStatus` (not `status`) to avoid
+     * shadowing the HTTP-status convention other `Error` subclasses in the SDK
+     * carry.
+     */
+    get migrationStatus(): MigrationStatus;
+}
+/**
+ * Thrown by `cancel` when the migration isn't in a cancellable state. Carries
+ * the migration (and thus its `status`).
+ */
+export declare class MigrationNotCancellableError extends Error {
+    readonly migration: Migration;
+    readonly id = "migration_not_cancellable";
+    constructor(migration: Migration);
+    get body(): {
+        id: string;
+        message: string;
+        status: "creating_target" | "preparing" | "migrating" | "completed" | "failed" | "cancelled" | "ready" | "promoting" | "unknown";
+    };
+    /**
+     * The migration's status. Named `migrationStatus` (not `status`) to avoid
+     * shadowing the HTTP-status convention other `Error` subclasses in the SDK
+     * carry.
+     */
+    get migrationStatus(): MigrationStatus;
+}
+/**
+ * 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 declare function isRunnable(status: MigrationStatus): boolean;
+/**
+ * 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 declare function isCancellable(status: MigrationStatus): boolean;
+/**
+ * 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 declare function info(ctx: Pick<ResourceCtx, 'data'>, targetAddonId: string, options?: MigrationOptions): Promise<Migration | undefined>;
+/**
+ * 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 declare function create(ctx: Pick<ResourceCtx, 'data'>, targetAddonId: string, body: MigrationCreateBody, options?: MigrationOptions): Promise<PostgresMigrationCreateResult>;
+/**
+ * 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 declare function run(ctx: Pick<ResourceCtx, 'data'>, targetAddonId: string, options?: MigrationOptions): Promise<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 declare function cancel(ctx: Pick<ResourceCtx, 'data'>, targetAddonId: string, options?: MigrationOptions): Promise<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 declare function listMigrationContext(ctx: Pick<ResourceCtx, 'data' | 'platform'>, appIdentity: string, options?: MigrationOptions): Promise<MigrationContext>;
+export declare const postgresMigrationExtensions: import("../../core/extend-resource.js").ResourceExtension<"data", "postgresMigration", {
+    abortBeforeRun: (targetAddonId: string, options?: MigrationOptions) => Promise<PostgresMigrationInfoResult>;
+    find: (targetAddonId: string, options?: MigrationOptions) => Promise<PostgresMigrationInfoResult | undefined>;
+    listMigrationContext: (appIdentity: string, options?: MigrationOptions) => Promise<MigrationContext>;
+    prepare: (targetAddonId: string, body: MigrationCreateBody, options?: MigrationOptions) => Promise<PostgresMigrationCreateResult>;
+    startWhenReady: (targetAddonId: string, options?: MigrationOptions) => Promise<PostgresMigrationInfoResult>;
+}>;