@heroku/sdk 0.7.1 → 0.8.0

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

@@ -1,6 +1,6 @@
 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 { ResolvedPgDatabase } from '../internal/resolve-pg-database.js';
 import type { WaitForTransferOptions } from '../wait-for-transfer.js';
 import { Poller } from '../../../utils/poller.js';
 export type CaptureAndWaitOptions = WaitForTransferOptions & {
@@ -8,7 +8,7 @@ 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>;
+    capturePoller?: Poller<ResolvedPgDatabase>;
     /**
      * Progress hooks fired once before waiting for the transfer to
      * complete `poller.onStart(backup)` and once after the transfer

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

@@ -1,23 +1,39 @@
 import type { ResourceCtx } from '../../../core/extend-resource.js';
-import type { ResolveAddonOptions, ResolvedAddOn } from '../../platform/add-on/index.js';
-export type ResolvePgDatabaseOptions = ResolveAddonOptions & {
+import type { ResolveAddonAttachmentOptions, ResolvedAddOnAttachment } from '../../platform/add-on-attachment/resolve.js';
+export type ResolvedPgDatabase = ResolvedAddOnAttachment['addon'];
+export type ResolvePgDatabaseOptions = ResolveAddonAttachmentOptions & {
+    appIdentity?: string;
     input?: string;
 };
 /**
- * Resolve a Heroku Postgres database add-on from any of the input
- * shapes the platform recognizes:
+ * Resolve a Heroku Postgres database add-on from an attachment identity.
  *
+ * `input` selects the attachment as follows:
  *   - omitted → the `DATABASE_URL` attachment on `appIdentity`.
- *   - `DATABASE_URL`, `HEROKU_POSTGRESQL_GREEN`, etc. → that attachment
- *     on `appIdentity`. Detected by SHOUTY_SNAKE_CASE shape.
- *   - `parent-app::branch-name` → branch reference. The portion before
- *     `::` is the parent app; the portion after is the branch add-on
- *     name.
- *   - any other string → a bare add-on identity (UUID, globally-unique
- *     name) routed through `resolveAddon`.
+ *   - `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`.
  *
- * Throws `AddonNotFoundError` (or `AddonAmbiguousError`) from the
- * underlying resolver. Throws if no input is given and no `appIdentity`
+ * 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.
  */
-export declare function resolvePgDatabase(ctx: Pick<ResourceCtx, 'platform'>, options?: ResolvePgDatabaseOptions): Promise<ResolvedAddOn>;
+export declare function resolvePgDatabase(ctx: Pick<ResourceCtx, 'platform'>, options?: ResolvePgDatabaseOptions): Promise<ResolvedPgDatabase>;

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

@@ -1,50 +1,94 @@
 import createDebug from 'debug';
-import { resolveAddon, resolveAddonByAttachment } from '../../platform/add-on/index.js';
+import { AddonAttachmentAmbiguousError, resolveAddonAttachment } from '../../platform/add-on-attachment/resolve.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 any of the input
- * shapes the platform recognizes:
+ * Resolve a Heroku Postgres database add-on from an attachment identity.
  *
+ * `input` selects the attachment as follows:
  *   - omitted → the `DATABASE_URL` attachment on `appIdentity`.
- *   - `DATABASE_URL`, `HEROKU_POSTGRESQL_GREEN`, etc. → that attachment
- *     on `appIdentity`. Detected by SHOUTY_SNAKE_CASE shape.
- *   - `parent-app::branch-name` → branch reference. The portion before
- *     `::` is the parent app; the portion after is the branch add-on
- *     name.
- *   - any other string → a bare add-on identity (UUID, globally-unique
- *     name) routed through `resolveAddon`.
+ *   - `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`.
  *
- * Throws `AddonNotFoundError` (or `AddonAmbiguousError`) from the
- * underlying resolver. Throws if no input is given and no `appIdentity`
+ * 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.
  */
 export async function resolvePgDatabase(ctx, options = {}) {
     const { appIdentity, input, ...rest } = options;
-    if (!input) {
-        if (!appIdentity) {
-            throw new Error('resolvePgDatabase requires either input or appIdentity to default to DATABASE_URL.');
-        }
-        debug('resolve branch=default-attachment app=%s attachment=%s', appIdentity, DEFAULT_PG_ATTACHMENT);
-        return resolveAddonByAttachment(ctx, appIdentity, DEFAULT_PG_ATTACHMENT, rest);
+    if (!input && !appIdentity) {
+        throw new Error('resolvePgDatabase requires either input or appIdentity to default to DATABASE_URL.');
     }
-    if (input.includes('::')) {
-        const { addon, app } = parseBranchReference(input, appIdentity);
-        debug('resolve branch=branch-reference input=%s addon=%s app=%s', input, addon, app ?? '<global>');
-        return resolveAddon(ctx, addon, { ...rest, appIdentity: app });
+    const databaseReference = input ?? DEFAULT_PG_ATTACHMENT;
+    const { addon, app } = databaseReference.includes('::')
+        ? parseBranchReference(databaseReference, appIdentity)
+        : { addon: databaseReference, app: appIdentity };
+    debug('resolve input=%s addon=%s app=%s', input ?? '<default>', addon, app ?? '<global>');
+    try {
+        const attachment = await resolveAddonAttachment(ctx, app, addon, { ...rest, addonService: PG_ADDON_SERVICE });
+        return attachment.addon;
     }
-    if (appIdentity && isAttachmentName(input)) {
-        debug('resolve branch=attachment-name app=%s attachment=%s', appIdentity, input);
-        return resolveAddonByAttachment(ctx, appIdentity, input, rest);
+    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;
     }
-    debug('resolve branch=bare-identity input=%s app=%s', input, appIdentity ?? '<global>');
-    return resolveAddon(ctx, input, { ...rest, appIdentity });
 }
-function isAttachmentName(input) {
-    return /^[A-Z][A-Z0-9_]*$/.test(input);
+/**
+ * Narrows ambiguous matches to a same-add-on group worth comparing by
+ * config var value. Returns `undefined` (not worth a config-vars round
+ * trip) unless every match shares the same add-on and attachment app.
+ */
+function collapseIfEquivalent(matches) {
+    const [first] = matches;
+    const sameAddon = matches.every(match => match.addon.id === first.addon.id && match.app.id === first.app.id);
+    return sameAddon ? matches : undefined;
+}
+/** The first config var name declared on an attachment that holds its connection URL. */
+function urlConfigVarName(configVars) {
+    return configVars.find(name => name.endsWith('_URL'));
+}
+/** Whether every match's own URL config var resolves to the same value in `config`. */
+function allMatchSameUrl(matches, config) {
+    const firstVarName = urlConfigVarName(matches[0].config_vars);
+    const firstValue = firstVarName && config[firstVarName];
+    if (!firstValue) {
+        return false;
+    }
+    return matches.every(match => {
+        const varName = urlConfigVarName(match.config_vars);
+        return varName !== undefined && config[varName] === firstValue;
+    });
 }
 function parseBranchReference(reference, fallbackApp) {
-    const match = reference.match(/^(.+)::(.+)$/);
+    const match = reference.match(/^(.+?)::(.+)$/);
     if (match) {
         return { addon: match[2], app: match[1] };
     }

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

@@ -1,6 +1,6 @@
 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 { ResolvedPgDatabase } from '../internal/resolve-pg-database.js';
 import type { WaitForTransferOptions } from '../wait-for-transfer.js';
 import { Poller } from '../../../utils/poller.js';
 export type RestoreAndWaitOptions = WaitForTransferOptions & {
@@ -13,7 +13,7 @@ export type RestoreAndWaitOptions = WaitForTransferOptions & {
      * `poller.onStart(addon)` and once after the restore is
      * created `poller.onStop(addon)`.
      */
-    restorePoller?: Poller<ResolvedAddOn>;
+    restorePoller?: Poller<ResolvedPgDatabase>;
     /**
      * Progress hooks fired once before waiting for the restore to
      * complete `poller.onStart(restore)` and once after the restore

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

@@ -1,3 +1,4 @@
+export { addOnAttachmentExtensions } from '../platform/add-on-attachment/index.js';
 export { addOnExtensions } from '../platform/add-on/index.js';
 export { appExtensions, type AppInfo, type DiffAppsOptions, type DiffRow, type PipelineCouplingDetail, } from '../platform/app/index.js';
 export { containerExtensions, type DockerReleasesBatchUpdateOpts, NotAContainerAppError, type ReleaseDockerImagesResult, type RemoveProcessTypesOpts, } from '../platform/container/index.js';

package/dist/resources/extensions/platform.js

@@ -1,3 +1,4 @@
+export { addOnAttachmentExtensions } from '../platform/add-on-attachment/index.js';
 export { addOnExtensions } from '../platform/add-on/index.js';
 export { appExtensions, } from '../platform/app/index.js';
 export { containerExtensions, NotAContainerAppError, } from '../platform/container/index.js';

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

@@ -8,11 +8,6 @@ import type { DescribedAddOn, ResolveAddonOptions } from './types.js';
  * - 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.

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

@@ -7,11 +7,6 @@ import { resolveAddonInternal } from './resolve.js';
  * - 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.

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

@@ -8,21 +8,19 @@ export { destroyAndWait } from './destroy-and-wait.js';
 export { AddonAmbiguousError, AddonConfirmationRequiredError, AddonNotFoundError, AddonProvisioningFailedError, } from './errors.js';
 export { listPlans, listPlansForAddon, type ListPlansForAddonOptions } from './list-plans.js';
 export { formatPlanPriceLabel, type FormatPlanPriceLabelOptions, type PlanPriceBreakdown, type PlanPriceKind, priceForPlan, } from './pricing.js';
-export { describeAttachment, resolveAddon, resolveAddonByAttachment } from './resolve.js';
-export type { AddOnOptions, CreateAndWaitOptions, DescribedAddOn, DestroyAndWaitOptions, ResolveAddonOptions, ResolvedAddOn, ResolvedAddOnAttachment, UpgradeAddOnOptions, WaitForProvisioningOptions, } from './types.js';
+export { resolveAddon } from './resolve.js';
+export type { AddOnOptions, CreateAndWaitOptions, DescribedAddOn, DestroyAndWaitOptions, ResolveAddonOptions, ResolvedAddOn, UpgradeAddOnOptions, WaitForProvisioningOptions, } from './types.js';
 export { upgrade } from './upgrade.js';
 export { waitForProvisioning } from './wait-for-provisioning.js';
 export declare const addOnExtensions: import("../../../core/extend-resource.js").ResourceExtension<"platform", "addOn", {
     createAndWait: (appIdentity: string, body: AddOnCreateOpts, options?: CreateAndWaitOptions) => Promise<AddOn>;
     describe: (addonIdentity: string, options?: ResolveAddonOptions) => Promise<import("./types.js").DescribedAddOn>;
-    describeAttachment: (appIdentity: string, attachmentName: string, options?: AddOnOptions) => Promise<import("./types.js").ResolvedAddOnAttachment>;
     destroyAndWait: (appIdentity: string, addonIdentity: string, options?: DestroyAndWaitOptions) => Promise<AddOn>;
     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<AddOn>;
     waitForProvisioning: (addon: AddOn, options?: WaitForProvisioningOptions) => Promise<AddOn>;
 }>;

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

@@ -4,7 +4,7 @@ import { describeAddon } from './describe.js';
 import { destroyAndWait } from './destroy-and-wait.js';
 import { listPlans, listPlansForAddon } from './list-plans.js';
 import { formatPlanPriceLabel, priceForPlan } from './pricing.js';
-import { describeAttachment, resolveAddon, resolveAddonByAttachment } from './resolve.js';
+import { resolveAddon } from './resolve.js';
 import { upgrade } from './upgrade.js';
 import { waitForProvisioning } from './wait-for-provisioning.js';
 export { createAndWait } from './create-and-wait.js';
@@ -13,20 +13,18 @@ export { destroyAndWait } from './destroy-and-wait.js';
 export { AddonAmbiguousError, AddonConfirmationRequiredError, AddonNotFoundError, AddonProvisioningFailedError, } from './errors.js';
 export { listPlans, listPlansForAddon } from './list-plans.js';
 export { formatPlanPriceLabel, priceForPlan, } from './pricing.js';
-export { describeAttachment, resolveAddon, resolveAddonByAttachment } from './resolve.js';
+export { resolveAddon } from './resolve.js';
 export { upgrade } from './upgrade.js';
 export { waitForProvisioning } from './wait-for-provisioning.js';
 export const addOnExtensions = extendResource('platform', 'addOn', ctx => ({
     createAndWait: (appIdentity, body, options) => createAndWait(ctx, appIdentity, body, options),
     describe: (addonIdentity, options) => describeAddon(ctx, addonIdentity, options),
-    describeAttachment: (appIdentity, attachmentName, options) => describeAttachment(ctx, appIdentity, attachmentName, options),
     destroyAndWait: (appIdentity, addonIdentity, options) => destroyAndWait(ctx, appIdentity, 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),
     waitForProvisioning: (addon, options) => waitForProvisioning(ctx, addon, options),
 }));

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

@@ -23,10 +23,7 @@ export declare function listPlans(ctx: Pick<ResourceCtx, 'platform'>, serviceIde
  * 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`)
+ * `addonIdentity` accepts the same forms as `resolveAddon`.
  *
  * Pass `appIdentity` via `options` when the add-on identity is
  * scoped to an app (same semantics as `resolveAddon`).

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

@@ -19,10 +19,7 @@ export async function listPlans(ctx, serviceIdentity, options = {}) {
  * 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`)
+ * `addonIdentity` accepts the same forms as `resolveAddon`.
  *
  * Pass `appIdentity` via `options` when the add-on identity is
  * scoped to an app (same semantics as `resolveAddon`).

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

@@ -1,18 +1,20 @@
 import type { ResourceCtx } from '../../../core/extend-resource.js';
 import type { PlatformClient } from '../../../services/platform.js';
-import type { AddOnOptions, ResolveAddonOptions, ResolvedAddOn, ResolvedAddOnAttachment } from './types.js';
+import type { ResolveAddonOptions, ResolvedAddOn } from './types.js';
 /**
  * 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`)
+ *   - an add-on UUID (`d5e3f2a4-...`)
+ *   - a globally-unique add-on name (`postgres-curved-12345`)
+ *   - an add-on service slug (`heroku-postgresql`)
+ *   - an add-on plan slug (`heroku-postgresql:essential-0`)
  *
- * 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.
+ * It may also be an add-on attachment identity:
+ *   - an attachment UUID (`2a4d5e3f-...`), name (`DATABASE`), or config
+ *     var (`DATABASE_URL`). These identities require `appIdentity`.
+ *   - an attachment name or config var prefixed with the app name
+ *     (`my-app::DATABASE`, `my-app::DATABASE_URL`).
  *
  * `addonService` (e.g. `heroku-postgresql`) is filtered client-side after
  * the resolve. The platform's server-side `addon_service` filter excludes
@@ -21,38 +23,8 @@ import type { AddOnOptions, ResolveAddonOptions, ResolvedAddOn, ResolvedAddOnAtt
  * 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 declare function resolveAddon(ctx: Pick<ResourceCtx, 'platform'>, addonIdentity: string, options?: ResolveAddonOptions): Promise<ResolvedAddOn>;
-/**
- * Describe an add-on *attachment* via its name on a given app.
- *
- * Use this when you have an attachment name (e.g. `DATABASE_URL`,
- * `HEROKU_POSTGRESQL_GREEN`) on a known app and need the attachment
- * itself — including its context-scoped `web_url` (the dashboard URL for
- * opening the add-on *from this app*, which differs from the add-on's own
- * billing-app `web_url`). Calls `addOnAttachment.resolution` and returns
- * the matched attachment with its resolved add-on.
- *
- * `web_url` is `string | null` by design: it is `null` for add-ons that
- * expose no web dashboard. A `null` here is a valid result, not a
- * not-found — callers who need a URL must handle it (e.g. fall back to
- * the add-on's own `web_url` via `resolveAddon`).
- *
- * To resolve just the add-on the attachment points to, use
- * `resolveAddonByAttachment`. For resolving by add-on identity, use
- * `resolveAddon`.
- */
-export declare function describeAttachment(ctx: Pick<ResourceCtx, 'platform'>, appIdentity: string, attachmentName: string, options?: AddOnOptions): Promise<ResolvedAddOnAttachment>;
-/**
- * Resolve the add-on that an attachment points to, by attachment name on a
- * given app. A thin wrapper over `describeAttachment` that returns only the
- * resolved add-on (not the attachment). Use `describeAttachment` when you
- * need the attachment's context-scoped `web_url`.
- */
-export declare function resolveAddonByAttachment(ctx: Pick<ResourceCtx, 'platform'>, appIdentity: string, attachmentName: string, options?: AddOnOptions): Promise<ResolvedAddOn>;
 export declare function resolveAddonInternal(platform: PlatformClient, addonIdentity: string, options?: {
     addonService?: string;
     appIdentity?: string;

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

@@ -1,18 +1,19 @@
-import { NotFoundError } from '@heroku/heroku-fetch';
 import { debug } from './debug.js';
 import { AddonAmbiguousError, AddonNotFoundError } from './errors.js';
 /**
  * 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`)
+ *   - an add-on UUID (`d5e3f2a4-...`)
+ *   - a globally-unique add-on name (`postgres-curved-12345`)
+ *   - an add-on service slug (`heroku-postgresql`)
+ *   - an add-on plan slug (`heroku-postgresql:essential-0`)
  *
- * 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.
+ * It may also be an add-on attachment identity:
+ *   - an attachment UUID (`2a4d5e3f-...`), name (`DATABASE`), or config
+ *     var (`DATABASE_URL`). These identities require `appIdentity`.
+ *   - an attachment name or config var prefixed with the app name
+ *     (`my-app::DATABASE`, `my-app::DATABASE_URL`).
  *
  * `addonService` (e.g. `heroku-postgresql`) is filtered client-side after
  * the resolve. The platform's server-side `addon_service` filter excludes
@@ -21,92 +22,25 @@ import { AddonAmbiguousError, AddonNotFoundError } from './errors.js';
  * 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);
 }
-/**
- * Describe an add-on *attachment* via its name on a given app.
- *
- * Use this when you have an attachment name (e.g. `DATABASE_URL`,
- * `HEROKU_POSTGRESQL_GREEN`) on a known app and need the attachment
- * itself — including its context-scoped `web_url` (the dashboard URL for
- * opening the add-on *from this app*, which differs from the add-on's own
- * billing-app `web_url`). Calls `addOnAttachment.resolution` and returns
- * the matched attachment with its resolved add-on.
- *
- * `web_url` is `string | null` by design: it is `null` for add-ons that
- * expose no web dashboard. A `null` here is a valid result, not a
- * not-found — callers who need a URL must handle it (e.g. fall back to
- * the add-on's own `web_url` via `resolveAddon`).
- *
- * To resolve just the add-on the attachment points to, use
- * `resolveAddonByAttachment`. For resolving by add-on identity, use
- * `resolveAddon`.
- */
-export async function describeAttachment(ctx, appIdentity, attachmentName, options = {}) {
-    options.signal?.throwIfAborted();
-    debug('describeAttachment app=%s attachment=%s', appIdentity, attachmentName);
-    // Scope the in-flight resolution call to the caller's signal so an abort
-    // mid-request is honored, not just before it starts.
-    const platform = options.signal ? ctx.platform.withOptions({ signal: options.signal }) : ctx.platform;
-    const matches = await platform.addOnAttachment.resolution({
-        // eslint-disable-next-line camelcase
-        addon_attachment: attachmentName,
-        app: appIdentity,
-    });
-    const attachment = matches[0];
-    if (!attachment?.addon?.id || !attachment.addon.app?.id) {
-        debug('describeAttachment matches=%d (no usable add-on returned)', matches.length);
-        throw new AddonNotFoundError();
-    }
-    debug('describeAttachment resolved addon=%s app=%s', attachment.addon.id, attachment.addon.app.id);
-    return attachment;
-}
-/**
- * Resolve the add-on that an attachment points to, by attachment name on a
- * given app. A thin wrapper over `describeAttachment` that returns only the
- * resolved add-on (not the attachment). Use `describeAttachment` when you
- * need the attachment's context-scoped `web_url`.
- */
-export async function resolveAddonByAttachment(ctx, appIdentity, attachmentName, options = {}) {
-    return (await describeAttachment(ctx, appIdentity, attachmentName, options)).addon;
-}
 export 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';
+    // If the add-on identity is app-scoped (contains `::`), we do not pass `appIdentity`
+    const app = appIdentity && !addonIdentity.includes('::') ? appIdentity : undefined;
+    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;
 }
 function singularize(matches) {
     if (matches.length === 0) {

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

@@ -7,10 +7,14 @@ export type ResolveAddonOptions = AddOnOptions & {
     appIdentity?: string;
 };
 /**
- * An add-on whose `app.id` and `id` are guaranteed non-null. This is what
- * the Platform's resolver returns for a successful match, but the schema
- * types both as optional. `singularize` enforces it at runtime so callers
- * can rely on the narrower type.
+ * An add-on that has passed through a resolver's `singularize` check:
+ * `app.id` and `id` are guaranteed non-null at runtime. At the currently
+ * installed `@heroku/types` schema, `AddOn` already types these as
+ * required, so this doesn't narrow anything today — it exists to give the
+ * SDK a stable name decoupled from the generated type (insurance against
+ * that schema loosening these back to optional) and to document, by name,
+ * that a value carrying this type has actually been through resolution
+ * rather than a plain `list()`/`info()` call.
  */
 export type ResolvedAddOn = AddOn & {
     app: AddOn['app'] & {
@@ -18,24 +22,6 @@ export type ResolvedAddOn = AddOn & {
     };
     id: string;
 };
-/**
- * An attachment whose add-on `id`/`app.id` are guaranteed non-null (as the
- * resolver enforces at runtime). `web_url` is scoped to the attached app's
- * context — the dashboard URL for opening this add-on *from this app*, which
- * differs from the add-on's own (billing-app) `web_url`.
- *
- * `web_url` remains `string | null` by design (inherited from
- * `AddOnAttachment`): it is `null` for add-ons that expose no web dashboard.
- * The resolver does not guarantee a URL — callers must handle the `null` case.
- */
-export type ResolvedAddOnAttachment = AddOnAttachment & {
-    addon: NonNullable<AddOnAttachment['addon']> & {
-        app: {
-            id: string;
-        };
-        id: string;
-    };
-};
 export type DescribedAddOn = ResolvedAddOn & {
     attachments: AddOnAttachment[];
 };

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

@@ -5,9 +5,8 @@ import type { UpgradeAddOnOptions } from './types.js';
  * 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.
+ * `resolveAddon` accepts. When `appIdentity` is provided, the resolve
+ * is scoped to that app.
  *
  * If `plan` is unqualified (no `:`), it's prefixed with the resolved
  * add-on's `addon_service.name` — so callers can pass `hobby` rather

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

@@ -4,9 +4,8 @@ import { resolveAddonInternal } from './resolve.js';
  * 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.
+ * `resolveAddon` accepts. When `appIdentity` is provided, the resolve
+ * is scoped to that app.
  *
  * If `plan` is unqualified (no `:`), it's prefixed with the resolved
  * add-on's `addon_service.name` — so callers can pass `hobby` rather

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

@@ -0,0 +1,6 @@
+import type { ResolveAddonAttachmentOptions } from './resolve.js';
+export { AddonAttachmentAmbiguousError, AddonAttachmentNotFoundError, resolveAddonAttachment } from './resolve.js';
+export type { ResolveAddonAttachmentOptions, ResolvedAddOnAttachment } from './resolve.js';
+export declare const addOnAttachmentExtensions: import("../../../core/extend-resource.js").ResourceExtension<"platform", "addOnAttachment", {
+    resolve: (appIdentity: string | undefined, attachmentName: string, options?: ResolveAddonAttachmentOptions) => Promise<import("./resolve.js").ResolvedAddOnAttachment>;
+}>;

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

@@ -0,0 +1,6 @@
+import { extendResource } from '../../../core/extend-resource.js';
+import { resolveAddonAttachment } from './resolve.js';
+export { AddonAttachmentAmbiguousError, AddonAttachmentNotFoundError, resolveAddonAttachment } from './resolve.js';
+export const addOnAttachmentExtensions = extendResource('platform', 'addOnAttachment', ctx => ({
+    resolve: (appIdentity, attachmentName, options) => resolveAddonAttachment(ctx, appIdentity, attachmentName, options),
+}));

package/dist/resources/platform/add-on-attachment/resolve.d.ts

@@ -0,0 +1,80 @@
+import type { AddOnAttachment } from '@heroku/types/3.sdk';
+import type { ResourceCtx } from '../../../core/extend-resource.js';
+export declare class AddonAttachmentNotFoundError 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 AddonAttachmentAmbiguousError extends Error {
+    readonly matches: AddOnAttachmentWithInclusions[];
+    readonly id = "multiple_matches";
+    readonly statusCode = 422;
+    constructor(matches: AddOnAttachmentWithInclusions[]);
+    get body(): {
+        id: string;
+        message: string;
+    };
+}
+/**
+ * `Accept-Inclusion: addon:plan,config_vars` requests the add-on's plan and
+ * the attachment's config var names, but @heroku/types doesn't model either
+ * inclusion. Extend locally rather than casting through `any`.
+ */
+export type AddOnAttachmentWithInclusions = AddOnAttachment & {
+    addon: AddOnAttachment['addon'] & {
+        plan: {
+            id?: string;
+            name: string;
+        };
+    };
+    config_vars: string[];
+};
+/**
+ * An attachment that has passed through `singularize`: its add-on `id`/
+ * `app.id` are guaranteed non-null at runtime. At the currently installed
+ * `@heroku/types` schema, `AddOnAttachment` already types these as
+ * required, so this doesn't narrow anything today — it exists to give the
+ * SDK a stable name decoupled from the generated type (insurance against
+ * that schema loosening these back to optional) and to document, by name,
+ * that a value carrying this type has actually been through resolution.
+ */
+export type ResolvedAddOnAttachment = AddOnAttachmentWithInclusions & {
+    addon: NonNullable<AddOnAttachmentWithInclusions['addon']> & {
+        app: {
+            id: string;
+        };
+        id: string;
+    };
+};
+export type ResolveAddonAttachmentOptions = {
+    /**
+     * Restrict matches to attachments whose add-on plan belongs to this
+     * add-on service (e.g. `heroku-postgresql`), filtered client-side.
+     */
+    addonService?: string;
+    signal?: AbortSignal;
+};
+/**
+ * Resolve a Platform add-on *attachment* by identity.
+ *
+ * The add-on attachment identity may be:
+ *   - an attachment UUID (`d5e3f2a4-...`)
+ *   - an attachment name (`DATABASE`)
+ *   - a config var (`DATABASE_URL`)
+ *   - an app-scoped attachment name or config var (`my-app::DATABASE`,
+ *    `my-app::DATABASE_URL`)
+ *   - a globally-unique add-on name (`postgres-curved-12345`)
+ *
+ * To resolve just the add-on the attachment points to, use `resolveAddon`.
+ *
+ * Always sends `Accept-Inclusion: addon:plan,config_vars` on the resolve
+ * request so matches come back with their add-on's plan (needed to filter
+ * by `addonService`) and their own config var names.
+ */
+export declare function resolveAddonAttachment(ctx: Pick<ResourceCtx, 'platform'>, appIdentity: string | undefined, attachmentName: string, options?: ResolveAddonAttachmentOptions): Promise<ResolvedAddOnAttachment>;

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

@@ -0,0 +1,78 @@
+import createDebug from 'debug';
+const debug = createDebug('heroku:sdk:resources:add-on-attachment');
+export class AddonAttachmentNotFoundError extends Error {
+    resource;
+    id = 'not_found';
+    statusCode = 404;
+    constructor(resource = 'addon attachment') {
+        super(`Couldn't find that ${resource}.`);
+        this.resource = resource;
+        this.name = 'AddonAttachmentNotFoundError';
+    }
+    get body() {
+        return { id: this.id, message: this.message, resource: this.resource };
+    }
+}
+export class AddonAttachmentAmbiguousError extends Error {
+    matches;
+    id = 'multiple_matches';
+    statusCode = 422;
+    constructor(matches) {
+        super(`Ambiguous identifier; multiple matching add-on attachments found: ${matches.map(m => m.name).join(', ')}.`);
+        this.matches = matches;
+        this.name = 'AddonAttachmentAmbiguousError';
+    }
+    get body() {
+        return { id: this.id, message: this.message };
+    }
+}
+/**
+ * Resolve a Platform add-on *attachment* by identity.
+ *
+ * The add-on attachment identity may be:
+ *   - an attachment UUID (`d5e3f2a4-...`)
+ *   - an attachment name (`DATABASE`)
+ *   - a config var (`DATABASE_URL`)
+ *   - an app-scoped attachment name or config var (`my-app::DATABASE`,
+ *    `my-app::DATABASE_URL`)
+ *   - a globally-unique add-on name (`postgres-curved-12345`)
+ *
+ * To resolve just the add-on the attachment points to, use `resolveAddon`.
+ *
+ * Always sends `Accept-Inclusion: addon:plan,config_vars` on the resolve
+ * request so matches come back with their add-on's plan (needed to filter
+ * by `addonService`) and their own config var names.
+ */
+export async function resolveAddonAttachment(ctx, appIdentity, attachmentName, options = {}) {
+    const { addonService, signal } = options;
+    signal?.throwIfAborted();
+    debug('resolve app=%s attachment=%s service=%s', appIdentity ?? '<global>', attachmentName, addonService ?? '<any>');
+    const platform = ctx.platform
+        .withHeaders({ 'Accept-Inclusion': 'addon:plan,config_vars' })
+        .withOptions({ signal });
+    const matches = await platform.addOnAttachment.resolution({
+        // eslint-disable-next-line camelcase
+        addon_attachment: attachmentName,
+        app: appIdentity,
+    });
+    const filtered = addonService
+        ? matches.filter(match => match.addon?.plan?.name?.split(':', 2)[0] === addonService)
+        : matches;
+    debug('resolve matches=%d filtered=%d (service=%s)', matches.length, filtered.length, addonService ?? '<any>');
+    const resolvedAttachment = singularize(filtered);
+    debug('resolve resolved attachment=%s addon=%s app=%s', resolvedAttachment.id, resolvedAttachment.addon.id, resolvedAttachment.addon.app.id);
+    return resolvedAttachment;
+}
+function singularize(matches) {
+    if (matches.length === 0) {
+        throw new AddonAttachmentNotFoundError();
+    }
+    if (matches.length > 1) {
+        throw new AddonAttachmentAmbiguousError(matches);
+    }
+    const match = matches[0];
+    if (!match.addon?.id || !match.addon?.app?.id) {
+        throw new Error(`Resolved attachment is missing required add-on fields (addon.id=${match.addon.id}, addon.app.id=${match.addon.app.id})`);
+    }
+    return match;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heroku/sdk",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "Heroku SDK",
   "author": "Heroku",
   "type": "module",
@@ -50,6 +50,10 @@
       "types": "./dist/resources/platform/add-on/index.d.ts",
       "default": "./dist/resources/platform/add-on/index.js"
     },
+    "./resources/platform/add-on-attachment": {
+      "types": "./dist/resources/platform/add-on-attachment/index.d.ts",
+      "default": "./dist/resources/platform/add-on-attachment/index.js"
+    },
     "./resources/platform/app": {
       "types": "./dist/resources/platform/app/index.d.ts",
       "default": "./dist/resources/platform/app/index.js"