@qawolf/ci-sdk 0.12.0 → 0.13.0

package/README.md

@@ -17,11 +17,12 @@ to determine the status of your CI/CD step/job/action.
 
 ## Example: Trigger Run on Deployment
 
+> ℹ️ [See the API documentation page for this endpoint](https://qawolf.notion.site/dd72e46ceb7f451dae4e9ef06f64a2cc).
+
 ```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,
@@ -51,6 +52,8 @@ const { attemptNotifyDeploy } = makeQaWolfSdk({
 
 ## Example: Poll for CI Greenlight Status
 
+> ℹ️ [See the API documentation page for this endpoint](https://qawolf.notion.site/1b170576efea411fa785842a71e7c99e).
+
 ```ts
 import { makeQaWolfSdk } from "@qawolf/ci-sdk";
 
@@ -63,7 +66,7 @@ const { pollCiGreenlightStatus } = makeQaWolfSdk({
   const { outcome } = await pollCiGreenlightStatus({
     runId,
     // Optional: Callback to be called when the run stage changes.
-    // See https://qawolf.notion.site/dc42843313c246c8bf2a3a314ceb2c61 for
+    // See https://qawolf.notion.site/1b170576efea411fa785842a71e7c99e for
     // documentation on these run stages.
     onRunStageChanged: (current, previous) => {
       console.log(current, previous);
@@ -86,10 +89,71 @@ This package follows the [SemVer](https://semver.org/) versioning scheme. Additi
 
 - 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.
+an up-to-date API usage version.
+<!-- There is a limitation in NPM preventing us from using relative links and hosting other MD files when the repository hosting code is not
+  public, hence we inline the changelog in the README. See https://github.com/npm/feedback/discussions/666 -->
+- We will provide a changelog for each release, which will be available in the Changelog section below.
 - 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.
 - Logs and debug messages are not considered part of the public API and can change at any time.
+
+# Changelog
+
+## v0.13.0
+
+- New `pollTimeout` parameter for `pollCiGreenlightStatus` to allow for a custom
+  timeout in milliseconds for the polling operation. It now defaults to two hours.
+- New `abortReason` and `httpStatus` fields added to the `PollCiGreenlightStatus` type
+  with `"aborted"` outcome to provide more context on why the poll was aborted.
+
+## v0.12.1
+
+- Export dependencies types from root module.
+- Refine `DeployConfig.hostingService` type to match API requirements.
+- Fix inaccessible changelog file from NPM.
+
+## v0.12.0
+
+- Define a more restrictive `LogDriver` interface for easy integration with GHA
+  `core` interface.
+
+## v0.11.0
+
+- Support `reproducedBugs` field from CI-greenlight API.
+
+> :warning: These are the last breaking changes brought to the 0.x major version.
+> These are being introduced while the SDK hasn't been advertised to the public yet.
+> Future changes will follow the SemVer versioning scheme.
+
+BREAKING CHANGES:
+
+- `pollCiGreenlightStatus` and `attemptNotifyDeploy` now return a "result" object
+  with an `outcome` field that can be either `"success"`, `"failed"` or `"aborted"`,
+  instead of exiting the process with a non-zero code. This will provide more
+  flexibility to the user to decide how to handle the outcome.
+
+## v0.10.3
+
+BREAKING CHANGES:
+
+- Renamed `attemptDeploy` to `attemptNotifyDeploy`.
+
+## v0.10.2
+
+- Avoid logging dots after URL names in the logs. Dots can confuse terminal
+  URL detection.
+
+## v0.10.1
+
+- Fix TypeScript types visibility.
+
+## v0.10.0
+
+Initial release.
+
+### Supported Endpoints
+
+- `/api/deploy_success`
+- `/api/v0/ci-greenlight/[root-run-id]`

package/dist/cjs/index.js

@@ -15,3 +15,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./lib/sdk/index.js"), exports);
+__exportStar(require("./lib/sdk/dependencies.js"), exports);

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

@@ -3,24 +3,33 @@ 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");
+// If you change these values, make sure you update the JSDoc
+// comments in the PollConfig type.
 const safeDefaults = {
     maxRetries: 10,
     retryInterval: 10 * 1000,
     runInProgressInterval: 30 * 1000,
     runUnderReviewInterval: 60 * 1000,
+    pollTimeout: 120 * 60 * 1000,
 };
 async function pollCiGreenlightStatus(deps, apiConfig, { runId, onRunStageChanged: onRunStageChanged = () => void 0, ...pollConfig }) {
     let retries = 0;
     const { log } = deps;
-    const { maxRetries = safeDefaults.maxRetries, retryInterval = safeDefaults.retryInterval, runInProgressInterval = safeDefaults.runInProgressInterval, runUnderReviewInterval = safeDefaults.runUnderReviewInterval, } = pollConfig;
+    const { maxRetries = safeDefaults.maxRetries, retryInterval = safeDefaults.retryInterval, runInProgressInterval = safeDefaults.runInProgressInterval, runUnderReviewInterval = safeDefaults.runUnderReviewInterval, pollTimeout = safeDefaults.pollTimeout, } = pollConfig;
     let currentStatus = undefined;
-    while (true) {
+    const startedAt = Date.now();
+    let hasTimedOut = false;
+    while (!(hasTimedOut = Date.now() - startedAt > pollTimeout)) {
         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 { outcome: "aborted" };
+            return {
+                outcome: "aborted",
+                abortReason: "4XX-client-error",
+                httpStatus: responseState.httpStatus,
+            };
         }
         if (!responseState.ok) {
             // This is a non-OK retryable status.
@@ -29,7 +38,24 @@ async function pollCiGreenlightStatus(deps, apiConfig, { runId, onRunStageChange
                 log.error(`🚫 Unrecoverable error${responseState.httpStatus
                     ? ` (status ${responseState.httpStatus})`
                     : ""} from CI greenlight, aborting after ${maxRetries} attempts.`);
-                return { outcome: "aborted" };
+                if (responseState.errorType === "network")
+                    return {
+                        outcome: "aborted",
+                        abortReason: "network-error",
+                        httpStatus: undefined,
+                    };
+                let abortReason = "XXX-other-http-code";
+                if (responseState.errorType === "not-found")
+                    abortReason = "404-run-not-found";
+                else if (responseState.errorType === "server")
+                    abortReason = "5XX-server-error";
+                else
+                    (0, utils_js_1.assertType)(responseState);
+                return {
+                    outcome: "aborted",
+                    abortReason,
+                    httpStatus: responseState.httpStatus,
+                };
             }
             const { errorType, httpStatus } = responseState;
             const retryLabel = `${httpStatus ? ` (status ${httpStatus})` : ""}, will try again... (${retries}/${maxRetries})`;
@@ -88,6 +114,23 @@ async function pollCiGreenlightStatus(deps, apiConfig, { runId, onRunStageChange
                 return { outcome: "failed", greenlightStatus };
             }
         }
+        if (runStage === "canceled") {
+            log.info(`🚫 Run was canceled. Aborting... Please contact support.\n${urlInfo}`);
+            return {
+                outcome: "aborted",
+                abortReason: "run-canceled",
+                httpStatus: undefined,
+            };
+        }
+        // Non-terminal run stages
+        if (hasTimedOut) {
+            log.warn(`❌ Poll timed out after ${pollTimeout / 1000}s. Aborting...`);
+            return {
+                outcome: "aborted",
+                abortReason: "poll-timed-out",
+                httpStatus: undefined,
+            };
+        }
         if (runStage === "initializing") {
             log.info(`⏳ Run is in progress... ${urlInfo}`);
             await (0, utils_js_1.sleep)(runInProgressInterval);
@@ -96,12 +139,16 @@ async function pollCiGreenlightStatus(deps, apiConfig, { runId, onRunStageChange
             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 { outcome: "aborted" };
-        }
-        else
+        else {
+            (0, utils_js_1.assertType)(runStage);
             throw new Error(`Unexpected run stage: ${runStage}`);
+        }
     }
+    log.warn(`❌ Poll timed out after ${pollTimeout / 1000}s. Aborting...`);
+    return {
+        outcome: "aborted",
+        abortReason: "poll-timed-out",
+        httpStatus: undefined,
+    };
 }
 exports.pollCiGreenlightStatus = pollCiGreenlightStatus;

package/dist/esm/index.js

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

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

@@ -1,23 +1,32 @@
-import { sleep, pluralize } from "../../utils.js";
+import { sleep, pluralize, assertType } from "../../utils.js";
 import { fetchCiGreenlightStatus, } from "../../api/ci-greenlight.js";
+// If you change these values, make sure you update the JSDoc
+// comments in the PollConfig type.
 const safeDefaults = {
     maxRetries: 10,
     retryInterval: 10 * 1000,
     runInProgressInterval: 30 * 1000,
     runUnderReviewInterval: 60 * 1000,
+    pollTimeout: 120 * 60 * 1000,
 };
 export async function pollCiGreenlightStatus(deps, apiConfig, { runId, onRunStageChanged: onRunStageChanged = () => void 0, ...pollConfig }) {
     let retries = 0;
     const { log } = deps;
-    const { maxRetries = safeDefaults.maxRetries, retryInterval = safeDefaults.retryInterval, runInProgressInterval = safeDefaults.runInProgressInterval, runUnderReviewInterval = safeDefaults.runUnderReviewInterval, } = pollConfig;
+    const { maxRetries = safeDefaults.maxRetries, retryInterval = safeDefaults.retryInterval, runInProgressInterval = safeDefaults.runInProgressInterval, runUnderReviewInterval = safeDefaults.runUnderReviewInterval, pollTimeout = safeDefaults.pollTimeout, } = pollConfig;
     let currentStatus = undefined;
-    while (true) {
+    const startedAt = Date.now();
+    let hasTimedOut = false;
+    while (!(hasTimedOut = Date.now() - startedAt > pollTimeout)) {
         const responseState = await fetchCiGreenlightStatus(apiConfig, {
             runId,
         }, deps);
         if (!responseState.ok && !responseState.canRetry) {
             log.error(`🚫 Unrecoverable error (status ${responseState.httpStatus}) from CI greenlight, aborting.`);
-            return { outcome: "aborted" };
+            return {
+                outcome: "aborted",
+                abortReason: "4XX-client-error",
+                httpStatus: responseState.httpStatus,
+            };
         }
         if (!responseState.ok) {
             // This is a non-OK retryable status.
@@ -26,7 +35,24 @@ export async function pollCiGreenlightStatus(deps, apiConfig, { runId, onRunStag
                 log.error(`🚫 Unrecoverable error${responseState.httpStatus
                     ? ` (status ${responseState.httpStatus})`
                     : ""} from CI greenlight, aborting after ${maxRetries} attempts.`);
-                return { outcome: "aborted" };
+                if (responseState.errorType === "network")
+                    return {
+                        outcome: "aborted",
+                        abortReason: "network-error",
+                        httpStatus: undefined,
+                    };
+                let abortReason = "XXX-other-http-code";
+                if (responseState.errorType === "not-found")
+                    abortReason = "404-run-not-found";
+                else if (responseState.errorType === "server")
+                    abortReason = "5XX-server-error";
+                else
+                    assertType(responseState);
+                return {
+                    outcome: "aborted",
+                    abortReason,
+                    httpStatus: responseState.httpStatus,
+                };
             }
             const { errorType, httpStatus } = responseState;
             const retryLabel = `${httpStatus ? ` (status ${httpStatus})` : ""}, will try again... (${retries}/${maxRetries})`;
@@ -85,6 +111,23 @@ export async function pollCiGreenlightStatus(deps, apiConfig, { runId, onRunStag
                 return { outcome: "failed", greenlightStatus };
             }
         }
+        if (runStage === "canceled") {
+            log.info(`🚫 Run was canceled. Aborting... Please contact support.\n${urlInfo}`);
+            return {
+                outcome: "aborted",
+                abortReason: "run-canceled",
+                httpStatus: undefined,
+            };
+        }
+        // Non-terminal run stages
+        if (hasTimedOut) {
+            log.warn(`❌ Poll timed out after ${pollTimeout / 1000}s. Aborting...`);
+            return {
+                outcome: "aborted",
+                abortReason: "poll-timed-out",
+                httpStatus: undefined,
+            };
+        }
         if (runStage === "initializing") {
             log.info(`⏳ Run is in progress... ${urlInfo}`);
             await sleep(runInProgressInterval);
@@ -93,11 +136,15 @@ export async function pollCiGreenlightStatus(deps, apiConfig, { runId, onRunStag
             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 { outcome: "aborted" };
-        }
-        else
+        else {
+            assertType(runStage);
             throw new Error(`Unexpected run stage: ${runStage}`);
+        }
     }
+    log.warn(`❌ Poll timed out after ${pollTimeout / 1000}s. Aborting...`);
+    return {
+        outcome: "aborted",
+        abortReason: "poll-timed-out",
+        httpStatus: undefined,
+    };
 }

package/dist/types/index.d.ts

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

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

@@ -64,7 +64,7 @@ export type CiGreenlightStatusBase = {
 };
 /**
  * The status of a CI greenlight run. See the API documentation here for
- * more details: https://qawolf.notion.site/dc42843313c246c8bf2a3a314ceb2c61
+ * more details: https://qawolf.notion.site/1b170576efea411fa785842a71e7c99e
  */
 export type CiGreenlightStatus = CiGreenlightStatusBase & ({
     blockingBugsCount: number;

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

@@ -1,12 +1,16 @@
 import { ApiConfig } from "../api-types.js";
 import { SdkDependencies } from "../sdk/dependencies.js";
+/**
+ * Refer to our official documentation for more information:
+ * https://qawolf.notion.site/dd72e46ceb7f451dae4e9ef06f64a2cc
+ */
 export type DeployConfig = {
     branch: string | undefined;
     commitUrl: string | undefined;
     deduplicationKey: string | undefined;
     deploymentType: string | undefined;
     deploymentUrl: string | undefined;
-    hostingService: string | undefined;
+    hostingService: "GitHub" | "GitLab" | undefined;
     sha: string | undefined;
     variables: Record<string, string> | undefined;
 };

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

@@ -2,11 +2,40 @@ import { CiGreenlightStatus } from "../../api/ci-greenlight.js";
 import { ApiConfig } from "../../api-types.js";
 import { SdkDependencies } from "../dependencies.js";
 export type PollConfig = {
+    /**
+     * Maximum number of network operations retries before aborting the job.
+     *
+     * @default 10
+     */
     maxRetries: number;
+    /**
+     * Interval in milliseconds between network operations retries.
+     *
+     * @default 10 seconds
+     */
     retryInterval: number;
+    /**
+     * Interval in milliseconds between polling for a run in progress.
+     *
+     * @default 30 seconds
+     */
     runInProgressInterval: number;
+    /**
+     * Interval in milliseconds between polling for a run under review.
+     *
+     * @default 60 minutes
+     */
     runUnderReviewInterval: number;
+    /**
+     * Timeout in milliseconds before aborting this polling operation.
+     *
+     * @default 120 minutes
+     */
+    pollTimeout: number;
 };
+export type HttpRelatedAbortReason = "4XX-client-error" | "404-run-not-found" | "5XX-server-error" | "XXX-other-http-code";
+export type NonHttpRelatedAbortReason = "poll-timed-out" | "run-canceled" | "network-error";
+export type AbortReason = NonHttpRelatedAbortReason | HttpRelatedAbortReason;
 export type PollCiGreenlightStatus = {
     /**
      * No blocking bugs were found in the run.
@@ -28,6 +57,15 @@ export type PollCiGreenlightStatus = {
      * The run was aborted due to an unrecoverable error.
      */
     outcome: "aborted";
+    abortReason: HttpRelatedAbortReason;
+    httpStatus: number;
+} | {
+    /**
+     * The run was aborted due to an unrecoverable error.
+     */
+    outcome: "aborted";
+    abortReason: NonHttpRelatedAbortReason;
+    httpStatus: undefined;
 };
 export type PollCiGreenlightParams = {
     runId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qawolf/ci-sdk",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "A simple SDK for interacting with QAWolf in CI scripts.",
   "type": "module",
   "private": false,
@@ -15,7 +15,8 @@
     "build": "./scripts/build.sh",
     "test": "jest",
     "prepare": "npm run build",
-    "publish": "./scripts/publish.sh"
+    "npm-publish": "./scripts/publish.sh",
+    "tsc:check": "tsc --noEmit"
   },
   "keywords": [],
   "author": "Jules Sam. Randolph<jules@qawolf.com>",

package/CHANGELOG.md

@@ -1,43 +0,0 @@
-# v0.12.0
-
-- Define a more restrictive `LogDriver` interface for easy integration with GHA
-  `core` interface.
-
-# v0.11.0
-
-- Support `reproducedBugs` field from CI-greenlight API.
-
-> :warning: These are the last breaking changes brought to the 0.x major version.
-> These are being introduced while the SDK hasn't been advertised to the public yet.
-> Future changes will follow the SemVer versioning scheme.
-
-BREAKING CHANGES:
-
-- `pollCiGreenlightStatus` and `attemptNotifyDeploy` now return a "result" object
-  with an `outcome` field that can be either `"success"`, `"failed"` or `"aborted"`,
-  instead of exiting the process with a non-zero code. This will provide more
-  flexibility to the user to decide how to handle the outcome.
-
-# v0.10.3
-
-BREAKING CHANGES:
-
-- Renamed `attemptDeploy` to `attemptNotifyDeploy`.
-
-# v0.10.2
-
-- Avoid logging dots after URL names in the logs. Dots can confuse terminal
-  URL detection.
-
-# v0.10.1
-
-- Fix TypeScript types visibility.
-
-# v0.10.0
-
-Initial release.
-
-## Supported Endpoints
-
-- `/api/deploy_success`
-- `/api/v0/ci-greenlight/[root-run-id]`