@siloy/hubspot-provisioning 0.0.0-stage → 0.1.1

package/dist/provisioning/src/api/client.js

@@ -0,0 +1,186 @@
+import { CLI_VERSION } from '../version.js';
+const POLL_MS = 5000;
+const WINDOW_MS = 15 * 60_000;
+/** A request (and reading its answer) without a client deadline is aborted after this long. */
+const MAX_REQUEST_MS = 60_000;
+const UNEXPECTED = 'The server answered in an unexpected format. Upgrade @siloy/hubspot-provisioning, or check PROVISIONING_URL.';
+const STATUSES = new Set(['queued', 'running', 'succeeded', 'failed']);
+/** The server refused, or answered something unreadable. `status` 0 is a network failure. `message` is the server's text. */
+export class CiApiError extends Error {
+    status;
+    code;
+    details;
+    constructor(status, code, message, details) {
+        super(message);
+        this.name = 'CiApiError';
+        this.status = status;
+        this.code = code;
+        if (details !== undefined)
+            this.details = details;
+    }
+}
+export class CiTimeoutError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CiTimeoutError';
+    }
+}
+/** Client for the three CI endpoints (#105). The key lives in a private field and is scrubbed from everything thrown. */
+export class CiClient {
+    #baseUrl;
+    #key;
+    #fetch;
+    #sleep;
+    #now;
+    #deadline;
+    constructor(options) {
+        this.#baseUrl = options.baseUrl.replace(/\/+$/, '');
+        this.#key = options.key;
+        this.#fetch = options.fetch ?? ((input, init) => fetch(input, init));
+        this.#sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+        this.#now = options.now ?? (() => new Date());
+        this.#deadline = options.deadline?.getTime();
+    }
+    createPlan(body) {
+        return this.#request('POST', '/api/ci/plans', isCreated, body);
+    }
+    getRun(runId) {
+        return this.#request('GET', `/api/ci/runs/${encodeURIComponent(runId)}`, isRunView);
+    }
+    createApply(planRunId) {
+        return this.#request('POST', '/api/ci/applies', isCreated, { planRunId });
+    }
+    /** Polls getRun every 5 s until status is succeeded/failed; throws CiTimeoutError after `timeoutMs`. */
+    async waitForRun(runId, timeoutMs) {
+        const own = this.#now().getTime() + timeoutMs;
+        const deadline = this.#deadline === undefined ? own : Math.min(own, this.#deadline);
+        for (;;) {
+            const run = await this.#request('GET', `/api/ci/runs/${encodeURIComponent(runId)}`, isRunView, undefined, deadline);
+            if (run.status === 'succeeded' || run.status === 'failed')
+                return run;
+            if (this.#now().getTime() + POLL_MS > deadline)
+                throw new CiTimeoutError(`Timed out waiting for run ${runId} to finish.`);
+            await this.#sleep(POLL_MS);
+        }
+    }
+    async #request(method, path, valid, body, ownDeadline) {
+        const deadline = ownDeadline ?? this.#deadline;
+        for (;;) {
+            const { response, text } = await this.#exchange(method, path, body, deadline);
+            if (response.ok) {
+                let parsed;
+                try {
+                    parsed = JSON.parse(text);
+                }
+                catch {
+                    throw new CiApiError(response.status, 'unexpected_response', UNEXPECTED);
+                }
+                if (!valid(parsed))
+                    throw new CiApiError(response.status, 'unexpected_response', UNEXPECTED);
+                return parsed;
+            }
+            const error = this.#errorOf(response.status, text);
+            if (error.status !== 429 || error.code !== 'rate_limited')
+                throw error;
+            const now = this.#now().getTime();
+            const wait = (Math.floor(now / WINDOW_MS) + 1) * WINDOW_MS + 1000 - now;
+            if (deadline !== undefined && now + wait > deadline)
+                throw new CiTimeoutError('Rate limited, and the next 15-minute window starts after the timeout.');
+            await this.#sleep(wait);
+        }
+    }
+    /**
+     * One request and its whole answer, under one abort signal: the time left to `deadline`, else 60 s. An abort at the
+     * deadline is CiTimeoutError; one at the 60 s cap is a `network` error.
+     */
+    async #exchange(method, path, body, deadline) {
+        const ms = deadline === undefined ? MAX_REQUEST_MS : deadline - this.#now().getTime();
+        if (ms <= 0)
+            throw new CiTimeoutError('The timeout ran out before the provisioning app answered.');
+        const signal = AbortSignal.timeout(ms);
+        const aborted = () => deadline === undefined
+            ? new CiApiError(0, 'network', `Could not reach ${this.#baseUrl}: request timed out after ${Math.round(ms / 1000)} s`)
+            : new CiTimeoutError('The timeout ran out before the provisioning app answered.');
+        const response = await this.#send(method, path, body, signal, aborted);
+        try {
+            return { response, text: await untilAborted(response.text(), signal) };
+        }
+        catch {
+            if (signal.aborted)
+                throw aborted();
+            throw new CiApiError(response.status, 'network', `Could not read the answer from ${this.#baseUrl}.`);
+        }
+    }
+    async #send(method, path, body, signal, aborted) {
+        try {
+            return await untilAborted(this.#fetch(`${this.#baseUrl}${path}`, {
+                method,
+                redirect: 'error',
+                signal,
+                headers: {
+                    authorization: `Bearer ${this.#key}`,
+                    'x-provisioning-cli-version': CLI_VERSION,
+                    'content-type': 'application/json',
+                    accept: 'application/json',
+                },
+                ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+            }), signal);
+        }
+        catch (error) {
+            if (signal.aborted)
+                throw aborted();
+            // Only text, never the cause object: it may hold the request, and with it the key.
+            throw new CiApiError(0, 'network', this.#scrub(`Could not reach ${this.#baseUrl}: ${reasonOf(error)}`));
+        }
+    }
+    #errorOf(status, text) {
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            return unreadable(status);
+        }
+        const body = parsed?.error;
+        if (!body || typeof body.code !== 'string' || typeof body.message !== 'string')
+            return unreadable(status);
+        return new CiApiError(status, body.code, this.#scrub(body.message), body.details === undefined ? undefined : JSON.parse(this.#scrub(JSON.stringify(body.details))));
+    }
+    #scrub(text) {
+        return this.#key ? text.split(this.#key).join('[key]') : text;
+    }
+}
+/** `promise`, or a rejection as soon as `signal` aborts: also for a fetch that ignores its signal. */
+function untilAborted(promise, signal) {
+    if (signal.aborted)
+        return Promise.reject(signal.reason);
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(signal.reason);
+        signal.addEventListener('abort', onAbort, { once: true });
+        promise.then((value) => { signal.removeEventListener('abort', onAbort); resolve(value); }, (error) => { signal.removeEventListener('abort', onAbort); reject(error); });
+    });
+}
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/** The minimal shape of a 201 from POST /api/ci/plans or /api/ci/applies. */
+function isCreated(body) {
+    return isObject(body) && typeof body.runId === 'string';
+}
+/** The minimal shape of a CiRunView: what the commands read without checking. */
+function isRunView(body) {
+    return isObject(body) && typeof body.id === 'string' && STATUSES.has(body.status)
+        && ['actions', 'conflicts', 'blocking', 'missingTargets'].every((name) => Array.isArray(body[name]));
+}
+function unreadable(status) {
+    return new CiApiError(status, 'http_error', `The server answered HTTP ${status} without a readable error.`);
+}
+/** The first non-empty of cause message/code, its first inner error's message/code, the error's own message. */
+function reasonOf(error) {
+    const outer = (error ?? {});
+    const cause = (outer.cause ?? {});
+    const inner = (Array.isArray(cause.errors) ? cause.errors[0] ?? {} : {});
+    for (const value of [cause.message, cause.code, inner.message, inner.code, outer.message]) {
+        if (typeof value === 'string' && value !== '')
+            return value;
+    }
+    return 'unknown error';
+}

package/dist/provisioning/src/api/commit.d.ts

@@ -0,0 +1,13 @@
+export interface CommitInfo {
+    sha: string;
+    ref: string;
+    ciRunUrl: string | null;
+}
+/** From flags, else GitHub Actions env. ciRunUrl = `${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}` when all three are set, else null. */
+export declare function commitInfo(env: Record<string, string | undefined>, flags: {
+    sha?: string;
+    ref?: string;
+    ciRunUrl?: string;
+}): CommitInfo | {
+    error: string;
+};

package/dist/provisioning/src/api/commit.js

@@ -0,0 +1,12 @@
+/** From flags, else GitHub Actions env. ciRunUrl = `${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}` when all three are set, else null. */
+export function commitInfo(env, flags) {
+    const sha = flags.sha || env.GITHUB_SHA;
+    if (!sha)
+        return { error: 'No commit sha: pass --sha or run in GitHub Actions (GITHUB_SHA).' };
+    const ref = flags.ref || env.GITHUB_REF;
+    if (!ref)
+        return { error: 'No commit ref: pass --ref or run in GitHub Actions (GITHUB_REF).' };
+    const { GITHUB_SERVER_URL: server, GITHUB_REPOSITORY: repository, GITHUB_RUN_ID: runId } = env;
+    const fromEnv = server && repository && runId ? `${server}/${repository}/actions/runs/${runId}` : null;
+    return { sha, ref, ciRunUrl: flags.ciRunUrl || fromEnv };
+}

package/dist/provisioning/src/api/types.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Request and response shapes of the CI API. Mirrors docs/ci-api.md; apps/web/test/server/ci/ci-contract.test.ts checks
+ * the server's types against these at typecheck time.
+ */
+/**
+ * An error, refusal or run error code. The listed ones are those docs/ci-api.md documents, plus the client's own
+ * `network`, `http_error` and `unexpected_response`; the server may add codes, so any string is accepted.
+ */
+export type KnownErrorCode = 'invalid' | 'cli_outdated' | 'unauthenticated' | 'forbidden' | 'deploy_key_expired' | 'not_found' | 'preview_plan' | 'plan_unclassified' | 'blocking_updates' | 'mapping_target_missing' | 'nothing_to_apply' | 'reconnect_required' | 'apply_locked' | 'missing_scopes' | 'conflict' | 'too_large' | 'rate_limited' | 'internal' | 'environment' | 'hubspot' | 'plan_changed' | 'apply_failed' | 'deploy_key_revoked' | 'portal_moved' | 'dispatch_failed' | 'timed_out' | 'stopped' | 'never_started' | 'input' | 'network' | 'http_error' | 'unexpected_response' | (string & {});
+export type CiMode = 'preview' | 'deploy';
+export type RunStatus = 'queued' | 'running' | 'succeeded' | 'failed';
+export interface CreatePlanRequest {
+    yaml: string;
+    mode: CiMode;
+    commit: {
+        sha: string;
+        ref: string;
+        ciRunUrl: string | null;
+    };
+    /** Defaults to `[]` on the server: no mapping check. */
+    mappingTargets?: {
+        objectType: string;
+        properties: string[];
+    }[];
+}
+export interface CreatePlanResponse {
+    runId: string;
+    versionId: string;
+    /** Null for a preview, unless it reused the latest numbered version. */
+    version: number | null;
+    reused: boolean;
+}
+export interface CreateApplyResponse {
+    runId: string;
+}
+export interface ClassifiedUpdate {
+    kind: string;
+    target: string;
+    field: string;
+    repo: unknown;
+    hubspot: unknown;
+    baseline?: unknown;
+}
+export interface BlockingUpdate extends ClassifiedUpdate {
+    reason: 'no_baseline' | 'changed_in_hubspot';
+}
+export interface CiRunView {
+    id: string;
+    kind: 'plan' | 'apply';
+    status: RunStatus;
+    mode: CiMode;
+    versionId: string;
+    version: number | null;
+    /** `"{kind}:{type}"` to count, mutating actions only. Null until the plan finished. */
+    summary: Record<string, number> | null;
+    actions: {
+        kind: string;
+        type: string;
+        target: string;
+        summary: string;
+    }[];
+    conflicts: {
+        target: string;
+        field: string;
+        blueprint: unknown;
+        portal: unknown;
+        remediation: string;
+    }[];
+    warnings: string[];
+    blocking: BlockingUpdate[];
+    allowed: ClassifiedUpdate[];
+    /** `property: null` means the whole object. */
+    missingTargets: {
+        objectType: string;
+        property: string | null;
+    }[];
+    baselineInvalid: boolean;
+    appliable: boolean;
+    refusal: {
+        code: KnownErrorCode;
+        message: string;
+    } | null;
+    applyRunId: string | null;
+    error: {
+        code: KnownErrorCode;
+        message: string;
+        action?: 'plan_again' | 'reconnect';
+        runId?: string;
+    } | null;
+    finishedAt: string | null;
+}
+export interface ApiErrorBody {
+    error: {
+        code: KnownErrorCode;
+        message: string;
+        details?: unknown;
+    };
+}

package/dist/provisioning/src/api/types.js

@@ -0,0 +1,5 @@
+/**
+ * Request and response shapes of the CI API. Mirrors docs/ci-api.md; apps/web/test/server/ci/ci-contract.test.ts checks
+ * the server's types against these at typecheck time.
+ */
+export {};

package/dist/provisioning/src/cli/commands.d.ts

@@ -0,0 +1,16 @@
+import { CiClient } from '../api/client.ts';
+/** The CI calls the commands make; CiClient implements it. */
+export type CiApi = Pick<CiClient, 'createPlan' | 'getRun' | 'createApply' | 'waitForRun'>;
+export interface CliIo {
+    out: (line: string) => void;
+    err: (line: string) => void;
+    env: Record<string, string | undefined>;
+    readFile: (path: string) => Promise<string>;
+    writeFile: (path: string, text: string) => Promise<void>;
+    /** Defaults to a CiClient. `deadline` is when the command's --timeout runs out. */
+    client?: (url: string, key: string, options: {
+        deadline: Date;
+    }) => CiApi;
+}
+/** Runs one CLI command (#105). Returns the exit code (0, 1 or 2). */
+export declare function runCli(argv: string[], io: CliIo): Promise<number>;