@qawolf/ci-sdk 1.1.1 → 1.3.0

package/README.md

@@ -14,6 +14,8 @@ to determine the status of your CI/CD step/job/action.
 - [Notify Deployment](#notify-deployment)
 - [Notify Preview Deployment (Pull Request / Merge Request Testing)](#notify-preview)
 - [Poll for CI Greenlight Status](#ci-greenlight)
+- [Advanced: Poll with Custom Control (Iterator)](#ci-greenlight-iterator)
+- [Notify a Terminated Ephemeral Environment](#notify-terminated-ephemeral-environment)
 - [Upload Run Input Artifacts](#upload-artifacts)
 - [Requirements](#requirements)
 - [Versioning](#versioning)
@@ -180,6 +182,174 @@ const { pollCiGreenlightStatus } = makeQaWolfSdk({
 })();
 ```
 
+<a id="ci-greenlight-iterator"></a>
+
+## Advanced: Poll with Custom Control (Iterator)
+
+For advanced use cases where you need fine-grained control over the polling lifecycle, use `makePollCiGreenlightStatusIterator`. This async generator gives you full control to implement custom logic such as:
+
+- Stop polling early based on time limits (e.g., "wait max 10 minutes in review then proceed")
+- Stop polling based on bug counts (e.g., "proceed if only 3 or fewer blocking bugs")
+- Implement custom logging or monitoring at each poll iteration
+- Access detailed bug data during the "under review" stage
+
+> ℹ️ [See the API documentation page for this endpoint](https://qawolf.notion.site/1b170576efea411fa785842a71e7c99e).
+
+### Example: Early Exit with Custom Logic
+
+> ⚠️ **Important**: When using the iterator, ensure you handle all run stages in your switch statement. The `default` case with `satisfies never` provides compile-time safety - if a new stage is added, TypeScript will error. This prevents silently passing your CI job while ignoring error conditions.
+
+```ts
+import { makeQaWolfSdk } from "@qawolf/ci-sdk";
+
+const { makePollCiGreenlightStatusIterator } = makeQaWolfSdk({
+  apiKey: "qawolf_xxxxx",
+});
+
+(async () => {
+  let underReviewStartTime: number | null = null;
+
+  const iterator = makePollCiGreenlightStatusIterator({
+    runId: "your-run-id",
+  });
+
+  for await (const iteration of iterator) {
+    // Check if the iterator yielded an abort result
+    if (iteration.isAborted) {
+      console.error(`Poll aborted: ${iteration.abortReason}`);
+      process.exit(1);
+    }
+
+    // Handle status iterations
+    const { status, stageChanged } = iteration;
+
+    switch (status.runStage) {
+      case "initializing":
+        console.log(`Run stage: ${status.runStage}`);
+        break;
+
+      case "underReview": {
+        // Track when we first enter underReview
+        if (stageChanged) {
+          underReviewStartTime = Date.now();
+          console.log(`Run stage: ${status.runStage}`);
+        }
+
+        const timeInUnderReview = underReviewStartTime
+          ? Date.now() - underReviewStartTime
+          : 0;
+
+        // Option 1: Stop after 10 minutes in review
+        if (timeInUnderReview > 10 * 60 * 1000) {
+          console.log("10 minutes in review, proceeding with deployment");
+          // Decide whether to fail CI based on your criteria
+          if (status.blockingBugsCount > 5) {
+            console.log("Too many blocking bugs, failing CI");
+            process.exit(1);
+          }
+          break;
+        }
+
+        // Option 2: Stop if bug count is acceptable
+        if (status.blockingBugsCount <= 3) {
+          console.log(
+            `Only ${status.blockingBugsCount} blocking bugs, acceptable to proceed`,
+          );
+          break;
+        }
+        break;
+      }
+
+      case "completed":
+        console.log(`Completed with greenlight: ${status.greenlight}`);
+        if (!status.greenlight) {
+          console.log("Run failed, blocking bugs found");
+          process.exit(1);
+        }
+        console.log("Run passed successfully");
+        return; // Exit the loop
+
+      case "canceled":
+        console.log("Run was canceled");
+        process.exit(1);
+
+      default:
+        // Exhaustive check - TypeScript will error if a case is missing
+        status.runStage satisfies never;
+        throw new Error(`Unexpected run stage: ${status.runStage}`);
+    }
+  }
+})();
+```
+
+### Yielded Iteration Object
+
+The iterator yields a discriminated union that can be either a status update or an abort notification:
+
+**Status Iteration** (`isAborted: false`):
+
+- `isAborted`: `false` - Indicates a normal status update
+- `status`: The current `CiGreenlightStatus` from the API
+- `previousStatus`: The status from the previous iteration (undefined on first iteration)
+- `stageChanged`: Boolean indicating if the run stage changed from the previous iteration
+- `elapsedMs`: Milliseconds elapsed since polling started
+
+**Aborted Iteration** (`isAborted: true`):
+
+- `isAborted`: `true` - Indicates the polling was aborted
+- `abortReason`: String indicating why polling was aborted (e.g., `"poll-timed-out"`, `"run-canceled"`, `"network-error"`, `"4XX-client-error"`, `"5XX-server-error"`)
+- `httpStatus`: HTTP status code if applicable, otherwise `undefined`
+- `elapsedMs`: Milliseconds elapsed since polling started
+
+**Important**: Always check `iteration.isAborted` to determine which type of result you received. When `isAborted === true`, you should handle the abort reason and exit appropriately.
+
+<a id="notify-terminated-ephemeral-environment"></a>
+
+## Notify a Terminated Ephemeral Environment
+
+> ℹ️ [See the API documentation page for this endpoint](https://qawolf.notion.site/2c45b2a994fb8096a42af8d41c811ae2).
+
+After you terminate an ephemeral environment or release it for something else to be installed in it, you should notify QA Wolf of that fact. When you notify us, we will stop all runs targeting that environment and check whether there are any changes to flows that need to be promoted to the static base environment. This eventually results in the environment showing as "closed" in QA Wolf.
+
+> ⚠️ **Note**: If you have the QA Wolf GitHub integration enabled for your preview testing, GitHub will notify us of PRs being merged or closed, and we use that notification to stop runs and trigger flow promotion. In this case, it is typically redundant and unnecessary to call this..
+
+> ⚠️ **Important**: PR/MR testing functionality must be activated by QA Wolf. Please reach out to your QA Wolf representative to enable this feature and help with the setup.
+
+```ts
+import {
+  type NotifyTerminatedEphemeralEnvironmentInput,
+  makeQaWolfSdk,
+} from "@qawolf/ci-sdk";
+
+// Example for environmentId
+const terminateConfig: NotifyTerminatedEphemeralEnvironmentInput = {
+  environmentId: "test-environment-id",
+};
+
+// Example for environmentAlias
+const terminateConfig: NotifyTerminatedEphemeralEnvironmentInput = {
+  environmentAlias: "test-environment",
+};
+
+// Example for deploymentUrl
+const terminateConfig: NotifyTerminatedEphemeralEnvironmentInput = {
+  deploymentUrl: "https://test-environment",
+};
+
+const { notifyTerminatedEphemeralEnvironment } = makeQaWolfSdk({
+  apiKey: "qawolf_xxxxx",
+});
+
+(async () => {
+  const result = await notifyTerminatedEphemeralEnvironment(terminateConfig);
+  if (result.outcome !== "success") {
+    // Fail the job.
+    process.exit(1);
+  }
+  const environmentId = result.environmentId;
+})();
+```
+
 <a id="upload-artifacts"></a>
 
 ## Upload Run Input Artifacts
@@ -294,6 +464,14 @@ This package follows the [SemVer](https://semver.org/) versioning scheme. Additi
 
 # Changelog
 
+## v1.3.0
+
+- New `notifyTerminatedEphemeralEnvironment` method
+
+## v1.2.0
+
+- New `makePollCiGreenlightStatusIterator` async generator function for advanced polling control with custom early-exit logic
+
 ## v1.1.0
 
 - New `ephemeralEnvironment` parameter for `attemptNotifyDeploy`