@qawolf/ci-sdk 0.10.0

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# v0.10.0
+
+Initial release.
+
+## Supported Endpoints
+
+- `/api/deploy_success`
+- `/api/v0/ci-greenlight/[root-run-id]`

package/README.md

@@ -0,0 +1,74 @@
+# QAWolf CI SDK
+
+> :warning: This is an experimental package. Please report any
+> issues you encounter to your support channel. It should still
+> provide a better experience than using our internal GraphQL
+> API directly.
+
+This package provides a TypeScript (CSM and ESM compatible) SDK
+to interact with the QAWolf Customer-facing API.
+
+## Example: Trigger Run on Deployment
+
+```ts
+import { type DeployConfig, makeQaWolfSdk } from "@qawolf/ci-sdk";
+
+// Edit this to your needs.
+// See documentation here: https://qawolf.notion.site/cfe5a209256448a5bcd825bcf2d87e34
+const deployConfig: DeployConfig = {
+  branch: undefined,
+  commitUrl: undefined,
+  deduplicationKey: undefined,
+  deploymentType: undefined,
+  deploymentUrl: undefined,
+  hostingService: undefined,
+  sha: undefined,
+  variables: undefined,
+};
+
+const { attemptDeploy } = makeQaWolfSdk({
+  apiKey: "qawolf_xxxxx",
+});
+
+(async () => {
+  const runId = await attemptDeploy(deployConfig);
+  // Store the runId as an output of the job to be used in a CI-greenlight job.
+  // This will depend on the CI platform you are using.
+})();
+```
+
+## Example: Poll for CI Greenlight Status
+
+```ts
+import { makeQaWolfSdk } from "@qawolf/ci-sdk";
+
+const { pollCiGreenlightStatus } = makeQaWolfSdk({
+  apiKey: "qawolf_xxxxx",
+});
+
+(async () => {
+  // Retrieve runId from the previous job.
+  await pollCiGreenlightStatus({
+    runId,
+    // Optional: Callback to be called when the run stage changes.
+    // See https://qawolf.notion.site/dc42843313c246c8bf2a3a314ceb2c61 for
+    // documentation on these run stages.
+    onRunStageChanged: (current, previous) => {
+      console.log(current, previous);
+    },
+  });
+})();
+```
+
+## Versioning
+
+This package follows the [SemVer](https://semver.org/) versioning scheme. Additional notes:
+
+- Versions below 1.0.0 still follow this scheme.
+- We recommend depending on the `^` range operator for this package, as it will not introduce breaking changes and guarantee
+  an up-to-date API usage version.
+- We will provide a changelog for each release, which will be available in the [CHANGELOG.md](./CHANGELOG.md) file.
+- This package major version will be bumped when an API breaking change is introduced. This won't
+  happen too often, and we will reach out to you and give advance notice when it does.
+- Only top-level exports are considered part of the public API and covered by SemVer.
+- Addition of new fields in the API response types are not considered breaking changes.

package/dist/cjs/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./lib/sdk/index.js"), exports);

package/dist/cjs/lib/api/ci-greenlight.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchCiGreenlightStatus = void 0;
+async function fetchCiGreenlightStatus({ serviceBase, apiKey }, { runId, }, { fetch: localFetch }) {
+    try {
+        const resp = await localFetch(new URL(`/api/v0/ci-greenlight/${encodeURIComponent(runId)}`, serviceBase), {
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+            },
+        });
+        if (resp.ok) {
+            const greenlightStatus = (await resp.json());
+            return {
+                greenlightStatus,
+                httpStatus: resp.status,
+                ok: true,
+            };
+        }
+        if (resp.status === 404) {
+            return {
+                canRetry: true,
+                errorType: "not-found",
+                httpStatus: resp.status,
+                ok: false,
+            };
+        }
+        if (resp.status >= 500) {
+            return {
+                canRetry: true,
+                errorType: "server",
+                httpStatus: resp.status,
+                ok: false,
+            };
+        }
+        return {
+            canRetry: false,
+            httpStatus: resp.status,
+            ok: false,
+        };
+    }
+    catch (e) {
+        return {
+            canRetry: true,
+            errorType: "network",
+            httpStatus: 0,
+            ok: false,
+        };
+    }
+}
+exports.fetchCiGreenlightStatus = fetchCiGreenlightStatus;

package/dist/cjs/lib/api/deploy.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.postDeploySuccess = void 0;
+async function postDeploySuccess({ apiKey, serviceBase }, { branch, commitUrl, deduplicationKey, deploymentType, deploymentUrl, hostingService, sha, variables, }, { fetch: localFetch }) {
+    try {
+        const response = await localFetch(new URL("/api/webhooks/deploy_success", serviceBase), {
+            body: JSON.stringify({
+                branch,
+                commit_url: commitUrl,
+                deduplication_key: deduplicationKey,
+                deployment_type: deploymentType,
+                deployment_url: deploymentUrl,
+                hosting_service: hostingService,
+                sha,
+                variables,
+            }),
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+                "Content-Type": "application/json",
+            },
+            method: "POST",
+        });
+        if (response.ok) {
+            const { results } = (await response.json());
+            const failedTrigger = results.find((t) => !!t.failure_reason);
+            const successfulTrigger = results.find((t) => !!t.created_suite_id);
+            if (successfulTrigger == null && failedTrigger == null) {
+                return {
+                    failureReason: "no-matched-trigger",
+                    success: false,
+                };
+            }
+            if (failedTrigger) {
+                return {
+                    details: failedTrigger.failure_reason,
+                    failureReason: "run-could-not-be-created",
+                    success: false,
+                };
+            }
+            if (!successfulTrigger) {
+                return {
+                    failureReason: "no-matched-trigger",
+                    success: false,
+                };
+            }
+            const runId = successfulTrigger.created_suite_id;
+            return { runId, success: true };
+        }
+        else {
+            if (response.status >= 500) {
+                return {
+                    failureReason: "server-error",
+                    httpStatus: response.status,
+                    success: false,
+                };
+            }
+            if (response.status === 401) {
+                return {
+                    failureReason: "unauthorized",
+                    httpStatus: response.status,
+                    success: false,
+                };
+            }
+            if (response.status === 403) {
+                return {
+                    failureReason: "forbidden",
+                    httpStatus: response.status,
+                    success: false,
+                };
+            }
+            return {
+                failureReason: "unrecoverable-error",
+                httpStatus: response.status,
+                success: false,
+            };
+        }
+    }
+    catch (e) {
+        return {
+            failureReason: "network-error",
+            success: false,
+        };
+    }
+}
+exports.postDeploySuccess = postDeploySuccess;

package/dist/cjs/lib/api/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./ci-greenlight.js"), exports);
+__exportStar(require("./deploy.js"), exports);

package/dist/cjs/lib/api-types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/lib/sdk/dependencies.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/lib/sdk/domain/attempt-deploy.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.attemptDeploy = void 0;
+const deploy_js_1 = require("../../api/deploy.js");
+const utils_js_1 = require("../../utils.js");
+async function attemptDeploy(deps, apiConfig, config) {
+    const { job, log } = deps;
+    const responseState = await (0, deploy_js_1.postDeploySuccess)(apiConfig, config, deps);
+    if (!responseState.success) {
+        if (responseState.failureReason === "no-matched-trigger") {
+            log.error(`🚫 No trigger matched the request, aborting. Please contact support.`);
+        }
+        else if (responseState.failureReason === "run-could-not-be-created") {
+            log.error(`🚫 Run could not be created, aborting. Reason: "${responseState.details}". Please contact support.`);
+        }
+        else if (responseState.failureReason === "network-error")
+            log.error(`🚫 Network error from deploy_success, aborting.`);
+        else if (responseState.failureReason === "server-error")
+            log.error(`🚫 Server error from deploy_success (status ${responseState.httpStatus}), aborting. Please contact support.`);
+        else if (responseState.failureReason === "unrecoverable-error") {
+            log.error(`🚫 Unrecoverable error from deploy_success (status ${responseState.httpStatus}), aborting. Please contact support.`);
+        }
+        else if (responseState.failureReason === "forbidden") {
+            log.error(`🚫 Forbidden error from deploy_success (status ${responseState.httpStatus}), aborting. Please contact support.`);
+        }
+        else if (responseState.failureReason === "unauthorized") {
+            log.error(`🚫 Unauthorized error from deploy_success (status ${responseState.httpStatus}), aborting. Please contact support.`);
+        }
+        else {
+            (0, utils_js_1.assertType)(responseState);
+        }
+        return job.abort();
+    }
+    log.info(`✅ Run created with ID: ${responseState.runId}`);
+    return responseState.runId;
+}
+exports.attemptDeploy = attemptDeploy;

package/dist/cjs/lib/sdk/domain/poll-ci-greenlight.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pollCiGreenlightStatus = void 0;
+const utils_js_1 = require("../../utils.js");
+const ci_greenlight_js_1 = require("../../api/ci-greenlight.js");
+const safeDefaults = {
+    maxRetries: 10,
+    retryInterval: 10 * 1000,
+    runInProgressInterval: 30 * 1000,
+    runUnderReviewInterval: 60 * 1000,
+};
+async function pollCiGreenlightStatus(deps, apiConfig, { runId, onRunStageChanged: onRunStageChanged = () => void 0, ...pollConfig }) {
+    let retries = 0;
+    const { job, log } = deps;
+    const { maxRetries = safeDefaults.maxRetries, retryInterval = safeDefaults.retryInterval, runInProgressInterval = safeDefaults.runInProgressInterval, runUnderReviewInterval = safeDefaults.runUnderReviewInterval, } = pollConfig;
+    let currentStatus = undefined;
+    while (true) {
+        const responseState = await (0, ci_greenlight_js_1.fetchCiGreenlightStatus)(apiConfig, {
+            runId,
+        }, deps);
+        if (!responseState.ok && !responseState.canRetry) {
+            log.error(`🚫 Unrecoverable error (status ${responseState.httpStatus}) from CI greenlight, aborting.`);
+            return job.abort();
+        }
+        if (!responseState.ok) {
+            // This is a non-OK retryable status.
+            retries += 1;
+            if (retries > maxRetries) {
+                log.error(`🚫 Unrecoverable error ${responseState.httpStatus
+                    ? `(status ${responseState.httpStatus})`
+                    : ""} from CI greenlight, aborting after ${maxRetries} attempts.`);
+                return job.abort();
+            }
+            const { errorType, httpStatus } = responseState;
+            const retryLabel = `${httpStatus ? `(status ${httpStatus})` : ""}, will try again... (${retries}/${maxRetries})`;
+            if (errorType === "network")
+                log.warn(`❌ Network error ${retryLabel}`);
+            else if (errorType === "not-found")
+                log.info(`⏳ Run not found ${retryLabel}`);
+            else if (errorType === "server")
+                log.warn(`❌ Server error ${retryLabel}`);
+            await (0, utils_js_1.sleep)(retryInterval);
+            continue;
+        }
+        // responseState.ok === true
+        retries = 0;
+        const { greenlightStatus } = responseState;
+        const previousStatus = currentStatus;
+        currentStatus = greenlightStatus;
+        if (!previousStatus ||
+            previousStatus.runStage !== greenlightStatus.runStage)
+            try {
+                await onRunStageChanged(greenlightStatus, previousStatus);
+            }
+            catch (e) {
+                log.error(`Error in onRunStageChanged callback`, e);
+            }
+        const urlInfo = `See ${greenlightStatus.relevantRunUrl}.`;
+        const { greenlight, relevantRunId, relevantRunUrl, relevantRunWithBugsUrl, rootRunId, rootRunUrl, runStage, } = greenlightStatus;
+        if (rootRunId !== relevantRunId) {
+            log.info(`Root run was superseded:
+  - Root: ${rootRunUrl}
+  - Superseding: ${relevantRunUrl}`);
+        }
+        if (runStage === "completed") {
+            const { blockingBugsCount, blockingBugUrls = [], nonBlockingBugsCount, nonBlockingBugUrls = [], } = greenlightStatus;
+            const blockingBugList = blockingBugUrls
+                .map((url) => `\n• ${url}`)
+                .join("");
+            const nonBlockingBugList = nonBlockingBugUrls
+                .map((url) => `\n• ${url}`)
+                .join("");
+            const bugsListInText = `${blockingBugUrls.length > 0 ? `\nBLOCKING BUGS:${blockingBugList}` : ""}${nonBlockingBugUrls.length > 0
+                ? `\nNON BLOCKING BUGS:${nonBlockingBugList}`
+                : ""}`;
+            if (greenlight) {
+                log.info(`✅ Run passed and no blocking bugs found ${nonBlockingBugsCount > 0
+                    ? ` and ${nonBlockingBugsCount} non-blocking bug${(0, utils_js_1.pluralize)(nonBlockingBugsCount)} found`
+                    : ""}.\n${urlInfo}`);
+                return;
+            }
+            else {
+                log.warn(`❌ Run failed and ${blockingBugsCount} blocking bug${(0, utils_js_1.pluralize)(blockingBugsCount)} found${nonBlockingBugsCount
+                    ? ` and ${nonBlockingBugsCount} non-blocking bug${(0, utils_js_1.pluralize)(nonBlockingBugsCount)}`
+                    : ""}.\nSee ${relevantRunWithBugsUrl}\n` +
+                    "You may review the priority of certain bugs to mark these non-blocking and retry the job.\n" +
+                    bugsListInText);
+                return job.fail();
+            }
+        }
+        if (runStage === "initializing") {
+            log.info(`⏳ Run is in progress... ${urlInfo}`);
+            await (0, utils_js_1.sleep)(runInProgressInterval);
+        }
+        else if (runStage === "underReview") {
+            log.info(`🕵️  Run is under review... ${urlInfo}`);
+            await (0, utils_js_1.sleep)(runUnderReviewInterval);
+        }
+        else if (runStage === "canceled") {
+            log.info(`🚫 Run was canceled. Aborting... Please contact support.\n${urlInfo}`);
+            return job.abort();
+        }
+        else
+            throw new Error(`Unexpected run stage: ${runStage}`);
+    }
+}
+exports.pollCiGreenlightStatus = pollCiGreenlightStatus;

package/dist/cjs/lib/sdk/index.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeQaWolfSdk = void 0;
+const attempt_deploy_js_1 = require("./domain/attempt-deploy.js");
+const default_js_1 = require("./job/default.js");
+const default_js_2 = require("./log/default.js");
+const poll_ci_greenlight_js_1 = require("./domain/poll-ci-greenlight.js");
+function makeQaWolfSdk({ apiKey, serviceBase = "https://app.qawolf.com/", }, { job = default_js_1.defaultJobDriver, log = default_js_2.defaultLogDriver, fetch = globalThis.fetch, } = {}) {
+    const deps = { job, log, fetch };
+    const apiConfig = { apiKey, serviceBase };
+    return {
+        attemptDeploy: attempt_deploy_js_1.attemptDeploy.bind(null, deps, apiConfig),
+        pollCiGreenlightStatus: poll_ci_greenlight_js_1.pollCiGreenlightStatus.bind(null, deps, apiConfig),
+    };
+}
+exports.makeQaWolfSdk = makeQaWolfSdk;

package/dist/cjs/lib/sdk/job/default.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultJobDriver = void 0;
+exports.defaultJobDriver = {
+    fail() {
+        process.exit(1);
+    },
+    abort() {
+        process.exit(1);
+    },
+};

package/dist/cjs/lib/sdk/log/default.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultLogDriver = void 0;
+exports.defaultLogDriver = {
+    info(message) {
+        console.log(message);
+    },
+    warn(message) {
+        console.warn(message);
+    },
+    error(message) {
+        console.error(message);
+    },
+};

package/dist/cjs/lib/utils.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertType = exports.pluralize = exports.sleep = void 0;
+async function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+exports.sleep = sleep;
+function pluralize(count) {
+    return count === 1 ? "" : "s";
+}
+exports.pluralize = pluralize;
+/**
+ * Statically verify that provided value is assignable to a desired type
+ */
+function assertType(_value) {
+    // noop
+}
+exports.assertType = assertType;

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type": "commonjs"}

package/dist/esm/index.js

@@ -0,0 +1 @@
+export * from "./lib/sdk/index.js";

package/dist/esm/lib/api/ci-greenlight.js

@@ -0,0 +1,46 @@
+export async function fetchCiGreenlightStatus({ serviceBase, apiKey }, { runId, }, { fetch: localFetch }) {
+    try {
+        const resp = await localFetch(new URL(`/api/v0/ci-greenlight/${encodeURIComponent(runId)}`, serviceBase), {
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+            },
+        });
+        if (resp.ok) {
+            const greenlightStatus = (await resp.json());
+            return {
+                greenlightStatus,
+                httpStatus: resp.status,
+                ok: true,
+            };
+        }
+        if (resp.status === 404) {
+            return {
+                canRetry: true,
+                errorType: "not-found",
+                httpStatus: resp.status,
+                ok: false,
+            };
+        }
+        if (resp.status >= 500) {
+            return {
+                canRetry: true,
+                errorType: "server",
+                httpStatus: resp.status,
+                ok: false,
+            };
+        }
+        return {
+            canRetry: false,
+            httpStatus: resp.status,
+            ok: false,
+        };
+    }
+    catch (e) {
+        return {
+            canRetry: true,
+            errorType: "network",
+            httpStatus: 0,
+            ok: false,
+        };
+    }
+}

package/dist/esm/lib/api/deploy.js

@@ -0,0 +1,81 @@
+export async function postDeploySuccess({ apiKey, serviceBase }, { branch, commitUrl, deduplicationKey, deploymentType, deploymentUrl, hostingService, sha, variables, }, { fetch: localFetch }) {
+    try {
+        const response = await localFetch(new URL("/api/webhooks/deploy_success", serviceBase), {
+            body: JSON.stringify({
+                branch,
+                commit_url: commitUrl,
+                deduplication_key: deduplicationKey,
+                deployment_type: deploymentType,
+                deployment_url: deploymentUrl,
+                hosting_service: hostingService,
+                sha,
+                variables,
+            }),
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+                "Content-Type": "application/json",
+            },
+            method: "POST",
+        });
+        if (response.ok) {
+            const { results } = (await response.json());
+            const failedTrigger = results.find((t) => !!t.failure_reason);
+            const successfulTrigger = results.find((t) => !!t.created_suite_id);
+            if (successfulTrigger == null && failedTrigger == null) {
+                return {
+                    failureReason: "no-matched-trigger",
+                    success: false,
+                };
+            }
+            if (failedTrigger) {
+                return {
+                    details: failedTrigger.failure_reason,
+                    failureReason: "run-could-not-be-created",
+                    success: false,
+                };
+            }
+            if (!successfulTrigger) {
+                return {
+                    failureReason: "no-matched-trigger",
+                    success: false,
+                };
+            }
+            const runId = successfulTrigger.created_suite_id;
+            return { runId, success: true };
+        }
+        else {
+            if (response.status >= 500) {
+                return {
+                    failureReason: "server-error",
+                    httpStatus: response.status,
+                    success: false,
+                };
+            }
+            if (response.status === 401) {
+                return {
+                    failureReason: "unauthorized",
+                    httpStatus: response.status,
+                    success: false,
+                };
+            }
+            if (response.status === 403) {
+                return {
+                    failureReason: "forbidden",
+                    httpStatus: response.status,
+                    success: false,
+                };
+            }
+            return {
+                failureReason: "unrecoverable-error",
+                httpStatus: response.status,
+                success: false,
+            };
+        }
+    }
+    catch (e) {
+        return {
+            failureReason: "network-error",
+            success: false,
+        };
+    }
+}

package/dist/esm/lib/api/index.js

@@ -0,0 +1,2 @@
+export * from "./ci-greenlight.js";
+export * from "./deploy.js";

package/dist/esm/lib/api-types.js

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

package/dist/esm/lib/sdk/dependencies.js

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

package/dist/esm/lib/sdk/domain/attempt-deploy.js

@@ -0,0 +1,33 @@
+import { postDeploySuccess } from "../../api/deploy.js";
+import { assertType } from "../../utils.js";
+export async function attemptDeploy(deps, apiConfig, config) {
+    const { job, log } = deps;
+    const responseState = await postDeploySuccess(apiConfig, config, deps);
+    if (!responseState.success) {
+        if (responseState.failureReason === "no-matched-trigger") {
+            log.error(`🚫 No trigger matched the request, aborting. Please contact support.`);
+        }
+        else if (responseState.failureReason === "run-could-not-be-created") {
+            log.error(`🚫 Run could not be created, aborting. Reason: "${responseState.details}". Please contact support.`);
+        }
+        else if (responseState.failureReason === "network-error")
+            log.error(`🚫 Network error from deploy_success, aborting.`);
+        else if (responseState.failureReason === "server-error")
+            log.error(`🚫 Server error from deploy_success (status ${responseState.httpStatus}), aborting. Please contact support.`);
+        else if (responseState.failureReason === "unrecoverable-error") {
+            log.error(`🚫 Unrecoverable error from deploy_success (status ${responseState.httpStatus}), aborting. Please contact support.`);
+        }
+        else if (responseState.failureReason === "forbidden") {
+            log.error(`🚫 Forbidden error from deploy_success (status ${responseState.httpStatus}), aborting. Please contact support.`);
+        }
+        else if (responseState.failureReason === "unauthorized") {
+            log.error(`🚫 Unauthorized error from deploy_success (status ${responseState.httpStatus}), aborting. Please contact support.`);
+        }
+        else {
+            assertType(responseState);
+        }
+        return job.abort();
+    }
+    log.info(`✅ Run created with ID: ${responseState.runId}`);
+    return responseState.runId;
+}

package/dist/esm/lib/sdk/domain/poll-ci-greenlight.js

@@ -0,0 +1,103 @@
+import { sleep, pluralize } from "../../utils.js";
+import { fetchCiGreenlightStatus, } from "../../api/ci-greenlight.js";
+const safeDefaults = {
+    maxRetries: 10,
+    retryInterval: 10 * 1000,
+    runInProgressInterval: 30 * 1000,
+    runUnderReviewInterval: 60 * 1000,
+};
+export async function pollCiGreenlightStatus(deps, apiConfig, { runId, onRunStageChanged: onRunStageChanged = () => void 0, ...pollConfig }) {
+    let retries = 0;
+    const { job, log } = deps;
+    const { maxRetries = safeDefaults.maxRetries, retryInterval = safeDefaults.retryInterval, runInProgressInterval = safeDefaults.runInProgressInterval, runUnderReviewInterval = safeDefaults.runUnderReviewInterval, } = pollConfig;
+    let currentStatus = undefined;
+    while (true) {
+        const responseState = await fetchCiGreenlightStatus(apiConfig, {
+            runId,
+        }, deps);
+        if (!responseState.ok && !responseState.canRetry) {
+            log.error(`🚫 Unrecoverable error (status ${responseState.httpStatus}) from CI greenlight, aborting.`);
+            return job.abort();
+        }
+        if (!responseState.ok) {
+            // This is a non-OK retryable status.
+            retries += 1;
+            if (retries > maxRetries) {
+                log.error(`🚫 Unrecoverable error ${responseState.httpStatus
+                    ? `(status ${responseState.httpStatus})`
+                    : ""} from CI greenlight, aborting after ${maxRetries} attempts.`);
+                return job.abort();
+            }
+            const { errorType, httpStatus } = responseState;
+            const retryLabel = `${httpStatus ? `(status ${httpStatus})` : ""}, will try again... (${retries}/${maxRetries})`;
+            if (errorType === "network")
+                log.warn(`❌ Network error ${retryLabel}`);
+            else if (errorType === "not-found")
+                log.info(`⏳ Run not found ${retryLabel}`);
+            else if (errorType === "server")
+                log.warn(`❌ Server error ${retryLabel}`);
+            await sleep(retryInterval);
+            continue;
+        }
+        // responseState.ok === true
+        retries = 0;
+        const { greenlightStatus } = responseState;
+        const previousStatus = currentStatus;
+        currentStatus = greenlightStatus;
+        if (!previousStatus ||
+            previousStatus.runStage !== greenlightStatus.runStage)
+            try {
+                await onRunStageChanged(greenlightStatus, previousStatus);
+            }
+            catch (e) {
+                log.error(`Error in onRunStageChanged callback`, e);
+            }
+        const urlInfo = `See ${greenlightStatus.relevantRunUrl}.`;
+        const { greenlight, relevantRunId, relevantRunUrl, relevantRunWithBugsUrl, rootRunId, rootRunUrl, runStage, } = greenlightStatus;
+        if (rootRunId !== relevantRunId) {
+            log.info(`Root run was superseded:
+  - Root: ${rootRunUrl}
+  - Superseding: ${relevantRunUrl}`);
+        }
+        if (runStage === "completed") {
+            const { blockingBugsCount, blockingBugUrls = [], nonBlockingBugsCount, nonBlockingBugUrls = [], } = greenlightStatus;
+            const blockingBugList = blockingBugUrls
+                .map((url) => `\n• ${url}`)
+                .join("");
+            const nonBlockingBugList = nonBlockingBugUrls
+                .map((url) => `\n• ${url}`)
+                .join("");
+            const bugsListInText = `${blockingBugUrls.length > 0 ? `\nBLOCKING BUGS:${blockingBugList}` : ""}${nonBlockingBugUrls.length > 0
+                ? `\nNON BLOCKING BUGS:${nonBlockingBugList}`
+                : ""}`;
+            if (greenlight) {
+                log.info(`✅ Run passed and no blocking bugs found ${nonBlockingBugsCount > 0
+                    ? ` and ${nonBlockingBugsCount} non-blocking bug${pluralize(nonBlockingBugsCount)} found`
+                    : ""}.\n${urlInfo}`);
+                return;
+            }
+            else {
+                log.warn(`❌ Run failed and ${blockingBugsCount} blocking bug${pluralize(blockingBugsCount)} found${nonBlockingBugsCount
+                    ? ` and ${nonBlockingBugsCount} non-blocking bug${pluralize(nonBlockingBugsCount)}`
+                    : ""}.\nSee ${relevantRunWithBugsUrl}\n` +
+                    "You may review the priority of certain bugs to mark these non-blocking and retry the job.\n" +
+                    bugsListInText);
+                return job.fail();
+            }
+        }
+        if (runStage === "initializing") {
+            log.info(`⏳ Run is in progress... ${urlInfo}`);
+            await sleep(runInProgressInterval);
+        }
+        else if (runStage === "underReview") {
+            log.info(`🕵️  Run is under review... ${urlInfo}`);
+            await sleep(runUnderReviewInterval);
+        }
+        else if (runStage === "canceled") {
+            log.info(`🚫 Run was canceled. Aborting... Please contact support.\n${urlInfo}`);
+            return job.abort();
+        }
+        else
+            throw new Error(`Unexpected run stage: ${runStage}`);
+    }
+}

package/dist/esm/lib/sdk/index.js

@@ -0,0 +1,12 @@
+import { attemptDeploy } from "./domain/attempt-deploy.js";
+import { defaultJobDriver } from "./job/default.js";
+import { defaultLogDriver } from "./log/default.js";
+import { pollCiGreenlightStatus } from "./domain/poll-ci-greenlight.js";
+export function makeQaWolfSdk({ apiKey, serviceBase = "https://app.qawolf.com/", }, { job = defaultJobDriver, log = defaultLogDriver, fetch = globalThis.fetch, } = {}) {
+    const deps = { job, log, fetch };
+    const apiConfig = { apiKey, serviceBase };
+    return {
+        attemptDeploy: attemptDeploy.bind(null, deps, apiConfig),
+        pollCiGreenlightStatus: pollCiGreenlightStatus.bind(null, deps, apiConfig),
+    };
+}

package/dist/esm/lib/sdk/job/default.js

@@ -0,0 +1,8 @@
+export const defaultJobDriver = {
+    fail() {
+        process.exit(1);
+    },
+    abort() {
+        process.exit(1);
+    },
+};

package/dist/esm/lib/sdk/log/default.js

@@ -0,0 +1,11 @@
+export const defaultLogDriver = {
+    info(message) {
+        console.log(message);
+    },
+    warn(message) {
+        console.warn(message);
+    },
+    error(message) {
+        console.error(message);
+    },
+};

package/dist/esm/lib/utils.js

@@ -0,0 +1,12 @@
+export async function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export function pluralize(count) {
+    return count === 1 ? "" : "s";
+}
+/**
+ * Statically verify that provided value is assignable to a desired type
+ */
+export function assertType(_value) {
+    // noop
+}

package/dist/esm/package.json

@@ -0,0 +1 @@
+{"type": "module"}

package/dist/types/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./lib/sdk/index.js";
+export type { CiGreenlightStatus, CiGreenlightStatusBase, DeployConfig, DeployStatus, } from "./lib/api/index.js";

package/dist/types/lib/api/ci-greenlight.d.ts

@@ -0,0 +1,60 @@
+import { ApiConfig } from "../api-types.js";
+import { SdkDependencies } from "../sdk/dependencies.js";
+export type CiGreenlightStatusBase = {
+    relevantRunId: string;
+    relevantRunUrl: string;
+    relevantRunWithBugsUrl: string;
+    rootRunId: string;
+    rootRunUrl: string;
+    workflowsDisabledAfterRunCount: number;
+    workflowsInRunCount: number;
+    workflowsUnderInvestigationCount: number;
+};
+/**
+ * The status of a CI greenlight run. See the API documentation here for
+ * more details: https://qawolf.notion.site/dc42843313c246c8bf2a3a314ceb2c61
+ */
+export type CiGreenlightStatus = CiGreenlightStatusBase & ({
+    blockingBugsCount: number;
+    blockingBugUrls: string[];
+    greenlight: boolean;
+    nonBlockingBugsCount: number;
+    nonBlockingBugUrls: string[];
+    runStage: "completed";
+} | {
+    greenlight: false;
+    runStage: "initializing" | "underReview" | "canceled";
+});
+export declare function fetchCiGreenlightStatus({ serviceBase, apiKey }: ApiConfig, { runId, }: {
+    runId: string;
+}, { fetch: localFetch }: SdkDependencies): Promise<{
+    readonly greenlightStatus: CiGreenlightStatus;
+    readonly httpStatus: number;
+    readonly ok: true;
+    readonly canRetry?: never;
+    readonly errorType?: never;
+} | {
+    readonly canRetry: true;
+    readonly errorType: "not-found";
+    readonly httpStatus: 404;
+    readonly ok: false;
+    readonly greenlightStatus?: never;
+} | {
+    readonly canRetry: true;
+    readonly errorType: "server";
+    readonly httpStatus: number;
+    readonly ok: false;
+    readonly greenlightStatus?: never;
+} | {
+    readonly canRetry: false;
+    readonly httpStatus: number;
+    readonly ok: false;
+    readonly greenlightStatus?: never;
+    readonly errorType?: never;
+} | {
+    readonly canRetry: true;
+    readonly errorType: "network";
+    readonly httpStatus: 0;
+    readonly ok: false;
+    readonly greenlightStatus?: never;
+}>;

package/dist/types/lib/api/deploy.d.ts

@@ -0,0 +1,67 @@
+import { ApiConfig } from "../api-types.js";
+import { SdkDependencies } from "../sdk/dependencies.js";
+export type DeployConfig = {
+    branch: string | undefined;
+    commitUrl: string | undefined;
+    deduplicationKey: string | undefined;
+    deploymentType: string | undefined;
+    deploymentUrl: string | undefined;
+    hostingService: string | undefined;
+    sha: string | undefined;
+    variables: Record<string, string> | undefined;
+};
+export type DeployStatus = {
+    results: Array<{
+        created_suite_id?: string;
+        failure_reason?: string;
+    }>;
+};
+export declare function postDeploySuccess({ apiKey, serviceBase }: ApiConfig, { branch, commitUrl, deduplicationKey, deploymentType, deploymentUrl, hostingService, sha, variables, }: Partial<DeployConfig>, { fetch: localFetch }: SdkDependencies): Promise<{
+    readonly failureReason: "no-matched-trigger";
+    readonly success: false;
+    readonly details?: never;
+    readonly runId?: never;
+    readonly httpStatus?: never;
+} | {
+    readonly details: string;
+    readonly failureReason: "run-could-not-be-created";
+    readonly success: false;
+    readonly runId?: never;
+    readonly httpStatus?: never;
+} | {
+    readonly runId: string;
+    readonly success: true;
+    readonly failureReason?: never;
+    readonly details?: never;
+    readonly httpStatus?: never;
+} | {
+    readonly failureReason: "server-error";
+    readonly httpStatus: number;
+    readonly success: false;
+    readonly details?: never;
+    readonly runId?: never;
+} | {
+    readonly failureReason: "unauthorized";
+    readonly httpStatus: 401;
+    readonly success: false;
+    readonly details?: never;
+    readonly runId?: never;
+} | {
+    readonly failureReason: "forbidden";
+    readonly httpStatus: 403;
+    readonly success: false;
+    readonly details?: never;
+    readonly runId?: never;
+} | {
+    readonly failureReason: "unrecoverable-error";
+    readonly httpStatus: number;
+    readonly success: false;
+    readonly details?: never;
+    readonly runId?: never;
+} | {
+    readonly failureReason: "network-error";
+    readonly success: false;
+    readonly details?: never;
+    readonly runId?: never;
+    readonly httpStatus?: never;
+}>;

package/dist/types/lib/api/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./ci-greenlight.js";
+export * from "./deploy.js";

package/dist/types/lib/api-types.d.ts

@@ -0,0 +1,4 @@
+export type ApiConfig = {
+    apiKey: string;
+    serviceBase: string;
+};

package/dist/types/lib/sdk/dependencies.d.ts

@@ -0,0 +1,28 @@
+export interface JobDriver {
+    /**
+     * Called only when job completed and failed.
+     * **This method must exit the process or throw**.
+     */
+    fail(): Promise<never>;
+    /**
+     * Called anywhere the job cannot continue and has to
+     * be aborted. **This method must exit the process or throw**.
+     *
+     * The main difference with "fail" is its semantics. For
+     * jobs performing tests, "fail" is called when the job
+     * completed and the tests yield a negative result.
+     * "abort" is called when the job could not complete.
+     */
+    abort(): Promise<never>;
+}
+export interface LogDriver {
+    info(...messages: unknown[]): void;
+    warn(...messages: unknown[]): void;
+    error(...messages: unknown[]): void;
+}
+export type FetchDriver = typeof fetch;
+export type SdkDependencies = {
+    job: JobDriver;
+    log: LogDriver;
+    fetch: FetchDriver;
+};

package/dist/types/lib/sdk/domain/attempt-deploy.d.ts

@@ -0,0 +1,4 @@
+import { DeployConfig } from "../../api/deploy.js";
+import { SdkDependencies } from "../dependencies.js";
+import { ApiConfig } from "../../api-types.js";
+export declare function attemptDeploy(deps: SdkDependencies, apiConfig: ApiConfig, config: Partial<DeployConfig>): Promise<string>;

package/dist/types/lib/sdk/domain/poll-ci-greenlight.d.ts

@@ -0,0 +1,17 @@
+import { CiGreenlightStatus } from "../../api/ci-greenlight.js";
+import { ApiConfig } from "../../api-types.js";
+import { SdkDependencies } from "../dependencies.js";
+export type PollConfig = {
+    maxRetries: number;
+    retryInterval: number;
+    runInProgressInterval: number;
+    runUnderReviewInterval: number;
+};
+export type PollCiGreenlightParams = {
+    runId: string;
+    /**
+     * Callback to be called when the lifecycle stage of the run changes.
+     */
+    onRunStageChanged?: (current: CiGreenlightStatus, previous: CiGreenlightStatus | undefined) => unknown | Promise<unknown>;
+} & Partial<PollConfig>;
+export declare function pollCiGreenlightStatus(deps: SdkDependencies, apiConfig: ApiConfig, { runId, onRunStageChanged: onRunStageChanged, ...pollConfig }: PollCiGreenlightParams): Promise<undefined>;

package/dist/types/lib/sdk/index.d.ts

@@ -0,0 +1,8 @@
+import { SdkDependencies } from "./dependencies.js";
+export declare function makeQaWolfSdk({ apiKey, serviceBase, }: {
+    apiKey: string;
+    serviceBase?: string;
+}, { job, log, fetch, }?: Partial<SdkDependencies>): {
+    attemptDeploy: (config: Partial<import("../api/deploy.js").DeployConfig>) => Promise<string>;
+    pollCiGreenlightStatus: (args_0: import("./domain/poll-ci-greenlight.js").PollCiGreenlightParams) => Promise<undefined>;
+};

package/dist/types/lib/sdk/job/default.d.ts

@@ -0,0 +1,2 @@
+import { type JobDriver } from "../dependencies.js";
+export declare const defaultJobDriver: JobDriver;

package/dist/types/lib/sdk/log/default.d.ts

@@ -0,0 +1,2 @@
+import { LogDriver } from "../dependencies.js";
+export declare const defaultLogDriver: LogDriver;

package/dist/types/lib/utils.d.ts

@@ -0,0 +1,6 @@
+export declare function sleep(ms: number): Promise<unknown>;
+export declare function pluralize(count: number): "" | "s";
+/**
+ * Statically verify that provided value is assignable to a desired type
+ */
+export declare function assertType<Type>(_value: Type): void;

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@qawolf/ci-sdk",
+  "version": "0.10.0",
+  "description": "A simple SDK for interacting with QAWolf in CI scripts.",
+  "type": "module",
+  "private": false,
+  "exports": {
+    "require": "./dist/cjs/index.js",
+    "import": "./dist/esm/index.js",
+    "default": "./dist/esm/index.js",
+    "types": "./dist/types/index.d.ts"
+  },
+  "main": "cjs/index.js",
+  "scripts": {
+    "build": "./scripts/build.sh",
+    "test": "jest",
+    "prepare": "npm run build"
+  },
+  "keywords": [],
+  "author": "Jules Sam. Randolph<jules@qawolf.com>",
+  "license": "MIT",
+  "engines": {
+    "node": ">= 16"
+  },
+  "devDependencies": {
+    "@jest/globals": "^29.7.0",
+    "@tsconfig/strictest": "^2.0.5",
+    "@types/node": "^20.12.2",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.2",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.4.3"
+  }
+}