@heroku/sdk 0.5.0 → 0.5.1

package/dist/resources/extensions/platform.d.ts

@@ -1,5 +1,6 @@
 export { addOnExtensions } from '../platform/add-on/index.js';
 export { appExtensions, type AppInfo, type PipelineCouplingDetail } from '../platform/app/index.js';
+export { type CreateAndWaitOptions, domainExtensions, type DomainOptions, type WaitForReadyOptions, } from '../platform/domain/index.js';
 export { dynoExtensions, DynoNotReadyError, type DynoState, waitForInfo, type WaitForInfoOptions, } from '../platform/dyno/index.js';
 export { type AttachmentAttachedEvent, type AttachmentDetachedEvent, type AttachmentUpdatedEvent, type HerokuLogEvent, logSessionExtensions, parseHerokuLogLine, type ProvisioningCompletedEvent, type ScaledToEntry, type ScaledToEvent, type StartingProcessEvent, type StateChangedEvent, } from '../platform/log-session/index.js';
 export { pipelineCouplingExtensions } from '../platform/pipeline/coupling.js';

package/dist/resources/extensions/platform.js

@@ -1,5 +1,6 @@
 export { addOnExtensions } from '../platform/add-on/index.js';
 export { appExtensions } from '../platform/app/index.js';
+export { domainExtensions, } from '../platform/domain/index.js';
 export { dynoExtensions, DynoNotReadyError, waitForInfo, } from '../platform/dyno/index.js';
 export { logSessionExtensions, parseHerokuLogLine, } from '../platform/log-session/index.js';
 export { pipelineCouplingExtensions } from '../platform/pipeline/coupling.js';

package/dist/resources/platform/domain/clear-custom-domains.d.ts

@@ -0,0 +1,9 @@
+import type { ResourceCtx } from '../../../core/extend-resource.js';
+import type { DomainOptions } from './types.js';
+/**
+ * Delete all custom domains from an app.
+ *
+ * Lists domains on the app, filters to kind === 'custom', and deletes
+ * each in sequence. Heroku-owned domains (kind === 'heroku') are skipped.
+ */
+export declare function clearCustomDomains(ctx: Pick<ResourceCtx, 'platform'>, appIdentity: string, options?: DomainOptions): Promise<void>;

package/dist/resources/platform/domain/clear-custom-domains.js

@@ -0,0 +1,19 @@
+/**
+ * Delete all custom domains from an app.
+ *
+ * Lists domains on the app, filters to kind === 'custom', and deletes
+ * each in sequence. Heroku-owned domains (kind === 'heroku') are skipped.
+ */
+export async function clearCustomDomains(ctx, appIdentity, options = {}) {
+    const { signal } = options;
+    signal?.throwIfAborted();
+    const platform = signal ? ctx.platform.withOptions({ signal }) : ctx.platform;
+    // List and filter to custom domains
+    const domains = await platform.domain.list(appIdentity);
+    const customDomains = domains.filter(d => d.kind === 'custom');
+    // Delete each in sequence
+    for (const domain of customDomains) {
+        signal?.throwIfAborted();
+        await platform.domain.delete(appIdentity, domain.hostname);
+    }
+}

package/dist/resources/platform/domain/create-and-wait.d.ts

@@ -0,0 +1,13 @@
+import type { Domain } from '@heroku/types/3.sdk';
+import type { ResourceCtx } from '../../../core/extend-resource.js';
+import type { CreateAndWaitOptions } from './types.js';
+/**
+ * Create a domain with SNI endpoint resolution and optional waiting.
+ *
+ * Steps:
+ * 1. If no explicit sniEndpoint option, list SNI endpoints on the app
+ * 2. If multiple SNI endpoints, call resolveSniEndpoint callback
+ * 3. Create the domain with SNI endpoint (defaults to null if not resolved)
+ * 4. If wait: true, poll until domain reaches ready status
+ */
+export declare function createAndWait(ctx: Pick<ResourceCtx, 'platform'>, appIdentity: string, hostname: string, options?: CreateAndWaitOptions): Promise<Domain>;

package/dist/resources/platform/domain/create-and-wait.js

@@ -0,0 +1,46 @@
+import { waitForReady } from './wait-for-ready.js';
+/**
+ * Create a domain with SNI endpoint resolution and optional waiting.
+ *
+ * Steps:
+ * 1. If no explicit sniEndpoint option, list SNI endpoints on the app
+ * 2. If multiple SNI endpoints, call resolveSniEndpoint callback
+ * 3. Create the domain with SNI endpoint (defaults to null if not resolved)
+ * 4. If wait: true, poll until domain reaches ready status
+ */
+export async function createAndWait(ctx, appIdentity, hostname, options = {}) {
+    const { resolveSniEndpoint, signal, sniEndpoint, timeoutMs, wait: shouldWait, waitIntervalMs, } = options;
+    signal?.throwIfAborted();
+    const platform = signal ? ctx.platform.withOptions({ signal }) : ctx.platform;
+    let resolvedSniEndpoint = null;
+    if (sniEndpoint) {
+        // Explicit SNI endpoint provided
+        resolvedSniEndpoint = sniEndpoint;
+    }
+    else {
+        // List SNI endpoints and resolve
+        const sniEndpoints = await platform.sniEndpoint.list(appIdentity);
+        if (sniEndpoints.length > 1) {
+            const sniEndpointSelection = await resolveSniEndpoint?.(sniEndpoints);
+            if (sniEndpointSelection) {
+                resolvedSniEndpoint = sniEndpointSelection;
+            }
+        }
+    }
+    // Create domain
+    let domain = await platform.domain.create(appIdentity, {
+        hostname,
+        // eslint-disable-next-line camelcase
+        sni_endpoint: resolvedSniEndpoint,
+    });
+    if (shouldWait && domain.status !== 'succeeded' && domain.status !== 'none') {
+        const [readyDomain] = await waitForReady(ctx, appIdentity, {
+            domain,
+            signal,
+            timeoutMs,
+            waitIntervalMs,
+        });
+        domain = readyDomain;
+    }
+    return domain;
+}

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

@@ -0,0 +1,10 @@
+import type { CreateAndWaitOptions, DomainOptions, WaitForReadyOptions } from './types.js';
+export { clearCustomDomains } from './clear-custom-domains.js';
+export { createAndWait } from './create-and-wait.js';
+export type { CreateAndWaitOptions, DomainOptions, WaitForReadyOptions, } from './types.js';
+export { waitForReady } from './wait-for-ready.js';
+export declare const domainExtensions: import("../../../core/extend-resource.js").ResourceExtension<"platform", "domain", {
+    add: (appIdentity: string, hostname: string, options?: CreateAndWaitOptions) => Promise<import("@heroku/types/3.sdk").Domain>;
+    clear: (appIdentity: string, options?: DomainOptions) => Promise<void>;
+    wait: (appIdentity: string, options?: WaitForReadyOptions) => Promise<import("@heroku/types/3.sdk").Domain[]>;
+}>;

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

@@ -0,0 +1,14 @@
+import { extendResource } from '../../../core/extend-resource.js';
+import { clearCustomDomains } from './clear-custom-domains.js';
+import { createAndWait } from './create-and-wait.js';
+import { waitForReady } from './wait-for-ready.js';
+// Re-export implementations for direct use
+export { clearCustomDomains } from './clear-custom-domains.js';
+export { createAndWait } from './create-and-wait.js';
+export { waitForReady } from './wait-for-ready.js';
+// Extension definition
+export const domainExtensions = extendResource('platform', 'domain', ctx => ({
+    add: (appIdentity, hostname, options) => createAndWait(ctx, appIdentity, hostname, options),
+    clear: (appIdentity, options) => clearCustomDomains(ctx, appIdentity, options),
+    wait: (appIdentity, options) => waitForReady(ctx, appIdentity, options),
+}));

package/dist/resources/platform/domain/test-utils.d.ts

@@ -0,0 +1,24 @@
+import type { Domain, SniEndpoint } from '@heroku/types/3.sdk';
+import { vi } from 'vitest';
+import type { ResourceCtx } from '../../../core/extend-resource.js';
+export type FakePlatform = {
+    domain: {
+        create: ReturnType<typeof vi.fn>;
+        delete: ReturnType<typeof vi.fn>;
+        info: ReturnType<typeof vi.fn>;
+        list: ReturnType<typeof vi.fn>;
+    };
+    sniEndpoint: {
+        list: ReturnType<typeof vi.fn>;
+    };
+    withOptions: ReturnType<typeof vi.fn>;
+};
+export declare function buildCtx(stubs?: {
+    domainCreate?: ReturnType<typeof vi.fn>;
+    domainDelete?: ReturnType<typeof vi.fn>;
+    domainInfo?: ReturnType<typeof vi.fn>;
+    domainList?: ReturnType<typeof vi.fn>;
+    sniEndpointList?: ReturnType<typeof vi.fn>;
+}): ResourceCtx;
+export declare function buildDomain(overrides?: Partial<Domain>): Domain;
+export declare function buildSniEndpoint(overrides?: Partial<SniEndpoint>): SniEndpoint;

package/dist/resources/platform/domain/test-utils.js

@@ -0,0 +1,60 @@
+import { vi } from 'vitest';
+export function buildCtx(stubs = {}) {
+    const platform = {
+        domain: {
+            create: stubs.domainCreate ?? vi.fn().mockResolvedValue({}),
+            delete: stubs.domainDelete ?? vi.fn().mockResolvedValue({}),
+            info: stubs.domainInfo ?? vi.fn().mockResolvedValue({}),
+            list: stubs.domainList ?? vi.fn().mockResolvedValue([]),
+        },
+        sniEndpoint: {
+            list: stubs.sniEndpointList ?? vi.fn().mockResolvedValue([]),
+        },
+        withOptions: vi.fn(function () {
+            return this;
+        }),
+    };
+    platform.withOptions.mockReturnValue(platform);
+    return {
+        data: {},
+        platform: platform,
+    };
+}
+export function buildDomain(overrides = {}) {
+    return {
+        acm_status: null,
+        acm_status_reason: null,
+        app: { id: 'app-123', name: 'test-app' },
+        cname: 'example.herokuapp.com',
+        created_at: '2024-01-01T00:00:00Z',
+        hostname: 'example.com',
+        id: 'domain-123',
+        kind: 'custom',
+        sni_endpoint: null,
+        status: 'pending',
+        updated_at: '2024-01-01T00:00:00Z',
+        ...overrides,
+    };
+}
+export function buildSniEndpoint(overrides = {}) {
+    return {
+        app: { id: 'app-123', name: 'test-app' },
+        certificate_chain: '-----BEGIN CERTIFICATE-----',
+        created_at: '2024-01-01T00:00:00Z',
+        display_name: 'example.com cert',
+        domains: ['example.com'],
+        id: 'sni-123',
+        name: 'tokyo-1234',
+        ssl_cert: {
+            'ca_signed?': true,
+            cert_domains: ['example.com'],
+            expires_at: '2025-01-01T00:00:00Z',
+            issuer: 'Let\'s Encrypt',
+            'self_signed?': false,
+            starts_at: '2024-01-01T00:00:00Z',
+            subject: 'CN=example.com',
+        },
+        updated_at: '2024-01-01T00:00:00Z',
+        ...overrides,
+    };
+}

package/dist/resources/platform/domain/types.d.ts

@@ -0,0 +1,58 @@
+import type { Domain, SniEndpoint } from '@heroku/types/3.sdk';
+export type DomainOptions = {
+    /**
+     * Abort signal to cancel the operation.
+     */
+    signal?: AbortSignal;
+};
+export type WaitForReadyOptions = DomainOptions & {
+    /**
+     * Domain to wait for.
+     */
+    domain?: Domain;
+    /**
+     * Hostname of the domain to wait for.
+     */
+    hostname?: string;
+    /**
+     * Maximum time in milliseconds to wait before giving up.
+     * If undefined, waits indefinitely (until signal aborted).
+     */
+    timeoutMs?: number;
+    /**
+     * Polling interval in milliseconds. Defaults to 5000.
+     */
+    waitIntervalMs?: number;
+};
+export type CreateAndWaitOptions = DomainOptions & {
+    /**
+     * Callback to resolve which SNI endpoint to use
+     * when one is not provided.
+     *
+     * @param candidates List of SNI endpoints to choose from
+     * @returns Promise resolving to the selected SNI endpoint
+     */
+    resolveSniEndpoint?: (candidates: SniEndpoint[]) => Promise<string> | string;
+    /**
+     * SNI endpoint to use.
+     *
+     * If provided, skips SNI endpoint listing and resolution.
+     */
+    sniEndpoint?: string;
+    /**
+     * Maximum time in milliseconds to wait when `wait` is true.
+     * Passed through to `waitForReady`.
+     */
+    timeoutMs?: number;
+    /**
+     * If true, waits for the domain to reach ready status after creation.
+     *
+     * Defaults to false (return immediately after create).
+     */
+    wait?: boolean;
+    /**
+     * Polling interval in milliseconds used when `wait` is true.
+     * Passed through to `waitForReady`.
+     */
+    waitIntervalMs?: number;
+};

package/dist/resources/platform/domain/types.js

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

package/dist/resources/platform/domain/wait-for-ready.d.ts

@@ -0,0 +1,12 @@
+import type { Domain } from '@heroku/types/3.sdk';
+import type { ResourceCtx } from '../../../core/extend-resource.js';
+import type { WaitForReadyOptions } from './types.js';
+/**
+ * Waits for all pending domains on an app
+ * to reach ready status ('succeeded' or 'none').
+ *
+ * If `domain` or `hostname` is provided, waits for the specific domain.
+ *
+ * @throws if the domain reaches a non-ready status (e.g., 'failed').
+ */
+export declare function waitForReady(ctx: Pick<ResourceCtx, 'platform'>, appIdentity: string, options?: WaitForReadyOptions): Promise<Domain[]>;

package/dist/resources/platform/domain/wait-for-ready.js

@@ -0,0 +1,46 @@
+import { wait } from '../../../utils/wait.js';
+const DEFAULT_WAIT_INTERVAL_MS = 5000;
+/**
+ * Waits for all pending domains on an app
+ * to reach ready status ('succeeded' or 'none').
+ *
+ * If `domain` or `hostname` is provided, waits for the specific domain.
+ *
+ * @throws if the domain reaches a non-ready status (e.g., 'failed').
+ */
+export async function waitForReady(ctx, appIdentity, options = {}) {
+    const { domain, hostname, signal, timeoutMs, waitIntervalMs = DEFAULT_WAIT_INTERVAL_MS } = options;
+    signal?.throwIfAborted();
+    const platform = signal ? ctx.platform.withOptions({ signal }) : ctx.platform;
+    let domains;
+    if (domain) {
+        domains = [domain];
+    }
+    else if (hostname) {
+        const domain = await platform.domain.info(appIdentity, hostname);
+        domains = [domain];
+    }
+    else {
+        const apiDomains = await platform.domain.list(appIdentity);
+        domains = apiDomains.filter(domain => domain.status === 'pending');
+    }
+    for (let i = 0; i < domains.length; i++) {
+        domains[i] = await waitForDomain(platform, appIdentity, domains[i], waitIntervalMs, timeoutMs, signal);
+    }
+    return domains;
+}
+async function waitForDomain(platform, appIdentity, domain, waitIntervalMs, timeoutMs, signal) {
+    const deadline = timeoutMs === undefined ? undefined : Date.now() + timeoutMs;
+    while (domain.status === 'pending') {
+        await wait(waitIntervalMs, signal);
+        const updatedDomain = await platform.domain.info(appIdentity, domain.id);
+        domain = updatedDomain;
+        if (deadline !== undefined && Date.now() >= deadline) {
+            throw new Error(`Timed out waiting for domain ${domain.hostname}`);
+        }
+    }
+    if (domain.status === 'succeeded' || domain.status === 'none') {
+        return domain;
+    }
+    throw new Error(`The domain creation finished with status ${domain.status}`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heroku/sdk",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Heroku SDK",
   "author": "Heroku",
   "type": "module",