@heroku/sdk 0.5.2 → 0.5.4

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>;
+}>;

package/dist/resources/platform/sni-endpoint/index.js

@@ -0,0 +1,6 @@
+import { extendResource } from '../../../core/extend-resource.js';
+import { createAndAssociate } from './create-and-associate.js';
+export { createAndAssociate } from './create-and-associate.js';
+export const sniEndpointExtensions = extendResource('platform', 'sniEndpoint', ctx => ({
+    createAndAssociate: (appIdentity, certificateChain, privateKey, options) => createAndAssociate(ctx, appIdentity, certificateChain, privateKey, options),
+}));

package/dist/resources/platform/telemetry-drain/index.d.ts

@@ -0,0 +1,6 @@
+import type { TelemetryDrainOptions, TelemetryDrainTarget } from './types.js';
+export { removeDrainsForTarget } from './remove-drains-for-target.js';
+export type { TelemetryDrainOptions, TelemetryDrainTarget } from './types.js';
+export declare const telemetryDrainExtensions: import("../../../core/extend-resource.js").ResourceExtension<"platform", "telemetryDrain", {
+    removeDrains: (target: TelemetryDrainTarget, options?: TelemetryDrainOptions) => Promise<import("@heroku/types/3.sdk").TelemetryDrain[]>;
+}>;

package/dist/resources/platform/telemetry-drain/index.js

@@ -0,0 +1,6 @@
+import { extendResource } from '../../../core/extend-resource.js';
+import { removeDrainsForTarget } from './remove-drains-for-target.js';
+export { removeDrainsForTarget } from './remove-drains-for-target.js';
+export const telemetryDrainExtensions = extendResource('platform', 'telemetryDrain', ctx => ({
+    removeDrains: (target, options) => removeDrainsForTarget(ctx, target, options),
+}));

package/dist/resources/platform/telemetry-drain/remove-drains-for-target.d.ts

@@ -0,0 +1,13 @@
+import type { TelemetryDrain } from '@heroku/types/3.sdk';
+import type { ResourceCtx } from '../../../core/extend-resource.js';
+import type { TelemetryDrainOptions, TelemetryDrainTarget } from './types.js';
+/**
+ * Remove all telemetry drains for a given app or space.
+ *
+ * Behavior:
+ * - Dispatches to listByApp or listBySpace based on target discriminant
+ * - Deletes all drains in parallel via Promise.all
+ * - Returns empty array if no drains exist
+ * - Rejects if any individual delete fails
+ */
+export declare function removeDrainsForTarget(ctx: Pick<ResourceCtx, 'platform'>, target: TelemetryDrainTarget, options?: TelemetryDrainOptions): Promise<TelemetryDrain[]>;

package/dist/resources/platform/telemetry-drain/remove-drains-for-target.js

@@ -0,0 +1,25 @@
+/**
+ * Remove all telemetry drains for a given app or space.
+ *
+ * Behavior:
+ * - Dispatches to listByApp or listBySpace based on target discriminant
+ * - Deletes all drains in parallel via Promise.all
+ * - Returns empty array if no drains exist
+ * - Rejects if any individual delete fails
+ */
+export async function removeDrainsForTarget(ctx, target, options = {}) {
+    const { signal } = options;
+    const { app, space } = target;
+    signal?.throwIfAborted();
+    const platform = signal ? ctx.platform.withOptions({ signal }) : ctx.platform;
+    let drains = [];
+    if (app) {
+        drains = await platform.telemetryDrain.listByApp(app);
+    }
+    else if (space) {
+        drains = await platform.telemetryDrain.listBySpace(space);
+    }
+    signal?.throwIfAborted();
+    const deletedDrains = await Promise.all(drains.map(drain => platform.telemetryDrain.delete(drain.id)));
+    return deletedDrains;
+}

package/dist/resources/platform/telemetry-drain/types.d.ts

@@ -0,0 +1,13 @@
+export type TelemetryDrainOptions = {
+    /**
+     * Abort signal to cancel the operation.
+     */
+    signal?: AbortSignal;
+};
+export type TelemetryDrainTarget = {
+    app: string;
+    space?: never;
+} | {
+    app?: never;
+    space: string;
+};

package/dist/resources/platform/telemetry-drain/types.js

@@ -0,0 +1 @@
+export {};

package/dist/resources/platform/test-run/index.d.ts

@@ -0,0 +1,5 @@
+import { type TestRunStatus, type WaitForStateOptions } from './wait-for-state.js';
+export { TestRunNotReadyError, type TestRunStatus, waitForState, type WaitForStateOptions, } from './wait-for-state.js';
+export declare const testRunExtensions: import("../../../core/extend-resource.js").ResourceExtension<"platform", "testRun", {
+    waitForState: (pipelineId: string, testRunNumber: number, targetStates: ReadonlyArray<string | TestRunStatus>, options?: WaitForStateOptions) => Promise<import("@heroku/types/3.sdk").TestRun>;
+}>;

package/dist/resources/platform/test-run/index.js

@@ -0,0 +1,9 @@
+import { extendResource } from '../../../core/extend-resource.js';
+import { waitForState } from './wait-for-state.js';
+export { TestRunNotReadyError, waitForState, } from './wait-for-state.js';
+// Resource key MUST be the camelCase `'testRun'` — it matches the generated
+// route-group export name that `mergeExtensions` looks up on the platform
+// client. The directory stays kebab (`test-run/`).
+export const testRunExtensions = extendResource('platform', 'testRun', ctx => ({
+    waitForState: (pipelineId, testRunNumber, targetStates, options) => waitForState(ctx, pipelineId, testRunNumber, targetStates, options),
+}));

package/dist/resources/platform/test-run/wait-for-state.d.ts

@@ -0,0 +1,68 @@
+import type { TestRun } from '@heroku/types/3.sdk';
+import type { ResourceCtx } from '../../../core/extend-resource.js';
+/**
+ * The documented `TestRun.status` values from the Platform API. Provided
+ * for autocomplete in {@link waitForState}'s `targetStates`; the runtime
+ * comparison is plain string membership (`targetStates.includes(run.status)`),
+ * so any string is accepted.
+ */
+export type TestRunStatus = TestRun['status'];
+/**
+ * Thrown by {@link waitForState} when the test run did not reach one of
+ * `targetStates` within `timeoutMs`. Carries the last observed run so
+ * callers can branch on its terminal `status` (e.g. distinguish a
+ * `failed` run from one still `building`). Mirrors `DynoNotReadyError`.
+ */
+export declare class TestRunNotReadyError extends Error {
+    readonly testRun: TestRun;
+    readonly expectedStates: ReadonlyArray<string>;
+    readonly timeoutMs: number;
+    readonly id = "test_run_not_ready";
+    constructor(testRun: TestRun, expectedStates: ReadonlyArray<string>, timeoutMs: number);
+}
+export type WaitForStateOptions = {
+    /**
+     * Delay between polls in milliseconds. Defaults to 1000.
+     */
+    intervalMs?: number;
+    /**
+     * Fires after every successful `testRun.infoByPipeline` call, including
+     * runs whose `status` does not yet match `targetStates` (and trigger
+     * another poll) AND the final matching run before it is returned. Use
+     * this to surface live state transitions in a UI. Exceptions thrown from
+     * this callback propagate and end the wait — there is no implicit catch.
+     */
+    onPoll?: (run: TestRun) => void;
+    /**
+     * Cancels the wait early. If already aborted, {@link waitForState}
+     * rejects before the first poll; if aborted mid-wait, the pending delay
+     * rejects with `signal.reason`.
+     */
+    signal?: AbortSignal;
+    /**
+     * Wall-clock budget in milliseconds before {@link TestRunNotReadyError}
+     * is thrown. Defaults to 600000 (10 minutes) — a finite default so a
+     * stuck run can't hang forever. Pass a larger value for long CI runs.
+     */
+    timeoutMs?: number;
+};
+/**
+ * Poll `testRun.infoByPipeline` until the run's `status` is one of
+ * `targetStates`, then return that run. Reuses the SDK's cancellable
+ * `wait()` helper to space polls — no bare `setTimeout` loop.
+ *
+ * Transient-error handling: errors from `infoByPipeline` **propagate**;
+ * there is no 404/429/503 retry. This matches the closest precedent,
+ * `promotePipeline`, and the original CLI `waitForStates`, which had no
+ * retry either — adopting `waitForInfo`'s transient retry would be behavior
+ * the eventual CLI caller never had.
+ *
+ * On exceeding `timeoutMs` without a match, throws {@link TestRunNotReadyError}
+ * carrying the last observed run.
+ *
+ * @example
+ * ```ts
+ * const run = await platform.testRun.waitForState(pipelineId, 42, ['debugging', 'errored'])
+ * ```
+ */
+export declare function waitForState(ctx: Pick<ResourceCtx, 'platform'>, pipelineId: string, testRunNumber: number, targetStates: ReadonlyArray<string | TestRunStatus>, options?: WaitForStateOptions): Promise<TestRun>;

package/dist/resources/platform/test-run/wait-for-state.js

@@ -0,0 +1,65 @@
+import { wait } from '../../../utils/wait.js';
+const DEFAULT_INTERVAL_MS = 1000;
+// Finite default so a stuck CI test run can't hang a caller forever.
+// Diverges deliberately from `promotePipeline`, which leaves `timeoutMs`
+// unbounded; callers that need longer can pass an explicit `timeoutMs`.
+const DEFAULT_TIMEOUT_MS = 600_000;
+/**
+ * Thrown by {@link waitForState} when the test run did not reach one of
+ * `targetStates` within `timeoutMs`. Carries the last observed run so
+ * callers can branch on its terminal `status` (e.g. distinguish a
+ * `failed` run from one still `building`). Mirrors `DynoNotReadyError`.
+ */
+export class TestRunNotReadyError extends Error {
+    testRun;
+    expectedStates;
+    timeoutMs;
+    id = 'test_run_not_ready';
+    constructor(testRun, expectedStates, timeoutMs) {
+        super(`Test run #${testRun.number} did not reach status ${expectedStates.join('/')} `
+            + `within ${timeoutMs}ms (last status: ${testRun.status}).`);
+        this.testRun = testRun;
+        this.expectedStates = expectedStates;
+        this.timeoutMs = timeoutMs;
+        this.name = 'TestRunNotReadyError';
+    }
+}
+/**
+ * Poll `testRun.infoByPipeline` until the run's `status` is one of
+ * `targetStates`, then return that run. Reuses the SDK's cancellable
+ * `wait()` helper to space polls — no bare `setTimeout` loop.
+ *
+ * Transient-error handling: errors from `infoByPipeline` **propagate**;
+ * there is no 404/429/503 retry. This matches the closest precedent,
+ * `promotePipeline`, and the original CLI `waitForStates`, which had no
+ * retry either — adopting `waitForInfo`'s transient retry would be behavior
+ * the eventual CLI caller never had.
+ *
+ * On exceeding `timeoutMs` without a match, throws {@link TestRunNotReadyError}
+ * carrying the last observed run.
+ *
+ * @example
+ * ```ts
+ * const run = await platform.testRun.waitForState(pipelineId, 42, ['debugging', 'errored'])
+ * ```
+ */
+export async function waitForState(ctx, pipelineId, testRunNumber, targetStates, options = {}) {
+    const { intervalMs = DEFAULT_INTERVAL_MS, onPoll, signal, timeoutMs = DEFAULT_TIMEOUT_MS, } = options;
+    signal?.throwIfAborted();
+    // Scope the in-flight info call to the caller's signal so an abort takes
+    // effect during the API call, not just during the backoff.
+    const platform = signal ? ctx.platform.withOptions({ signal }) : ctx.platform;
+    const deadline = Date.now() + timeoutMs;
+    while (true) {
+        signal?.throwIfAborted();
+        const run = await platform.testRun.infoByPipeline(pipelineId, testRunNumber);
+        onPoll?.(run);
+        if (targetStates.includes(run.status)) {
+            return run;
+        }
+        if (Date.now() >= deadline) {
+            throw new TestRunNotReadyError(run, targetStates, timeoutMs);
+        }
+        await wait(intervalMs, signal);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heroku/sdk",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "Heroku SDK",
   "author": "Heroku",
   "type": "module",
@@ -50,6 +50,14 @@
       "types": "./dist/resources/platform/pipeline/*.d.ts",
       "default": "./dist/resources/platform/pipeline/*.js"
     },
+    "./resources/platform/test-run": {
+      "types": "./dist/resources/platform/test-run/index.d.ts",
+      "default": "./dist/resources/platform/test-run/index.js"
+    },
+    "./resources/data/redis": {
+      "types": "./dist/resources/data/redis/index.d.ts",
+      "default": "./dist/resources/data/redis/index.js"
+    },
     "./resources/*": {
       "types": "./dist/resources/*.d.ts",
       "default": "./dist/resources/*.js"
@@ -91,8 +99,8 @@
     "vitest": "^4.1.4"
   },
   "dependencies": {
-    "@heroku/heroku-fetch": "^0.1.1-beta",
-    "@heroku/types": "^3.0.0-beta",
+    "@heroku/heroku-fetch": "^0.1.3",
+    "@heroku/types": "^4.0.1",
     "debug": "^4.4.0"
   }
 }