@heroku/sdk 0.9.0 → 0.11.0

package/README.md

@@ -16,7 +16,7 @@ The simplest entry point is the `HerokuSDK` class. It exposes both the Platform
 import { HerokuSDK } from '@heroku/sdk'
 import { appExtensions } from '@heroku/sdk/extensions/platform'
 
-// Reads token from HEROKU_API_KEY or ~/.netrc
+// Zero-arg reads the token from HEROKU_API_KEY (see Authentication below)
 const sdk = new HerokuSDK({ extensions: [appExtensions] })
 
 // Upstream route (auto-generated from the API spec)
@@ -49,6 +49,40 @@ You can also pass options directly:
 const sdk = new HerokuSDK({ clientOptions: { token: 'your-api-token' } })
 ```
 
+### Authentication
+
+The SDK core is transport-agnostic: it reads no local files or keychains itself,
+so it also runs in the browser. Token resolution is handled by
+`@heroku/heroku-fetch`, which has a single default and otherwise defers to
+whatever you pass in:
+
+1. **`HEROKU_API_KEY` (the default)** — with no explicit token, heroku-fetch's
+   default provider reads `HEROKU_API_KEY` from the environment, so a zero-arg
+   `new HerokuSDK()` is authenticated whenever that variable is set.
+2. **An explicit `token` (opt in to anything else)** — pass `clientOptions.token`
+   (or a per-service `clientOptionsByService`) and the SDK uses it instead of the
+   `HEROKU_API_KEY` default. This is how you authenticate from any other
+   credential source — for example a token stored by `heroku login`, which the
+   Heroku CLI resolves and injects itself (see the note below).
+
+> **Note:** To authenticate as a logged-in Heroku CLI user, resolve the stored
+> token in your (Node) application with
+> [`@heroku/heroku-credential-manager`](https://github.com/heroku/heroku-credential-manager)
+> and pass it in:
+>
+> ```ts
+> import { getAuth } from '@heroku/heroku-credential-manager'
+> import { HerokuSDK } from '@heroku/sdk'
+>
+> // account: your Heroku login email; host: the API host (usually api.heroku.com)
+> const { token } = await getAuth(account, 'api.heroku.com')
+> const sdk = new HerokuSDK({ clientOptions: { token } })
+> ```
+>
+> This keeps keychain/filesystem access in the Node consumer (CLI, MCP server,
+> VS Code extension) rather than in the SDK core, so the SDK stays usable in the
+> browser.
+
 Common client options apply to every service. In particular, a common `baseUrl`
 overrides every service's default host, including Metrics and Repositories. Use
 shallow per-service overrides when only specific services should use a host or

package/dist/resources/data/database.js

@@ -2,32 +2,32 @@ import { extendResource } from '../../core/extend-resource.js';
 import { resolvePgDatabase } from './internal/resolve-pg-database.js';
 export async function describe(ctx, appIdentity, addonIdentity, options = {}) {
     options.signal?.throwIfAborted();
-    const addon = await resolvePgDatabase(ctx, { appIdentity, input: addonIdentity, ...options });
+    const addon = await resolvePgDatabase(ctx, appIdentity, { input: addonIdentity, ...options });
     return ctx.data.database.info(addon.id);
 }
 export async function upgradeWaitStatus(ctx, appIdentity, addonIdentity, options = {}) {
     options.signal?.throwIfAborted();
-    const addon = await resolvePgDatabase(ctx, { appIdentity, input: addonIdentity, ...options });
+    const addon = await resolvePgDatabase(ctx, appIdentity, { input: addonIdentity, ...options });
     return ctx.data.database.upgradeWaitStatus(addon.id);
 }
 export async function dryRunUpgrade(ctx, appIdentity, addonIdentity, body = {}, options = {}) {
     options.signal?.throwIfAborted();
-    const addon = await resolvePgDatabase(ctx, { appIdentity, input: addonIdentity, ...options });
+    const addon = await resolvePgDatabase(ctx, appIdentity, { input: addonIdentity, ...options });
     return ctx.data.database.dryRunUpgrade(addon.id, body);
 }
 export async function runUpgrade(ctx, appIdentity, addonIdentity, body = {}, options = {}) {
     options.signal?.throwIfAborted();
-    const addon = await resolvePgDatabase(ctx, { appIdentity, input: addonIdentity, ...options });
+    const addon = await resolvePgDatabase(ctx, appIdentity, { input: addonIdentity, ...options });
     return ctx.data.database.runUpgrade(addon.id, body);
 }
 export async function prepareUpgrade(ctx, appIdentity, addonIdentity, body = {}, options = {}) {
     options.signal?.throwIfAborted();
-    const addon = await resolvePgDatabase(ctx, { appIdentity, input: addonIdentity, ...options });
+    const addon = await resolvePgDatabase(ctx, appIdentity, { input: addonIdentity, ...options });
     return ctx.data.database.prepareUpgrade(addon.id, body);
 }
 export async function cancelUpgrade(ctx, appIdentity, addonIdentity, options = {}) {
     options.signal?.throwIfAborted();
-    const addon = await resolvePgDatabase(ctx, { appIdentity, input: addonIdentity, ...options });
+    const addon = await resolvePgDatabase(ctx, appIdentity, { input: addonIdentity, ...options });
     return ctx.data.database.cancelUpgrade(addon.id);
 }
 export const databaseExtensions = extendResource('data', 'database', ctx => ({

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

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

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

@@ -6,10 +6,19 @@ export type ResolvedPgDatabaseWithAttachment = {
     attachment: ResolvedAddOnAttachment;
 };
 export type ResolvePgDatabaseOptions = ResolveAddonAttachmentOptions & {
-    appIdentity?: string;
     includeAttachment?: boolean;
     input?: string;
 };
+/**
+ * Thrown by `resolvePgDatabase` when the attachment resolution endpoint
+ * does not find a match, the matched attachment is not the configured
+ * Postgres service, or the app has no Postgres databases at all.
+ */
+export declare class PgDatabaseNotFoundError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
 /**
  * Resolve a Heroku Postgres database add-on from an attachment identity.
  *
@@ -23,7 +32,8 @@ export type ResolvePgDatabaseOptions = ResolveAddonAttachmentOptions & {
  *     `::` 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`.
+ *     globally-unique add-on name) → routed through `resolveAddonAttachment`,
+ *     scoped to `appIdentity`.
  *
  * This function only uses the attachment resolver. To resolve a database
  * through the add-on resolve endpoint, call `resolveAddon` directly.
@@ -37,11 +47,22 @@ export type ResolvePgDatabaseOptions = ResolveAddonAttachmentOptions & {
  * 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.
+ * Throws a `PgDatabaseNotFoundError` when the resolve endpoint 404s, the matched
+ * attachment is not the configured Postgres service, or the app has no databases.
+ * Throws an `AddonAttachmentAmbiguousError` when the remaining matches are not
+ * the same database. Throws a plain `Error` if `appIdentity` is empty and `input`
+ * has no `::`-prefixed app to fall back on.
+ *
+ * `resolvePgDatabase` should not throw a bare `NotFoundError`.
+ * Extensions that use it typically couple it with a second data call
+ * (e.g. `data.database.info(addon.id)`) that can also 404. Callers often
+ * catch `NotFoundError` to handle that second call's failure specifically.
+ * However, if a resolution failure surfaced as a `NotFoundError` too, that
+ * catch would swallow it and mislabel it as the second call's failure instead.
+ * Resolution failures are reported as `PgDatabaseNotFoundError` so the two stay
+ * separable by type.
  */
-export declare function resolvePgDatabase(ctx: Pick<ResourceCtx, 'platform'>, options: ResolvePgDatabaseOptions & {
+export declare function resolvePgDatabase(ctx: Pick<ResourceCtx, 'platform'>, appIdentity: string, options: ResolvePgDatabaseOptions & {
     includeAttachment: true;
 }): Promise<ResolvedPgDatabaseWithAttachment>;
-export declare function resolvePgDatabase(ctx: Pick<ResourceCtx, 'platform'>, options?: ResolvePgDatabaseOptions): Promise<ResolvedPgDatabase>;
+export declare function resolvePgDatabase(ctx: Pick<ResourceCtx, 'platform'>, appIdentity: string, options?: ResolvePgDatabaseOptions): Promise<ResolvedPgDatabase>;

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

@@ -1,36 +1,105 @@
+import { NotFoundError } from '@heroku/heroku-fetch';
 import createDebug from 'debug';
-import { AddonAttachmentAmbiguousError, resolveAddonAttachment } from '../../platform/add-on-attachment/resolve.js';
-import { getAddonService } from './postgres-utils.js';
+import { AddonAttachmentAmbiguousError, AddonAttachmentNotFoundError, resolveAddonAttachment } from '../../platform/add-on-attachment/resolve.js';
+import { getAddonService, isPostgresAddon } from './postgres-utils.js';
 const debug = createDebug('heroku:sdk:resources:database');
 const DEFAULT_PG_ATTACHMENT = 'DATABASE_URL';
-const PG_ADDON_SERVICE = getAddonService();
-export async function resolvePgDatabase(ctx, options = {}) {
-    const { appIdentity, includeAttachment, input, ...rest } = options;
-    if (!input && !appIdentity) {
-        throw new Error('resolvePgDatabase requires either input or appIdentity to default to DATABASE_URL.');
+/**
+ * Thrown by `resolvePgDatabase` when the attachment resolution endpoint
+ * does not find a match, the matched attachment is not the configured
+ * Postgres service, or the app has no Postgres databases at all.
+ */
+export class PgDatabaseNotFoundError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'PgDatabaseNotFoundError';
     }
+}
+export async function resolvePgDatabase(ctx, appIdentity, options = {}) {
+    const { includeAttachment, input, ...rest } = options;
     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>');
+    if (!app) {
+        throw new Error('resolvePgDatabase requires a non-empty app identity.');
+    }
+    debug('resolve input=%s addon=%s app=%s', input ?? '<default>', addon, app);
     let attachment;
     try {
-        attachment = await resolveAddonAttachment(ctx, app, addon, { ...rest, addonService: PG_ADDON_SERVICE });
+        attachment = await resolveAddonAttachment(ctx, app, addon, { ...rest, addonService: getAddonService() });
     }
     catch (error) {
-        if (!(error instanceof AddonAttachmentAmbiguousError))
+        if (error instanceof NotFoundError || error instanceof AddonAttachmentNotFoundError) {
+            throw await buildDatabaseNotFoundError(ctx, app, addon, error, rest.signal);
+        }
+        if (error instanceof AddonAttachmentAmbiguousError) {
+            const equivalent = collapseIfEquivalent(error.matches);
+            if (!equivalent)
+                throw error;
+            let config;
+            try {
+                config = await ctx.platform
+                    .withOptions({ signal: rest.signal })
+                    .configVar.infoForApp(equivalent[0].app.name);
+            }
+            catch (configVarError) {
+                rest.signal?.throwIfAborted();
+                debug('config var lookup failed while collapsing ambiguous matches: %O', configVarError);
+                throw error;
+            }
+            if (!allMatchSameUrl(equivalent, config))
+                throw error;
+            attachment = equivalent[0];
+        }
+        else {
             throw error;
-        const equivalent = collapseIfEquivalent(error.matches);
-        if (!equivalent)
-            throw error;
-        const config = await ctx.platform.configVar.infoForApp(equivalent[0].app.name);
-        if (!allMatchSameUrl(equivalent, config))
-            throw error;
-        attachment = equivalent[0];
+        }
     }
     return includeAttachment ? { addon: attachment.addon, attachment } : attachment.addon;
 }
+async function buildDatabaseNotFoundError(ctx, appIdentity, attachmentId, error, signal) {
+    let attachments;
+    try {
+        attachments = await listPostgresAttachments(ctx, appIdentity, signal);
+    }
+    catch (listError) {
+        signal?.throwIfAborted();
+        if (listError instanceof NotFoundError) {
+            // `NotFoundError` from the attachment resolution endpoint is ambiguous.
+            // It could be because the app doesn't exist, or because the attachment
+            // doesn't exist. The endpoint for listing all attachments only 404s when
+            // the app doesn't exist, so we rethrow the error to cover that case.
+            throw new PgDatabaseNotFoundError(`Couldn't find that app: ${appIdentity}`, { cause: listError });
+        }
+        debug('listing attachments failed while building not-found error: %O', listError);
+        throw new PgDatabaseNotFoundError(`Could not resolve ${stripUrlSuffix(attachmentId)} on ${appIdentity}`, { cause: error });
+    }
+    if (attachments.length === 0) {
+        return new PgDatabaseNotFoundError(`${appIdentity} has no ${getAddonService()} databases`, { cause: error });
+    }
+    const validOptions = attachments
+        .map(attachment => {
+        const urlVarName = urlConfigVarName(attachment.config_vars);
+        return urlVarName ? stripUrlSuffix(urlVarName) : attachment.name;
+    })
+        .join(', ');
+    const databaseName = stripUrlSuffix(attachmentId);
+    if (error instanceof AddonAttachmentNotFoundError) {
+        return new PgDatabaseNotFoundError(`${databaseName} is not a ${getAddonService()} database on ${appIdentity}. Valid options are: ${validOptions}`, { cause: error });
+    }
+    return new PgDatabaseNotFoundError(`Unknown database: ${databaseName} on ${appIdentity}. Valid options are: ${validOptions}`, { cause: error });
+}
+async function listPostgresAttachments(ctx, appIdentity, signal) {
+    const attachments = await ctx.platform
+        .withHeaders({ 'Accept-Inclusion': 'addon:plan,config_vars' })
+        .withOptions({ signal })
+        .addOnAttachment.listByApp(appIdentity);
+    return attachments.filter(attachment => isPostgresAddon(attachment.addon));
+}
+function stripUrlSuffix(name) {
+    return name.endsWith('_URL') ? name.slice(0, -4) : name;
+}
 /**
  * Narrows ambiguous matches to a same-add-on group worth comparing by
  * config var value. Returns `undefined` (not worth a config-vars round
@@ -62,5 +131,5 @@ function parseBranchReference(reference, fallbackApp) {
     if (match) {
         return { addon: match[2], app: match[1] };
     }
-    return fallbackApp ? { addon: reference, app: fallbackApp } : { addon: reference };
+    return { addon: reference, app: fallbackApp };
 }

package/dist/resources/data/maintenance.js

@@ -2,7 +2,7 @@ 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 });
+    const addon = await resolvePgDatabase(ctx, appIdentity, { input: addonIdentity, ...options });
     return ctx.data.maintenance.info(addon.id);
 }
 export const maintenanceExtensions = extendResource('data', 'maintenance', ctx => ({

package/dist/resources/data/postgres-database.js

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

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

@@ -3,7 +3,7 @@ import { waitForTransfer } from './wait-for-transfer.js';
 export async function captureAndWait(ctx, appIdentity, addonIdentity, options = {}) {
     const { capturePoller, signal, waitPoller } = options;
     signal?.throwIfAborted();
-    const addon = await resolvePgDatabase(ctx, { appIdentity, input: addonIdentity, ...options });
+    const addon = await resolvePgDatabase(ctx, appIdentity, { input: addonIdentity, ...options });
     capturePoller?.onStart?.(addon);
     const backup = await ctx.data.backup.create(addon.id);
     capturePoller?.onStop?.(addon);

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

@@ -3,7 +3,7 @@ import { waitForTransfer } from './wait-for-transfer.js';
 export async function restoreAndWait(ctx, appIdentity, addonIdentity, backupUrl, options = {}) {
     const { extensions, restorePoller, signal, waitPoller } = options;
     signal?.throwIfAborted();
-    const addon = await resolvePgDatabase(ctx, { appIdentity, input: addonIdentity, ...options });
+    const addon = await resolvePgDatabase(ctx, appIdentity, { input: addonIdentity, ...options });
     restorePoller?.onStart?.(addon);
     // eslint-disable-next-line camelcase
     const restore = await ctx.data.restore.create(addon.id, { backup_url: backupUrl, extensions });

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

@@ -9,8 +9,8 @@ export async function list(ctx, appIdentity, options = {}) {
 }
 export async function create(ctx, appIdentity, addonIdentity, body, options = {}) {
     options.signal?.throwIfAborted();
-    const { addon, attachment } = await resolvePgDatabase(ctx, {
-        appIdentity, includeAttachment: true, input: addonIdentity, ...options,
+    const { addon, attachment } = await resolvePgDatabase(ctx, appIdentity, {
+        includeAttachment: true, input: addonIdentity, ...options,
     });
     let requestBody = body;
     if (!requestBody.schedule_name) {
@@ -21,7 +21,7 @@ export async function create(ctx, appIdentity, addonIdentity, body, options = {}
 }
 export async function del(ctx, appIdentity, addonIdentity, scheduleId, options = {}) {
     options.signal?.throwIfAborted();
-    const addon = await resolvePgDatabase(ctx, { appIdentity, input: addonIdentity, ...options });
+    const addon = await resolvePgDatabase(ctx, appIdentity, { input: addonIdentity, ...options });
     return ctx.data.transferSchedule.delete(addon.id, scheduleId);
 }
 export const transferScheduleExtensions = extendResource('data', 'transferSchedule', ctx => ({

package/dist/services/metrics.js

@@ -6,7 +6,7 @@ export function createMetricsClient(options = {}) {
     // Metrics is a distinct host that heroku-fetch does not model as a first-class
     // service, so we use `service: 'custom'` with an explicit base URL. Auth (bearer
     // token) is resolved by heroku-fetch exactly as for platform/data — same
-    // HEROKU_API_KEY / netrc source, shared across services on one SDK instance.
+    // HEROKU_API_KEY / explicit-token source, shared across services on one SDK instance.
     //
     // Unlike platform/data, `service: 'custom'` sends no default Accept header, so we
     // set `application/vnd.heroku+json; version=3` explicitly to match what meetas

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heroku/sdk",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Heroku SDK",
   "author": "Heroku",
   "type": "module",
@@ -110,6 +110,7 @@
       "types": "./dist/resources/data/transfer/index.d.ts",
       "default": "./dist/resources/data/transfer/index.js"
     },
+    "./resources/data/internal/*": null,
     "./resources/*": {
       "types": "./dist/resources/*.d.ts",
       "default": "./dist/resources/*.js"
@@ -153,7 +154,7 @@
     "vitest": "^4.1.4"
   },
   "dependencies": {
-    "@heroku/heroku-fetch": "^0.1.4",
+    "@heroku/heroku-fetch": "^0.2.0",
     "@heroku/types": "^5.0.0",
     "debug": "^4.4.0"
   }