@heroku/sdk 0.8.0 → 0.9.0

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

@@ -0,0 +1,10 @@
+import type { AddOn } from '@heroku/types/3.sdk';
+import { ResourceCtx } from '../../../core/extend-resource.js';
+/**
+ * Returns an arbitrary legacy database add-on based on the provided app name.
+ */
+export declare function getArbitraryLegacyDB(ctx: Pick<ResourceCtx, 'platform'>, appIdentity: string): Promise<AddOn>;
+export declare const getAddonService: () => string;
+export declare const isPostgresAddon: (addon: AddOn) => boolean;
+export declare const isAdvancedDatabase: (addon: AddOn) => boolean;
+export declare const isLegacyDatabase: (addon: AddOn) => boolean;

package/dist/resources/data/internal/postgres-utils.js

@@ -0,0 +1,17 @@
+import createDebug from 'debug';
+const debug = createDebug('postgres-utils');
+/**
+ * Returns an arbitrary legacy database add-on based on the provided app name.
+ */
+export async function getArbitraryLegacyDB(ctx, appIdentity) {
+    debug(`fetching arbitrary legacy database on ${appIdentity}`);
+    const addons = await ctx.platform.addOn.listByApp(appIdentity);
+    const addon = addons.find(a => a.app.name === appIdentity && isLegacyDatabase(a));
+    if (!addon)
+        throw new Error(`No Heroku Postgres legacy database on ${appIdentity}`);
+    return addon;
+}
+export const getAddonService = () => process.env.HEROKU_POSTGRESQL_ADDON_NAME || process.env.HEROKU_DATA_SERVICE || 'heroku-postgresql';
+export const isPostgresAddon = (addon) => addon.plan?.name?.split(':', 2)[0] === getAddonService();
+export const isAdvancedDatabase = (addon) => isPostgresAddon(addon) && /^(advanced|performance)/.test(addon.plan?.name?.split(':', 2)[1] ?? '');
+export const isLegacyDatabase = (addon) => isPostgresAddon(addon) && !isAdvancedDatabase(addon);

package/dist/resources/data/internal/resolve-pg-database.d.ts

@@ -1,8 +1,13 @@
 import type { ResourceCtx } from '../../../core/extend-resource.js';
 import type { ResolveAddonAttachmentOptions, ResolvedAddOnAttachment } from '../../platform/add-on-attachment/resolve.js';
 export type ResolvedPgDatabase = ResolvedAddOnAttachment['addon'];
+export type ResolvedPgDatabaseWithAttachment = {
+    addon: ResolvedPgDatabase;
+    attachment: ResolvedAddOnAttachment;
+};
 export type ResolvePgDatabaseOptions = ResolveAddonAttachmentOptions & {
     appIdentity?: string;
+    includeAttachment?: boolean;
     input?: string;
 };
 /**
@@ -36,4 +41,7 @@ export type ResolvePgDatabaseOptions = ResolveAddonAttachmentOptions & {
  * from the underlying resolver. Throws if no input is given and no `appIdentity`
  * is available to default the attachment lookup to.
  */
+export declare function resolvePgDatabase(ctx: Pick<ResourceCtx, 'platform'>, options: ResolvePgDatabaseOptions & {
+    includeAttachment: true;
+}): Promise<ResolvedPgDatabaseWithAttachment>;
 export declare function resolvePgDatabase(ctx: Pick<ResourceCtx, 'platform'>, options?: ResolvePgDatabaseOptions): Promise<ResolvedPgDatabase>;

package/dist/resources/data/internal/resolve-pg-database.js

@@ -1,41 +1,11 @@
 import createDebug from 'debug';
 import { AddonAttachmentAmbiguousError, resolveAddonAttachment } from '../../platform/add-on-attachment/resolve.js';
+import { getAddonService } from './postgres-utils.js';
 const debug = createDebug('heroku:sdk:resources:database');
 const DEFAULT_PG_ATTACHMENT = 'DATABASE_URL';
-const PG_ADDON_SERVICE = process.env.HEROKU_POSTGRESQL_ADDON_NAME ?? process.env.HEROKU_DATA_SERVICE ?? 'heroku-postgresql';
-/**
- * Resolve a Heroku Postgres database add-on from an attachment identity.
- *
- * `input` selects the attachment as follows:
- *   - omitted → the `DATABASE_URL` attachment on `appIdentity`.
- *   - `parent-app::attachment-or-config-var` (e.g. `my-app::DATABASE_URL`)
- *     → an attachment or config var on `parent-app`.
- *   - `parent-app::branch-name` (e.g. `my-app::my-branch`) → branch add-on
- *     name on `parent-app`.
- *   - Both `::` forms are handled the same way here: we split on the first
- *     `::` ourselves and send `app`/`addon` as separate fields, which
- *     works for either shape.
- *   - any other string (attachment name, config var, UUID, or
- *     globally-unique add-on name) → routed through `resolveAddonAttachment`.
- *
- * This function only uses the attachment resolver. To resolve a database
- * through the add-on resolve endpoint, call `resolveAddon` directly.
- *
- * The returned add-on is the identity nested on the attachment (`id`,
- * `name`, `app`, and the plan stub), not a full `ResolvedAddOn`. To get
- * that shape, call `resolveAddon` with the returned add-on's `id`.
- *
- * If the resolver finds multiple matches that all point at the same add-on
- * (same `addon.id`/attachment `app.id`) and whose own `_URL` config var
- * resolves to the same value on the app, they're treated as equivalent
- * (e.g. the same database attached under two names) rather than ambiguous.
- *
- * Throws `AddonAttachmentNotFoundError` (or `AddonAttachmentAmbiguousError`)
- * from the underlying resolver. Throws if no input is given and no `appIdentity`
- * is available to default the attachment lookup to.
- */
+const PG_ADDON_SERVICE = getAddonService();
 export async function resolvePgDatabase(ctx, options = {}) {
-    const { appIdentity, input, ...rest } = options;
+    const { appIdentity, includeAttachment, input, ...rest } = options;
     if (!input && !appIdentity) {
         throw new Error('resolvePgDatabase requires either input or appIdentity to default to DATABASE_URL.');
     }
@@ -44,22 +14,22 @@ export async function resolvePgDatabase(ctx, options = {}) {
         ? parseBranchReference(databaseReference, appIdentity)
         : { addon: databaseReference, app: appIdentity };
     debug('resolve input=%s addon=%s app=%s', input ?? '<default>', addon, app ?? '<global>');
+    let attachment;
     try {
-        const attachment = await resolveAddonAttachment(ctx, app, addon, { ...rest, addonService: PG_ADDON_SERVICE });
-        return attachment.addon;
+        attachment = await resolveAddonAttachment(ctx, app, addon, { ...rest, addonService: PG_ADDON_SERVICE });
     }
     catch (error) {
-        if (error instanceof AddonAttachmentAmbiguousError) {
-            const equivalent = collapseIfEquivalent(error.matches);
-            if (equivalent) {
-                const config = await ctx.platform.configVar.infoForApp(equivalent[0].app.name);
-                if (allMatchSameUrl(equivalent, config)) {
-                    return equivalent[0].addon;
-                }
-            }
-        }
-        throw error;
+        if (!(error instanceof AddonAttachmentAmbiguousError))
+            throw error;
+        const equivalent = collapseIfEquivalent(error.matches);
+        if (!equivalent)
+            throw error;
+        const config = await ctx.platform.configVar.infoForApp(equivalent[0].app.name);
+        if (!allMatchSameUrl(equivalent, config))
+            throw error;
+        attachment = equivalent[0];
     }
+    return includeAttachment ? { addon: attachment.addon, attachment } : attachment.addon;
 }
 /**
  * Narrows ambiguous matches to a same-add-on group worth comparing by

package/dist/resources/data/{backup → transfer}/capture-and-wait.d.ts

@@ -1,8 +1,15 @@
-import type { BackupCreateResult, TransferInfoByAppResult } from '@heroku/types/data';
+import type { TransferInfoByAppResult } from '@heroku/types/data';
 import type { ResourceCtx } from '../../../core/extend-resource.js';
 import type { ResolvedPgDatabase } from '../internal/resolve-pg-database.js';
-import type { WaitForTransferOptions } from '../wait-for-transfer.js';
+import type { WaitForTransferOptions } from './wait-for-transfer.js';
 import { Poller } from '../../../utils/poller.js';
+/**
+ * `data.backup.create`'s declared return type, `BackupCreateResult`, only
+ * lists `uuid`/`from_type`/`to_type`, but the actual response includes the
+ * full transfer record. Widen the type here so callers (e.g. `waitPoller`) can
+ * use the full transfer record.
+ */
+export type BackupCreateInfo = TransferInfoByAppResult;
 export type CaptureAndWaitOptions = WaitForTransferOptions & {
     /**
      * Progress hooks fired once before capturing the backup `poller.onStart(addon)`
@@ -14,6 +21,6 @@ export type CaptureAndWaitOptions = WaitForTransferOptions & {
      * complete `poller.onStart(backup)` and once after the transfer
      * finishes successfully `poller.onStop(backup)`.
      */
-    waitPoller?: Poller<BackupCreateResult>;
+    waitPoller?: Poller<BackupCreateInfo>;
 };
 export declare function captureAndWait(ctx: Pick<ResourceCtx, 'data' | 'platform'>, appIdentity: string, addonIdentity?: string, options?: CaptureAndWaitOptions): Promise<TransferInfoByAppResult>;

package/dist/resources/data/{backup → transfer}/capture-and-wait.js

@@ -1,5 +1,5 @@
 import { resolvePgDatabase } from '../internal/resolve-pg-database.js';
-import { waitForTransfer } from '../wait-for-transfer.js';
+import { waitForTransfer } from './wait-for-transfer.js';
 export async function captureAndWait(ctx, appIdentity, addonIdentity, options = {}) {
     const { capturePoller, signal, waitPoller } = options;
     signal?.throwIfAborted();

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

@@ -0,0 +1,11 @@
+import type { CaptureAndWaitOptions } from './capture-and-wait.js';
+import type { RestoreAndWaitOptions } from './restore-and-wait.js';
+export { captureAndWait, type CaptureAndWaitOptions } from './capture-and-wait.js';
+export { restoreAndWait, type RestoreAndWaitOptions } from './restore-and-wait.js';
+export { transferExtensions, TransferFailedError, TransferTimeoutError, type WaitForTransferOptions, } from './wait-for-transfer.js';
+export declare const restoreExtensions: import("../../../core/extend-resource.js").ResourceExtension<"data", "restore", {
+    restoreAndWait: (appIdentity: string, addonIdentity: string | undefined, backupUrl: string, options?: RestoreAndWaitOptions) => Promise<import("@heroku/types/data").TransferInfoByAppResult>;
+}>;
+export declare const backupExtensions: import("../../../core/extend-resource.js").ResourceExtension<"data", "backup", {
+    captureAndWait: (appIdentity: string, addonIdentity?: string, options?: CaptureAndWaitOptions) => Promise<import("@heroku/types/data").TransferInfoByAppResult>;
+}>;

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

@@ -0,0 +1,12 @@
+import { extendResource } from '../../../core/extend-resource.js';
+import { captureAndWait } from './capture-and-wait.js';
+import { restoreAndWait } from './restore-and-wait.js';
+export { captureAndWait } from './capture-and-wait.js';
+export { restoreAndWait } from './restore-and-wait.js';
+export { transferExtensions, TransferFailedError, TransferTimeoutError, } from './wait-for-transfer.js';
+export const restoreExtensions = extendResource('data', 'restore', ctx => ({
+    restoreAndWait: (appIdentity, addonIdentity, backupUrl, options) => restoreAndWait(ctx, appIdentity, addonIdentity, backupUrl, options),
+}));
+export const backupExtensions = extendResource('data', 'backup', ctx => ({
+    captureAndWait: (appIdentity, addonIdentity, options) => captureAndWait(ctx, appIdentity, addonIdentity, options),
+}));

package/dist/resources/data/{restore → transfer}/restore-and-wait.d.ts

@@ -1,8 +1,15 @@
-import type { RestoreCreateResult, TransferInfoByAppResult } from '@heroku/types/data';
+import type { TransferInfoByAppResult } from '@heroku/types/data';
 import type { ResourceCtx } from '../../../core/extend-resource.js';
 import type { ResolvedPgDatabase } from '../internal/resolve-pg-database.js';
-import type { WaitForTransferOptions } from '../wait-for-transfer.js';
+import type { WaitForTransferOptions } from './wait-for-transfer.js';
 import { Poller } from '../../../utils/poller.js';
+/**
+ * `data.restore.create`'s declared return type, `RestoreCreateResult`, only
+ * lists `uuid`/`from_type`/`to_type`, but the actual response includes the
+ * full transfer record. Widen the type here so callers (e.g. `waitPoller`) can
+ * use the full transfer record.
+ */
+export type RestoreCreateInfo = TransferInfoByAppResult;
 export type RestoreAndWaitOptions = WaitForTransferOptions & {
     /**
      * Extension names to preinstall on the restore target.
@@ -19,6 +26,6 @@ export type RestoreAndWaitOptions = WaitForTransferOptions & {
      * complete `poller.onStart(restore)` and once after the restore
      * reaches a terminal state `poller.onStop(restore)`.
      */
-    waitPoller?: Poller<RestoreCreateResult>;
+    waitPoller?: Poller<RestoreCreateInfo>;
 };
 export declare function restoreAndWait(ctx: Pick<ResourceCtx, 'data' | 'platform'>, appIdentity: string, addonIdentity: string | undefined, backupUrl: string, options?: RestoreAndWaitOptions): Promise<TransferInfoByAppResult>;

package/dist/resources/data/{restore → transfer}/restore-and-wait.js

@@ -1,5 +1,5 @@
 import { resolvePgDatabase } from '../internal/resolve-pg-database.js';
-import { waitForTransfer } from '../wait-for-transfer.js';
+import { waitForTransfer } from './wait-for-transfer.js';
 export async function restoreAndWait(ctx, appIdentity, addonIdentity, backupUrl, options = {}) {
     const { extensions, restorePoller, signal, waitPoller } = options;
     signal?.throwIfAborted();

package/dist/resources/data/{wait-for-transfer.d.ts → transfer/wait-for-transfer.d.ts}

@@ -1,5 +1,5 @@
 import type { TransferInfoByAppResult } from '@heroku/types/data';
-import type { ResourceCtx } from '../../core/extend-resource.js';
+import type { ResourceCtx } from '../../../core/extend-resource.js';
 /**
  * Thrown by `waitForTransfer` when the transfer reaches a terminal state
  * with `succeeded: false`.
@@ -59,6 +59,6 @@ export type WaitForTransferOptions = {
  * if the transfer does not finish before timeout.
  */
 export declare function waitForTransfer(ctx: Pick<ResourceCtx, 'data'>, appIdentity: string, transferId: string, options?: WaitForTransferOptions): Promise<TransferInfoByAppResult>;
-export declare const transferExtensions: import("../../core/extend-resource.js").ResourceExtension<"data", "transfer", {
+export declare const transferExtensions: import("../../../core/extend-resource.js").ResourceExtension<"data", "transfer", {
     waitForTransfer: (appIdentity: string, transferId: string, options?: WaitForTransferOptions) => Promise<TransferInfoByAppResult>;
 }>;

package/dist/resources/data/{wait-for-transfer.js → transfer/wait-for-transfer.js}

@@ -1,5 +1,5 @@
-import { extendResource } from '../../core/extend-resource.js';
-import { wait } from '../../utils/wait.js';
+import { extendResource } from '../../../core/extend-resource.js';
+import { wait } from '../../../utils/wait.js';
 const DEFAULT_INTERVAL_MS = 3000;
 const MAX_FAILURES = 20;
 /**

package/dist/resources/data/transfer-schedule.d.ts

@@ -9,11 +9,11 @@ export type TransferSchedule = {
 export type TransferScheduleOptions = {
     signal?: AbortSignal;
 };
-export declare function list(ctx: Pick<ResourceCtx, 'data' | 'platform'>, appIdentity: string, addonIdentity?: string, options?: TransferScheduleOptions): Promise<TransferSchedule[]>;
+export declare function list(ctx: Pick<ResourceCtx, 'data' | 'platform'>, appIdentity: string, options?: TransferScheduleOptions): Promise<TransferSchedule[]>;
 export declare function create(ctx: Pick<ResourceCtx, 'data' | 'platform'>, appIdentity: string, addonIdentity: string | undefined, body: TransferScheduleCreateOpts, options?: TransferScheduleOptions): Promise<TransferScheduleCreateResult>;
 export declare function del(ctx: Pick<ResourceCtx, 'data' | 'platform'>, appIdentity: string, addonIdentity: string | undefined, scheduleId: string, options?: TransferScheduleOptions): Promise<TransferScheduleDeleteResult>;
 export declare const transferScheduleExtensions: import("../../core/extend-resource.js").ResourceExtension<"data", "transferSchedule", {
     create: (appIdentity: string, addonIdentity: string | undefined, body: TransferScheduleCreateOpts, options?: TransferScheduleOptions) => Promise<TransferScheduleCreateResult>;
     delete: (appIdentity: string, addonIdentity: string | undefined, scheduleId: string, options?: TransferScheduleOptions) => Promise<TransferScheduleDeleteResult>;
-    list: (appIdentity: string, addonIdentity?: string, options?: TransferScheduleOptions) => Promise<TransferSchedule[]>;
+    list: (appIdentity: string, options?: TransferScheduleOptions) => Promise<TransferSchedule[]>;
 }>;

package/dist/resources/data/transfer-schedule.js

@@ -1,14 +1,23 @@
 import { extendResource } from '../../core/extend-resource.js';
+import { getArbitraryLegacyDB } from './internal/postgres-utils.js';
 import { resolvePgDatabase } from './internal/resolve-pg-database.js';
-export async function list(ctx, appIdentity, addonIdentity, options = {}) {
+export async function list(ctx, appIdentity, options = {}) {
     options.signal?.throwIfAborted();
-    const addon = await resolvePgDatabase(ctx, { appIdentity, input: addonIdentity, ...options });
+    // Schedules are app-scoped, so any legacy DB ID unlocks the app's list.
+    const addon = await getArbitraryLegacyDB(ctx, appIdentity);
     return ctx.data.transferSchedule.list(addon.id);
 }
 export async function create(ctx, appIdentity, addonIdentity, body, options = {}) {
     options.signal?.throwIfAborted();
-    const addon = await resolvePgDatabase(ctx, { appIdentity, input: addonIdentity, ...options });
-    return ctx.data.transferSchedule.create(addon.id, body);
+    const { addon, attachment } = await resolvePgDatabase(ctx, {
+        appIdentity, includeAttachment: true, input: addonIdentity, ...options,
+    });
+    let requestBody = body;
+    if (!requestBody.schedule_name) {
+        // eslint-disable-next-line camelcase
+        requestBody = { ...body, schedule_name: `${attachment.name}_URL` };
+    }
+    return ctx.data.transferSchedule.create(addon.id, requestBody);
 }
 export async function del(ctx, appIdentity, addonIdentity, scheduleId, options = {}) {
     options.signal?.throwIfAborted();
@@ -18,5 +27,5 @@ export async function del(ctx, appIdentity, addonIdentity, scheduleId, options =
 export const transferScheduleExtensions = extendResource('data', 'transferSchedule', ctx => ({
     create: (appIdentity, addonIdentity, body, options) => create(ctx, appIdentity, addonIdentity, body, options),
     delete: (appIdentity, addonIdentity, scheduleId, options) => del(ctx, appIdentity, addonIdentity, scheduleId, options),
-    list: (appIdentity, addonIdentity, options) => list(ctx, appIdentity, addonIdentity, options),
+    list: (appIdentity, options) => list(ctx, appIdentity, options),
 }));

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

@@ -1,8 +1,6 @@
-export { backupExtensions } from '../data/backup/index.js';
 export { databaseExtensions } from '../data/database.js';
 export { maintenanceExtensions } from '../data/maintenance.js';
 export { postgresDatabaseExtensions } from '../data/postgres-database.js';
 export { redisExtensions } from '../data/redis/index.js';
-export { restoreExtensions } from '../data/restore/index.js';
 export { type TransferSchedule, transferScheduleExtensions } from '../data/transfer-schedule.js';
-export { transferExtensions, TransferFailedError, TransferTimeoutError, } from '../data/wait-for-transfer.js';
+export { backupExtensions, type CaptureAndWaitOptions, type RestoreAndWaitOptions, restoreExtensions, transferExtensions, TransferFailedError, TransferTimeoutError, type WaitForTransferOptions, } from '../data/transfer/index.js';

package/dist/resources/extensions/data.js

@@ -1,8 +1,6 @@
-export { backupExtensions } from '../data/backup/index.js';
 export { databaseExtensions } from '../data/database.js';
 export { maintenanceExtensions } from '../data/maintenance.js';
 export { postgresDatabaseExtensions } from '../data/postgres-database.js';
 export { redisExtensions } from '../data/redis/index.js';
-export { restoreExtensions } from '../data/restore/index.js';
 export { transferScheduleExtensions } from '../data/transfer-schedule.js';
-export { transferExtensions, TransferFailedError, TransferTimeoutError, } from '../data/wait-for-transfer.js';
+export { backupExtensions, restoreExtensions, transferExtensions, TransferFailedError, TransferTimeoutError, } from '../data/transfer/index.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heroku/sdk",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Heroku SDK",
   "author": "Heroku",
   "type": "module",
@@ -102,17 +102,13 @@
       "types": "./dist/resources/platform/vpn-connection/index.d.ts",
       "default": "./dist/resources/platform/vpn-connection/index.js"
     },
-    "./resources/data/backup": {
-      "types": "./dist/resources/data/backup/index.d.ts",
-      "default": "./dist/resources/data/backup/index.js"
-    },
     "./resources/data/redis": {
       "types": "./dist/resources/data/redis/index.d.ts",
       "default": "./dist/resources/data/redis/index.js"
     },
-    "./resources/data/restore": {
-      "types": "./dist/resources/data/restore/index.d.ts",
-      "default": "./dist/resources/data/restore/index.js"
+    "./resources/data/transfer": {
+      "types": "./dist/resources/data/transfer/index.d.ts",
+      "default": "./dist/resources/data/transfer/index.js"
     },
     "./resources/*": {
       "types": "./dist/resources/*.d.ts",

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

@@ -1,5 +0,0 @@
-import type { CaptureAndWaitOptions } from './capture-and-wait.js';
-export { captureAndWait, type CaptureAndWaitOptions } from './capture-and-wait.js';
-export declare const backupExtensions: import("../../../core/extend-resource.js").ResourceExtension<"data", "backup", {
-    captureAndWait: (appIdentity: string, addonIdentity?: string, options?: CaptureAndWaitOptions) => Promise<import("@heroku/types/data").TransferInfoByAppResult>;
-}>;

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

@@ -1,6 +0,0 @@
-import { extendResource } from '../../../core/extend-resource.js';
-import { captureAndWait } from './capture-and-wait.js';
-export { captureAndWait } from './capture-and-wait.js';
-export const backupExtensions = extendResource('data', 'backup', ctx => ({
-    captureAndWait: (appIdentity, addonIdentity, options) => captureAndWait(ctx, appIdentity, addonIdentity, options),
-}));

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

@@ -1,5 +0,0 @@
-import type { RestoreAndWaitOptions } from './restore-and-wait.js';
-export { restoreAndWait, type RestoreAndWaitOptions } from './restore-and-wait.js';
-export declare const restoreExtensions: import("../../../core/extend-resource.js").ResourceExtension<"data", "restore", {
-    restoreAndWait: (appIdentity: string, addonIdentity: string | undefined, backupUrl: string, options?: RestoreAndWaitOptions) => Promise<import("@heroku/types/data").TransferInfoByAppResult>;
-}>;

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

@@ -1,6 +0,0 @@
-import { extendResource } from '../../../core/extend-resource.js';
-import { restoreAndWait } from './restore-and-wait.js';
-export { restoreAndWait } from './restore-and-wait.js';
-export const restoreExtensions = extendResource('data', 'restore', ctx => ({
-    restoreAndWait: (appIdentity, addonIdentity, backupUrl, options) => restoreAndWait(ctx, appIdentity, addonIdentity, backupUrl, options),
-}));