@heroku/sdk 0.1.0-alpha.0

package/dist/core/create-client.js

@@ -0,0 +1,48 @@
+import { HerokuApiClient } from '@heroku/heroku-fetch';
+import createDebug from 'debug';
+import { dispatch } from './dispatcher.js';
+const debug = createDebug('heroku:sdk:client');
+export function createClient(routes, options = {}) {
+    const httpClient = new HerokuApiClient(options);
+    return buildClientProxy(httpClient, routes);
+}
+function mergeStickyOptions(base, next) {
+    const merged = { ...base };
+    if (next.headers || base?.headers) {
+        merged.headers = { ...base?.headers, ...next.headers };
+    }
+    // signal and timeout 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;
+    return merged;
+}
+function buildClientProxy(httpClient, routes, inheritedOptions) {
+    return new Proxy({}, {
+        get(_target, resourceKey) {
+            if (resourceKey === 'withOptions') {
+                return (options) => buildClientProxy(httpClient, routes, mergeStickyOptions(inheritedOptions, options));
+            }
+            if (resourceKey === 'withHeaders') {
+                return (headers) => buildClientProxy(httpClient, routes, mergeStickyOptions(inheritedOptions, { headers }));
+            }
+            if (!Object.hasOwn(routes, resourceKey)) {
+                debug('unknown resource: %s', resourceKey);
+                return;
+            }
+            const resourceRoutes = routes[resourceKey];
+            return new Proxy({}, {
+                get(_t, methodKey) {
+                    const route = resourceRoutes[methodKey];
+                    if (!route) {
+                        debug('unknown method: %s.%s', resourceKey, methodKey);
+                        return;
+                    }
+                    return (...args) => dispatch(httpClient, route, args, `${resourceKey}.${methodKey}`, inheritedOptions);
+                },
+            });
+        },
+    });
+}

package/dist/core/dispatcher.d.ts

@@ -0,0 +1,3 @@
+import type { HerokuApiClient, RequestOptions } from '@heroku/heroku-fetch';
+import type { RouteDefinition } from '@heroku/types/types';
+export declare function dispatch(client: HerokuApiClient, route: RouteDefinition, args: unknown[], invocation?: string, requestOptions?: RequestOptions): Promise<unknown>;

package/dist/core/dispatcher.js

@@ -0,0 +1,80 @@
+import createDebug from 'debug';
+import { countPlaceholders, interpolatePath } from './interpolate-path.js';
+const debug = createDebug('heroku:sdk:dispatcher');
+const MAX_PAGES = 500;
+function hasCallerRangeHeader(requestOptions) {
+    if (!requestOptions?.headers)
+        return false;
+    return Object.keys(requestOptions.headers).some(k => k.toLowerCase() === 'range');
+}
+export async function dispatch(client, route, args, invocation, requestOptions) {
+    const placeholderCount = countPlaceholders(route.path);
+    const pathParams = args.slice(0, placeholderCount);
+    const remaining = args.slice(placeholderCount);
+    const path = interpolatePath(route.path, pathParams);
+    let body;
+    if (route.hasRequestBody && remaining.length > 0) {
+        body = remaining[0];
+    }
+    debug('%s %s %s -> %s hasBody=%s', invocation ?? 'dispatch', route.method, route.path, path, body !== undefined);
+    const response = await callMethod(client, route.method, path, body, requestOptions);
+    const contentLength = response.headers.get('content-length');
+    if (response.status === 204 || contentLength === '0') {
+        debug('%s empty response status=%d content-length=%s', invocation ?? 'dispatch', response.status, contentLength ?? '');
+        return undefined;
+    }
+    const result = await response.json();
+    if (route.method !== 'GET' || !Array.isArray(result) || hasCallerRangeHeader(requestOptions)) {
+        return result;
+    }
+    const nextRange = response.headers.get('next-range');
+    if (!nextRange)
+        return result;
+    return followPages(client, path, result, nextRange, invocation, requestOptions);
+}
+/* eslint-disable no-await-in-loop -- pagination is inherently sequential; each page depends on the previous next-range header */
+async function followPages(client, path, firstPage, initialRange, invocation, requestOptions) {
+    const accumulated = [...firstPage];
+    let nextRange = initialRange;
+    let pages = 1;
+    while (nextRange && pages < MAX_PAGES) {
+        const pageOptions = {
+            ...requestOptions,
+            headers: { ...requestOptions?.headers, Range: nextRange },
+        };
+        debug('%s paginate page=%d range=%s', invocation ?? 'dispatch', pages + 1, nextRange);
+        const pageResponse = await callMethod(client, 'GET', path, undefined, pageOptions);
+        const pageBody = await pageResponse.json();
+        if (Array.isArray(pageBody)) {
+            accumulated.push(...pageBody);
+        }
+        nextRange = pageResponse.headers.get('next-range');
+        pages++;
+    }
+    debug('%s pagination complete pages=%d total=%d', invocation ?? 'dispatch', pages, accumulated.length);
+    return accumulated;
+}
+/* eslint-enable no-await-in-loop */
+function callMethod(client, method, path, body, requestOptions) {
+    switch (method) {
+        case 'DELETE': {
+            return requestOptions ? client.delete(path, requestOptions) : client.delete(path);
+        }
+        case 'GET': {
+            return requestOptions ? client.get(path, requestOptions) : client.get(path);
+        }
+        case 'PATCH': {
+            return requestOptions ? client.patch(path, body, requestOptions) : client.patch(path, body);
+        }
+        case 'POST': {
+            return requestOptions ? client.post(path, body, requestOptions) : client.post(path, body);
+        }
+        case 'PUT': {
+            return requestOptions ? client.put(path, body, requestOptions) : client.put(path, body);
+        }
+        default: {
+            debug('unsupported HTTP method=%s path=%s', method, path);
+            throw new Error(`Unsupported HTTP method: ${method}`);
+        }
+    }
+}

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

@@ -0,0 +1,24 @@
+import type { DataClient } from '../services/data.js';
+import type { PlatformClient } from '../services/platform.js';
+export type ServiceName = 'data' | 'platform';
+export type ResourceCtx = {
+    data: DataClient;
+    platform: PlatformClient;
+};
+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;
+    resource: R;
+    service: S;
+};
+export declare function extendResource<S extends ServiceName, R extends string, M extends ResourceMethods>(service: S, resource: R, factory: (ctx: ResourceCtx) => M): ResourceExtension<S, R, M>;
+export type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+export type ExtensionsFor<Exts extends readonly ResourceExtension[], S extends ServiceName> = Extract<Exts[number], ResourceExtension<S, string, ResourceMethods>>;
+export type MethodsForResource<E, R extends string> = UnionToIntersection<E extends ResourceExtension<ServiceName, R, infer M> ? M : never>;
+type ResourceKeysOf<E> = E extends ResourceExtension<ServiceName, infer R, ResourceMethods> ? R : never;
+export type ApplyExtensions<Base, E> = {
+    [K in keyof Base]: K extends ResourceKeysOf<E> ? MethodsForResource<E, K & string> & Omit<Base[K], keyof MethodsForResource<E, K & string>> : Base[K];
+} & {
+    [K in ResourceKeysOf<E> as K extends keyof Base ? never : K]: MethodsForResource<E, K & string>;
+};
+export {};

package/dist/core/extend-resource.js

@@ -0,0 +1,3 @@
+export function extendResource(service, resource, factory) {
+    return { factory, resource, service };
+}

package/dist/core/extensions-proxy.d.ts

@@ -0,0 +1,2 @@
+import type { ResourceCtx, ResourceExtension } from './extend-resource.js';
+export declare function mergeExtensions<T extends object>(client: T, extensions: readonly ResourceExtension[], ctx: ResourceCtx): T;

package/dist/core/extensions-proxy.js

@@ -0,0 +1,56 @@
+import createDebug from 'debug';
+const debug = createDebug('heroku:sdk:extensions');
+export function mergeExtensions(client, extensions, ctx) {
+    const methodsByResource = new Map();
+    for (const ext of extensions) {
+        const factoryMethods = ext.factory(ctx);
+        debug('loaded extension service=%s resource=%s methods=%o', ext.service, ext.resource, Object.keys(factoryMethods));
+        const merged = methodsByResource.get(ext.resource) ?? {};
+        Object.assign(merged, factoryMethods);
+        methodsByResource.set(ext.resource, merged);
+    }
+    for (const [resource, methods] of methodsByResource) {
+        const routeResource = client[resource];
+        if (routeResource && typeof routeResource === 'object') {
+            for (const methodName of Object.keys(methods)) {
+                if (methodName in routeResource) {
+                    debug('extension shadows upstream route: %s.%s', resource, methodName);
+                }
+            }
+        }
+    }
+    return new Proxy(client, {
+        get(target, resourceKey, receiver) {
+            // `withOptions` / `withHeaders` on the routes client return a
+            // fresh routes proxy without our extensions layer. Intercept
+            // them so the result is re-wrapped with the same extensions —
+            // otherwise extension methods (like `addOn.listPlans`) silently
+            // disappear after a `sdk.platform.withOptions({signal}).addOn`
+            // chain.
+            if (resourceKey === 'withOptions' || resourceKey === 'withHeaders') {
+                const inner = Reflect.get(target, resourceKey, receiver);
+                if (typeof inner !== 'function') {
+                    return inner;
+                }
+                return (...args) => {
+                    const rewrapped = inner.apply(target, args);
+                    return mergeExtensions(rewrapped, extensions, ctx);
+                };
+            }
+            const extMethods = methodsByResource.get(resourceKey);
+            const routeResource = Reflect.get(target, resourceKey, receiver);
+            if (!extMethods) {
+                return routeResource;
+            }
+            const innerTarget = routeResource && typeof routeResource === 'object' ? routeResource : {};
+            return new Proxy(innerTarget, {
+                get(routeTarget, methodKey, methodReceiver) {
+                    if (Object.hasOwn(extMethods, methodKey)) {
+                        return extMethods[methodKey];
+                    }
+                    return Reflect.get(routeTarget, methodKey, methodReceiver);
+                },
+            });
+        },
+    });
+}

package/dist/core/heroku-sdk.d.ts

@@ -0,0 +1,14 @@
+import type { HerokuApiClientOptions } from '@heroku/heroku-fetch';
+import type { DataClient } from '../services/data.js';
+import type { PlatformClient } from '../services/platform.js';
+import type { ApplyExtensions, ExtensionsFor, ResourceExtension } from './extend-resource.js';
+export type HerokuSDKOptions<Exts extends readonly ResourceExtension[]> = {
+    clientOptions?: HerokuApiClientOptions;
+    extensions?: Exts;
+};
+export declare class HerokuSDK<const Exts extends readonly ResourceExtension[] = readonly ResourceExtension[]> {
+    #private;
+    constructor(options?: HerokuSDKOptions<Exts>);
+    get data(): ApplyExtensions<DataClient, ExtensionsFor<Exts, 'data'>>;
+    get platform(): ApplyExtensions<PlatformClient, ExtensionsFor<Exts, 'platform'>>;
+}

package/dist/core/heroku-sdk.js

@@ -0,0 +1,54 @@
+import { createDataClient } from '../services/data.js';
+import { createPlatformClient } from '../services/platform.js';
+import { mergeExtensions } from './extensions-proxy.js';
+function partitionByService(extensions) {
+    const map = new Map();
+    for (const ext of extensions) {
+        const list = map.get(ext.service) ?? [];
+        list.push(ext);
+        map.set(ext.service, list);
+    }
+    return map;
+}
+export class HerokuSDK {
+    #clientOptions;
+    #ctx;
+    #data;
+    #extensionsByService;
+    #platform;
+    #rawData;
+    #rawPlatform;
+    constructor(options = {}) {
+        this.#clientOptions = options.clientOptions ?? {};
+        this.#extensionsByService = partitionByService(options.extensions ?? []);
+    }
+    get data() {
+        this.#data ??= mergeExtensions(this.#getRawData(), this.#extensionsByService.get('data') ?? [], this.#getCtx());
+        return this.#data;
+    }
+    get platform() {
+        this.#platform ??= mergeExtensions(this.#getRawPlatform(), this.#extensionsByService.get('platform') ?? [], this.#getCtx());
+        return this.#platform;
+    }
+    #getCtx() {
+        this.#ctx ??= Object.defineProperties({}, {
+            data: {
+                enumerable: true,
+                get: () => this.#getRawData(),
+            },
+            platform: {
+                enumerable: true,
+                get: () => this.#getRawPlatform(),
+            },
+        });
+        return this.#ctx;
+    }
+    #getRawData() {
+        this.#rawData ??= createDataClient(this.#clientOptions);
+        return this.#rawData;
+    }
+    #getRawPlatform() {
+        this.#rawPlatform ??= createPlatformClient(this.#clientOptions);
+        return this.#rawPlatform;
+    }
+}

package/dist/core/interpolate-path.d.ts

@@ -0,0 +1,3 @@
+export declare const PLACEHOLDER: RegExp;
+export declare function countPlaceholders(template: string): number;
+export declare function interpolatePath(template: string, params: string[]): string;

package/dist/core/interpolate-path.js

@@ -0,0 +1,13 @@
+export const PLACEHOLDER = /\{[^}]+\}/g;
+export function countPlaceholders(template) {
+    return template.match(PLACEHOLDER)?.length ?? 0;
+}
+export function interpolatePath(template, params) {
+    let i = 0;
+    return template.replaceAll(PLACEHOLDER, () => {
+        if (i >= params.length) {
+            throw new Error(`Missing path parameter at index ${i} for template: ${template}`);
+        }
+        return encodeURIComponent(params[i++]);
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { extendResource, type ResourceCtx, type ResourceExtension, type ServiceName, } from './core/extend-resource.js';
+export { HerokuSDK, type HerokuSDKOptions } from './core/heroku-sdk.js';
+export type { HerokuApiClientOptions } from '@heroku/heroku-fetch';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { extendResource, } from './core/extend-resource.js';
+export { HerokuSDK } from './core/heroku-sdk.js';

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

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

package/dist/resources/data/backup.js

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

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

@@ -0,0 +1,54 @@
+import type { DatabaseInfoResult } from '@heroku/types/data';
+import type { ResourceCtx } from '../../core/extend-resource.js';
+export type DatabaseOptions = {
+    signal?: AbortSignal;
+};
+export type DatabaseUpgradeBody = {
+    version?: string;
+};
+export type DatabaseDescribeResult = DatabaseInfoResult & {
+    following?: string;
+    'hot_standby?'?: boolean;
+    num_connections?: number;
+    num_tables?: number;
+    postgres_version?: string;
+    'standalone?'?: boolean;
+};
+export type DatabaseUpgradeWaitResult = {
+    'error?': boolean;
+    message: string;
+    step: string;
+    'waiting?': boolean;
+};
+export type DatabaseUpgradeResponse = {
+    message: string;
+};
+type DatabaseDataClient = {
+    database: {
+        cancelUpgrade(name: string): Promise<DatabaseUpgradeResponse>;
+        dryRunUpgrade(name: string, body: DatabaseUpgradeBody): Promise<DatabaseUpgradeResponse>;
+        info(name: string): Promise<DatabaseDescribeResult>;
+        prepareUpgrade(name: string, body: DatabaseUpgradeBody): Promise<DatabaseUpgradeResponse>;
+        runUpgrade(name: string, body: DatabaseUpgradeBody): Promise<DatabaseUpgradeResponse>;
+        upgradeWaitStatus(name: string): Promise<DatabaseUpgradeWaitResult>;
+    };
+};
+type DatabaseCtx = {
+    data: DatabaseDataClient;
+    platform: ResourceCtx['platform'];
+};
+export declare function describe(ctx: DatabaseCtx, appIdentity: string, addonIdentity?: string, options?: DatabaseOptions): Promise<DatabaseDescribeResult>;
+export declare function upgradeWaitStatus(ctx: DatabaseCtx, appIdentity: string, addonIdentity?: string, options?: DatabaseOptions): Promise<DatabaseUpgradeWaitResult>;
+export declare function dryRunUpgrade(ctx: DatabaseCtx, appIdentity: string, addonIdentity?: string, body?: DatabaseUpgradeBody, options?: DatabaseOptions): Promise<DatabaseUpgradeResponse>;
+export declare function runUpgrade(ctx: DatabaseCtx, appIdentity: string, addonIdentity?: string, body?: DatabaseUpgradeBody, options?: DatabaseOptions): Promise<DatabaseUpgradeResponse>;
+export declare function prepareUpgrade(ctx: DatabaseCtx, appIdentity: string, addonIdentity?: string, body?: DatabaseUpgradeBody, options?: DatabaseOptions): Promise<DatabaseUpgradeResponse>;
+export declare function cancelUpgrade(ctx: DatabaseCtx, appIdentity: string, addonIdentity?: string, options?: DatabaseOptions): Promise<DatabaseUpgradeResponse>;
+export declare const databaseExtensions: import("../../core/extend-resource.js").ResourceExtension<"data", "database", {
+    cancelUpgrade: (appIdentity: string, addonIdentity?: string, options?: DatabaseOptions) => Promise<DatabaseUpgradeResponse>;
+    describe: (appIdentity: string, addonIdentity?: string, options?: DatabaseOptions) => Promise<DatabaseDescribeResult>;
+    dryRunUpgrade: (appIdentity: string, addonIdentity?: string, body?: DatabaseUpgradeBody, options?: DatabaseOptions) => Promise<DatabaseUpgradeResponse>;
+    prepareUpgrade: (appIdentity: string, addonIdentity?: string, body?: DatabaseUpgradeBody, options?: DatabaseOptions) => Promise<DatabaseUpgradeResponse>;
+    runUpgrade: (appIdentity: string, addonIdentity?: string, body?: DatabaseUpgradeBody, options?: DatabaseOptions) => Promise<DatabaseUpgradeResponse>;
+    upgradeWaitStatus: (appIdentity: string, addonIdentity?: string, options?: DatabaseOptions) => Promise<DatabaseUpgradeWaitResult>;
+}>;
+export {};

package/dist/resources/data/database.js

@@ -0,0 +1,44 @@
+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 });
+    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 });
+    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 });
+    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 });
+    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 });
+    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 });
+    return ctx.data.database.cancelUpgrade(addon.id);
+}
+export const databaseExtensions = extendResource('data', 'database', rawCtx => {
+    // Bridge heroku-types' loose client types to the adapter's strongly-typed contract
+    const ctx = rawCtx;
+    return {
+        cancelUpgrade: (appIdentity, addonIdentity, options) => cancelUpgrade(ctx, appIdentity, addonIdentity, options),
+        describe: (appIdentity, addonIdentity, options) => describe(ctx, appIdentity, addonIdentity, options),
+        dryRunUpgrade: (appIdentity, addonIdentity, body, options) => dryRunUpgrade(ctx, appIdentity, addonIdentity, body, options),
+        prepareUpgrade: (appIdentity, addonIdentity, body, options) => prepareUpgrade(ctx, appIdentity, addonIdentity, body, options),
+        runUpgrade: (appIdentity, addonIdentity, body, options) => runUpgrade(ctx, appIdentity, addonIdentity, body, options),
+        upgradeWaitStatus: (appIdentity, addonIdentity, options) => upgradeWaitStatus(ctx, appIdentity, addonIdentity, options),
+    };
+});

package/dist/resources/data/internal/resolve-addon-id.d.ts

@@ -0,0 +1,2 @@
+import type { PlatformClient } from '../../../services/platform.js';
+export declare function resolveAddonId(platform: PlatformClient, appIdentity: string, addonIdentity?: string): Promise<string>;

package/dist/resources/data/internal/resolve-addon-id.js

@@ -0,0 +1,13 @@
+export async function resolveAddonId(platform, appIdentity, addonIdentity) {
+    const matches = await platform.addOnAttachment.resolution({
+        // eslint-disable-next-line camelcase
+        addon_attachment: addonIdentity ?? 'DATABASE_URL',
+        app: appIdentity,
+    });
+    const attachment = matches[0];
+    const addonId = attachment?.addon?.id;
+    if (!addonId) {
+        throw new Error(`Could not resolve add-on for ${appIdentity}${addonIdentity ? `::${addonIdentity}` : ''}`);
+    }
+    return addonId;
+}

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

@@ -0,0 +1,23 @@
+import type { ResourceCtx } from '../../../core/extend-resource.js';
+import type { ResolveAddonOptions, ResolvedAddOn } from '../../platform/add-on/index.js';
+export type ResolvePgDatabaseOptions = ResolveAddonOptions & {
+    input?: string;
+};
+/**
+ * Resolve a Heroku Postgres database add-on from any of the input
+ * shapes the platform recognizes:
+ *
+ *   - 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`.
+ *
+ * Throws `AddonNotFoundError` (or `AddonAmbiguousError`) 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>;

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

@@ -0,0 +1,52 @@
+import createDebug from 'debug';
+import { resolveAddon, resolveAddonByAttachment } from '../../platform/add-on/index.js';
+const debug = createDebug('heroku:sdk:resources:database');
+const DEFAULT_PG_ATTACHMENT = 'DATABASE_URL';
+/**
+ * Resolve a Heroku Postgres database add-on from any of the input
+ * shapes the platform recognizes:
+ *
+ *   - 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`.
+ *
+ * Throws `AddonNotFoundError` (or `AddonAmbiguousError`) 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.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 });
+    }
+    if (appIdentity && isAttachmentName(input)) {
+        debug('resolve branch=attachment-name app=%s attachment=%s', appIdentity, input);
+        return resolveAddonByAttachment(ctx, appIdentity, input, rest);
+    }
+    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);
+}
+function parseBranchReference(reference, fallbackApp) {
+    const match = reference.match(/^(.+)::(.+)$/);
+    if (match) {
+        return { addon: match[2], app: match[1] };
+    }
+    return fallbackApp ? { addon: reference, app: fallbackApp } : { addon: reference };
+}

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

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

package/dist/resources/data/maintenance.js

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

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

@@ -0,0 +1,11 @@
+import type { PostgresCredentialInfoResult, PostgresCredentialListResult } from '@heroku/types/data';
+import type { ResourceCtx } from '../../core/extend-resource.js';
+export type PostgresCredentialOptions = {
+    signal?: AbortSignal;
+};
+export declare function list(ctx: Pick<ResourceCtx, 'data' | 'platform'>, appIdentity: string, addonIdentity?: string, options?: PostgresCredentialOptions): Promise<PostgresCredentialListResult>;
+export declare function info(ctx: Pick<ResourceCtx, 'data' | 'platform'>, appIdentity: string, credName: string, addonIdentity?: string, options?: PostgresCredentialOptions): Promise<PostgresCredentialInfoResult>;
+export declare const postgresCredentialExtensions: import("../../index.js").ResourceExtension<"data", "postgresCredential", {
+    info: (appIdentity: string, credName: string, addonIdentity?: string, options?: PostgresCredentialOptions) => Promise<PostgresCredentialInfoResult>;
+    list: (appIdentity: string, addonIdentity?: string, options?: PostgresCredentialOptions) => Promise<PostgresCredentialListResult>;
+}>;

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

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

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

@@ -0,0 +1,32 @@
+import type { ResourceCtx } from '../../core/extend-resource.js';
+export type ListCredentialsOptions = {
+    signal?: AbortSignal;
+};
+export type CredentialInfo = {
+    credentials: Array<{
+        connections?: null | number;
+        password: string;
+        state: string;
+        user: string;
+    }>;
+    database: string;
+    host: string;
+    name: string;
+    port: string;
+    state: string;
+    uuid: string;
+};
+type CredentialsDataClient = {
+    postgresDatabase: {
+        listCredentials(name: string): Promise<CredentialInfo[]>;
+    };
+};
+type CredentialsCtx = {
+    data: CredentialsDataClient;
+    platform: ResourceCtx['platform'];
+};
+export declare function listCredentials(ctx: CredentialsCtx, appIdentity: string, addonIdentity?: string, options?: ListCredentialsOptions): Promise<CredentialInfo[]>;
+export declare const postgresDatabaseExtensions: import("../../core/extend-resource.js").ResourceExtension<"data", "postgresDatabase", {
+    listCredentials: (appIdentity: string, addonIdentity?: string, options?: ListCredentialsOptions) => Promise<CredentialInfo[]>;
+}>;
+export {};

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

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