@heroku/sdk 0.1.0-alpha.0

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

@@ -0,0 +1,128 @@
+import { HerokuApiClient } from '@heroku/heroku-fetch';
+import createDebug from 'debug';
+import { extendResource } from '../../core/extend-resource.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);
+    }
+}
+function wait(ms, signal) {
+    return new Promise((resolve, reject) => {
+        function onAbort() {
+            clearTimeout(timer);
+            reject(signal.reason ?? new Error('Aborted'));
+        }
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        if (signal) {
+            if (signal.aborted) {
+                clearTimeout(timer);
+                reject(signal.reason ?? new Error('Aborted'));
+                return;
+            }
+            signal.addEventListener('abort', onAbort, { once: true });
+        }
+    });
+}

package/dist/resources/platform/pipeline.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.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/shield.d.ts

@@ -0,0 +1,2 @@
+export declare function shieldToPrivate(size: string): string;
+export declare function privateToShield(size: string): string;

package/dist/resources/platform/shield.js

@@ -0,0 +1,6 @@
+export function shieldToPrivate(size) {
+    return size.replace(/^Shield-/, 'Private-');
+}
+export function privateToShield(size) {
+    return size.replace(/^Private-/, 'Shield-');
+}

package/dist/services/data.d.ts

@@ -0,0 +1,5 @@
+import type { HerokuApiClientOptions } from '@heroku/heroku-fetch';
+import type { HerokuClient } from '@heroku/types/data';
+import type { RoutesClientExtras } from '../core/create-client.js';
+export type DataClient = HerokuClient & RoutesClientExtras<HerokuClient>;
+export declare function createDataClient(options?: HerokuApiClientOptions): DataClient;

package/dist/services/data.js

@@ -0,0 +1,5 @@
+import * as routes from '@heroku/types/data/routes';
+import { createClient } from '../core/create-client.js';
+export function createDataClient(options = {}) {
+    return createClient(routes, { service: 'data', ...options });
+}

package/dist/services/platform.d.ts

@@ -0,0 +1,5 @@
+import type { HerokuApiClientOptions } from '@heroku/heroku-fetch';
+import type { HerokuClient } from '@heroku/types/3.sdk';
+import type { RoutesClientExtras } from '../core/create-client.js';
+export type PlatformClient = HerokuClient & RoutesClientExtras<HerokuClient>;
+export declare function createPlatformClient(options?: HerokuApiClientOptions): PlatformClient;

package/dist/services/platform.js

@@ -0,0 +1,5 @@
+import * as routes from '@heroku/types/3.sdk/routes';
+import { createClient } from '../core/create-client.js';
+export function createPlatformClient(options = {}) {
+    return createClient(routes, { service: 'platform', ...options });
+}

package/dist/utils/wait.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Promise-based delay that respects an optional AbortSignal.
+ *
+ * Resolves after `ms` milliseconds. If `signal` is provided and is
+ * (or becomes) aborted, the promise rejects with `signal.reason`
+ * (or `new Error('Aborted')` if `reason` is unset) and clears the
+ * pending timer.
+ *
+ * Used by polling loops in resource extensions (e.g. `addOn.createAndWait`,
+ * `pipelinePromotion.promote`) to space out poll requests while staying
+ * responsive to cancellation.
+ *
+ * @param ms Milliseconds to wait before resolving.
+ * @param signal Optional AbortSignal to cancel the wait early.
+ */
+export declare function wait(ms: number, signal?: AbortSignal): Promise<void>;

package/dist/utils/wait.js

@@ -0,0 +1,35 @@
+/**
+ * Promise-based delay that respects an optional AbortSignal.
+ *
+ * Resolves after `ms` milliseconds. If `signal` is provided and is
+ * (or becomes) aborted, the promise rejects with `signal.reason`
+ * (or `new Error('Aborted')` if `reason` is unset) and clears the
+ * pending timer.
+ *
+ * Used by polling loops in resource extensions (e.g. `addOn.createAndWait`,
+ * `pipelinePromotion.promote`) to space out poll requests while staying
+ * responsive to cancellation.
+ *
+ * @param ms Milliseconds to wait before resolving.
+ * @param signal Optional AbortSignal to cancel the wait early.
+ */
+export function wait(ms, signal) {
+    return new Promise((resolve, reject) => {
+        function onAbort() {
+            clearTimeout(timer);
+            reject(signal.reason ?? new Error('Aborted'));
+        }
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        if (signal) {
+            if (signal.aborted) {
+                clearTimeout(timer);
+                reject(signal.reason ?? new Error('Aborted'));
+                return;
+            }
+            signal.addEventListener('abort', onAbort, { once: true });
+        }
+    });
+}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@heroku/sdk",
+  "version": "0.1.0-alpha.0",
+  "description": "Heroku SDK",
+  "author": "Heroku",
+  "type": "module",
+  "main": "dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./platform": {
+      "types": "./dist/services/platform.d.ts",
+      "default": "./dist/services/platform.js"
+    },
+    "./data": {
+      "types": "./dist/services/data.d.ts",
+      "default": "./dist/services/data.js"
+    },
+    "./extensions/platform": {
+      "types": "./dist/resources/extensions/platform.d.ts",
+      "default": "./dist/resources/extensions/platform.js"
+    },
+    "./extensions/data": {
+      "types": "./dist/resources/extensions/data.d.ts",
+      "default": "./dist/resources/extensions/data.js"
+    },
+    "./resources/*": {
+      "types": "./dist/resources/*.d.ts",
+      "default": "./dist/resources/*.js"
+    }
+  },
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/heroku/heroku-sdk"
+  },
+  "scripts": {
+    "build": "tsc",
+    "coverage": "vitest --run --coverage",
+    "example": "tsx",
+    "lint": "eslint",
+    "lint:fix": "eslint --fix",
+    "prepare": "npm run build",
+    "test": "vitest --run"
+  },
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@heroku-cli/test-utils": "^0.3.0",
+    "@types/debug": "^4.1.12",
+    "@types/node": "^25.6.2",
+    "@vitest/coverage-v8": "^4.1.8",
+    "eslint": "^9.39.4",
+    "eslint-config-oclif": "^6.0.167",
+    "eslint-plugin-vitest": "0.5.4",
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.4"
+  },
+  "dependencies": {
+    "@heroku/heroku-fetch": "^0.1.1-beta",
+    "@heroku/types": "^3.0.0-beta",
+    "debug": "^4.4.0"
+  }
+}