@heroku/sdk 0.5.1 → 0.5.3

package/dist/resources/platform/app/wait-for-acm-certificates.js

@@ -0,0 +1,51 @@
+import { wait } from '../../../utils/wait.js';
+const DEFAULT_WAIT_INTERVAL_MS = 15_000;
+/**
+ * Waits for ACM (Automated Certificate Management) certificates to be
+ * issued on all custom domains of an app.
+ *
+ * Polls the app's domains until every `custom` domain reaches a
+ * terminal `acm_status` of `'cert issued'` or `'failed'`, then returns
+ * the custom domains. `heroku` domains are ignored and never block
+ * termination.
+ *
+ * @throws if any custom domain finishes with `acm_status: 'failed'`
+ * (`'ACM not enabled for some domains'`), or if `timeoutMs` elapses
+ * before all custom domains reach a terminal status.
+ */
+export async function waitForACMCertificates(ctx, appIdentity, options = {}) {
+    const { intervalMs = DEFAULT_WAIT_INTERVAL_MS, signal, timeoutMs } = options;
+    signal?.throwIfAborted();
+    const platform = signal ? ctx.platform.withOptions({ signal }) : ctx.platform;
+    function terminal(domains) {
+        return domains
+            .filter(domain => domain.kind === 'custom')
+            .every(domain => domain.acm_status === 'cert issued' || domain.acm_status === 'failed');
+    }
+    function someFailed(domains) {
+        return domains
+            .filter(domain => domain.kind === 'custom')
+            .some(domain => domain.acm_status === 'failed');
+    }
+    function backoff(attempts) {
+        const multiplier = attempts < 60 ? Math.floor(attempts / 20) : 3;
+        return intervalMs * (1 + multiplier);
+    }
+    let domains = await platform.domain.list(appIdentity);
+    if (!terminal(domains)) {
+        const deadline = timeoutMs === undefined ? undefined : Date.now() + timeoutMs;
+        let retries = 0;
+        while (!terminal(domains)) {
+            await wait(backoff(retries), signal);
+            if (deadline !== undefined && Date.now() >= deadline) {
+                throw new Error(`Timed out waiting for ACM certificates on app ${appIdentity}`);
+            }
+            domains = await platform.domain.list(appIdentity);
+            retries++;
+        }
+    }
+    if (someFailed(domains)) {
+        throw new Error('ACM not enabled for some domains');
+    }
+    return domains.filter(domain => domain.kind === 'custom');
+}

package/dist/resources/platform/container/ensure-container-stack.d.ts

@@ -0,0 +1,18 @@
+import type { App } from '@heroku/types/3.sdk';
+import type { ResourceCtx } from '../../../core/extend-resource.js';
+import type { ContainerOptions } from './index.js';
+export declare class NotAContainerAppError extends Error {
+    readonly app: Pick<App, 'build_stack' | 'id' | 'name' | 'stack'>;
+    readonly id = "not_a_container_app";
+    constructor(app: Pick<App, 'build_stack' | 'id' | 'name' | 'stack'>);
+    get body(): {
+        app: Pick<App, "stack" | "id" | "name" | "build_stack">;
+        id: string;
+        message: string;
+    };
+}
+/**
+ * Ensure that the given app is a container app.
+ * @throws {NotAContainerAppError} if the app is not a container app
+ */
+export declare function ensureContainerStack(ctx: Pick<ResourceCtx, 'platform'>, appIdentity: string, options?: ContainerOptions): Promise<void>;

package/dist/resources/platform/container/ensure-container-stack.js

@@ -0,0 +1,32 @@
+export class NotAContainerAppError extends Error {
+    app;
+    id = 'not_a_container_app';
+    constructor(app) {
+        super('This operation is for Docker apps only.');
+        this.app = app;
+        this.name = 'NotAContainerAppError';
+    }
+    get body() {
+        return { app: this.app, id: this.id, message: this.message };
+    }
+}
+/**
+ * Ensure that the given app is a container app.
+ * @throws {NotAContainerAppError} if the app is not a container app
+ */
+export async function ensureContainerStack(ctx, appIdentity, options = {}) {
+    const { signal } = options;
+    signal?.throwIfAborted();
+    const platform = signal ? ctx.platform.withOptions({ signal }) : ctx.platform;
+    const app = await platform.app.info(appIdentity);
+    const allowedStack = 'container';
+    if (app.build_stack.name !== allowedStack && app.stack.name !== allowedStack) {
+        throw new NotAContainerAppError({
+            // eslint-disable-next-line camelcase
+            build_stack: app.build_stack,
+            id: app.id,
+            name: app.name,
+            stack: app.stack,
+        });
+    }
+}

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

@@ -0,0 +1,13 @@
+import { type DockerReleasesBatchUpdateOpts } from './release-images.js';
+import { type RemoveProcessTypesOpts } from './remove-process-types.js';
+export { ensureContainerStack, NotAContainerAppError } from './ensure-container-stack.js';
+export { type DockerReleasesBatchUpdateOpts, releaseDockerImages, type ReleaseDockerImagesResult } from './release-images.js';
+export { removeProcessTypes, type RemoveProcessTypesOpts } from './remove-process-types.js';
+export type ContainerOptions = {
+    signal?: AbortSignal;
+};
+export declare const containerExtensions: import("../../../core/extend-resource.js").ResourceExtension<"platform", "container", {
+    ensureContainerStack: (appIdentity: string, options?: ContainerOptions) => Promise<void>;
+    releaseImages: (appIdentity: string, imagesByProcessType: DockerReleasesBatchUpdateOpts[], options?: ContainerOptions) => Promise<import("./release-images.js").ReleaseDockerImagesResult>;
+    removeProcessTypes: (appIdentity: string, processTypes: string[], options?: RemoveProcessTypesOpts) => Promise<import("@heroku/types/3.sdk").Formation[]>;
+}>;

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

@@ -0,0 +1,12 @@
+import { extendResource } from '../../../core/extend-resource.js';
+import { ensureContainerStack } from './ensure-container-stack.js';
+import { releaseDockerImages } from './release-images.js';
+import { removeProcessTypes } from './remove-process-types.js';
+export { ensureContainerStack, NotAContainerAppError } from './ensure-container-stack.js';
+export { releaseDockerImages } from './release-images.js';
+export { removeProcessTypes } from './remove-process-types.js';
+export const containerExtensions = extendResource('platform', 'container', ctx => ({
+    ensureContainerStack: (appIdentity, options) => ensureContainerStack(ctx, appIdentity, options),
+    releaseImages: (appIdentity, imagesByProcessType, options) => releaseDockerImages(ctx, appIdentity, imagesByProcessType, options),
+    removeProcessTypes: (appIdentity, processTypes, options) => removeProcessTypes(ctx, appIdentity, processTypes, options),
+}));

package/dist/resources/platform/container/release-images.d.ts

@@ -0,0 +1,21 @@
+import type { Release } from '@heroku/types/3.sdk';
+import type { ResourceCtx } from '../../../core/extend-resource.js';
+import type { ContainerOptions } from './index.js';
+/**
+ * An update item for the `3.docker-releases` API variant.
+ *
+ * The `docker_image` field is only available with
+ * `Accept: application/vnd.heroku+json; version=3.docker-releases`
+ */
+export type DockerReleasesBatchUpdateOpts = {
+    docker_image: string;
+    type: string;
+};
+export type ReleaseDockerImagesResult = {
+    newRelease: Release | undefined;
+    oldRelease: Release | undefined;
+};
+/**
+ * Release Docker images to a container app.
+ */
+export declare function releaseDockerImages(ctx: Pick<ResourceCtx, 'platform'>, appIdentity: string, imagesByProcessType: DockerReleasesBatchUpdateOpts[], options?: ContainerOptions): Promise<ReleaseDockerImagesResult>;

package/dist/resources/platform/container/release-images.js

@@ -0,0 +1,23 @@
+import { ensureContainerStack } from './ensure-container-stack.js';
+/**
+ * Release Docker images to a container app.
+ */
+export async function releaseDockerImages(ctx, appIdentity, imagesByProcessType, options = {}) {
+    await ensureContainerStack(ctx, appIdentity, options);
+    const platform = options.signal ? ctx.platform.withOptions({ signal: options.signal }) : ctx.platform;
+    const oldReleases = await platform
+        .withHeaders({ Range: 'version ..; max=1, order=desc' })
+        .release.list(appIdentity);
+    const oldRelease = oldReleases[0];
+    await platform
+        .withHeaders({ Accept: 'application/vnd.heroku+json; version=3.docker-releases' })
+        .formation.batchUpdate(appIdentity, { updates: imagesByProcessType });
+    const newReleases = await platform
+        .withHeaders({ Range: 'version ..; max=1, order=desc' })
+        .release.list(appIdentity);
+    const newRelease = newReleases[0];
+    return {
+        newRelease,
+        oldRelease,
+    };
+}

package/dist/resources/platform/container/remove-process-types.d.ts

@@ -0,0 +1,22 @@
+import type { Formation } from '@heroku/types/3.sdk';
+import type { ResourceCtx } from '../../../core/extend-resource.js';
+import type { ContainerOptions } from './index.js';
+export type RemoveProcessTypesOpts = {
+    /**
+     * Fires `onStart` immediately before, and `onStop` immediately after,
+     * each process type's `formation.update` call. Process types are
+     * removed one at a time (not concurrently) so a caller can drive a
+     * single shared UI element (e.g. a CLI spinner) across the whole
+     * batch. If an update rejects, its `onStart` has already fired but
+     * `onStop` never will — the rejection propagates immediately and any
+     * remaining process types are not attempted.
+     */
+    onProgress?: {
+        onStart?: (processType: string) => void;
+        onStop?: (processType: string) => void;
+    };
+} & ContainerOptions;
+/**
+ * Remove one or more process types from a container app
+ */
+export declare function removeProcessTypes(ctx: Pick<ResourceCtx, 'platform'>, appIdentity: string, processTypes: string[], options?: RemoveProcessTypesOpts): Promise<Formation[]>;

package/dist/resources/platform/container/remove-process-types.js

@@ -0,0 +1,20 @@
+import { ensureContainerStack } from './ensure-container-stack.js';
+/**
+ * Remove one or more process types from a container app
+ */
+export async function removeProcessTypes(ctx, appIdentity, processTypes, options = {}) {
+    await ensureContainerStack(ctx, appIdentity, options);
+    const platform = options.signal ? ctx.platform.withOptions({ signal: options.signal }) : ctx.platform;
+    // eslint-disable-next-line camelcase
+    const requestBody = { docker_image: null };
+    const updatedFormations = [];
+    for (const processType of processTypes) {
+        options.onProgress?.onStart?.(processType);
+        const formation = await platform
+            .withHeaders({ Accept: 'application/vnd.heroku+json; version=3.docker-releases' })
+            .formation.update(appIdentity, processType, requestBody);
+        options.onProgress?.onStop?.(processType);
+        updatedFormations.push(formation);
+    }
+    return updatedFormations;
+}

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

@@ -1,7 +1,9 @@
 import type { Formation } from '@heroku/types/3.sdk';
 import type { StickyRouteOptions } from '../../../core/create-client.js';
 import type { ResourceCtx } from '../../../core/extend-resource.js';
+import { type RunDynoOptions } from './run.js';
 import { type WaitForInfoOptions } from './wait-for-info.js';
+export { runDyno, type RunDynoOptions } from './run.js';
 export { DynoNotReadyError, type DynoState, waitForInfo, type WaitForInfoOptions, } from './wait-for-info.js';
 export type DynoOptions = {
     signal?: AbortSignal;
@@ -39,6 +41,7 @@ export declare function scaleDynos(ctx: {
 export declare function restartDynos(ctx: Pick<ResourceCtx, 'platform'>, appIdentity: string, target?: RestartDynosTarget, options?: DynoOptions): Promise<void>;
 export declare const dynoExtensions: import("../../../core/extend-resource.js").ResourceExtension<"platform", "dyno", {
     restart: (appIdentity: string, target?: RestartDynosTarget, options?: DynoOptions) => Promise<void>;
+    run: (appIdentity: string, command: string, options?: RunDynoOptions) => Promise<import("@heroku/types/3.sdk").Dyno>;
     scale: {
         (appIdentity: string, updates: ScaleDynosUpdate, options?: DynoOptions): Promise<Formation>;
         (appIdentity: string, updates: ScaleDynosUpdate[], options?: DynoOptions): Promise<Formation[]>;

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

@@ -1,5 +1,7 @@
 import { extendResource } from '../../../core/extend-resource.js';
+import { runDyno } from './run.js';
 import { waitForInfo } from './wait-for-info.js';
+export { runDyno } from './run.js';
 export { DynoNotReadyError, waitForInfo, } from './wait-for-info.js';
 export async function scaleDynos(ctx, appIdentity, updates, options = {}) {
     options.signal?.throwIfAborted();
@@ -24,6 +26,7 @@ export async function restartDynos(ctx, appIdentity, target, options = {}) {
 }
 export const dynoExtensions = extendResource('platform', 'dyno', ctx => ({
     restart: (appIdentity, target, options) => (restartDynos(ctx, appIdentity, target, options)),
+    run: (appIdentity, command, options) => (runDyno(ctx, appIdentity, command, options)),
     scale: ((appIdentity, updates, options) => scaleDynos(ctx, appIdentity, updates, options)),
     waitForInfo: (appIdentity, dynoIdentity, options) => (waitForInfo(ctx, appIdentity, dynoIdentity, options)),
 }));

package/dist/resources/platform/dyno/run.d.ts

@@ -0,0 +1,76 @@
+import type { HerokuApiClientOptions } from '@heroku/heroku-fetch';
+import type { Dyno } from '@heroku/types/3.sdk';
+import type { ResourceCtx } from '../../../core/extend-resource.js';
+export type RunDynoOptions = {
+    /**
+     * When `true`, the platform returns a dyno with a non-null
+     * `attach_url` the caller can use to open its own interactive
+     * session (STDIN/STDOUT rendezvous). The SDK itself does not open
+     * the connection.
+     */
+    attach?: boolean;
+    /**
+     * Options forwarded to the raw `HerokuApiClient` created for the
+     * exec-inside path (`dyno` is set). The route registry has no entry
+     * for `POST /apps/{app}/dynos/{dyno}`, so that call is issued via a
+     * bare client. Ignored when `dyno` is omitted — the standard
+     * create-one-off path uses the SDK's own routes client.
+     */
+    clientOptions?: HerokuApiClientOptions;
+    /**
+     * If set, exec `command` inside the named dyno via
+     * `POST /apps/{app}/dynos/{dyno}` with the `version=3.run-inside`
+     * Accept variant. Omit to create a new one-off dyno via
+     * `POST /apps/{app}/dynos`.
+     */
+    dyno?: string;
+    /** Additional environment variables layered onto the dyno. */
+    env?: Record<string, string>;
+    /**
+     * When `true`, `command` is appended with `; echo "￿
+     * heroku-command-exit-status: $?"` to surface the process exit
+     * code over the attach stream. Consumers may parse this line to
+     * recover the exit code.
+     *
+     * Because the wrap uses a bare `;`, `command` must be a single
+     * shell statement that terminates cleanly with `;`. Trailing `&`
+     * (backgrounding), line continuations (`\`), unclosed quotes, or
+     * unterminated heredocs will break the wrap and produce a shell
+     * syntax error or garbled output. Callers who need those
+     * constructs should wrap them in a subshell or `{ ...; }` group
+     * themselves before passing `command`.
+     */
+    exitCode?: boolean;
+    /**
+     * Serialized to the platform as `force_no_tty`. Forces an attached
+     * one-off dyno to not run in a TTY even when the caller's
+     * environment looks like one.
+     */
+    forceNoTTY?: boolean;
+    signal?: AbortSignal;
+    size?: string;
+    type?: string;
+};
+/**
+ * Create a one-off dyno or exec a command inside an existing one.
+ *
+ * Route selection:
+ *   - `POST /apps/{app}/dynos` (default) creates a new one-off dyno.
+ *     Uses the SDK's routes client, which sends the platform
+ *     service's default `Accept: version=3` header.
+ *   - `POST /apps/{app}/dynos/{dyno}` (when `options.dyno` is set)
+ *     execs the command inside the named dyno. Uses a raw
+ *     `HerokuApiClient` with `Accept: version=3.sdk` because the
+ *     routes registry has no entry for this endpoint.
+ *
+ * Retries: the runtime API occasionally returns 409 while a newly
+ * pushed app's release is still propagating. This is transient and
+ * short-lived, so 409 is retried up to two times back-to-back with no
+ * delay. Any other error propagates. Matches the retry semantics of
+ * the historical CLI implementation.
+ *
+ * The returned `Dyno` includes `attach_url` for callers who want to
+ * open their own interactive session; the SDK does not establish the
+ * session, spawn ssh, or manage TTY state.
+ */
+export declare function runDyno(ctx: Pick<ResourceCtx, 'platform'>, appIdentity: string, command: string, options?: RunDynoOptions): Promise<Dyno>;

package/dist/resources/platform/dyno/run.js

@@ -0,0 +1,74 @@
+import { HerokuApiClient, HerokuApiError } from '@heroku/heroku-fetch';
+const DEFAULT_RUN_RETRIES = 2;
+const ACCEPT_RUN_INSIDE = 'application/vnd.heroku+json; version=3.sdk';
+/**
+ * Create a one-off dyno or exec a command inside an existing one.
+ *
+ * Route selection:
+ *   - `POST /apps/{app}/dynos` (default) creates a new one-off dyno.
+ *     Uses the SDK's routes client, which sends the platform
+ *     service's default `Accept: version=3` header.
+ *   - `POST /apps/{app}/dynos/{dyno}` (when `options.dyno` is set)
+ *     execs the command inside the named dyno. Uses a raw
+ *     `HerokuApiClient` with `Accept: version=3.sdk` because the
+ *     routes registry has no entry for this endpoint.
+ *
+ * Retries: the runtime API occasionally returns 409 while a newly
+ * pushed app's release is still propagating. This is transient and
+ * short-lived, so 409 is retried up to two times back-to-back with no
+ * delay. Any other error propagates. Matches the retry semantics of
+ * the historical CLI implementation.
+ *
+ * The returned `Dyno` includes `attach_url` for callers who want to
+ * open their own interactive session; the SDK does not establish the
+ * session, spawn ssh, or manage TTY state.
+ */
+export async function runDyno(ctx, appIdentity, command, options = {}) {
+    options.signal?.throwIfAborted();
+    const body = {
+        command: options.exitCode
+            ? `${command}; echo "￿ heroku-command-exit-status: $?"`
+            : command,
+    };
+    if (options.attach !== undefined)
+        body.attach = options.attach;
+    if (options.env !== undefined)
+        body.env = options.env;
+    if (options.forceNoTTY !== undefined)
+        body.force_no_tty = options.forceNoTTY;
+    if (options.size !== undefined)
+        body.size = options.size;
+    if (options.type !== undefined)
+        body.type = options.type;
+    /* eslint-disable no-await-in-loop -- retry is inherently sequential on 409 */
+    let attemptsLeft = DEFAULT_RUN_RETRIES + 1;
+    while (true) {
+        attemptsLeft--;
+        try {
+            return await postRun(ctx, appIdentity, body, options);
+        }
+        catch (error) {
+            if (attemptsLeft > 0 && error instanceof HerokuApiError && error.statusCode === 409) {
+                continue;
+            }
+            throw error;
+        }
+    }
+    /* eslint-enable no-await-in-loop */
+}
+async function postRun(ctx, appIdentity, body, options) {
+    if (options.dyno) {
+        const apiClient = new HerokuApiClient({
+            ...options.clientOptions,
+            service: 'platform',
+        });
+        const path = `/apps/${encodeURIComponent(appIdentity)}/dynos/${encodeURIComponent(options.dyno)}`;
+        const response = await apiClient.post(path, body, {
+            headers: { Accept: ACCEPT_RUN_INSIDE },
+            signal: options.signal,
+        });
+        return (await response.json());
+    }
+    const platform = options.signal ? ctx.platform.withOptions({ signal: options.signal }) : ctx.platform;
+    return platform.dyno.create(appIdentity, body);
+}

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

@@ -73,10 +73,20 @@ export async function* streamLogs(ctx, appIdentity, options = {}) {
                 service: 'custom',
                 token: '',
             });
-            const response = await logplexClient.stream(`${parsed.pathname}${parsed.search}`);
+            // Fir's telemetry-proxy sends newline-delimited plain text by
+            // default, but concatenates records with zero delimiter bytes —
+            // splitting on '\n' yields nothing. Requesting SSE flips the
+            // proxy into `text/event-stream`, where each record is framed
+            // as `id: N\ndata: <line>\n\n` (Cedar's logplex ignores the
+            // header and keeps sending `text/plain`).
+            const response = await logplexClient.stream(`${parsed.pathname}${parsed.search}`, {
+                headers: { Accept: 'text/event-stream' },
+            });
             if (!response.body) {
                 throw new Error('Logplex stream returned no body.');
             }
+            const contentType = response.headers.get('content-type') ?? '';
+            const isSse = contentType.toLowerCase().includes('text/event-stream');
             const reader = response.body.getReader();
             const decoder = new TextDecoder();
             let pending = '';
@@ -101,22 +111,46 @@ export async function* streamLogs(ctx, appIdentity, options = {}) {
                         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) {
+                    if (isSse) {
+                        // SSE events are separated by a blank line (`\n\n`). Each
+                        // event holds `data:` field lines whose values, joined by
+                        // `\n` per the spec, are the log line to yield.
+                        let boundary = pending.indexOf('\n\n');
+                        while (boundary !== -1) {
+                            const frame = pending.slice(0, boundary);
+                            pending = pending.slice(boundary + 2);
+                            // Any complete SSE frame — including heartbeats with no
+                            // data — is proof the transport is healthy, so reset the
+                            // retry counter here rather than only on yielded lines.
                             consecutiveTransportErrors = 0;
-                            yield line;
+                            const line = extractSseData(frame);
+                            if (line.length > 0)
+                                yield line;
+                            boundary = pending.indexOf('\n\n');
+                        }
+                    }
+                    else {
+                        let newlineIndex = pending.indexOf('\n');
+                        while (newlineIndex !== -1) {
+                            const line = pending.slice(0, newlineIndex);
+                            pending = pending.slice(newlineIndex + 1);
+                            if (line.length > 0) {
+                                consecutiveTransportErrors = 0;
+                                yield line;
+                            }
+                            newlineIndex = pending.indexOf('\n');
                         }
-                        newlineIndex = pending.indexOf('\n');
                     }
                 }
                 // Flush any trailing partial line that didn't end in '\n'.
-                const trailing = pending + decoder.decode();
-                if (trailing.length > 0) {
-                    consecutiveTransportErrors = 0;
-                    yield trailing;
+                // Only meaningful for the plain-text path — an SSE stream that
+                // ends mid-frame has no complete event to yield.
+                if (!isSse) {
+                    const trailing = pending + decoder.decode();
+                    if (trailing.length > 0) {
+                        consecutiveTransportErrors = 0;
+                        yield trailing;
+                    }
                 }
             }
             finally {
@@ -162,6 +196,31 @@ export async function* streamLogs(ctx, appIdentity, options = {}) {
     }
     /* eslint-enable no-await-in-loop */
 }
+/**
+ * Extract the joined `data:` field values from a single SSE event
+ * frame, per the HTML Living Standard's event-stream parsing rules.
+ * Lines beginning with `:` are comments and skipped; other field
+ * names (`id`, `event`, `retry`) are ignored — we only care about
+ * the log payload. Multiple `data:` lines within one event are
+ * joined with `\n`.
+ */
+function extractSseData(frame) {
+    const dataLines = [];
+    for (const rawLine of frame.split('\n')) {
+        if (!rawLine || rawLine.startsWith(':'))
+            continue;
+        const colon = rawLine.indexOf(':');
+        const field = colon === -1 ? rawLine : rawLine.slice(0, colon);
+        if (field !== 'data')
+            continue;
+        // Per spec: strip a single leading space from the value.
+        let value = colon === -1 ? '' : rawLine.slice(colon + 1);
+        if (value.startsWith(' '))
+            value = value.slice(1);
+        dataLines.push(value);
+    }
+    return dataLines.join('\n');
+}
 /**
  * Resolves after `ms` milliseconds, or rejects if the signal aborts
  * first. Used between recreate attempts so a persistent transport

package/dist/resources/platform/sni-endpoint/create-and-associate.d.ts

@@ -0,0 +1,38 @@
+import type { SniEndpoint } from '@heroku/types/3.sdk';
+import type { ResourceCtx } from '../../../core/extend-resource.js';
+export type CreateAndAssociateOptions = {
+    intervalMs?: number;
+    /** Required. Given the wildcard-matched candidate hostnames, returns the subset to associate. */
+    resolveDomains: (candidates: string[]) => Promise<string[]>;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+};
+/**
+ * Create an SNI endpoint (SSL certificate) on an app and associate it with the
+ * app's matching domains.
+ *
+ * Ports the CLI `certs:add` business logic into the SDK.
+ *
+ * Steps:
+ * 1. Create the SNI endpoint from the given certificate chain and private key.
+ * 2. Wait for the app's domains to reach ready status (replaces the old CNAME poll).
+ *    The SDK waits on domain STATUS (`succeeded`/`none`) via `domain.waitForReady`
+ *    rather than the CLI's old `cname`-defined readiness check, polling at a default
+ *    1000ms interval to mirror the CLI's `waitForDomains` cadence. `timeoutMs`
+ *    defaults to 30s and is applied per pending domain (not a single global budget),
+ *    so an app with several pending domains can wait longer than 30s overall.
+ * 3. List the (now stable) app domains and wildcard-match them against the
+ *    certificate's `cert_domains`.
+ * 4. If any domains matched, invoke `resolveDomains` — the interactive selection
+ *    hook the consumer supplies — to choose which matched hostnames to associate.
+ * 5. Associate the selected hostnames with the endpoint in parallel via
+ *    `PATCH /apps/{app}/domains/{hostname}` (`domain.update`).
+ *
+ * If no domains match the certificate, neither `resolveDomains` nor any
+ * association call is made.
+ *
+ * @throws if the domain readiness wait times out or a domain fails, or if any
+ * association call rejects.
+ * @returns the created SNI endpoint.
+ */
+export declare function createAndAssociate(ctx: Pick<ResourceCtx, 'platform'>, appIdentity: string, certificateChain: string, privateKey: string, options: CreateAndAssociateOptions): Promise<SniEndpoint>;

package/dist/resources/platform/sni-endpoint/create-and-associate.js

@@ -0,0 +1,86 @@
+import { waitForReady } from '../domain/wait-for-ready.js';
+const DEFAULT_WAIT_INTERVAL_MS = 1000;
+const DEFAULT_TIMEOUT_MS = 30_000;
+/**
+ * Create an SNI endpoint (SSL certificate) on an app and associate it with the
+ * app's matching domains.
+ *
+ * Ports the CLI `certs:add` business logic into the SDK.
+ *
+ * Steps:
+ * 1. Create the SNI endpoint from the given certificate chain and private key.
+ * 2. Wait for the app's domains to reach ready status (replaces the old CNAME poll).
+ *    The SDK waits on domain STATUS (`succeeded`/`none`) via `domain.waitForReady`
+ *    rather than the CLI's old `cname`-defined readiness check, polling at a default
+ *    1000ms interval to mirror the CLI's `waitForDomains` cadence. `timeoutMs`
+ *    defaults to 30s and is applied per pending domain (not a single global budget),
+ *    so an app with several pending domains can wait longer than 30s overall.
+ * 3. List the (now stable) app domains and wildcard-match them against the
+ *    certificate's `cert_domains`.
+ * 4. If any domains matched, invoke `resolveDomains` — the interactive selection
+ *    hook the consumer supplies — to choose which matched hostnames to associate.
+ * 5. Associate the selected hostnames with the endpoint in parallel via
+ *    `PATCH /apps/{app}/domains/{hostname}` (`domain.update`).
+ *
+ * If no domains match the certificate, neither `resolveDomains` nor any
+ * association call is made.
+ *
+ * @throws if the domain readiness wait times out or a domain fails, or if any
+ * association call rejects.
+ * @returns the created SNI endpoint.
+ */
+// Signature mirrors the CLI `certs:add` / plan-locked public API:
+// createAndAssociate(app, certChain, privateKey, {resolveDomains}).
+// eslint-disable-next-line max-params
+export async function createAndAssociate(ctx, appIdentity, certificateChain, privateKey, options) {
+    const { intervalMs = DEFAULT_WAIT_INTERVAL_MS, resolveDomains, signal, timeoutMs = DEFAULT_TIMEOUT_MS, } = options;
+    signal?.throwIfAborted();
+    const platform = signal ? ctx.platform.withOptions({ signal }) : ctx.platform;
+    const sniEndpoint = await platform.sniEndpoint.create(appIdentity, {
+        certificate_chain: certificateChain,
+        private_key: privateKey,
+    });
+    await waitForReady(ctx, appIdentity, { signal, timeoutMs, waitIntervalMs: intervalMs });
+    const apiDomains = await platform.domain.list(appIdentity);
+    const appDomains = apiDomains.map(d => d.hostname);
+    const certDomains = (sniEndpoint.ssl_cert.cert_domains ?? []);
+    const matched = matchDomains(certDomains, appDomains);
+    if (matched.length > 0) {
+        const selected = await resolveDomains(matched);
+        await Promise.all(selected.map(hostname => platform.domain.update(appIdentity, hostname, { sni_endpoint: sniEndpoint.name })));
+    }
+    return sniEndpoint;
+}
+function splitDomains(domains) {
+    return domains.map(domain => [domain.slice(0, 1), domain.slice(1)]);
+}
+// Adapted from the CLI `certs/add.ts` matcher, but ADDS `^`/`$` anchors to fix a
+// prefix-match bug: without them a wildcard cert like `*.example.com` would match
+// hostnames that merely share a prefix (e.g. `www.example.com.evil.org`). Wildcard
+// certs must not match such hostnames, so both ends of the pattern are anchored.
+function createMatcherFromSplitDomain([firstChar, rest]) {
+    const matcherContents = [];
+    if (firstChar === '*') {
+        matcherContents.push(String.raw `^[\w\-]+`);
+    }
+    else {
+        matcherContents.push(`^${firstChar}`);
+    }
+    const escapedRest = rest.replaceAll('.', String.raw `\.`);
+    matcherContents.push(escapedRest);
+    return new RegExp(`${matcherContents.join('')}$`);
+}
+function matchDomains(certDomains, appDomains) {
+    const splitCertDomains = splitDomains(certDomains);
+    const matchers = splitCertDomains.map(splitDomain => createMatcherFromSplitDomain(splitDomain));
+    if (splitCertDomains.some(domain => (domain[0] === '*'))) {
+        const matchedDomains = [];
+        for (const appDomain of appDomains) {
+            if (matchers.some(matcher => matcher.test(appDomain))) {
+                matchedDomains.push(appDomain);
+            }
+        }
+        return matchedDomains;
+    }
+    return certDomains.filter(domain => appDomains.includes(domain));
+}

package/dist/resources/platform/sni-endpoint/index.d.ts

@@ -0,0 +1,5 @@
+import type { CreateAndAssociateOptions } from './create-and-associate.js';
+export { createAndAssociate, type CreateAndAssociateOptions } from './create-and-associate.js';
+export declare const sniEndpointExtensions: import("../../../core/extend-resource.js").ResourceExtension<"platform", "sniEndpoint", {
+    createAndAssociate: (appIdentity: string, certificateChain: string, privateKey: string, options: CreateAndAssociateOptions) => Promise<import("@heroku/types/3.sdk").SniEndpoint>;
+}>;