@heroku/sdk 0.6.4 → 0.7.0

package/dist/resources/data/backup/capture-and-wait.d.ts

@@ -0,0 +1,19 @@
+import type { BackupCreateResult, TransferInfoByAppResult } from '@heroku/types/data';
+import type { ResourceCtx } from '../../../core/extend-resource.js';
+import type { ResolvedAddOn } from '../../platform/add-on/index.js';
+import type { WaitForTransferOptions } from '../wait-for-transfer.js';
+import { Poller } from '../../../utils/poller.js';
+export type CaptureAndWaitOptions = WaitForTransferOptions & {
+    /**
+     * Progress hooks fired once before capturing the backup `poller.onStart(addon)`
+     * and once after the backup is created `poller.onStop(addon)`.
+     */
+    capturePoller?: Poller<ResolvedAddOn>;
+    /**
+     * Progress hooks fired once before waiting for the transfer to
+     * complete `poller.onStart(backup)` and once after the transfer
+     * finishes successfully `poller.onStop(backup)`.
+     */
+    waitPoller?: Poller<BackupCreateResult>;
+};
+export declare function captureAndWait(ctx: Pick<ResourceCtx, 'data' | 'platform'>, appIdentity: string, addonIdentity?: string, options?: CaptureAndWaitOptions): Promise<TransferInfoByAppResult>;

package/dist/resources/data/backup/capture-and-wait.js

@@ -0,0 +1,14 @@
+import { resolvePgDatabase } from '../internal/resolve-pg-database.js';
+import { waitForTransfer } from '../wait-for-transfer.js';
+export async function captureAndWait(ctx, appIdentity, addonIdentity, options = {}) {
+    const { capturePoller, signal, waitPoller } = options;
+    signal?.throwIfAborted();
+    const addon = await resolvePgDatabase(ctx, { appIdentity, input: addonIdentity, ...options });
+    capturePoller?.onStart?.(addon);
+    const backup = await ctx.data.backup.create(addon.id);
+    capturePoller?.onStop?.(addon);
+    waitPoller?.onStart?.(backup);
+    const transfer = await waitForTransfer(ctx, addon.app.name, backup.uuid, options);
+    waitPoller?.onStop?.(backup);
+    return transfer;
+}

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

@@ -0,0 +1,5 @@
+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

@@ -0,0 +1,6 @@
+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

@@ -0,0 +1,5 @@
+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

@@ -0,0 +1,6 @@
+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),
+}));

package/dist/resources/data/restore/restore-and-wait.d.ts

@@ -0,0 +1,24 @@
+import type { RestoreCreateResult, TransferInfoByAppResult } from '@heroku/types/data';
+import type { ResourceCtx } from '../../../core/extend-resource.js';
+import type { ResolvedAddOn } from '../../platform/add-on/index.js';
+import type { WaitForTransferOptions } from '../wait-for-transfer.js';
+import { Poller } from '../../../utils/poller.js';
+export type RestoreAndWaitOptions = WaitForTransferOptions & {
+    /**
+     * Extension names to preinstall on the restore target.
+     */
+    extensions?: string[];
+    /**
+     * Progress hooks fired once before creating the restore
+     * `poller.onStart(addon)` and once after the restore is
+     * created `poller.onStop(addon)`.
+     */
+    restorePoller?: Poller<ResolvedAddOn>;
+    /**
+     * Progress hooks fired once before waiting for the restore to
+     * complete `poller.onStart(restore)` and once after the restore
+     * reaches a terminal state `poller.onStop(restore)`.
+     */
+    waitPoller?: Poller<RestoreCreateResult>;
+};
+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/restore-and-wait.js

@@ -0,0 +1,15 @@
+import { resolvePgDatabase } from '../internal/resolve-pg-database.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();
+    const addon = await resolvePgDatabase(ctx, { appIdentity, input: addonIdentity, ...options });
+    restorePoller?.onStart?.(addon);
+    // eslint-disable-next-line camelcase
+    const restore = await ctx.data.restore.create(addon.id, { backup_url: backupUrl, extensions });
+    restorePoller?.onStop?.(addon);
+    waitPoller?.onStart?.(restore);
+    const transfer = await waitForTransfer(ctx, addon.app.name, restore.uuid, options);
+    waitPoller?.onStop?.(restore);
+    return transfer;
+}

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

@@ -0,0 +1,19 @@
+import type { TransferScheduleCreateOpts, TransferScheduleCreateResult, TransferScheduleDeleteResult } from '@heroku/types/data';
+import type { ResourceCtx } from '../../core/extend-resource.js';
+export type TransferSchedule = {
+    hour: number;
+    name: string;
+    timezone: string;
+    uuid: string;
+};
+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 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[]>;
+}>;

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

@@ -0,0 +1,22 @@
+import { extendResource } from '../../core/extend-resource.js';
+import { resolvePgDatabase } from './internal/resolve-pg-database.js';
+export async function list(ctx, appIdentity, addonIdentity, options = {}) {
+    options.signal?.throwIfAborted();
+    const addon = await resolvePgDatabase(ctx, { appIdentity, input: addonIdentity, ...options });
+    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);
+}
+export async function del(ctx, appIdentity, addonIdentity, scheduleId, options = {}) {
+    options.signal?.throwIfAborted();
+    const addon = await resolvePgDatabase(ctx, { appIdentity, input: addonIdentity, ...options });
+    return ctx.data.transferSchedule.delete(addon.id, scheduleId);
+}
+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),
+}));

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

@@ -0,0 +1,64 @@
+import type { TransferInfoByAppResult } from '@heroku/types/data';
+import type { ResourceCtx } from '../../core/extend-resource.js';
+/**
+ * Thrown by `waitForTransfer` when the transfer reaches a terminal state
+ * with `succeeded: false`.
+ */
+export declare class TransferFailedError extends Error {
+    readonly transfer: TransferInfoByAppResult;
+    readonly id = "transfer_failed";
+    constructor(transfer: TransferInfoByAppResult);
+    get body(): {
+        id: string;
+        message: string;
+    };
+}
+/**
+ * Thrown by `waitForTransfer` when `timeoutMs` elapses before the
+ * transfer reaches a terminal state.
+ */
+export declare class TransferTimeoutError extends Error {
+    readonly transferId: string;
+    readonly timeoutMs: number;
+    readonly id = "transfer_timeout";
+    constructor(transferId: string, timeoutMs: number);
+    get body(): {
+        id: string;
+        message: string;
+    };
+}
+export type WaitForTransferOptions = {
+    /**
+     * Polling interval in milliseconds. Defaults to 3000 (3s)
+     */
+    intervalMs?: number;
+    /**
+     * Fired after every wait poll with the latest transfer record,
+     * letting callers drive a status display.
+     */
+    onPoll?: (transfer: TransferInfoByAppResult | undefined) => void;
+    /**
+     * Abort signal to cancel the operation.
+     */
+    signal?: AbortSignal;
+    /**
+     * Maximum total time to wait before throwing `TransferTimeoutError`.
+     * If omitted, polls until the transfer finishes or `signal` aborts.
+     */
+    timeoutMs?: number;
+    /**
+     * Fetch full log lines when `true`.
+     */
+    verbose?: boolean;
+};
+/**
+ * Poll `data.transfer.infoByApp` until the transfer reaches a terminal
+ * state (`finished_at` set).
+ *
+ * Throws `TransferFailedError` if the transfer fails or `TransferTimeoutError`
+ * 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", {
+    waitForTransfer: (appIdentity: string, transferId: string, options?: WaitForTransferOptions) => Promise<TransferInfoByAppResult>;
+}>;

package/dist/resources/data/wait-for-transfer.js

@@ -0,0 +1,80 @@
+import { extendResource } from '../../core/extend-resource.js';
+import { wait } from '../../utils/wait.js';
+const DEFAULT_INTERVAL_MS = 3000;
+const MAX_FAILURES = 20;
+/**
+ * Thrown by `waitForTransfer` when the transfer reaches a terminal state
+ * with `succeeded: false`.
+ */
+export class TransferFailedError extends Error {
+    transfer;
+    id = 'transfer_failed';
+    constructor(transfer) {
+        super('An error occurred and the transfer did not finish.');
+        this.transfer = transfer;
+        this.name = 'TransferFailedError';
+    }
+    get body() {
+        return { id: this.id, message: this.message };
+    }
+}
+/**
+ * Thrown by `waitForTransfer` when `timeoutMs` elapses before the
+ * transfer reaches a terminal state.
+ */
+export class TransferTimeoutError extends Error {
+    transferId;
+    timeoutMs;
+    id = 'transfer_timeout';
+    constructor(transferId, timeoutMs) {
+        super(`Transfer '${transferId}' did not finish within ${timeoutMs}ms`);
+        this.transferId = transferId;
+        this.timeoutMs = timeoutMs;
+        this.name = 'TransferTimeoutError';
+    }
+    get body() {
+        return { id: this.id, message: this.message };
+    }
+}
+/**
+ * Poll `data.transfer.infoByApp` until the transfer reaches a terminal
+ * state (`finished_at` set).
+ *
+ * Throws `TransferFailedError` if the transfer fails or `TransferTimeoutError`
+ * if the transfer does not finish before timeout.
+ */
+export async function waitForTransfer(ctx, appIdentity, transferId, options = {}) {
+    const { intervalMs = DEFAULT_INTERVAL_MS, onPoll, signal, timeoutMs, verbose, } = options;
+    signal?.throwIfAborted();
+    const data = signal ? ctx.data.withOptions({ signal }) : ctx.data;
+    const deadline = timeoutMs === undefined ? undefined : Date.now() + timeoutMs;
+    let failures = 0;
+    let transfer;
+    while (true) {
+        signal?.throwIfAborted();
+        try {
+            transfer = await data.transfer.infoByApp(appIdentity, transferId, { verbose });
+        }
+        catch (error) {
+            failures++;
+            if (failures > MAX_FAILURES) {
+                throw error;
+            }
+        }
+        onPoll?.(transfer);
+        if (transfer?.finished_at) {
+            if (transfer.succeeded) {
+                return transfer;
+            }
+            const verboseTransfer = verbose ? transfer : await data.transfer.infoByApp(appIdentity, transferId, { verbose: true });
+            throw new TransferFailedError(verboseTransfer);
+        }
+        if (deadline !== undefined && Date.now() >= deadline) {
+            throw new TransferTimeoutError(transferId, timeoutMs);
+        }
+        await wait(intervalMs, signal);
+    }
+}
+export const transferExtensions = extendResource('data', 'transfer', ctx => ({
+    waitForTransfer: (appIdentity, transferId, options) => waitForTransfer(ctx, appIdentity, transferId, options),
+}));

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

@@ -1,5 +1,8 @@
+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 { transferExtensions } from '../data/transfer.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';

package/dist/resources/extensions/data.js

@@ -1,5 +1,8 @@
+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 { transferExtensions } from '../data/transfer.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';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heroku/sdk",
-  "version": "0.6.4",
+  "version": "0.7.0",
   "description": "Heroku SDK",
   "author": "Heroku",
   "type": "module",
@@ -98,10 +98,18 @@
       "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/*": {
       "types": "./dist/resources/*.d.ts",
       "default": "./dist/resources/*.js"

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

@@ -1,9 +0,0 @@
-import type { TransferListByAppResult } from '@heroku/types/data';
-import type { ResourceCtx } from '../../core/extend-resource.js';
-export type TransferOptions = {
-    signal?: AbortSignal;
-};
-export declare function listByApp(ctx: Pick<ResourceCtx, 'data' | 'platform'>, appIdentity: string, addonIdentity?: string, options?: TransferOptions): Promise<TransferListByAppResult>;
-export declare const transferExtensions: import("../../core/extend-resource.js").ResourceExtension<"data", "transfer", {
-    listByApp: (appIdentity: string, addonIdentity?: string, options?: TransferOptions) => Promise<TransferListByAppResult>;
-}>;

package/dist/resources/data/transfer.js

@@ -1,19 +0,0 @@
-import { extendResource } from '../../core/extend-resource.js';
-import { resolvePgDatabase } from './internal/resolve-pg-database.js';
-export async function listByApp(ctx, appIdentity, addonIdentity, options = {}) {
-    options.signal?.throwIfAborted();
-    let addon;
-    try {
-        addon = await resolvePgDatabase(ctx, { appIdentity, input: addonIdentity, ...options });
-    }
-    catch (error) {
-        if (error instanceof Error && 'statusCode' in error && error.statusCode === 404) {
-            return [];
-        }
-        throw error;
-    }
-    return ctx.data.transfer.listByApp(addon.id);
-}
-export const transferExtensions = extendResource('data', 'transfer', ctx => ({
-    listByApp: (appIdentity, addonIdentity, options) => listByApp(ctx, appIdentity, addonIdentity, options),
-}));