@heroku/sdk 0.1.0-alpha.0

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

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

package/dist/resources/data/postgres.js

@@ -0,0 +1,10 @@
+import { extendResource } from '../../core/extend-resource.js';
+import { resolvePgDatabase } from './internal/resolve-pg-database.js';
+export async function info(ctx, appIdentity, addonIdentity, options = {}) {
+    options.signal?.throwIfAborted();
+    const addon = await resolvePgDatabase(ctx, { appIdentity, input: addonIdentity, ...options });
+    return ctx.data.postgres.info(addon.id);
+}
+export const postgresExtensions = extendResource('data', 'postgres', ctx => ({
+    info: (appIdentity, addonIdentity, options) => info(ctx, appIdentity, addonIdentity, options),
+}));

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

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

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

@@ -0,0 +1,10 @@
+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 const transferScheduleExtensions = extendResource('data', 'transferSchedule', ctx => ({
+    list: (appIdentity, addonIdentity, options) => list(ctx, appIdentity, addonIdentity, options),
+}));

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

@@ -0,0 +1,49 @@
+import type { ResourceCtx } from '../../core/extend-resource.js';
+export type TransferOptions = {
+    signal?: AbortSignal;
+};
+export type BackupTransfer = {
+    canceled_at: string;
+    created_at: string;
+    deleted_at: string;
+    finished_at: string;
+    from_name: string;
+    from_type: string;
+    from_url: string;
+    logs: Array<{
+        created_at: string;
+        level: string;
+        message: string;
+    }>;
+    num: number;
+    num_keep: number;
+    options: Record<string, unknown>;
+    processed_bytes: number;
+    purged_at: string;
+    schedule?: {
+        uuid: string;
+    };
+    source_bytes: number;
+    started_at: string;
+    succeeded: boolean;
+    to_name: string;
+    to_type: string;
+    to_url: string;
+    updated_at: string;
+    uuid: string;
+    warnings: number;
+};
+type TransferDataClient = {
+    transfer: {
+        listByApp(name: string): Promise<BackupTransfer[]>;
+    };
+};
+type TransferCtx = {
+    data: TransferDataClient;
+    platform: ResourceCtx['platform'];
+};
+export declare function listByApp(ctx: TransferCtx, appIdentity: string, addonIdentity?: string, options?: TransferOptions): Promise<BackupTransfer[]>;
+export declare const transferExtensions: import("../../core/extend-resource.js").ResourceExtension<"data", "transfer", {
+    listByApp: (appIdentity: string, addonIdentity?: string, options?: TransferOptions) => Promise<BackupTransfer[]>;
+}>;
+export {};

package/dist/resources/data/transfer.js

@@ -0,0 +1,14 @@
+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();
+    const addon = await resolvePgDatabase(ctx, { appIdentity, input: addonIdentity, ...options });
+    return ctx.data.transfer.listByApp(addon.id);
+}
+export const transferExtensions = extendResource('data', 'transfer', rawCtx => {
+    // Bridge heroku-types' loose client types to the adapter's strongly-typed contract
+    const ctx = rawCtx;
+    return {
+        listByApp: (appIdentity, addonIdentity, options) => listByApp(ctx, appIdentity, addonIdentity, options),
+    };
+});

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

@@ -0,0 +1,4 @@
+export { databaseExtensions } from '../data/database.js';
+export { maintenanceExtensions } from '../data/maintenance.js';
+export { postgresDatabaseExtensions } from '../data/postgres-database.js';
+export { transferExtensions } from '../data/transfer.js';

package/dist/resources/extensions/data.js

@@ -0,0 +1,4 @@
+export { databaseExtensions } from '../data/database.js';
+export { maintenanceExtensions } from '../data/maintenance.js';
+export { postgresDatabaseExtensions } from '../data/postgres-database.js';
+export { transferExtensions } from '../data/transfer.js';

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

@@ -0,0 +1,8 @@
+export { addOnExtensions } from '../platform/add-on/index.js';
+export { appExtensions, type AppInfo, type PipelineCouplingDetail } from '../platform/app/index.js';
+export { dynoExtensions } from '../platform/dyno/index.js';
+export { type AttachmentAttachedEvent, type AttachmentDetachedEvent, type AttachmentUpdatedEvent, type HerokuLogEvent, logSessionExtensions, parseHerokuLogLine, type ProvisioningCompletedEvent, type ScaledToEntry, type ScaledToEvent, type StartingProcessEvent, type StateChangedEvent, } from '../platform/log-session/index.js';
+export { pipelineCouplingExtensions } from '../platform/pipeline/coupling.js';
+export { pipelineExtensions } from '../platform/pipeline/index.js';
+export { pipelinePromotionExtensions } from '../platform/pipeline/promotion.js';
+export { privateToShield, shieldToPrivate } from '../platform/shield.js';

package/dist/resources/extensions/platform.js

@@ -0,0 +1,8 @@
+export { addOnExtensions } from '../platform/add-on/index.js';
+export { appExtensions } from '../platform/app/index.js';
+export { dynoExtensions } from '../platform/dyno/index.js';
+export { logSessionExtensions, parseHerokuLogLine, } from '../platform/log-session/index.js';
+export { pipelineCouplingExtensions } from '../platform/pipeline/coupling.js';
+export { pipelineExtensions } from '../platform/pipeline/index.js';
+export { pipelinePromotionExtensions } from '../platform/pipeline/promotion.js';
+export { privateToShield, shieldToPrivate } from '../platform/shield.js';

package/dist/resources/platform/add-on/create-and-wait.d.ts

@@ -0,0 +1,28 @@
+import type { AddOn, AddOnCreateOpts } from '@heroku/types/3.sdk';
+import type { ResourceCtx } from '../../../core/extend-resource.js';
+import type { CreateAndWaitOptions } from './types.js';
+/**
+ * Create an add-on and optionally wait for provisioning to complete.
+ *
+ * Wraps `addOn.create` with three pieces of orchestration:
+ *
+ *   - 423 `confirmation_required` from the platform is converted to a
+ *     typed `AddonConfirmationRequiredError`. Callers should catch
+ *     this, prompt the user for confirmation, and retry the call with
+ *     `body.confirm` set.
+ *   - When `wait: true` is set, polls `addOn.infoByApp` on a
+ *     `waitIntervalMs` cadence until the add-on's `state` is no longer
+ *     `provisioning`. Throws `AddonProvisioningFailedError` if the
+ *     terminal state is `deprovisioned`.
+ *   - `options.onProvisioning` fires once after the create response
+ *     when polling is about to begin, letting callers surface a
+ *     two-phase status display ("Created" → "Waiting").
+ *
+ * Both the create and poll calls are issued with `Accept-Expansion:
+ * addon_service,plan` so the response includes the full plan shape
+ * (price, unit, etc.). The create call additionally sets
+ * `X-Heroku-Legacy-Provider-Messages: true` to opt into
+ * provider-supplied `provision_message` text on the response — without
+ * it the platform silently omits that field.
+ */
+export declare function createAndWait(ctx: Pick<ResourceCtx, 'platform'>, appIdentity: string, body: AddOnCreateOpts, options?: CreateAndWaitOptions): Promise<AddOn>;

package/dist/resources/platform/add-on/create-and-wait.js

@@ -0,0 +1,63 @@
+import { HerokuApiError } from '@heroku/heroku-fetch';
+import { wait } from '../../../utils/wait.js';
+import { AddonConfirmationRequiredError, AddonProvisioningFailedError } from './errors.js';
+const DEFAULT_CREATE_WAIT_INTERVAL_MS = 5000;
+/**
+ * Create an add-on and optionally wait for provisioning to complete.
+ *
+ * Wraps `addOn.create` with three pieces of orchestration:
+ *
+ *   - 423 `confirmation_required` from the platform is converted to a
+ *     typed `AddonConfirmationRequiredError`. Callers should catch
+ *     this, prompt the user for confirmation, and retry the call with
+ *     `body.confirm` set.
+ *   - When `wait: true` is set, polls `addOn.infoByApp` on a
+ *     `waitIntervalMs` cadence until the add-on's `state` is no longer
+ *     `provisioning`. Throws `AddonProvisioningFailedError` if the
+ *     terminal state is `deprovisioned`.
+ *   - `options.onProvisioning` fires once after the create response
+ *     when polling is about to begin, letting callers surface a
+ *     two-phase status display ("Created" → "Waiting").
+ *
+ * Both the create and poll calls are issued with `Accept-Expansion:
+ * addon_service,plan` so the response includes the full plan shape
+ * (price, unit, etc.). The create call additionally sets
+ * `X-Heroku-Legacy-Provider-Messages: true` to opt into
+ * provider-supplied `provision_message` text on the response — without
+ * it the platform silently omits that field.
+ */
+export async function createAndWait(ctx, appIdentity, body, options = {}) {
+    options.signal?.throwIfAborted();
+    const platform = ctx.platform.withHeaders({ 'Accept-Expansion': 'addon_service,plan' });
+    let addon;
+    try {
+        addon = await platform
+            .withHeaders({ 'X-Heroku-Legacy-Provider-Messages': 'true' })
+            .addOn.create(appIdentity, body);
+    }
+    catch (error) {
+        if (error instanceof HerokuApiError && error.id === 'confirmation_required') {
+            throw new AddonConfirmationRequiredError(error.message);
+        }
+        throw error;
+    }
+    if (!options.wait || addon.state !== 'provisioning') {
+        if (addon.state === 'deprovisioned') {
+            throw new AddonProvisioningFailedError(addon);
+        }
+        return addon;
+    }
+    await options.onProvisioning?.(addon);
+    const intervalMs = options.waitIntervalMs ?? DEFAULT_CREATE_WAIT_INTERVAL_MS;
+    while (addon.state === 'provisioning') {
+        options.signal?.throwIfAborted();
+        // eslint-disable-next-line no-await-in-loop
+        await wait(intervalMs, options.signal);
+        // eslint-disable-next-line no-await-in-loop
+        addon = await platform.addOn.infoByApp(appIdentity, addon.name);
+    }
+    if (addon.state === 'deprovisioned') {
+        throw new AddonProvisioningFailedError(addon);
+    }
+    return addon;
+}

package/dist/resources/platform/add-on/debug.d.ts

@@ -0,0 +1,2 @@
+import createDebug from 'debug';
+export declare const debug: createDebug.Debugger;

package/dist/resources/platform/add-on/debug.js

@@ -0,0 +1,2 @@
+import createDebug from 'debug';
+export const debug = createDebug('heroku:sdk:resources:add-on');

package/dist/resources/platform/add-on/describe.d.ts

@@ -0,0 +1,20 @@
+import type { ResourceCtx } from '../../../core/extend-resource.js';
+import type { DescribedAddOn, ResolveAddonOptions } from './types.js';
+/**
+ * Resolve, describe, and decorate an add-on for display.
+ *
+ * - Resolves the add-on by identity (optionally scoped to an app).
+ * - Loads the add-on's attachments.
+ * - Returns a copy with `plan.price` set from `billed_price` (so the
+ *   value reflects any grandfathered/contract pricing).
+ *
+ * If `appIdentity` is provided and the platform returns 404 (resource
+ * `add_on`), the resolve falls back to a global lookup. This handles
+ * the case where the add-on belongs to a different app than the one
+ * supplied.
+ *
+ * Requests the `version=3.sdk` accept variant with `addon_service,plan`
+ * expansion so the resolved add-on includes the full `Plan` shape
+ * (`price.unit`, etc.) needed to render pricing.
+ */
+export declare function describeAddon(ctx: Pick<ResourceCtx, 'platform'>, addonIdentity: string, options?: ResolveAddonOptions): Promise<DescribedAddOn>;

package/dist/resources/platform/add-on/describe.js

@@ -0,0 +1,51 @@
+import { resolveAddonInternal } from './resolve.js';
+/**
+ * Resolve, describe, and decorate an add-on for display.
+ *
+ * - Resolves the add-on by identity (optionally scoped to an app).
+ * - Loads the add-on's attachments.
+ * - Returns a copy with `plan.price` set from `billed_price` (so the
+ *   value reflects any grandfathered/contract pricing).
+ *
+ * If `appIdentity` is provided and the platform returns 404 (resource
+ * `add_on`), the resolve falls back to a global lookup. This handles
+ * the case where the add-on belongs to a different app than the one
+ * supplied.
+ *
+ * Requests the `version=3.sdk` accept variant with `addon_service,plan`
+ * expansion so the resolved add-on includes the full `Plan` shape
+ * (`price.unit`, etc.) needed to render pricing.
+ */
+export async function describeAddon(ctx, addonIdentity, options = {}) {
+    options.signal?.throwIfAborted();
+    // Accept-Expansion is scoped to the resolve call (addOn.resolution
+    // serializer accepts addon_service + plan expansions). The
+    // /addons/:id/addon-attachments endpoint uses Accept-Inclusion, not
+    // Accept-Expansion, and rejects an unknown expansion header.
+    const resolvingPlatform = ctx.platform.withHeaders({
+        Accept: 'application/vnd.heroku+json; version=3.sdk',
+        'Accept-Expansion': 'addon_service,plan',
+    });
+    const addon = await resolveAddonInternal(resolvingPlatform, addonIdentity, {
+        addonService: options.addonService,
+        appIdentity: options.appIdentity,
+    });
+    options.signal?.throwIfAborted();
+    const attachments = await ctx.platform.addOnAttachment.listByAddOn(addon.id);
+    const plan = addon.plan;
+    return {
+        ...addon,
+        ...(plan && { plan: { ...plan, price: grandfatheredPrice(addon) } }),
+        attachments,
+    };
+}
+function grandfatheredPrice(addon) {
+    const price = addon.plan?.price;
+    return {
+        ...price,
+        ...(addon.billed_price && {
+            cents: addon.billed_price.cents,
+            contract: addon.billed_price.contract,
+        }),
+    };
+}

package/dist/resources/platform/add-on/errors.d.ts

@@ -0,0 +1,51 @@
+import type { AddOn } from '@heroku/types/3.sdk';
+export declare class AddonNotFoundError extends Error {
+    readonly resource: string;
+    readonly id = "not_found";
+    readonly statusCode = 404;
+    constructor(resource?: string);
+    get body(): {
+        id: string;
+        message: string;
+        resource: string;
+    };
+}
+export declare class AddonAmbiguousError extends Error {
+    readonly matches: AddOn[];
+    readonly id = "multiple_matches";
+    readonly statusCode = 422;
+    constructor(matches: AddOn[]);
+    get body(): {
+        id: string;
+        message: string;
+    };
+}
+/**
+ * Thrown by `createAndWait` when the Platform returns 423
+ * `confirmation_required`. Callers that want to prompt the user should
+ * catch this, gather a confirmation value, and retry the call with
+ * `body.confirm` set.
+ */
+export declare class AddonConfirmationRequiredError extends Error {
+    readonly platformMessage: string;
+    readonly id = "confirmation_required";
+    readonly statusCode = 423;
+    constructor(platformMessage: string);
+    get body(): {
+        id: string;
+        message: string;
+    };
+}
+/**
+ * Thrown by `createAndWait` when the Platform reports the add-on
+ * settled into a non-provisioned terminal state (e.g. `deprovisioned`).
+ */
+export declare class AddonProvisioningFailedError extends Error {
+    readonly addon: AddOn;
+    readonly id = "provisioning_failed";
+    constructor(addon: AddOn);
+    get body(): {
+        id: string;
+        message: string;
+    };
+}

package/dist/resources/platform/add-on/errors.js

@@ -0,0 +1,61 @@
+export class AddonNotFoundError extends Error {
+    resource;
+    id = 'not_found';
+    statusCode = 404;
+    constructor(resource = 'addon') {
+        super(`Couldn't find that ${resource}.`);
+        this.resource = resource;
+        this.name = 'AddonNotFoundError';
+    }
+    get body() {
+        return { id: this.id, message: this.message, resource: this.resource };
+    }
+}
+export class AddonAmbiguousError extends Error {
+    matches;
+    id = 'multiple_matches';
+    statusCode = 422;
+    constructor(matches) {
+        super(`Ambiguous identifier; multiple matching add-ons found: ${matches.map(m => m.name).join(', ')}.`);
+        this.matches = matches;
+        this.name = 'AddonAmbiguousError';
+    }
+    get body() {
+        return { id: this.id, message: this.message };
+    }
+}
+/**
+ * Thrown by `createAndWait` when the Platform returns 423
+ * `confirmation_required`. Callers that want to prompt the user should
+ * catch this, gather a confirmation value, and retry the call with
+ * `body.confirm` set.
+ */
+export class AddonConfirmationRequiredError extends Error {
+    platformMessage;
+    id = 'confirmation_required';
+    statusCode = 423;
+    constructor(platformMessage) {
+        super(platformMessage);
+        this.platformMessage = platformMessage;
+        this.name = 'AddonConfirmationRequiredError';
+    }
+    get body() {
+        return { id: this.id, message: this.message };
+    }
+}
+/**
+ * Thrown by `createAndWait` when the Platform reports the add-on
+ * settled into a non-provisioned terminal state (e.g. `deprovisioned`).
+ */
+export class AddonProvisioningFailedError extends Error {
+    addon;
+    id = 'provisioning_failed';
+    constructor(addon) {
+        super(`The add-on was unable to be created, with status ${addon.state}.`);
+        this.addon = addon;
+        this.name = 'AddonProvisioningFailedError';
+    }
+    get body() {
+        return { id: this.id, message: this.message };
+    }
+}

package/dist/resources/platform/add-on/index.d.ts

@@ -0,0 +1,23 @@
+import type { AddOnCreateOpts } from '@heroku/types/3.sdk';
+import type { ListPlansForAddonOptions } from './list-plans.js';
+import type { AddOnOptions, CreateAndWaitOptions, ResolveAddonOptions, UpgradeAddOnOptions } from './types.js';
+import { formatPlanPriceLabel, priceForPlan } from './pricing.js';
+export { createAndWait } from './create-and-wait.js';
+export { describeAddon } from './describe.js';
+export { AddonAmbiguousError, AddonConfirmationRequiredError, AddonNotFoundError, AddonProvisioningFailedError, } from './errors.js';
+export { listPlans, listPlansForAddon, type ListPlansForAddonOptions } from './list-plans.js';
+export { formatPlanPriceLabel, type FormatPlanPriceLabelOptions, type PlanPriceBreakdown, priceForPlan, } from './pricing.js';
+export { resolveAddon, resolveAddonByAttachment } from './resolve.js';
+export type { AddOnOptions, CreateAndWaitOptions, DescribedAddOn, ResolveAddonOptions, ResolvedAddOn, UpgradeAddOnOptions, } from './types.js';
+export { upgrade } from './upgrade.js';
+export declare const addOnExtensions: import("../../../core/extend-resource.js").ResourceExtension<"platform", "addOn", {
+    createAndWait: (appIdentity: string, body: AddOnCreateOpts, options?: CreateAndWaitOptions) => Promise<import("@heroku/types/3.sdk").AddOn>;
+    describe: (addonIdentity: string, options?: ResolveAddonOptions) => Promise<import("./types.js").DescribedAddOn>;
+    formatPlanPriceLabel: typeof formatPlanPriceLabel;
+    listPlans: (serviceIdentity: string, options?: AddOnOptions) => Promise<import("@heroku/types/3.sdk").Plan[]>;
+    listPlansForAddon: (addonIdentity: string, options?: ListPlansForAddonOptions) => Promise<import("@heroku/types/3.sdk").Plan[]>;
+    priceForPlan: typeof priceForPlan;
+    resolve: (addonIdentity: string, options?: ResolveAddonOptions) => Promise<import("./types.js").ResolvedAddOn>;
+    resolveByAttachment: (appIdentity: string, attachmentName: string, options?: AddOnOptions) => Promise<import("./types.js").ResolvedAddOn>;
+    upgrade: (addonIdentity: string, plan: string, options?: UpgradeAddOnOptions) => Promise<import("@heroku/types/3.sdk").AddOn>;
+}>;

package/dist/resources/platform/add-on/index.js

@@ -0,0 +1,25 @@
+import { extendResource } from '../../../core/extend-resource.js';
+import { createAndWait } from './create-and-wait.js';
+import { describeAddon } from './describe.js';
+import { listPlans, listPlansForAddon } from './list-plans.js';
+import { formatPlanPriceLabel, priceForPlan } from './pricing.js';
+import { resolveAddon, resolveAddonByAttachment } from './resolve.js';
+import { upgrade } from './upgrade.js';
+export { createAndWait } from './create-and-wait.js';
+export { describeAddon } from './describe.js';
+export { AddonAmbiguousError, AddonConfirmationRequiredError, AddonNotFoundError, AddonProvisioningFailedError, } from './errors.js';
+export { listPlans, listPlansForAddon } from './list-plans.js';
+export { formatPlanPriceLabel, priceForPlan, } from './pricing.js';
+export { resolveAddon, resolveAddonByAttachment } from './resolve.js';
+export { upgrade } from './upgrade.js';
+export const addOnExtensions = extendResource('platform', 'addOn', ctx => ({
+    createAndWait: (appIdentity, body, options) => createAndWait(ctx, appIdentity, body, options),
+    describe: (addonIdentity, options) => describeAddon(ctx, addonIdentity, options),
+    formatPlanPriceLabel,
+    listPlans: (serviceIdentity, options) => listPlans(ctx, serviceIdentity, options),
+    listPlansForAddon: (addonIdentity, options) => listPlansForAddon(ctx, addonIdentity, options),
+    priceForPlan,
+    resolve: (addonIdentity, options) => resolveAddon(ctx, addonIdentity, options),
+    resolveByAttachment: (appIdentity, attachmentName, options) => resolveAddonByAttachment(ctx, appIdentity, attachmentName, options),
+    upgrade: (addonIdentity, plan, options) => upgrade(ctx, addonIdentity, plan, options),
+}));

package/dist/resources/platform/add-on/list-plans.d.ts

@@ -0,0 +1,34 @@
+import type { Plan } from '@heroku/types/3.sdk';
+import type { ResourceCtx } from '../../../core/extend-resource.js';
+import type { AddOnOptions, ResolveAddonOptions } from './types.js';
+/**
+ * Subset of {@link ResolveAddonOptions} accepted by
+ * {@link listPlansForAddon}. The `addonService` filter is intentionally
+ * omitted: once you've pinned an add-on identity, filtering its
+ * resolution by service name is nonsensical.
+ */
+export type ListPlansForAddonOptions = Pick<ResolveAddonOptions, 'appIdentity' | 'signal'>;
+/**
+ * List the plans available for an add-on service, sorted ascending by
+ * `price.cents`. Plans without a price (or with equal prices) are
+ * returned later in the list.
+ */
+export declare function listPlans(ctx: Pick<ResourceCtx, 'platform'>, serviceIdentity: string, options?: AddOnOptions): Promise<Plan[]>;
+/**
+ * List the plans available for the add-on service of an existing
+ * add-on, sorted ascending by `price.cents`.
+ *
+ * Convenience wrapper that resolves the add-on first to look up its
+ * `addon_service.name`, then delegates to `listPlans`. Saves callers
+ * the dance of fetching the add-on, plucking its service id/name, and
+ * passing it through.
+ *
+ * `addonIdentity` accepts the same forms as `resolveAddon`:
+ *   - a UUID
+ *   - a globally-unique add-on name
+ *   - a namespaced credential reference (`name::SECONDARY`)
+ *
+ * Pass `appIdentity` via `options` when the add-on identity is
+ * scoped to an app (same semantics as `resolveAddon`).
+ */
+export declare function listPlansForAddon(ctx: Pick<ResourceCtx, 'platform'>, addonIdentity: string, options?: ListPlansForAddonOptions): Promise<Plan[]>;

package/dist/resources/platform/add-on/list-plans.js

@@ -0,0 +1,53 @@
+import { AddonNotFoundError } from './errors.js';
+import { resolveAddonInternal } from './resolve.js';
+/**
+ * List the plans available for an add-on service, sorted ascending by
+ * `price.cents`. Plans without a price (or with equal prices) are
+ * returned later in the list.
+ */
+export async function listPlans(ctx, serviceIdentity, options = {}) {
+    options.signal?.throwIfAborted();
+    const plans = await ctx.platform.plan.listByAddOn(serviceIdentity);
+    return [...plans].sort(byPriceCentsAsc);
+}
+/**
+ * List the plans available for the add-on service of an existing
+ * add-on, sorted ascending by `price.cents`.
+ *
+ * Convenience wrapper that resolves the add-on first to look up its
+ * `addon_service.name`, then delegates to `listPlans`. Saves callers
+ * the dance of fetching the add-on, plucking its service id/name, and
+ * passing it through.
+ *
+ * `addonIdentity` accepts the same forms as `resolveAddon`:
+ *   - a UUID
+ *   - a globally-unique add-on name
+ *   - a namespaced credential reference (`name::SECONDARY`)
+ *
+ * Pass `appIdentity` via `options` when the add-on identity is
+ * scoped to an app (same semantics as `resolveAddon`).
+ */
+export async function listPlansForAddon(ctx, addonIdentity, options = {}) {
+    options.signal?.throwIfAborted();
+    const addon = await resolveAddonInternal(ctx.platform, addonIdentity, {
+        appIdentity: options.appIdentity,
+    });
+    // The route accepts either name or id; name is stable across
+    // environments and easier to identify in logs.
+    const serviceName = addon.addon_service?.name;
+    if (!serviceName) {
+        // The resolve found the add-on but the response was missing the
+        // service info we need to look up plans. Treat this as not-found
+        // for the caller's purpose (they wanted a plans list and we
+        // can't produce one).
+        throw new AddonNotFoundError();
+    }
+    return listPlans(ctx, serviceName, options);
+}
+function byPriceCentsAsc(a, b) {
+    return sortableCents(a) - sortableCents(b);
+}
+function sortableCents(plan) {
+    const cents = plan.price?.cents;
+    return typeof cents === 'number' ? cents : Number.MAX_SAFE_INTEGER;
+}

package/dist/resources/platform/add-on/pricing.d.ts

@@ -0,0 +1,72 @@
+import type { Plan } from '@heroku/types/3.sdk';
+export type PlanPriceBreakdown = {
+    /** raw price as reported by the API, in cents */
+    cents: number;
+    /** True when the price is negotiated outside monthly add-on billing */
+    contract: boolean;
+    /** True when the price is billed per use rather than at a fixed cadence */
+    metered: boolean;
+    /**
+     * Equivalent hourly cost in cents (may be fractional). Equal to
+     * `cents` when `unit` is `'hour'`; computed as `cents /
+     * HOURS_PER_MONTH` when `unit` is `'month'`. `undefined` when the
+     * unit is anything else — callers can omit the per-hour label
+     * rather than render misleading numbers.
+     */
+    perHourCents: number | undefined;
+    /**
+     * Equivalent monthly cost in cents. Equal to `cents` when `unit` is
+     * `'month'`; computed as `cents * HOURS_PER_MONTH` when `unit` is
+     * `'hour'`. `undefined` when the unit is anything else.
+     */
+    perMonthCents: number | undefined;
+    /** unit reported by the API (e.g. `'month'`, `'hour'`) */
+    unit: string;
+};
+/**
+ * Break a plan's price down into monthly- and hourly-equivalent
+ * cents, normalizing across the API's billing unit. Consumers that
+ * display "max $X/month (~$Y/hour)" labels should call this rather
+ * than dividing `cents` by hours themselves; centralizing the math
+ * keeps the 30-day-month assumption (Heroku's documented convention)
+ * in one place.
+ *
+ * Returns `undefined` if the plan has no usable `price.cents` value.
+ * `Plan.price` is typed as optional in `@heroku/types`, and consumers
+ * occasionally receive partial responses depending on the Accept
+ * variant.
+ *
+ * `perMonthCents` and `perHourCents` are themselves `undefined` when
+ * the API reports a unit other than `'month'` or `'hour'` — callers
+ * should omit those parts of their label rather than show fabricated
+ * numbers.
+ *
+ * @param plan The plan to break down. Pass the whole `Plan` rather
+ *   than just `plan.price` so the helper can pick up future fields
+ *   without API churn at call sites.
+ */
+export declare function priceForPlan(plan: Plan): PlanPriceBreakdown | undefined;
+export type FormatPlanPriceLabelOptions = {
+    /** ISO 4217 currency code passed to `Intl.NumberFormat`. Default: `'USD'`. */
+    currency?: string;
+    /** BCP 47 locale tag passed to `Intl.NumberFormat`. Default: `'en-US'`. */
+    locale?: string;
+};
+/**
+ * Format a plan's price as a human-readable suffix:
+ * `"$0.007 / hour (Max $5/month)"`. Returns an empty string when the
+ * plan has no displayable price (no `price.cents`, an unknown unit,
+ * a metered plan, or a contract-priced plan) — callers can compose
+ * their final label as `${name}${suffix ? ' - ' + suffix : ''}`
+ * without per-call defensive checks.
+ *
+ * Locale and currency default to `'en-US'` / `'USD'`. Pass options
+ * to override.
+ *
+ * @example
+ * ```ts
+ * const suffix = formatPlanPriceLabel(plan);
+ * const label = suffix ? `${plan.human_name} - ${suffix}` : plan.human_name;
+ * ```
+ */
+export declare function formatPlanPriceLabel(plan: Plan, options?: FormatPlanPriceLabelOptions): string;