@heroku/sdk 0.1.0-beta.0

package/dist/resources/platform/log-session.js

@@ -0,0 +1,167 @@
+import { HerokuApiClient } from '@heroku/heroku-fetch';
+import createDebug from 'debug';
+import { extendResource } from '../../core/extend-resource.js';
+import { getGeneration } from './app.js';
+const debug = createDebug('heroku:sdk:resources:log-session');
+const DEFAULT_FIR_SESSION_TIMEOUT_MS = 15 * 60 * 1000;
+const FIR_TIMEOUT_ERROR_MESSAGE = 'Fir log stream timeout';
+/**
+ * Stream logs for an app, yielding one line at a time.
+ *
+ * Creates a log session via `logSession.create`, opens the resulting
+ * `logplex_url`, and parses the chunked plain-text response into
+ * newline-delimited entries. Use `tail: true` to keep the stream
+ * open; `recreateSession: true` (the default when tailing) makes the
+ * SDK transparently re-open a new session after the platform's idle
+ * timeout, so the iterator keeps yielding without the caller having
+ * to handle the reconnect.
+ *
+ * The iterator terminates cleanly when:
+ *   - the platform closes a non-tailing stream (all lines yielded)
+ *   - `signal` is aborted (an `AbortError` propagates)
+ *   - `recreateSession` is false and the platform closes a tail
+ *
+ * The iterator throws on:
+ *   - non-2xx response from the logplex URL
+ *   - errors thrown by `logSession.create` (auth, app-not-found, etc.)
+ */
+export async function* streamLogs(ctx, appIdentity, options = {}) {
+    const { dyno, lines, sessionTimeoutMs = DEFAULT_FIR_SESSION_TIMEOUT_MS, signal, source, tail = false, type, } = options;
+    signal?.throwIfAborted();
+    const generation = await getGeneration(ctx, appIdentity, { signal });
+    const isFir = generation === 'fir';
+    // Fir doesn't support a bounded session; the platform always streams.
+    const effectiveTail = isFir ? true : tail;
+    const recreateSession = options.recreateSession ?? effectiveTail;
+    const createOpts = buildCreateOpts({
+        dyno, isFir, lines, source, tail: effectiveTail, type,
+    });
+    // The recreate loop is inherently sequential: each session must
+    // close before we ask for the next one.
+    /* eslint-disable no-await-in-loop */
+    let isRecreate = false;
+    while (true) {
+        debug('streamLogs creating session app=%s generation=%s tail=%s', appIdentity, generation ?? '<unknown>', effectiveTail);
+        const session = await ctx.platform.logSession.create(appIdentity, createOpts);
+        if (!session.logplex_url) {
+            throw new Error('Log session response did not include a logplex_url.');
+        }
+        await options.onSessionCreated?.({ generation, isRecreate });
+        isRecreate = true;
+        debug('streamLogs session=%s opening stream', session.id);
+        let timedOut = false;
+        let timeoutHandle;
+        try {
+            // Logplex URLs hit a region-specific stream host (e.g.
+            // virginia.sessions.logs.heroku.com). The token is embedded in
+            // the URL, so we use a custom-service client with no auth and
+            // a per-call baseUrl; this also picks up heroku-fetch's
+            // env-var proxy support.
+            const parsed = new URL(session.logplex_url);
+            const logplexClient = new HerokuApiClient({
+                baseUrl: parsed.origin,
+                service: 'custom',
+                token: '',
+            });
+            const response = await logplexClient.stream(`${parsed.pathname}${parsed.search}`);
+            if (!response.body) {
+                throw new Error('Logplex stream returned no body.');
+            }
+            const reader = response.body.getReader();
+            const decoder = new TextDecoder();
+            let pending = '';
+            // Force a recreate after sessionTimeoutMs of silence; ignored
+            // when not tailing.
+            const armTimeout = () => {
+                if (!recreateSession)
+                    return;
+                if (timeoutHandle)
+                    clearTimeout(timeoutHandle);
+                timeoutHandle = setTimeout(() => {
+                    timedOut = true;
+                    debug('streamLogs session=%s timed out after %dms', session.id, sessionTimeoutMs);
+                    reader.cancel().catch(() => { });
+                }, sessionTimeoutMs);
+            };
+            armTimeout();
+            try {
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    armTimeout();
+                    pending += decoder.decode(value, { stream: true });
+                    let newlineIndex = pending.indexOf('\n');
+                    while (newlineIndex !== -1) {
+                        const line = pending.slice(0, newlineIndex);
+                        pending = pending.slice(newlineIndex + 1);
+                        if (line.length > 0)
+                            yield line;
+                        newlineIndex = pending.indexOf('\n');
+                    }
+                }
+                // Flush any trailing partial line that didn't end in '\n'.
+                const trailing = pending + decoder.decode();
+                if (trailing.length > 0)
+                    yield trailing;
+            }
+            finally {
+                if (timeoutHandle)
+                    clearTimeout(timeoutHandle);
+                reader.releaseLock();
+            }
+            if (timedOut) {
+                debug('streamLogs session=%s recreating after timeout', session.id);
+                continue;
+            }
+            if (!recreateSession) {
+                return;
+            }
+            debug('streamLogs session=%s remote closed; recreating', session.id);
+        }
+        catch (error) {
+            if (timeoutHandle)
+                clearTimeout(timeoutHandle);
+            if (signal?.aborted)
+                throw error;
+            if (timedOut)
+                continue;
+            // Translate Fir's documented timeout error message into a recreate.
+            if (error instanceof Error && error.message === FIR_TIMEOUT_ERROR_MESSAGE && recreateSession) {
+                continue;
+            }
+            throw error;
+        }
+    }
+    /* eslint-enable no-await-in-loop */
+}
+/**
+ * Translate the SDK's consumer-facing options into the shape the
+ * platform's `log-sessions` endpoint expects per generation:
+ *   - Cedar's session takes a single `dyno` field that historically
+ *     accepted either a process type or a specific dyno; we collapse
+ *     `dyno || type` for the caller. `lines` and `tail` are honored.
+ *   - Fir's session takes `dyno` and `type` separately and ignores
+ *     `lines`; the stream always tails.
+ */
+function buildCreateOpts(options) {
+    const createOpts = { source: options.source };
+    if (options.isFir) {
+        if (options.dyno)
+            createOpts.dyno = options.dyno;
+        if (options.type)
+            createOpts.type = options.type;
+    }
+    else {
+        const cedarDyno = options.dyno ?? options.type;
+        if (cedarDyno)
+            createOpts.dyno = cedarDyno;
+        if (options.lines !== undefined)
+            createOpts.lines = options.lines;
+        createOpts.tail = options.tail;
+    }
+    return createOpts;
+}
+export const logSessionExtensions = extendResource('platform', 'logSession', ctx => ({
+    streamLogs: (appIdentity, options) => streamLogs(ctx, appIdentity, options),
+}));

package/dist/resources/platform/pipeline/coupling.d.ts

@@ -0,0 +1,27 @@
+import type { PipelineCoupling, TeamApp } from '@heroku/types/3.sdk';
+import type { ResourceCtx } from '../../../core/extend-resource.js';
+export type PipelineWarning = {
+    limit: number;
+    pipelineId: string;
+    type: 'apps_truncated';
+};
+export type ListPipelineAppsOptions = {
+    onWarning?: (warning: PipelineWarning) => void;
+    signal?: AbortSignal;
+};
+export type AppWithPipelineCoupling = TeamApp & {
+    pipelineCoupling: PipelineCoupling;
+};
+/**
+ * List the apps coupled to a pipeline, each decorated with its
+ * `PipelineCoupling`.
+ *
+ * Couplings missing an app id are dropped before issuing the bulk
+ * filter call. If the pipeline has more than 1000 couplings, an
+ * `onWarning` handler must be supplied to opt into a truncated
+ * result; otherwise this throws.
+ */
+export declare function listPipelineApps(ctx: Pick<ResourceCtx, 'platform'>, pipelineId: string, options?: ListPipelineAppsOptions): Promise<AppWithPipelineCoupling[]>;
+export declare const pipelineCouplingExtensions: import("../../../index.js").ResourceExtension<"platform", "pipelineCoupling", {
+    listApps: (pipelineId: string, options?: ListPipelineAppsOptions) => Promise<AppWithPipelineCoupling[]>;
+}>;

package/dist/resources/platform/pipeline/coupling.js

@@ -0,0 +1,55 @@
+import createDebug from 'debug';
+import { extendResource } from '../../../core/extend-resource.js';
+const debug = createDebug('heroku:sdk:resources:pipeline-coupling');
+const APPS_FILTER_LIMIT = 1000;
+/**
+ * List the apps coupled to a pipeline, each decorated with its
+ * `PipelineCoupling`.
+ *
+ * Couplings missing an app id are dropped before issuing the bulk
+ * filter call. If the pipeline has more than 1000 couplings, an
+ * `onWarning` handler must be supplied to opt into a truncated
+ * result; otherwise this throws.
+ */
+export async function listPipelineApps(ctx, pipelineId, options = {}) {
+    options.signal?.throwIfAborted();
+    const allCouplings = await ctx.platform.pipelineCoupling.listByPipeline(pipelineId);
+    // Drop malformed couplings (no app id) before issuing the bulk filter call.
+    const couplings = allCouplings.filter(coupling => coupling.app?.id);
+    const skipped = allCouplings.length - couplings.length;
+    if (skipped > 0) {
+        debug('listPipelineApps pipeline=%s skipped=%d couplings without app.id', pipelineId, skipped);
+    }
+    if (couplings.length === 0) {
+        return [];
+    }
+    let couplingsToResolve = couplings;
+    if (couplings.length > APPS_FILTER_LIMIT) {
+        if (!options.onWarning) {
+            throw new Error(`Pipeline ${pipelineId} has more than ${APPS_FILTER_LIMIT} apps. `
+                + 'Pass an onWarning handler to opt into a truncated result.');
+        }
+        debug('listPipelineApps pipeline=%s truncating couplings=%d limit=%d', pipelineId, couplings.length, APPS_FILTER_LIMIT);
+        options.onWarning({ limit: APPS_FILTER_LIMIT, pipelineId, type: 'apps_truncated' });
+        couplingsToResolve = couplings.slice(0, APPS_FILTER_LIMIT);
+    }
+    options.signal?.throwIfAborted();
+    const ids = couplingsToResolve.map(coupling => coupling.app.id);
+    const apps = await ctx.platform
+        .withHeaders({ Range: `id ..; max=${APPS_FILTER_LIMIT};` })
+        .filterApps.apps({ in: { id: ids } });
+    if (apps.length !== ids.length) {
+        debug('listPipelineApps pipeline=%s requested=%d returned=%d', pipelineId, ids.length, apps.length);
+    }
+    const couplingByAppId = new Map();
+    for (const coupling of couplingsToResolve) {
+        couplingByAppId.set(coupling.app.id, coupling);
+    }
+    return apps.map(app => ({
+        ...app,
+        pipelineCoupling: couplingByAppId.get(app.id),
+    }));
+}
+export const pipelineCouplingExtensions = extendResource('platform', 'pipelineCoupling', ctx => ({
+    listApps: (pipelineId, options) => listPipelineApps(ctx, pipelineId, options),
+}));

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

@@ -0,0 +1,53 @@
+import type { Pipeline } from '@heroku/types/3.sdk';
+import { type HerokuApiClientOptions } from '@heroku/heroku-fetch';
+import type { ResourceCtx } from '../../../core/extend-resource.js';
+export type ResolvePipelineOptions = {
+    clientOptions?: HerokuApiClientOptions;
+    signal?: AbortSignal;
+};
+export declare class PipelineNotFoundError extends Error {
+    readonly identity: string;
+    readonly id = "not_found";
+    readonly statusCode = 404;
+    constructor(identity: string);
+    get body(): {
+        id: string;
+        message: string;
+        resource: string;
+    };
+}
+export declare class PipelineAmbiguousError extends Error {
+    readonly identity: string;
+    readonly matches: Pipeline[];
+    readonly id = "multiple_matches";
+    readonly statusCode = 422;
+    constructor(identity: string, matches: Pipeline[]);
+    get body(): {
+        id: string;
+        message: string;
+    };
+}
+/**
+ * Resolve a Pipeline by identity.
+ *
+ * The identity may be:
+ *   - a UUID — fetched directly via `pipeline.info`.
+ *   - a name — looked up via `GET /pipelines?eq[name]=<name>`. Pipeline
+ *     names are not unique platform-wide, so a name lookup may return
+ *     zero, one, or many matches.
+ *
+ * The name path uses a raw `HerokuApiClient` because the route
+ * registry's `pipeline.list` doesn't accept query params, and we don't
+ * want to bake those params into the routes-generated client (where
+ * they would leak across unrelated calls).
+ *
+ * Errors:
+ *   - throws `PipelineNotFoundError` when no pipeline matches the name.
+ *   - throws `PipelineAmbiguousError` when more than one does. Callers
+ *     that want to prompt the user should catch this and inspect
+ *     `error.matches`.
+ */
+export declare function resolvePipeline(ctx: Pick<ResourceCtx, 'platform'>, identity: string, options?: ResolvePipelineOptions): Promise<Pipeline>;
+export declare const pipelineExtensions: import("../../../index.js").ResourceExtension<"platform", "pipeline", {
+    resolve: (identity: string, options?: ResolvePipelineOptions) => Promise<Pipeline>;
+}>;

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

@@ -0,0 +1,75 @@
+import { HerokuApiClient } from '@heroku/heroku-fetch';
+import { extendResource } from '../../../core/extend-resource.js';
+export class PipelineNotFoundError extends Error {
+    identity;
+    id = 'not_found';
+    statusCode = 404;
+    constructor(identity) {
+        super(`Couldn't find a pipeline matching '${identity}'.`);
+        this.identity = identity;
+        this.name = 'PipelineNotFoundError';
+    }
+    get body() {
+        return { id: this.id, message: this.message, resource: 'pipeline' };
+    }
+}
+export class PipelineAmbiguousError extends Error {
+    identity;
+    matches;
+    id = 'multiple_matches';
+    statusCode = 422;
+    constructor(identity, matches) {
+        super(`Ambiguous identifier; multiple pipelines named '${identity}' found (${matches.length} matches).`);
+        this.identity = identity;
+        this.matches = matches;
+        this.name = 'PipelineAmbiguousError';
+    }
+    get body() {
+        return { id: this.id, message: this.message };
+    }
+}
+const UUID_RE = /^[\da-f]{8}-[\da-f]{4}-[\da-f]{4}-[\da-f]{4}-[\da-f]{12}$/i;
+/**
+ * Resolve a Pipeline by identity.
+ *
+ * The identity may be:
+ *   - a UUID — fetched directly via `pipeline.info`.
+ *   - a name — looked up via `GET /pipelines?eq[name]=<name>`. Pipeline
+ *     names are not unique platform-wide, so a name lookup may return
+ *     zero, one, or many matches.
+ *
+ * The name path uses a raw `HerokuApiClient` because the route
+ * registry's `pipeline.list` doesn't accept query params, and we don't
+ * want to bake those params into the routes-generated client (where
+ * they would leak across unrelated calls).
+ *
+ * Errors:
+ *   - throws `PipelineNotFoundError` when no pipeline matches the name.
+ *   - throws `PipelineAmbiguousError` when more than one does. Callers
+ *     that want to prompt the user should catch this and inspect
+ *     `error.matches`.
+ */
+export async function resolvePipeline(ctx, identity, options = {}) {
+    options.signal?.throwIfAborted();
+    if (UUID_RE.test(identity)) {
+        return ctx.platform.pipeline.info(identity);
+    }
+    const apiClient = new HerokuApiClient({
+        ...options.clientOptions,
+        service: 'platform',
+    });
+    const response = await apiClient.get('/pipelines', {
+        searchParams: { 'eq[name]': identity },
+    });
+    const matches = (await response.json());
+    if (matches.length === 0) {
+        throw new PipelineNotFoundError(identity);
+    }
+    if (matches.length > 1) {
+        throw new PipelineAmbiguousError(identity, matches);
+    }
+    return matches[0];
+}
+export const pipelineExtensions = extendResource('platform', 'pipeline', ctx => ({
+    resolve: (identity, options) => resolvePipeline(ctx, identity, options),
+}));

package/dist/resources/platform/pipeline/promotion.d.ts

@@ -0,0 +1,21 @@
+import type { PipelinePromotion, PipelinePromotionCreateOpts, PipelinePromotionTarget } from '@heroku/types/3.sdk';
+import type { ResourceCtx } from '../../../core/extend-resource.js';
+export type ReleaseStreamContext = {
+    stream: ReadableStream<Uint8Array>;
+    target: PipelinePromotionTarget;
+};
+export type PromotePipelineOptions = {
+    intervalMs?: number;
+    onReleaseStream?: (context: ReleaseStreamContext) => Promise<void> | void;
+    releaseStreamMaxAttempts?: number;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+};
+export type PromotePipelineResult = {
+    promotion: PipelinePromotion;
+    targets: PipelinePromotionTarget[];
+};
+export declare function promotePipeline(ctx: Pick<ResourceCtx, 'platform'>, body: PipelinePromotionCreateOpts, options?: PromotePipelineOptions): Promise<PromotePipelineResult>;
+export declare const pipelinePromotionExtensions: import("../../../index.js").ResourceExtension<"platform", "pipelinePromotion", {
+    promote: (body: PipelinePromotionCreateOpts, options?: PromotePipelineOptions) => Promise<PromotePipelineResult>;
+}>;

package/dist/resources/platform/pipeline/promotion.js

@@ -0,0 +1,109 @@
+import { HerokuApiClient } from '@heroku/heroku-fetch';
+import createDebug from 'debug';
+import { extendResource } from '../../../core/extend-resource.js';
+import { wait } from '../../../utils/wait.js';
+const debug = createDebug('heroku:sdk:resources:pipeline-promotion');
+const DEFAULT_INTERVAL_MS = 1000;
+const DEFAULT_RELEASE_STREAM_MAX_ATTEMPTS = 100;
+export async function promotePipeline(ctx, body, options = {}) {
+    const { intervalMs = DEFAULT_INTERVAL_MS, onReleaseStream, releaseStreamMaxAttempts = DEFAULT_RELEASE_STREAM_MAX_ATTEMPTS, signal, timeoutMs, } = options;
+    debug('promote source=%s targets=%d', body.source?.app?.id ?? '<unknown>', body.targets?.length ?? 0);
+    const promotion = await ctx.platform.pipelinePromotion.create(body);
+    if (!promotion.id) {
+        throw new Error('Pipeline promotion response did not include an id');
+    }
+    debug('promote created promotion=%s intervalMs=%d timeoutMs=%s', promotion.id, intervalMs, timeoutMs ?? '<none>');
+    const deadline = timeoutMs === undefined ? undefined : Date.now() + timeoutMs;
+    const streamRunner = onReleaseStream
+        ? createReleaseStreamRunner(ctx, onReleaseStream, releaseStreamMaxAttempts, intervalMs, signal)
+        : undefined;
+    let poll = 0;
+    while (true) {
+        signal?.throwIfAborted();
+        poll++;
+        // eslint-disable-next-line no-await-in-loop
+        const targets = await ctx.platform.pipelinePromotionTarget.list(promotion.id);
+        debug('promote poll=%d promotion=%s statuses=%o', poll, promotion.id, targets.map(target => target.status));
+        if (targets.every(target => target.status !== 'pending')) {
+            debug('promote terminal promotion=%s polls=%d', promotion.id, poll);
+            return { promotion, targets };
+        }
+        // eslint-disable-next-line no-await-in-loop
+        await streamRunner?.(targets);
+        if (deadline !== undefined && Date.now() >= deadline) {
+            throw new Error(`Pipeline promotion ${promotion.id} did not reach a terminal state within ${timeoutMs}ms`);
+        }
+        // eslint-disable-next-line no-await-in-loop
+        await wait(intervalMs, signal);
+    }
+}
+/**
+ * Returns a function that, on first call where `targets` is a single
+ * promotion target with `release.id` and `app.id`, fetches the release's
+ * output stream and hands it to `onReleaseStream`. Subsequent calls are
+ * no-ops; the stream is one-shot per promotion.
+ */
+function createReleaseStreamRunner(ctx, onReleaseStream, releaseStreamMaxAttempts, intervalMs, signal) {
+    let handled = false;
+    return async (targets) => {
+        if (handled || targets.length !== 1)
+            return;
+        const target = targets[0];
+        if (!target.release?.id || !target.app?.id)
+            return;
+        handled = true;
+        debug('promote release-stream lookup app=%s release=%s', target.app.id, target.release.id);
+        const release = await ctx.platform.release.info(target.app.id, target.release.id);
+        if (!release.output_stream_url) {
+            debug('promote release-stream skipped reason=no-output-stream-url');
+            return;
+        }
+        debug('promote release-stream fetching url=%s maxAttempts=%d', release.output_stream_url, releaseStreamMaxAttempts);
+        const stream = await fetchReleaseOutput(release.output_stream_url, releaseStreamMaxAttempts, intervalMs, signal);
+        await onReleaseStream({ stream, target });
+    };
+}
+export const pipelinePromotionExtensions = extendResource('platform', 'pipelinePromotion', ctx => ({
+    promote: (body, options) => promotePipeline(ctx, body, options),
+}));
+async function fetchReleaseOutput(url, maxAttempts, intervalMs, signal) {
+    const parsed = new URL(url);
+    const path = `${parsed.pathname}${parsed.search}`;
+    // The release output URL points at a third-party stream host (e.g. busl).
+    // Use a custom-service client so the platform prefixUrl and bearer token
+    // don't leak across origins.
+    const buslClient = new HerokuApiClient({
+        baseUrl: parsed.origin,
+        service: 'custom',
+        token: '',
+    });
+    let attempt = 0;
+    while (true) {
+        signal?.throwIfAborted();
+        attempt++;
+        let response;
+        try {
+            // eslint-disable-next-line no-await-in-loop
+            response = await buslClient.stream(path);
+        }
+        catch {
+            // Treat HTTP errors thrown by the api-client as a retryable miss.
+            response = undefined;
+        }
+        if (response?.ok && response.body) {
+            debug('release-stream attempt=%d status=%d ok stream=true', attempt, response.status);
+            return response.body;
+        }
+        debug('release-stream attempt=%d status=%s ok=false', attempt, response?.status ?? '<error>');
+        if (response?.body) {
+            // Drain so the connection can be reused.
+            // eslint-disable-next-line no-await-in-loop
+            await response.body.cancel().catch(() => { });
+        }
+        if (attempt >= maxAttempts) {
+            throw new Error('stream release output not available');
+        }
+        // eslint-disable-next-line no-await-in-loop
+        await wait(intervalMs, signal);
+    }
+}

package/dist/resources/platform/pipeline-coupling.d.ts

@@ -0,0 +1,27 @@
+import type { PipelineCoupling, TeamApp } from '@heroku/types/3.sdk';
+import type { ResourceCtx } from '../../core/extend-resource.js';
+export type PipelineWarning = {
+    limit: number;
+    pipelineId: string;
+    type: 'apps_truncated';
+};
+export type ListPipelineAppsOptions = {
+    onWarning?: (warning: PipelineWarning) => void;
+    signal?: AbortSignal;
+};
+export type AppWithPipelineCoupling = TeamApp & {
+    pipelineCoupling: PipelineCoupling;
+};
+/**
+ * List the apps coupled to a pipeline, each decorated with its
+ * `PipelineCoupling`.
+ *
+ * Couplings missing an app id are dropped before issuing the bulk
+ * filter call. If the pipeline has more than 1000 couplings, an
+ * `onWarning` handler must be supplied to opt into a truncated
+ * result; otherwise this throws.
+ */
+export declare function listPipelineApps(ctx: Pick<ResourceCtx, 'platform'>, pipelineId: string, options?: ListPipelineAppsOptions): Promise<AppWithPipelineCoupling[]>;
+export declare const pipelineCouplingExtensions: import("../../index.js").ResourceExtension<"platform", "pipelineCoupling", {
+    listApps: (pipelineId: string, options?: ListPipelineAppsOptions) => Promise<AppWithPipelineCoupling[]>;
+}>;

package/dist/resources/platform/pipeline-coupling.js

@@ -0,0 +1,55 @@
+import createDebug from 'debug';
+import { extendResource } from '../../core/extend-resource.js';
+const debug = createDebug('heroku:sdk:resources:pipeline-coupling');
+const APPS_FILTER_LIMIT = 1000;
+/**
+ * List the apps coupled to a pipeline, each decorated with its
+ * `PipelineCoupling`.
+ *
+ * Couplings missing an app id are dropped before issuing the bulk
+ * filter call. If the pipeline has more than 1000 couplings, an
+ * `onWarning` handler must be supplied to opt into a truncated
+ * result; otherwise this throws.
+ */
+export async function listPipelineApps(ctx, pipelineId, options = {}) {
+    options.signal?.throwIfAborted();
+    const allCouplings = await ctx.platform.pipelineCoupling.listByPipeline(pipelineId);
+    // Drop malformed couplings (no app id) before issuing the bulk filter call.
+    const couplings = allCouplings.filter(coupling => coupling.app?.id);
+    const skipped = allCouplings.length - couplings.length;
+    if (skipped > 0) {
+        debug('listPipelineApps pipeline=%s skipped=%d couplings without app.id', pipelineId, skipped);
+    }
+    if (couplings.length === 0) {
+        return [];
+    }
+    let couplingsToResolve = couplings;
+    if (couplings.length > APPS_FILTER_LIMIT) {
+        if (!options.onWarning) {
+            throw new Error(`Pipeline ${pipelineId} has more than ${APPS_FILTER_LIMIT} apps. `
+                + 'Pass an onWarning handler to opt into a truncated result.');
+        }
+        debug('listPipelineApps pipeline=%s truncating couplings=%d limit=%d', pipelineId, couplings.length, APPS_FILTER_LIMIT);
+        options.onWarning({ limit: APPS_FILTER_LIMIT, pipelineId, type: 'apps_truncated' });
+        couplingsToResolve = couplings.slice(0, APPS_FILTER_LIMIT);
+    }
+    options.signal?.throwIfAborted();
+    const ids = couplingsToResolve.map(coupling => coupling.app.id);
+    const apps = await ctx.platform
+        .withHeaders({ Range: `id ..; max=${APPS_FILTER_LIMIT};` })
+        .filterApps.apps({ in: { id: ids } });
+    if (apps.length !== ids.length) {
+        debug('listPipelineApps pipeline=%s requested=%d returned=%d', pipelineId, ids.length, apps.length);
+    }
+    const couplingByAppId = new Map();
+    for (const coupling of couplingsToResolve) {
+        couplingByAppId.set(coupling.app.id, coupling);
+    }
+    return apps.map(app => ({
+        ...app,
+        pipelineCoupling: couplingByAppId.get(app.id),
+    }));
+}
+export const pipelineCouplingExtensions = extendResource('platform', 'pipelineCoupling', ctx => ({
+    listApps: (pipelineId, options) => listPipelineApps(ctx, pipelineId, options),
+}));

package/dist/resources/platform/pipeline-promotion.d.ts

@@ -0,0 +1,21 @@
+import type { PipelinePromotion, PipelinePromotionCreateOpts, PipelinePromotionTarget } from '@heroku/types/3.sdk';
+import type { ResourceCtx } from '../../core/extend-resource.js';
+export type ReleaseStreamContext = {
+    stream: ReadableStream<Uint8Array>;
+    target: PipelinePromotionTarget;
+};
+export type PromotePipelineOptions = {
+    intervalMs?: number;
+    onReleaseStream?: (context: ReleaseStreamContext) => Promise<void> | void;
+    releaseStreamMaxAttempts?: number;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+};
+export type PromotePipelineResult = {
+    promotion: PipelinePromotion;
+    targets: PipelinePromotionTarget[];
+};
+export declare function promotePipeline(ctx: Pick<ResourceCtx, 'platform'>, body: PipelinePromotionCreateOpts, options?: PromotePipelineOptions): Promise<PromotePipelineResult>;
+export declare const pipelinePromotionExtensions: import("../../index.js").ResourceExtension<"platform", "pipelinePromotion", {
+    promote: (body: PipelinePromotionCreateOpts, options?: PromotePipelineOptions) => Promise<PromotePipelineResult>;
+}>;