@heroku/sdk 0.1.0-beta.0

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

@@ -0,0 +1,354 @@
+import { HerokuApiError, NotFoundError } from '@heroku/heroku-fetch';
+import createDebug from 'debug';
+import { extendResource } from '../../core/extend-resource.js';
+const debug = createDebug('heroku:sdk:resources:add-on');
+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 };
+    }
+}
+/**
+ * Change the plan of an add-on.
+ *
+ * Resolves the add-on first so the caller can pass any identifier
+ * (UUID, globally unique name, or namespaced `service::name`). When
+ * `appIdentity` is provided, the resolve is scoped to that app and
+ * falls back to a global resolve if the platform returns 404 add_on.
+ *
+ * If `plan` is unqualified (no `:`), it's prefixed with the resolved
+ * add-on's `addon_service.name` — so callers can pass `hobby` rather
+ * than `heroku-redis:hobby` if they don't already know the service.
+ *
+ * `options.onResolved` fires after the resolve and before the update,
+ * receiving the resolved add-on. Useful for surfacing pre-update
+ * state (the add-on's current plan, app, etc.) without an extra
+ * round-trip.
+ */
+export async function upgrade(ctx, addonIdentity, plan, options = {}) {
+    options.signal?.throwIfAborted();
+    const addon = await resolveAddonInternal(ctx.platform, addonIdentity, {
+        addonService: options.addonService,
+        appIdentity: options.appIdentity,
+    });
+    await options.onResolved?.(addon);
+    options.signal?.throwIfAborted();
+    const qualifiedPlan = plan.includes(':')
+        ? plan
+        : `${addon.addon_service?.name}:${plan}`;
+    if (qualifiedPlan !== plan) {
+        debug('upgrade plan qualified plan=%s qualified=%s', plan, qualifiedPlan);
+    }
+    debug('upgrade addon=%s app=%s plan=%s', addon.id, addon.app.id, qualifiedPlan);
+    return ctx.platform.addOn.update(addon.app.id, addon.id, { plan: qualifiedPlan });
+}
+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;
+}
+function wait(ms, signal) {
+    return new Promise((resolve, reject) => {
+        function onAbort() {
+            clearTimeout(timer);
+            reject(signal.reason ?? new Error('Aborted'));
+        }
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        if (signal) {
+            if (signal.aborted) {
+                clearTimeout(timer);
+                reject(signal.reason ?? new Error('Aborted'));
+                return;
+            }
+            signal.addEventListener('abort', onAbort, { once: true });
+        }
+    });
+}
+/**
+ * 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);
+}
+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;
+}
+/**
+ * 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,
+    };
+}
+/**
+ * Resolve a Platform add-on by identity.
+ *
+ * The add-on identity may be:
+ *   - a UUID (`d5e3f2a4-...`)
+ *   - a globally-unique name (`postgres-curved-12345`)
+ *   - a namespaced credential reference (`postgres-curved-12345::SECONDARY`)
+ *
+ * When `appIdentity` is provided, the resolve is scoped to that app first
+ * and falls back to a global resolve if the platform returns 404 add_on.
+ * Namespaced identities (containing `::`) skip the app-scoped lookup
+ * because they are globally unique.
+ *
+ * `addonService` (e.g. `heroku-postgresql`) is filtered client-side after
+ * the resolve. The platform's server-side `addon_service` filter excludes
+ * alpha add-ons, so we don't pass it through.
+ *
+ * Errors:
+ *   - throws `AddonNotFoundError` if no match is found
+ *   - throws `AddonAmbiguousError` if multiple matches remain after filtering
+ *
+ * For attachment-based resolution (e.g. `DATABASE_URL` on a particular
+ * app), use `resolveAddonByAttachment` instead.
+ */
+export async function resolveAddon(ctx, addonIdentity, options = {}) {
+    options.signal?.throwIfAborted();
+    return resolveAddonInternal(ctx.platform, addonIdentity, options);
+}
+/**
+ * Resolve a Platform add-on via one of its attachments on a given app.
+ *
+ * Use this when you have an attachment name (e.g. `DATABASE_URL`,
+ * `HEROKU_POSTGRESQL_GREEN`) on a known app, rather than an add-on
+ * identity. Calls `addOnAttachment.resolution` and returns the add-on
+ * the matched attachment points to.
+ *
+ * For resolving by add-on identity, use `resolveAddon`.
+ */
+export async function resolveAddonByAttachment(ctx, appIdentity, attachmentName, options = {}) {
+    options.signal?.throwIfAborted();
+    debug('resolveByAttachment app=%s attachment=%s', appIdentity, attachmentName);
+    const matches = await ctx.platform.addOnAttachment.resolution({
+        // eslint-disable-next-line camelcase
+        addon_attachment: attachmentName,
+        app: appIdentity,
+    });
+    const attachment = matches[0];
+    const addon = attachment?.addon;
+    if (!addon?.id || !addon.app?.id) {
+        debug('resolveByAttachment matches=%d (no usable add-on returned)', matches.length);
+        throw new AddonNotFoundError();
+    }
+    debug('resolveByAttachment resolved addon=%s app=%s', addon.id, addon.app.id);
+    return addon;
+}
+async function resolveAddonInternal(platform, addonIdentity, options = {}) {
+    const { addonService, appIdentity } = options;
+    const resolveBy = async (app) => {
+        const body = app ? { addon: addonIdentity, app } : { addon: addonIdentity };
+        debug('resolve addon=%s app=%s service=%s', addonIdentity, app ?? '<global>', addonService ?? '<any>');
+        const matches = await platform.addOn.resolution(body);
+        const filtered = addonService
+            ? matches.filter(addon => addon.addon_service?.name === addonService)
+            : matches;
+        debug('resolve matches=%d filtered=%d (service=%s)', matches.length, filtered.length, addonService ?? '<any>');
+        const resolvedAddon = singularize(filtered);
+        debug('resolve resolved addon=%s app=%s', resolvedAddon.id, resolvedAddon.app.id);
+        return resolvedAddon;
+    };
+    if (!appIdentity || addonIdentity.includes('::')) {
+        debug('resolve scope=global reason=%s', appIdentity ? 'namespaced-identity' : 'no-app');
+        return resolveBy();
+    }
+    try {
+        return await resolveBy(appIdentity);
+    }
+    catch (error) {
+        if (isAddOnNotFound(error)) {
+            debug('resolve app-scope 404 add_on, falling back to global addon=%s', addonIdentity);
+            return resolveBy();
+        }
+        throw error;
+    }
+}
+function isAddOnNotFound(error) {
+    return error instanceof NotFoundError && error.resource === 'add_on';
+}
+function singularize(matches) {
+    if (matches.length === 0) {
+        throw new AddonNotFoundError();
+    }
+    if (matches.length > 1) {
+        throw new AddonAmbiguousError(matches);
+    }
+    const match = matches[0];
+    if (!match.id || !match.app?.id) {
+        throw new Error(`Resolved add-on is missing required fields (id=${match.id}, app.id=${match.app?.id})`);
+    }
+    return match;
+}
+function grandfatheredPrice(addon) {
+    const price = addon.plan?.price;
+    return {
+        ...price,
+        ...(addon.billed_price && {
+            cents: addon.billed_price.cents,
+            contract: addon.billed_price.contract,
+        }),
+    };
+}
+export const addOnExtensions = extendResource('platform', 'addOn', ctx => ({
+    createAndWait: (appIdentity, body, options) => createAndWait(ctx, appIdentity, body, options),
+    describe: (addonIdentity, options) => describeAddon(ctx, addonIdentity, options),
+    listPlans: (serviceIdentity, options) => listPlans(ctx, serviceIdentity, options),
+    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/app/index.d.ts

@@ -0,0 +1,58 @@
+import type { App } from '@heroku/types/3.sdk';
+import type { ResourceCtx } from '../../../core/extend-resource.js';
+import type { DescribeAppOptions } from './info.js';
+export { type AppInfo, describeApp, type DescribeAppOptions, type PipelineCouplingDetail, } from './info.js';
+export type AppMaintenanceOptions = {
+    signal?: AbortSignal;
+};
+export type GenerationKind = 'cedar' | 'fir';
+export type GetGenerationOptions = {
+    signal?: AbortSignal;
+};
+export type IsShieldedOptions = {
+    signal?: AbortSignal;
+};
+export type GetProcessTierOptions = {
+    signal?: AbortSignal;
+};
+export type ProcessTier = 'basic' | 'eco' | 'performance' | 'private' | 'shield' | 'standard' | (string & {});
+export declare function enableMaintenance(ctx: Pick<ResourceCtx, 'platform'>, appIdentity: string, options?: AppMaintenanceOptions): Promise<App>;
+export declare function disableMaintenance(ctx: Pick<ResourceCtx, 'platform'>, appIdentity: string, options?: AppMaintenanceOptions): Promise<App>;
+/**
+ * Look up the platform generation (`cedar` or `fir`) of an app.
+ *
+ * Issues `app.info` with the `version=3.sdk` Accept variant so the
+ * response includes the `generation` field, then normalizes the
+ * platform's strings to the `'cedar' | 'fir'` union. Returns
+ * `undefined` if the platform reports an unrecognized value (e.g. a
+ * future generation name we haven't taught the SDK about).
+ */
+export declare function getGeneration(ctx: Pick<ResourceCtx, 'platform'>, appIdentity: string, options?: GetGenerationOptions): Promise<GenerationKind | undefined>;
+type AppInfoResult = App & {
+    process_tier?: string;
+    space?: null | {
+        shield?: boolean;
+    };
+};
+type AppInfoPlatform = {
+    app: {
+        info(appIdentity: string): Promise<AppInfoResult>;
+    };
+    withOptions(opts: {
+        signal: AbortSignal;
+    }): AppInfoPlatform;
+};
+export declare function isShielded(ctx: {
+    platform: AppInfoPlatform;
+}, appIdentity: string, options?: IsShieldedOptions): Promise<boolean>;
+export declare function getProcessTier(ctx: {
+    platform: AppInfoPlatform;
+}, appIdentity: string, options?: GetProcessTierOptions): Promise<ProcessTier | undefined>;
+export declare const appExtensions: import("../../../index.js").ResourceExtension<"platform", "app", {
+    describe: (appIdentity: string, options?: DescribeAppOptions) => Promise<import("./info.js").AppInfo>;
+    disableMaintenance: (appIdentity: string, options?: AppMaintenanceOptions) => Promise<App>;
+    enableMaintenance: (appIdentity: string, options?: AppMaintenanceOptions) => Promise<App>;
+    getGeneration: (appIdentity: string, options?: GetGenerationOptions) => Promise<GenerationKind | undefined>;
+    getProcessTier: (appIdentity: string, options?: GetProcessTierOptions) => Promise<ProcessTier | undefined>;
+    isShielded: (appIdentity: string, options?: IsShieldedOptions) => Promise<boolean>;
+}>;

package/dist/resources/platform/app/index.js

@@ -0,0 +1,53 @@
+import { extendResource } from '../../../core/extend-resource.js';
+import { describeApp } from './info.js';
+export { describeApp, } from './info.js';
+export async function enableMaintenance(ctx, appIdentity, options = {}) {
+    options.signal?.throwIfAborted();
+    return ctx.platform.app.update(appIdentity, { maintenance: true });
+}
+export async function disableMaintenance(ctx, appIdentity, options = {}) {
+    options.signal?.throwIfAborted();
+    return ctx.platform.app.update(appIdentity, { maintenance: false });
+}
+/**
+ * Look up the platform generation (`cedar` or `fir`) of an app.
+ *
+ * Issues `app.info` with the `version=3.sdk` Accept variant so the
+ * response includes the `generation` field, then normalizes the
+ * platform's strings to the `'cedar' | 'fir'` union. Returns
+ * `undefined` if the platform reports an unrecognized value (e.g. a
+ * future generation name we haven't taught the SDK about).
+ */
+export async function getGeneration(ctx, appIdentity, options = {}) {
+    options.signal?.throwIfAborted();
+    const platform = ctx.platform.withHeaders({
+        Accept: 'application/vnd.heroku+json; version=3.sdk',
+    });
+    const app = await platform.app.info(appIdentity);
+    return parseGeneration(app.generation);
+}
+function parseGeneration(value) {
+    if (value === 'cedar' || value === 'fir')
+        return value;
+    return undefined;
+}
+export async function isShielded(ctx, appIdentity, options = {}) {
+    options.signal?.throwIfAborted();
+    const platform = options.signal ? ctx.platform.withOptions({ signal: options.signal }) : ctx.platform;
+    const app = await platform.app.info(appIdentity);
+    return Boolean(app.space?.shield);
+}
+export async function getProcessTier(ctx, appIdentity, options = {}) {
+    options.signal?.throwIfAborted();
+    const platform = options.signal ? ctx.platform.withOptions({ signal: options.signal }) : ctx.platform;
+    const app = await platform.app.info(appIdentity);
+    return app.process_tier;
+}
+export const appExtensions = extendResource('platform', 'app', ctx => ({
+    describe: (appIdentity, options) => describeApp(ctx, appIdentity, options),
+    disableMaintenance: (appIdentity, options) => disableMaintenance(ctx, appIdentity, options),
+    enableMaintenance: (appIdentity, options) => enableMaintenance(ctx, appIdentity, options),
+    getGeneration: (appIdentity, options) => getGeneration(ctx, appIdentity, options),
+    getProcessTier: (appIdentity, options) => getProcessTier(ctx, appIdentity, options),
+    isShielded: (appIdentity, options) => isShielded(ctx, appIdentity, options),
+}));

package/dist/resources/platform/app/info.d.ts

@@ -0,0 +1,30 @@
+import type { AddOn, App, Collaborator, Dyno, PipelineCoupling } from '@heroku/types/3.sdk';
+import type { ResourceCtx } from '../../../core/extend-resource.js';
+export type DescribeAppOptions = {
+    signal?: AbortSignal;
+};
+export type PipelineCouplingDetail = PipelineCoupling & {
+    pipeline: {
+        id?: string;
+        name: string;
+    };
+    stage: 'development' | 'production' | 'review' | 'staging' | 'test';
+};
+export type AppInfo = {
+    addons: AddOn[];
+    app: App;
+    collaborators: Collaborator[];
+    dynos: Dyno[];
+    pipelineCoupling: null | PipelineCouplingDetail;
+};
+/**
+ * Composite "describe this app" view: parallel-fetches add-ons, the app
+ * itself, dynos, collaborators, and the pipeline coupling.
+ *
+ * Hard-fails on add-ons or app (the response is meaningless without
+ * either). Soft-fails on dynos, collaborators, and pipeline coupling —
+ * any error collapses to an empty default. The broad .catch is
+ * intentional v1 fidelity with the Heroku CLI's apps:info; a future
+ * tightening to specific status codes is non-breaking.
+ */
+export declare function describeApp(ctx: Pick<ResourceCtx, 'platform'>, appIdentity: string, options?: DescribeAppOptions): Promise<AppInfo>;

package/dist/resources/platform/app/info.js

@@ -0,0 +1,27 @@
+/**
+ * Composite "describe this app" view: parallel-fetches add-ons, the app
+ * itself, dynos, collaborators, and the pipeline coupling.
+ *
+ * Hard-fails on add-ons or app (the response is meaningless without
+ * either). Soft-fails on dynos, collaborators, and pipeline coupling —
+ * any error collapses to an empty default. The broad .catch is
+ * intentional v1 fidelity with the Heroku CLI's apps:info; a future
+ * tightening to specific status codes is non-breaking.
+ */
+export async function describeApp(ctx, appIdentity, options = {}) {
+    options.signal?.throwIfAborted();
+    const platform = options.signal
+        ? ctx.platform.withOptions({ signal: options.signal })
+        : ctx.platform;
+    const [addons, app, dynos, collaborators, pipelineCoupling] = await Promise.all([
+        platform.addOn.listByApp(appIdentity),
+        platform.app.info(appIdentity),
+        platform.dyno.list(appIdentity).catch(() => []),
+        platform.collaborator.list(appIdentity).catch(() => []),
+        platform.pipelineCoupling.infoByApp(appIdentity)
+            .catch(() => null),
+    ]);
+    return {
+        addons, app, collaborators, dynos, pipelineCoupling,
+    };
+}

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

@@ -0,0 +1,56 @@
+import type { App } from '@heroku/types/3.sdk';
+import type { ResourceCtx } from '../../core/extend-resource.js';
+export type AppMaintenanceOptions = {
+    signal?: AbortSignal;
+};
+export type GenerationKind = 'cedar' | 'fir';
+export type GetGenerationOptions = {
+    signal?: AbortSignal;
+};
+export type IsShieldedOptions = {
+    signal?: AbortSignal;
+};
+export type GetProcessTierOptions = {
+    signal?: AbortSignal;
+};
+export type ProcessTier = 'eco' | 'basic' | 'standard' | 'performance' | 'private' | 'shield' | (string & {});
+export declare function enableMaintenance(ctx: Pick<ResourceCtx, 'platform'>, appIdentity: string, options?: AppMaintenanceOptions): Promise<App>;
+export declare function disableMaintenance(ctx: Pick<ResourceCtx, 'platform'>, appIdentity: string, options?: AppMaintenanceOptions): Promise<App>;
+/**
+ * Look up the platform generation (`cedar` or `fir`) of an app.
+ *
+ * Issues `app.info` with the `version=3.sdk` Accept variant so the
+ * response includes the `generation` field, then normalizes the
+ * platform's strings to the `'cedar' | 'fir'` union. Returns
+ * `undefined` if the platform reports an unrecognized value (e.g. a
+ * future generation name we haven't taught the SDK about).
+ */
+export declare function getGeneration(ctx: Pick<ResourceCtx, 'platform'>, appIdentity: string, options?: GetGenerationOptions): Promise<GenerationKind | undefined>;
+type AppInfoResult = App & {
+    process_tier?: string;
+    space?: {
+        shield?: boolean;
+    } | null;
+};
+type AppInfoPlatform = {
+    app: {
+        info(appIdentity: string): Promise<AppInfoResult>;
+    };
+    withOptions(opts: {
+        signal: AbortSignal;
+    }): AppInfoPlatform;
+};
+export declare function isShielded(ctx: {
+    platform: AppInfoPlatform;
+}, appIdentity: string, options?: IsShieldedOptions): Promise<boolean>;
+export declare function getProcessTier(ctx: {
+    platform: AppInfoPlatform;
+}, appIdentity: string, options?: GetProcessTierOptions): Promise<ProcessTier | undefined>;
+export declare const appExtensions: import("../../index.js").ResourceExtension<"platform", "app", {
+    disableMaintenance: (appIdentity: string, options?: AppMaintenanceOptions) => Promise<App>;
+    enableMaintenance: (appIdentity: string, options?: AppMaintenanceOptions) => Promise<App>;
+    getGeneration: (appIdentity: string, options?: GetGenerationOptions) => Promise<GenerationKind | undefined>;
+    getProcessTier: (appIdentity: string, options?: GetProcessTierOptions) => Promise<ProcessTier | undefined>;
+    isShielded: (appIdentity: string, options?: IsShieldedOptions) => Promise<boolean>;
+}>;
+export {};

package/dist/resources/platform/app.js

@@ -0,0 +1,50 @@
+import { extendResource } from '../../core/extend-resource.js';
+export async function enableMaintenance(ctx, appIdentity, options = {}) {
+    options.signal?.throwIfAborted();
+    return ctx.platform.app.update(appIdentity, { maintenance: true });
+}
+export async function disableMaintenance(ctx, appIdentity, options = {}) {
+    options.signal?.throwIfAborted();
+    return ctx.platform.app.update(appIdentity, { maintenance: false });
+}
+/**
+ * Look up the platform generation (`cedar` or `fir`) of an app.
+ *
+ * Issues `app.info` with the `version=3.sdk` Accept variant so the
+ * response includes the `generation` field, then normalizes the
+ * platform's strings to the `'cedar' | 'fir'` union. Returns
+ * `undefined` if the platform reports an unrecognized value (e.g. a
+ * future generation name we haven't taught the SDK about).
+ */
+export async function getGeneration(ctx, appIdentity, options = {}) {
+    options.signal?.throwIfAborted();
+    const platform = ctx.platform.withHeaders({
+        Accept: 'application/vnd.heroku+json; version=3.sdk',
+    });
+    const app = await platform.app.info(appIdentity);
+    return parseGeneration(app.generation);
+}
+function parseGeneration(value) {
+    if (value === 'cedar' || value === 'fir')
+        return value;
+    return undefined;
+}
+export async function isShielded(ctx, appIdentity, options = {}) {
+    options.signal?.throwIfAborted();
+    const platform = options.signal ? ctx.platform.withOptions({ signal: options.signal }) : ctx.platform;
+    const app = await platform.app.info(appIdentity);
+    return Boolean(app.space?.shield);
+}
+export async function getProcessTier(ctx, appIdentity, options = {}) {
+    options.signal?.throwIfAborted();
+    const platform = options.signal ? ctx.platform.withOptions({ signal: options.signal }) : ctx.platform;
+    const app = await platform.app.info(appIdentity);
+    return app.process_tier;
+}
+export const appExtensions = extendResource('platform', 'app', ctx => ({
+    disableMaintenance: (appIdentity, options) => disableMaintenance(ctx, appIdentity, options),
+    enableMaintenance: (appIdentity, options) => enableMaintenance(ctx, appIdentity, options),
+    getGeneration: (appIdentity, options) => getGeneration(ctx, appIdentity, options),
+    getProcessTier: (appIdentity, options) => getProcessTier(ctx, appIdentity, options),
+    isShielded: (appIdentity, options) => isShielded(ctx, appIdentity, options),
+}));

package/dist/resources/platform/dyno/index.d.ts

@@ -0,0 +1,45 @@
+import type { Formation } from '@heroku/types/3.sdk';
+import type { StickyRouteOptions } from '../../../core/create-client.js';
+import type { ResourceCtx } from '../../../core/extend-resource.js';
+export type DynoOptions = {
+    signal?: AbortSignal;
+};
+export type ScaleDynosUpdate = {
+    dyno_size?: {
+        id?: string;
+        name?: string;
+    };
+    quantity?: number | string;
+    size?: string;
+    type: string;
+};
+export type RestartDynosTarget = {
+    dyno: string;
+} | {
+    type: string;
+};
+type FormationClient = {
+    batchUpdate(appIdentity: string, body: {
+        updates: ScaleDynosUpdate[];
+    }): Promise<Formation[]>;
+    update(appIdentity: string, type: string, body: Omit<ScaleDynosUpdate, 'type'>): Promise<Formation>;
+};
+type ScalePlatform = {
+    formation: FormationClient;
+    withOptions(opts: StickyRouteOptions): ScalePlatform;
+};
+export declare function scaleDynos(ctx: {
+    platform: ScalePlatform;
+}, appIdentity: string, updates: ScaleDynosUpdate, options?: DynoOptions): Promise<Formation>;
+export declare function scaleDynos(ctx: {
+    platform: ScalePlatform;
+}, appIdentity: string, updates: ScaleDynosUpdate[], options?: DynoOptions): Promise<Formation[]>;
+export declare function restartDynos(ctx: Pick<ResourceCtx, 'platform'>, appIdentity: string, target?: RestartDynosTarget, options?: DynoOptions): Promise<void>;
+export declare const dynoExtensions: import("../../../index.js").ResourceExtension<"platform", "dyno", {
+    restart: (appIdentity: string, target?: RestartDynosTarget, options?: DynoOptions) => Promise<void>;
+    scale: {
+        (appIdentity: string, updates: ScaleDynosUpdate, options?: DynoOptions): Promise<Formation>;
+        (appIdentity: string, updates: ScaleDynosUpdate[], options?: DynoOptions): Promise<Formation[]>;
+    };
+}>;
+export {};