@heroku/sdk 0.11.2 → 0.12.1

package/dist/core/create-client.d.ts

@@ -7,7 +7,7 @@ type RoutesModule = Record<string, Record<string, RouteDefinition>>;
  * and `stream` are deliberately excluded — those belong on the
  * individual route call, not on the client wrapper.
  */
-export type StickyRouteOptions = Pick<RequestOptions, 'headers' | 'signal' | 'timeout'> & {
+export type StickyRouteOptions = Pick<RequestOptions, 'headers' | 'reauthorize' | 'signal' | 'timeout'> & {
     /**
      * Request body applied to write calls on the derived client. Primarily
      * for methods whose route metadata lacks `hasRequestBody` (e.g. DELETE
@@ -30,7 +30,12 @@ export type RoutesClientExtras<T> = {
      * Returns a same-shaped client where each route call applies the
      * provided options. Caller-supplied headers override the api-client's
      * defaults; subsequent `withOptions` calls layer headers and replace
-     * signal / timeout.
+     * signal / timeout / reauthorize.
+     *
+     * Pass `reauthorize: false` to opt the derived client's calls out of the
+     * client-level 401 refresh (see {@link RequestOptions.reauthorize}) — for
+     * call sites where a 401 means something other than an expired Heroku
+     * credential and must not drive a login.
      *
      * The original client is not mutated.
      */

package/dist/core/create-client.js

@@ -11,12 +11,15 @@ function mergeStickyOptions(base, next) {
     if (next.headers || base?.headers) {
         merged.headers = { ...base?.headers, ...next.headers };
     }
-    // signal, timeout, and body are not additive — last wins, but only if
-    // the caller actually set them. Otherwise the previous value persists.
+    // signal, timeout, reauthorize, and body are not additive — last wins,
+    // but only if the caller actually set them. Otherwise the previous value
+    // persists.
     if (next.signal !== undefined)
         merged.signal = next.signal;
     if (next.timeout !== undefined)
         merged.timeout = next.timeout;
+    if (next.reauthorize !== undefined)
+        merged.reauthorize = next.reauthorize;
     if (next.body !== undefined)
         merged.body = next.body;
     return merged;

package/dist/core/extend-resource.d.ts

@@ -1,3 +1,5 @@
+import type { HerokuApiClientOptions } from '@heroku/heroku-fetch';
+import { HerokuApiClient } from '@heroku/heroku-fetch';
 import type { DashboardBackendClient } from '../services/dashboard-backend.js';
 import type { DataClient } from '../services/data.js';
 import type { MetricsClient } from '../services/metrics.js';
@@ -14,10 +16,58 @@ type BaseResourceCtx = {
     platform: PlatformClient;
     repositories: RepositoriesClient;
 };
-export type ResourceCtx = BaseResourceCtx & {
+export type ResourceCtx = {
+    /**
+     * Build a raw {@link HerokuApiClient} that inherits the SDK's resolved
+     * client options for the `inheritFrom` service bundle (token,
+     * `userAgent`/headers, `signal`, `timeout`, `warn`, …), with `overrides`
+     * applied last.
+     *
+     * `inheritFrom` selects *which resolved option bundle to start from* — not
+     * the wire service; pass `service` in `overrides` to redirect the client to
+     * a different host and auth behavior. The returned client is raw, NOT the
+     * managed service client: it does not carry that client's `defaultAccept`
+     * (e.g. the platform's `version=3.sdk`) or routes proxy, so callers issue
+     * `get`/`post`/`stream` directly and set `Accept` per call.
+     *
+     * When `overrides.service === 'custom'` the inherited bundle is narrowed to
+     * identity and cancellation only (never auth/routing), so a custom stream
+     * host can't receive the Heroku token, a `reauthorize` login callback, or
+     * consumer headers. Prefer {@link makeCustomHostClient} for that case rather
+     * than assembling the overrides by hand.
+     *
+     * Optional for compatibility with existing extension contexts; prefer
+     * {@link makeCtxClient} at call sites so a context predating this stays
+     * on the pre-threading behavior.
+     *
+     * TODO(next major): make this required on ResourceCtx and drop the
+     * {@link makeCtxClient} fallback once external hand-built contexts are no
+     * longer supported.
+     */
+    makeClient?: (inheritFrom: ServiceName, overrides?: HerokuApiClientOptions) => HerokuApiClient;
     /** Available to SDK-provided extensions; optional for compatibility with existing extension contexts. */
     repositoriesApi?: RepositoriesApiClient;
-};
+} & BaseResourceCtx;
+/**
+ * Build a raw {@link HerokuApiClient} from a resource context, inheriting the
+ * SDK's resolved client options for the `inheritFrom` service bundle
+ * (identity, `signal`, `warn`, token, …) with `overrides` applied last. Falls
+ * back to a bare client carrying only `overrides` when the context predates
+ * {@link ResourceCtx.makeClient} (e.g. a hand-built test ctx, or a standalone
+ * call with no SDK behind it), preserving the pre-threading behavior exactly.
+ */
+export declare function makeCtxClient(ctx: Pick<ResourceCtx, 'makeClient'>, inheritFrom: ServiceName, overrides?: HerokuApiClientOptions): HerokuApiClient;
+/**
+ * Build a raw {@link HerokuApiClient} for a non-Heroku-credential host — a
+ * custom stream/API host the routes-generated clients don't cover (logplex,
+ * busl, exec-manager). Inherits only the SDK's identity and cancellation from
+ * the platform option bundle; forces `service: 'custom'`, the given `baseUrl`,
+ * and an empty `token`, and drops every auth/routing option (`reauthorize`,
+ * `headers`, `hooks`, `twoFactor`, `region`, …) so none crosses to the
+ * third-party origin. `overrides` the call site explicitly sets still apply —
+ * use them for a per-host header or timeout, not to smuggle inherited auth.
+ */
+export declare function makeCustomHostClient(ctx: Pick<ResourceCtx, 'makeClient'>, baseUrl: string, overrides?: Omit<HerokuApiClientOptions, 'baseUrl' | 'service' | 'token'>): HerokuApiClient;
 export type ResourceMethods = Record<string, (...args: any[]) => any>;
 export type ResourceExtension<S extends ServiceName = ServiceName, R extends string = string, M extends ResourceMethods = ResourceMethods> = {
     factory: (ctx: ResourceCtx) => M;

package/dist/core/extend-resource.js

@@ -1,3 +1,30 @@
+import { HerokuApiClient } from '@heroku/heroku-fetch';
+/**
+ * Build a raw {@link HerokuApiClient} from a resource context, inheriting the
+ * SDK's resolved client options for the `inheritFrom` service bundle
+ * (identity, `signal`, `warn`, token, …) with `overrides` applied last. Falls
+ * back to a bare client carrying only `overrides` when the context predates
+ * {@link ResourceCtx.makeClient} (e.g. a hand-built test ctx, or a standalone
+ * call with no SDK behind it), preserving the pre-threading behavior exactly.
+ */
+export function makeCtxClient(ctx, inheritFrom, overrides = {}) {
+    return ctx.makeClient ? ctx.makeClient(inheritFrom, overrides) : new HerokuApiClient(overrides);
+}
+/**
+ * Build a raw {@link HerokuApiClient} for a non-Heroku-credential host — a
+ * custom stream/API host the routes-generated clients don't cover (logplex,
+ * busl, exec-manager). Inherits only the SDK's identity and cancellation from
+ * the platform option bundle; forces `service: 'custom'`, the given `baseUrl`,
+ * and an empty `token`, and drops every auth/routing option (`reauthorize`,
+ * `headers`, `hooks`, `twoFactor`, `region`, …) so none crosses to the
+ * third-party origin. `overrides` the call site explicitly sets still apply —
+ * use them for a per-host header or timeout, not to smuggle inherited auth.
+ */
+export function makeCustomHostClient(ctx, baseUrl, overrides = {}) {
+    return makeCtxClient(ctx, 'platform', {
+        ...overrides, baseUrl, service: 'custom', token: '',
+    });
+}
 export function extendResource(service, resource, factory) {
     return { factory, resource, service };
 }

package/dist/core/heroku-sdk.js

@@ -1,3 +1,4 @@
+import { HerokuApiClient } from '@heroku/heroku-fetch';
 import { createDashboardBackendClient } from '../services/dashboard-backend.js';
 import { createDataClient } from '../services/data.js';
 import { createMetricsClient } from '../services/metrics.js';
@@ -5,7 +6,17 @@ import { createNotificationsClient } from '../services/notifications.js';
 import { createPlatformClient } from '../services/platform.js';
 import { createRepositoriesApiClient } from '../services/repositories-api.js';
 import { createRepositoriesClient } from '../services/repositories.js';
+import { SDK_VERSION } from '../version.js';
 import { mergeExtensions } from './extensions-proxy.js';
+/**
+ * Default `User-Agent` identity for SDK-originated traffic. {@link HerokuSDK}
+ * applies it as a fill-if-absent default on every service client (in its
+ * `#getClientOptions` merge), so requests the SDK drives stay identifiable even
+ * when the consumer passes no `userAgent`. A consumer-supplied
+ * `clientOptions.userAgent` — or a per-service override — wins. The version is
+ * stamped from package.json at build time; see `src/version.ts`.
+ */
+const DEFAULT_USER_AGENT = { name: '@heroku/sdk', version: SDK_VERSION };
 function partitionByService(extensions) {
     const map = new Map();
     for (const ext of extensions) {
@@ -15,6 +26,26 @@ function partitionByService(extensions) {
     }
     return map;
 }
+/**
+ * The options a custom-host client (`service: 'custom'`) inherits from the
+ * SDK's resolved bundle: identity and cancellation only. Every
+ * Heroku-credential-domain option — auth (`token`, `reauthorize`, `twoFactor`),
+ * routing (`headers`, `region`, `defaultAccept`), and consumer
+ * `hooks`/`onResponseMetadata` — is intentionally dropped so it never reaches a
+ * third-party origin (logplex, busl, exec-manager): sending the bearer token or
+ * a consumer `Authorization` header cross-origin would leak credentials, and
+ * inheriting `reauthorize` would turn a non-Heroku 401 into a spurious
+ * `heroku login`.
+ */
+function pickCustomHostOptions(options) {
+    return {
+        ...(options.debug !== undefined && { debug: options.debug }),
+        ...(options.signal !== undefined && { signal: options.signal }),
+        ...(options.timeout !== undefined && { timeout: options.timeout }),
+        ...(options.userAgent !== undefined && { userAgent: options.userAgent }),
+        ...(options.warn !== undefined && { warn: options.warn }),
+    };
+}
 export class HerokuSDK {
     #clientOptions;
     #clientOptionsByService;
@@ -72,6 +103,7 @@ export class HerokuSDK {
         const serviceOptions = { ...serviceOverride };
         delete serviceOptions.service;
         return {
+            userAgent: DEFAULT_USER_AGENT,
             ...this.#clientOptions,
             ...serviceOptions,
         };
@@ -86,6 +118,17 @@ export class HerokuSDK {
                 enumerable: true,
                 get: () => this.#getRawData(),
             },
+            makeClient: {
+                enumerable: true,
+                value: (inheritFrom, overrides = {}) => {
+                    const resolved = this.#getClientOptions(inheritFrom);
+                    // A custom host is not the Heroku credential domain: start from
+                    // identity/cancellation only, never the auth/routing options that
+                    // would leak across origins or drive a re-login on a foreign 401.
+                    const base = overrides.service === 'custom' ? pickCustomHostOptions(resolved) : resolved;
+                    return new HerokuApiClient({ ...base, ...overrides });
+                },
+            },
             metrics: {
                 enumerable: true,
                 get: () => this.#getRawMetrics(),
@@ -122,7 +165,7 @@ export class HerokuSDK {
         return this.#rawMetrics;
     }
     #getRawNotifications() {
-        this.#rawNotifications ??= createNotificationsClient(this.#clientOptions);
+        this.#rawNotifications ??= createNotificationsClient(this.#getClientOptions('notifications'));
         return this.#rawNotifications;
     }
     #getRawPlatform() {

package/dist/resources/data/database-credential/create.d.ts

@@ -0,0 +1,17 @@
+import type { PostgresCredentialCreateOpts, PostgresCredentialCreateResult, PostgresDatabaseCreateCredentialsResult } from '@heroku/types/data';
+import type { ResourceCtx } from '../../../core/extend-resource.js';
+import type { ResolvedAddOn } from '../../platform/add-on/types.js';
+import type { DatabaseCredentialOptions } from './index.js';
+export type CreateDatabaseCredentialResult = {
+    addon: ResolvedAddOn;
+    credential: PostgresCredentialCreateResult | PostgresDatabaseCreateCredentialsResult;
+};
+/**
+ * Creates a credential on a Postgres database, dispatching to the
+ * Advanced-tier or classic-tier endpoint based on the resolved add-on's plan.
+ *
+ * Essential and legacy Essential-tier databases don't support custom credentials.
+ *
+ * Returns the resolved addon alongside the created credential
+ */
+export declare function create(ctx: Pick<ResourceCtx, 'data' | 'platform'>, addonIdentity: string, body: PostgresCredentialCreateOpts, options?: DatabaseCredentialOptions): Promise<CreateDatabaseCredentialResult>;

package/dist/resources/data/database-credential/create.js

@@ -0,0 +1,28 @@
+import { withSignal } from '../../../core/with-signal.js';
+import { resolveAddonInternal } from '../../platform/add-on/resolve.js';
+import { getPostgresServiceName, isAdvancedDatabase, isEssentialTier } from '../internal/postgres-utils.js';
+/**
+ * Creates a credential on a Postgres database, dispatching to the
+ * Advanced-tier or classic-tier endpoint based on the resolved add-on's plan.
+ *
+ * Essential and legacy Essential-tier databases don't support custom credentials.
+ *
+ * Returns the resolved addon alongside the created credential
+ */
+export async function create(ctx, addonIdentity, body, options = {}) {
+    const { appIdentity, signal } = options;
+    signal?.throwIfAborted();
+    // Bind the signal so the resolve and create requests abort in flight.
+    const platform = withSignal(ctx.platform, signal);
+    const addon = await resolveAddonInternal(platform, addonIdentity, {
+        addonService: getPostgresServiceName(), appIdentity,
+    });
+    if (isEssentialTier(addon)) {
+        throw new Error('You can\'t create custom credentials on Essential-tier databases.');
+    }
+    const data = withSignal(ctx.data, signal);
+    const credential = await (isAdvancedDatabase(addon)
+        ? data.postgresCredential.create(addon.id, body)
+        : data.postgresDatabase.createCredentials(addon.id, body));
+    return { addon, credential };
+}

package/dist/resources/data/database-credential/destroy.d.ts

@@ -0,0 +1,17 @@
+import type { PostgresDatabaseDeleteCredentialResult } from '@heroku/types/data';
+import type { ResourceCtx } from '../../../core/extend-resource.js';
+import type { ResolvedAddOn } from '../../platform/add-on/types.js';
+import type { DatabaseCredentialOptions } from './index.js';
+export type DestroyDatabaseCredentialResult = {
+    addon: ResolvedAddOn;
+    result: PostgresDatabaseDeleteCredentialResult | void;
+};
+/**
+ * Destroys a credential on a Postgres database, dispatching to the
+ * Advanced-tier or classic-tier endpoint based on the resolved add-on's plan.
+ *
+ * The owner credential (Advanced tier) and the default credential (classic/Essential
+ * tier) can't be destroyed, custom credentials can't be destroyed on Essential-tier
+ * databases, and a credential still attached to any app must be detached first.
+ */
+export declare function destroy(ctx: Pick<ResourceCtx, 'data' | 'platform'>, addonIdentity: string, credName: string, options?: DatabaseCredentialOptions): Promise<DestroyDatabaseCredentialResult>;

package/dist/resources/data/database-credential/destroy.js

@@ -0,0 +1,55 @@
+import { withSignal } from '../../../core/with-signal.js';
+import { resolveAddonInternal } from '../../platform/add-on/resolve.js';
+import { parseAttachmentFactors } from '../internal/parse-attachment-factors.js';
+import { getPostgresServiceName, isAdvancedDatabase, isEssentialDatabase, isLegacyEssentialDatabase, } from '../internal/postgres-utils.js';
+/**
+ * Destroys a credential on a Postgres database, dispatching to the
+ * Advanced-tier or classic-tier endpoint based on the resolved add-on's plan.
+ *
+ * The owner credential (Advanced tier) and the default credential (classic/Essential
+ * tier) can't be destroyed, custom credentials can't be destroyed on Essential-tier
+ * databases, and a credential still attached to any app must be detached first.
+ */
+export async function destroy(ctx, addonIdentity, credName, options = {}) {
+    const { appIdentity, signal } = options;
+    signal?.throwIfAborted();
+    // Bind the signal so the resolve and destroy requests abort in flight.
+    const platform = withSignal(ctx.platform, signal);
+    const addon = await resolveAddonInternal(platform, addonIdentity, {
+        addonService: getPostgresServiceName(), appIdentity,
+    });
+    const data = withSignal(ctx.data, signal);
+    const isEssentialTier = isEssentialDatabase(addon);
+    const isLegacyEssentialTier = isLegacyEssentialDatabase(addon);
+    const isAdvancedTier = isAdvancedDatabase(addon);
+    let credAttachments = [];
+    if (isAdvancedTier) {
+        const [{ items: availableCreds }, attachments] = await Promise.all([
+            data.postgresCredential.list(addon.id),
+            platform.addOnAttachment.listByAddOn(addon.id),
+        ]);
+        const ownerCred = availableCreds.find(cred => cred.type === 'owner');
+        if (ownerCred?.name === credName) {
+            throw new Error('You can\'t destroy the owner credential.');
+        }
+        credAttachments = attachments.filter(a => parseAttachmentFactors(a.namespace).role === credName);
+    }
+    else if (isEssentialTier) {
+        throw new Error('You can\'t destroy custom credentials on Essential-tier databases.');
+    }
+    else if (isLegacyEssentialTier || credName === 'default') {
+        throw new Error('You can\'t destroy the default credential.');
+    }
+    else {
+        const attachments = await platform.addOnAttachment.listByAddOn(addon.id);
+        credAttachments = attachments.filter(a => a.namespace === `credential:${credName}`);
+    }
+    const credAttachmentApps = [...new Set(credAttachments.map(a => a.app.name))];
+    if (credAttachmentApps.length > 0) {
+        throw new Error(`You must detach the credential ${credName} from the app${credAttachmentApps.length > 1 ? 's' : ''} ${credAttachmentApps.join(', ')} before destroying it.`);
+    }
+    const result = await (isAdvancedTier
+        ? data.postgresCredential.delete(addon.id, credName)
+        : data.postgresDatabase.deleteCredential(addon.id, credName));
+    return { addon, result };
+}

package/dist/resources/data/database-credential/get-url.d.ts

@@ -0,0 +1,25 @@
+import type { ResourceCtx } from '../../../core/extend-resource.js';
+import type { ResolvedAddOn } from '../../platform/add-on/types.js';
+import type { DatabaseCredentialOptions } from './index.js';
+export type CredentialConnectionInfo = {
+    credName: string;
+    database: string;
+    host: string;
+    password: string;
+    port: number;
+    url: string;
+    user: string;
+};
+export type GetDatabaseCredentialUrlResult = {
+    addon: ResolvedAddOn;
+    credentialConnectionInfo: CredentialConnectionInfo;
+};
+/**
+ * Looks up the active connection info for a Postgres database credential,
+ * dispatching to the Advanced-tier or classic-tier endpoint based on the
+ * resolved add-on's plan, and returns a ready-to-use connection URL.
+ *
+ * `credName` defaults to the owner credential on the Advanced tier, or the
+ * `default` credential on the classic tier.
+ */
+export declare function getUrl(ctx: Pick<ResourceCtx, 'data' | 'platform'>, addonIdentity: string, credName?: string, options?: DatabaseCredentialOptions): Promise<GetDatabaseCredentialUrlResult>;

package/dist/resources/data/database-credential/get-url.js

@@ -0,0 +1,68 @@
+import { withSignal } from '../../../core/with-signal.js';
+import { resolveAddonInternal } from '../../platform/add-on/resolve.js';
+import { getPostgresServiceName, isAdvancedCredential, isAdvancedDatabase, isEssentialTier, } from '../internal/postgres-utils.js';
+/**
+ * Looks up the active connection info for a Postgres database credential,
+ * dispatching to the Advanced-tier or classic-tier endpoint based on the
+ * resolved add-on's plan, and returns a ready-to-use connection URL.
+ *
+ * `credName` defaults to the owner credential on the Advanced tier, or the
+ * `default` credential on the classic tier.
+ */
+export async function getUrl(ctx, addonIdentity, credName, options = {}) {
+    options.signal?.throwIfAborted();
+    // Bind the signal so the resolve and lookup requests abort in flight.
+    const platform = withSignal(ctx.platform, options.signal);
+    const addon = await resolveAddonInternal(platform, addonIdentity, {
+        addonService: getPostgresServiceName(), appIdentity: options.appIdentity,
+    });
+    const data = withSignal(ctx.data, options.signal);
+    if (isEssentialTier(addon) && credName && credName !== 'default') {
+        throw new Error('Essential-tier databases don\'t support named credentials.');
+    }
+    let name;
+    let info;
+    if (isAdvancedDatabase(addon)) {
+        name = credName;
+        if (!name) {
+            const { items } = await data.postgresCredential.list(addon.id);
+            name = items.find(item => item.type === 'owner')?.name;
+            if (!name) {
+                throw new Error(`There are no active credentials on the database ${addon.name}.`);
+            }
+        }
+        info = await data.postgresCredential.info(addon.id, name);
+    }
+    else {
+        name = credName || 'default';
+        info = await data.postgresDatabase.infoCredential(addon.id, name);
+    }
+    const activeCred = isAdvancedCredential(info)
+        ? info.roles.find(r => r.state === 'active')
+        : info.credentials.find(c => c.state === 'active');
+    if (!activeCred) {
+        throw new Error(`The credential ${name} isn't active on the database ${addon.name}.`);
+    }
+    const credInfo = {
+        credName: name,
+        database: info.database,
+        host: info.host,
+        password: activeCred.password,
+        port: info.port,
+        user: activeCred.user,
+    };
+    const url = new URL(`postgres://${credInfo.host}/${credInfo.database}`);
+    url.port = credInfo.port.toString();
+    if (credInfo.user && credInfo.password) {
+        url.username = credInfo.user;
+        url.password = credInfo.password;
+    }
+    const credentialConnectionInfo = {
+        ...credInfo,
+        url: url.toString(),
+    };
+    return {
+        addon,
+        credentialConnectionInfo,
+    };
+}

package/dist/resources/data/database-credential/index.d.ts

@@ -0,0 +1,24 @@
+import type { PostgresCredentialCreateOpts } from '@heroku/types/data';
+import type { RotateAllDatabaseCredentialsResult, RotateDatabaseCredentialOptions, RotateDatabaseCredentialOpts, RotateDatabaseCredentialResult } from './rotate.js';
+export type DatabaseCredentialOptions = {
+    appIdentity?: string;
+    signal?: AbortSignal;
+};
+export { create, type CreateDatabaseCredentialResult } from './create.js';
+export { destroy, type DestroyDatabaseCredentialResult } from './destroy.js';
+export { type GetDatabaseCredentialUrlResult, getUrl, } from './get-url.js';
+export { NotAdvancedDatabaseError } from './list.js';
+export { list, type ListDatabaseCredentialsResult } from './list.js';
+export { rotate, type RotateAllDatabaseCredentialsResult, type RotateDatabaseCredentialOptions, type RotateDatabaseCredentialOpts, type RotateDatabaseCredentialPreview, type RotateDatabaseCredentialResult, } from './rotate.js';
+export declare const databaseCredentialExtensions: import("../../../core/extend-resource.js").ResourceExtension<"data", "databaseCredential", {
+    create: (addonIdentity: string, body: PostgresCredentialCreateOpts, options?: DatabaseCredentialOptions) => Promise<import("./create.js").CreateDatabaseCredentialResult>;
+    destroy: (addonIdentity: string, credName: string, options?: DatabaseCredentialOptions) => Promise<import("./destroy.js").DestroyDatabaseCredentialResult>;
+    getUrl: (addonIdentity: string, credName?: string, options?: DatabaseCredentialOptions) => Promise<import("./get-url.js").GetDatabaseCredentialUrlResult>;
+    list: (addonIdentity: string, options?: DatabaseCredentialOptions) => Promise<import("./list.js").ListDatabaseCredentialsResult>;
+    rotate: {
+        (addonIdentity: string, body: RotateDatabaseCredentialOpts & {
+            all: true;
+        }, options?: RotateDatabaseCredentialOptions): Promise<RotateAllDatabaseCredentialsResult>;
+        (addonIdentity: string, body?: RotateDatabaseCredentialOpts, options?: RotateDatabaseCredentialOptions): Promise<RotateDatabaseCredentialResult>;
+    };
+}>;

package/dist/resources/data/database-credential/index.js

@@ -0,0 +1,24 @@
+import { extendResource } from '../../../core/extend-resource.js';
+import { create } from './create.js';
+import { destroy } from './destroy.js';
+import { getUrl } from './get-url.js';
+import { list } from './list.js';
+import { rotate } from './rotate.js';
+export { create } from './create.js';
+export { destroy } from './destroy.js';
+export { getUrl, } from './get-url.js';
+export { NotAdvancedDatabaseError } from './list.js';
+export { list } from './list.js';
+export { rotate, } from './rotate.js';
+export const databaseCredentialExtensions = extendResource('data', 'databaseCredential', ctx => {
+    function rotateCredential(addonIdentity, body, options) {
+        return rotate(ctx, addonIdentity, body, options);
+    }
+    return {
+        create: (addonIdentity, body, options) => create(ctx, addonIdentity, body, options),
+        destroy: (addonIdentity, credName, options) => destroy(ctx, addonIdentity, credName, options),
+        getUrl: (addonIdentity, credName, options) => getUrl(ctx, addonIdentity, credName, options),
+        list: (addonIdentity, options) => list(ctx, addonIdentity, options),
+        rotate: rotateCredential,
+    };
+});

package/dist/resources/data/database-credential/list.d.ts

@@ -0,0 +1,32 @@
+import type { PostgresCredentialListResult } from '@heroku/types/data';
+import type { ResourceCtx } from '../../../core/extend-resource.js';
+import type { ResolvedAddOn } from '../../platform/add-on/types.js';
+import { DatabaseCredentialOptions } from './index.js';
+/**
+ * Thrown by `list` when the resolved add-on is not an Advanced-tier
+ * database. Carries the resolved addon so callers that need its identity
+ * (e.g. to point the user at the classic-tier equivalent) don't need a
+ * second resolve call.
+ */
+export declare class NotAdvancedDatabaseError extends Error {
+    readonly addon: ResolvedAddOn;
+    readonly id = "not_advanced_database";
+    constructor(addon: ResolvedAddOn);
+    get body(): {
+        id: string;
+        message: string;
+    };
+}
+export type ListDatabaseCredentialsResult = {
+    addon: ResolvedAddOn;
+    credentials: PostgresCredentialListResult;
+};
+/**
+ * Lists credentials on an Advanced-tier Postgres database. Classic-tier
+ * databases don't support this endpoint; use `postgresDatabase.listCredentials`
+ * for those instead.
+ *
+ * Throws `NotAdvancedDatabaseError` (carrying the resolved addon) if
+ * `addonIdentity` doesn't resolve to an Advanced-tier database.
+ */
+export declare function list(ctx: Pick<ResourceCtx, 'data' | 'platform'>, addonIdentity: string, options?: DatabaseCredentialOptions): Promise<ListDatabaseCredentialsResult>;

package/dist/resources/data/database-credential/list.js

@@ -0,0 +1,44 @@
+import { withSignal } from '../../../core/with-signal.js';
+import { resolveAddonInternal } from '../../platform/add-on/resolve.js';
+import { getPostgresServiceName, isAdvancedDatabase } from '../internal/postgres-utils.js';
+/**
+ * Thrown by `list` when the resolved add-on is not an Advanced-tier
+ * database. Carries the resolved addon so callers that need its identity
+ * (e.g. to point the user at the classic-tier equivalent) don't need a
+ * second resolve call.
+ */
+export class NotAdvancedDatabaseError extends Error {
+    addon;
+    id = 'not_advanced_database';
+    constructor(addon) {
+        super(`You can only list credentials on Advanced-tier databases. ${addon.name} isn't an Advanced-tier database.`);
+        this.addon = addon;
+        this.name = 'NotAdvancedDatabaseError';
+    }
+    get body() {
+        return { id: this.id, message: this.message };
+    }
+}
+/**
+ * Lists credentials on an Advanced-tier Postgres database. Classic-tier
+ * databases don't support this endpoint; use `postgresDatabase.listCredentials`
+ * for those instead.
+ *
+ * Throws `NotAdvancedDatabaseError` (carrying the resolved addon) if
+ * `addonIdentity` doesn't resolve to an Advanced-tier database.
+ */
+export async function list(ctx, addonIdentity, options = {}) {
+    const { appIdentity, signal } = options;
+    signal?.throwIfAborted();
+    // Bind the signal so the resolve and list requests abort in flight.
+    const platform = withSignal(ctx.platform, signal);
+    const addon = await resolveAddonInternal(platform, addonIdentity, {
+        addonService: getPostgresServiceName(), appIdentity,
+    });
+    if (!isAdvancedDatabase(addon)) {
+        throw new NotAdvancedDatabaseError(addon);
+    }
+    const data = withSignal(ctx.data, signal);
+    const credentials = await data.postgresCredential.list(addon.id);
+    return { addon, credentials };
+}

package/dist/resources/data/database-credential/rotate.d.ts

@@ -0,0 +1,56 @@
+import type { PostgresDatabaseInfoCredentialResult as NonAdvancedCredentialInfo, PostgresCredentialListResult, PostgresDatabaseRotateCredentialResult, PostgresDatabaseRotateCredentialsResult, PostgresRotateCredentialsResult } from '@heroku/types/data';
+import { AddOnAttachment } from '@heroku/types/3.sdk';
+import type { ResourceCtx } from '../../../core/extend-resource.js';
+import type { ResolvedAddOn } from '../../platform/add-on/types.js';
+import type { DatabaseCredentialOptions } from './index.js';
+type AdvancedCredentialInfo = PostgresCredentialListResult['items'][number];
+export type RotateDatabaseCredentialOptions = DatabaseCredentialOptions & {
+    /**
+     * Fires before the rotate request, allowing the caller to perform any
+     * necessary pre-rotation checks or UI rendering.
+     */
+    beforeRotate?: (preview: RotateDatabaseCredentialPreview) => Promise<void> | void;
+};
+export type RotateDatabaseCredentialOpts = {
+    /** Rotate every credential on the database instead of a single one. */
+    all?: boolean;
+    /** Name of the credential to rotate. Defaults to owner or default credential. */
+    credName?: string;
+    /** Immediately kill connections using the credential(s) being rotated. */
+    forced?: boolean;
+};
+/**
+ * Resolved state of a rotation, passed to `beforeRotate` before the request
+ * is sent: the add-on, the credential that will rotate, the owner and default
+ * credentials, whether the database is Advanced or Essential tier, and the
+ * add-on's attachments.
+ */
+export type RotateDatabaseCredentialPreview = {
+    addon: ResolvedAddOn;
+    attachments: AddOnAttachment[];
+    credToRotate?: AdvancedCredentialInfo | NonAdvancedCredentialInfo;
+    defaultCred?: NonAdvancedCredentialInfo;
+    isAdvancedTier: boolean;
+    isEssentialTier: boolean;
+    ownerCred?: AdvancedCredentialInfo;
+};
+export type RotateAllDatabaseCredentialsResult = {
+    addon: ResolvedAddOn;
+    credentials: PostgresDatabaseRotateCredentialsResult | PostgresRotateCredentialsResult;
+};
+export type RotateDatabaseCredentialResult = {
+    addon: ResolvedAddOn;
+    credential: PostgresDatabaseRotateCredentialResult | void;
+};
+/**
+ * Rotates one or all credentials on a Postgres database, dispatching to the
+ * Advanced-tier or classic-tier endpoint based on the resolved add-on's plan.
+ *
+ * Essential and legacy Essential-tier databases don't support named-credential
+ * rotation.
+ */
+export declare function rotate(ctx: Pick<ResourceCtx, 'data' | 'platform'>, addonIdentity: string, body: RotateDatabaseCredentialOpts & {
+    all: true;
+}, options?: RotateDatabaseCredentialOptions): Promise<RotateAllDatabaseCredentialsResult>;
+export declare function rotate(ctx: Pick<ResourceCtx, 'data' | 'platform'>, addonIdentity: string, body?: RotateDatabaseCredentialOpts, options?: RotateDatabaseCredentialOptions): Promise<RotateDatabaseCredentialResult>;
+export {};