@qawolf/ci-sdk 3.0.0 → 3.2.0

package/README.md

@@ -11,9 +11,12 @@ to determine the status of your CI/CD step/job/action.
 
 ## Table of Contents
 
-- [Notify Deployment](#notify-deployment)
+- [API Keys and Workspaces](#api-keys)
+- [Report a Deployment](#report-deployment)
+- [Wait for a Verdict](#wait-for-verdict)
+- [Notify Deployment (deprecated)](#notify-deployment)
 - [Notify Preview Deployment (Pull Request / Merge Request Testing)](#notify-preview)
-- [Poll for CI Greenlight Status](#ci-greenlight)
+- [Poll for CI Greenlight Status (deprecated)](#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)
@@ -21,10 +24,302 @@ to determine the status of your CI/CD step/job/action.
 - [Versioning](#versioning)
 - [Changelog](#changelog)
 
+<a id="api-keys"></a>
+
+## API Keys and Workspaces
+
+Every call you make is authenticated by the `apiKey` you pass to `makeQaWolfSdk`, and every call
+acts on exactly one workspace. How that workspace is determined depends on which kind of API key
+you hold:
+
+- A **workspace API key** (also called a team API key) already belongs to a single workspace. It
+  implies the workspace, so you never need to name one.
+- An **organization API key** or a **user API key** can reach several workspaces, so it does not
+  imply one. You name the workspace by passing `workspaceId` on the call.
+
+`workspaceId` is the ID of the workspace (team) you want the call to act on. If you are not sure
+which value to use, ask your QA Wolf representative; `attemptNotifyDeploy` also reports the
+workspace it selected, with its ID, in the warning described below.
+
+### Passing `workspaceId`
+
+The field is accepted on every function that acts on a workspace:
+
+```ts
+const { attemptNotifyDeploy, generateSignedUrlForRunInputsExecutablesStorage } =
+  makeQaWolfSdk({
+    apiKey: "qawolf_xxxxx",
+  });
+
+// Organization and user API keys must name the workspace on each call.
+await generateSignedUrlForRunInputsExecutablesStorage({
+  destinationFilePath: "unityexpo.ipa",
+  workspaceId: "your-workspace-id",
+});
+
+await attemptNotifyDeploy({
+  ...deployConfig,
+  workspaceId: "your-workspace-id",
+});
+```
+
+`notifyTerminatedEphemeralEnvironment` accepts `workspaceId` the same way.
+
+### What happens when it is missing
+
+Omitting `workspaceId` with an organization or user API key is handled differently depending on the
+call, so it is worth knowing which behavior to expect:
+
+| Function                                          | Behavior when `workspaceId` is omitted                                                                                                 |
+| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `generateSignedUrlForTempTeamStorage`             | Fails. The backend answers HTTP `400` with the message `workspaceId is a required query parameter for organization and user API keys`. |
+| `generateSignedUrlForRunInputsExecutablesStorage` | Same as above — the backend answers HTTP `400`.                                                                                        |
+| `attemptNotifyDeploy`                             | Succeeds against your organization's first-created workspace and returns a `warning` naming it.                                        |
+| `notifyTerminatedEphemeralEnvironment`            | Succeeds against your organization's first-created workspace and returns a `warning` naming it.                                        |
+
+> ⚠️ The signed-URL functions **require** `workspaceId` for organization and user API keys — they do
+> not fall back to a default workspace. A `400` from either function, especially when the API key and
+> artifact name are otherwise correct, most often means `workspaceId` was not sent.
+
+When this happens, the SDK logs the real status before it reports the outcome, so the log line is
+the reliable signal:
+
+```
+❌ [callGenerateSignedUrlForRunInputsExecutablesStorage] 400 Bad Request undefined
+🚫 Unrecoverable error (status 0) when generating signed upload url: Network error, aborting request to generate signed URL. aborting. undefined
+```
+
+The `400 Bad Request` on the first line is the actual response. The `status 0` and "Network error"
+on the second line are misreported and do not indicate a transport problem — read the first line
+and add `workspaceId`.
+
+For the same reason, do not branch on `httpStatus` or `abortReason` to detect this case: a failed
+signed-URL request currently reports `httpStatus: 0` and `abortReason: "client-network-error"`
+whatever the real status was. Treat any `success: false` from these two functions as a request that
+did not reach a signed URL, and check the logged status to find out why.
+
+Passing `workspaceId` with a workspace API key is unnecessary but harmless, as long as the ID names
+the key's own workspace. Naming a workspace the key cannot reach fails with HTTP `403`.
+
+`workspaceId` support was added in `@qawolf/ci-sdk` 2.2.0. On earlier versions, use a
+workspace-scoped API key.
+
+<a id="report-deployment"></a>
+
+## Report a Deployment
+
+Report a deployment through the public `deployment.reportStatus` API. A deployment's first `success` report is what evaluates your triggers, so this is the call that starts a run.
+
+> ⚠️ Triggers only see deployments reported this way. `attemptNotifyDeploy` reports through the legacy `deploy_success` webhook and is deprecated.
+
+### Example
+
+```ts
+import { detectProviderDeploymentId, makeQaWolfSdk } from "@qawolf/ci-sdk";
+
+const { deployment } = makeQaWolfSdk({ apiKey: "qawolf_xxxxx" });
+
+(async () => {
+  // `{ outcome: "detected", ci: "github", id: "18273645-2-deploy" }` on GitHub
+  // Actions, Jenkins, GitLab CI, CircleCI, Bitbucket Pipelines and Buildkite;
+  // `{ outcome: "unsupported" }` elsewhere, in which case compose the id from
+  // your own CI's variables.
+  const detected = detectProviderDeploymentId();
+  if (detected.outcome !== "detected") process.exit(1);
+
+  const result = await deployment.reportStatus({
+    environment: { name: "staging" },
+    metadata: {
+      commitSha: process.env.GITHUB_SHA,
+      ref: process.env.GITHUB_REF_NAME,
+      repository: process.env.GITHUB_REPOSITORY,
+    },
+    providerDeploymentId: detected.id,
+    status: "success",
+    workspaceId: "your-workspace-id",
+  });
+  if (result.outcome !== "reported") {
+    // `result.outcome` says why, and the refusal arms carry the server's
+    // explanation in `result.message` when it sent one.
+    process.exit(1);
+  }
+  console.log(
+    `Reported deployment ${result.deployment.id}: ${result.deployment.url}`,
+  );
+})();
+```
+
+The parameters are exactly the input of `deployment.reportStatus`; `ReportDeploymentParams` is derived from the published `@qawolf/api-contracts` package, so the SDK cannot drift from the API. Every field the legacy webhook accepted has an equivalent: `environmentVariables`, `deployTarget`, ephemeral environments through `environment.ephemeral` and `environment.baseEphemeralEnvironment`, and `metadata.repository` / `pullRequestNumber` / `commitSha` / `ref`.
+
+### `status`
+
+You choose the status: `pending`, `success`, `failure` or `inactive`. Only a deployment's **first `success`** report evaluates triggers, and it is the only report that does. A `pending` report records the deployment and starts nothing, so report `pending` when the deploy begins if you want it visible, and report `success` when the deploy is actually live — that second call is what starts the run. A trigger added or unpaused after that first `success` does not make the deployment evaluate again; report the deployment under a new `providerDeploymentId` to evaluate it against the current triggers.
+
+### `providerDeploymentId`
+
+This is the deployment's identity. Reports that share one update the same deployment, and the deployment stays bound to the environment its first report resolved.
+
+It is required, and the SDK never guesses it. Beware that `GITHUB_RUN_ID` alone is **stable across re-runs** and **shared by every job in the workflow**: a re-run of a failed job, or a second job deploying alongside the first, would report into the deployment that already evaluated, create no run, and appear to hang. `detectProviderDeploymentId()` composes an id that is distinct for every job definition and every re-run:
+
+| CI system           | Detected on                                       | Id                                                                         |
+| ------------------- | ------------------------------------------------- | -------------------------------------------------------------------------- |
+| GitHub Actions      | `GITHUB_ACTIONS`                                  | `GITHUB_RUN_ID`-`GITHUB_RUN_ATTEMPT`-`GITHUB_JOB`                          |
+| GitLab CI           | `GITLAB_CI`                                       | `CI_PIPELINE_ID`-`CI_JOB_ID`                                               |
+| CircleCI            | `CIRCLECI`                                        | `CIRCLE_WORKFLOW_ID`-`CIRCLE_BUILD_NUM`                                    |
+| Buildkite           | `BUILDKITE`                                       | `BUILDKITE_BUILD_ID`-`BUILDKITE_JOB_ID`-`BUILDKITE_RETRY_COUNT`            |
+| Jenkins             | `JENKINS_URL` or `JENKINS_HOME`                   | `BUILD_TAG`                                                                |
+| Bitbucket Pipelines | `BITBUCKET_WORKSPACE` or `BITBUCKET_BUILD_NUMBER` | `BITBUCKET_BUILD_NUMBER`-`BITBUCKET_STEP_UUID`-`BITBUCKET_STEP_RUN_NUMBER` |
+
+Jenkins needs no job or attempt part: `BUILD_TAG` is `jenkins-<job name>-<build number>`, and Jenkins allocates a fresh build number for every re-run you can start from outside the build. Bitbucket needs all three, because rerunning only the failed steps keeps the build number while parallel steps share both it and the step run number.
+
+The helper reports `{ outcome: "missing-variables", missingVariables }` when the CI system is recognized but a variable is absent, and `{ outcome: "unsupported" }` on any other CI, rather than guess an id that would not change on a re-run.
+
+#### Concurrent deployments from one job definition
+
+The guarantee stops at the job definition. Where one definition deploys more than once at a time, nothing in the environment tells the deployments apart, and the helper alone would hand them all the same id:
+
+| CI system      | What collides                                                                                       |
+| -------------- | --------------------------------------------------------------------------------------------------- |
+| GitHub Actions | Every leg of a `strategy.matrix` shares `GITHUB_JOB`, `GITHUB_RUN_ID` and `GITHUB_RUN_ATTEMPT`.     |
+| Jenkins        | A declarative `matrix` or `parallel` block runs its branches inside one build, sharing `BUILD_TAG`. |
+| CircleCI       | A job run with `parallelism` shares `CIRCLE_BUILD_NUM` across its containers.                       |
+
+GitLab CI, Buildkite and Bitbucket Pipelines are not affected: `CI_JOB_ID`, `BUILDKITE_JOB_ID` and `BITBUCKET_STEP_UUID` are already distinct for each parallel leg.
+
+Pass a `discriminator` for those, and for any job that loops over several environments. It is appended to the composed id:
+
+```ts
+const detected = detectProviderDeploymentId({
+  // In GitHub Actions: `discriminator: ${{ toJSON(matrix) }}` through an env
+  // variable, or just the one matrix value that names the deployment.
+  discriminator: process.env.DEPLOY_ENVIRONMENT,
+});
+```
+
+`detectProviderDeploymentId` also takes `env`, which defaults to `process.env`. Composing the `providerDeploymentId` yourself is always an option; the helper is a convenience, not a requirement.
+
+### `workspaceId`
+
+`deployment.reportStatus` requires `workspaceId` for every key kind; a workspace API key must name its own workspace. See [API Keys and Workspaces](#api-keys).
+
+### Result
+
+`deployment.reportStatus` returns a discriminated union and never throws for an outcome you are expected to branch on. Branch on `outcome` alone:
+
+| `outcome`               | Meaning                                                                                    |
+| ----------------------- | ------------------------------------------------------------------------------------------ |
+| `reported`              | Carries `deployment`, the whole resource: `id`, `status` and `url`.                        |
+| `invalid-request`       | The report did not satisfy the contract. Carries `message`.                                |
+| `unauthorized`          | The API key is unknown, or may not act on this workspace. Carries `message`.               |
+| `not-found`             | The workspace or environment named in the report does not exist. Carries `message`.        |
+| `conflict`              | The `providerDeploymentId` is already bound to a different environment. Carries `message`. |
+| `server-error`          | QA Wolf failed to record the report; retrying is reasonable. Carries `httpStatus`.         |
+| `unexpected-status`     | A status this SDK version does not map. Carries `httpStatus` and `message`.                |
+| `network-error`         | The request never reached QA Wolf, or the connection dropped.                              |
+| `invalid-response-body` | QA Wolf answered with a body the contract rejects.                                         |
+
+So `if (result.outcome !== "reported") process.exit(1)` is the whole check a gate needs.
+
+The response carries the deployment only, not the resulting runs. Waiting for a verdict is not part of this call.
+
+### Migrating from `attemptNotifyDeploy`
+
+```diff
+-const { attemptNotifyDeploy } = makeQaWolfSdk({ apiKey });
++const { deployment } = makeQaWolfSdk({ apiKey });
+
+-const deploy = await attemptNotifyDeploy({
+-  branch: process.env.GITHUB_REF_NAME,
+-  deploymentType: "staging",
+-  hostingService: "GitHub",
+-  sha: process.env.GITHUB_SHA,
+-});
+-if (deploy.outcome === "skipped") process.exit(0);
+-if (deploy.outcome !== "success") process.exit(1);
++const detected = detectProviderDeploymentId();
++if (detected.outcome !== "detected") process.exit(1);
++const deploy = await deployment.reportStatus({
++  environment: { name: "staging" },
++  metadata: { commitSha: process.env.GITHUB_SHA, ref: process.env.GITHUB_REF_NAME },
++  providerDeploymentId: detected.id,
++  status: "success",
++  workspaceId: "your-workspace-id",
++});
++if (deploy.outcome !== "reported") process.exit(1);
+```
+
+`detectProviderDeploymentId()` composes the run, attempt and job, so two jobs in one workflow do not report into the same deployment. Compose the id yourself only if you would rather not call it, and include the job.
+
+Four things move: `deploymentType` becomes `environment.name`; `branch` / `sha` become `metadata`; `providerDeploymentId` is new and required (`deduplicationKey` is subsumed by it); `hostingService` disappears, since the code host comes from your integration. There is no `skipped` outcome: whether a trigger matched is not known at report time. `pollCiGreenlightStatus` takes a run id that only `attemptNotifyDeploy` returns; a pipeline that waits for a verdict moves to [`deployment.waitForVerdict`](#wait-for-verdict), which takes the deployment id this call returns.
+
+<a id="wait-for-verdict"></a>
+
+## Wait for a Verdict
+
+`deployment.waitForVerdict` blocks until QA Wolf can say whether a deployment's tests passed. Give it the deployment id [the report](#report-deployment) returned; working out which runs the deployment produced happens inside.
+
+> ⚠️ Set `timeout` below your CI job's own ceiling. When the job's ceiling fires first, the job is killed with no run link and no explanation. When ours fires first, you get `timed-out` with the stage, the elapsed time, and every run URL we know about.
+
+### Example
+
+```ts
+const { deployment } = makeQaWolfSdk({ apiKey: "qawolf_xxxxx" });
+
+const report = await deployment.reportStatus({ /* ... */ status: "success" });
+if (report.outcome !== "reported") process.exit(1);
+
+const verdict = await deployment.waitForVerdict({
+  deploymentId: report.deployment.id,
+  timeout: 45 * 60 * 1000,
+});
+
+process.exit(["passed", "not-tested"].includes(verdict.outcome) ? 0 : 1);
+```
+
+### Result
+
+Like every function here, it never throws. Branch on `outcome` alone:
+
+| `outcome`               | Meaning                                                                                                  |
+| ----------------------- | -------------------------------------------------------------------------------------------------------- |
+| `passed`                | Every run QA Wolf started passed. Carries `runs`.                                                        |
+| `failed`                | A run found a bug that is still open and serious enough to block. Carries `runs` and `blockingBugCount`. |
+| `not-tested`            | Nothing tested this deployment. Carries `reason` and a `triggers` note per trigger saying why.           |
+| `run-canceled`          | A run was canceled, so there is no verdict. This is not a pass. Carries `runs`.                          |
+| `timed-out`             | The budget ran out. Carries `elapsedMs`, `lastStage` and any `runs` it had already looked up.            |
+| `canceled-by-caller`    | The `signal` you passed was aborted.                                                                     |
+| `unauthorized`          | The API key is unknown, or may not read this deployment. Carries `message`.                              |
+| `not-found`             | No such deployment. Carries `message`.                                                                   |
+| `server-error`          | QA Wolf kept failing after every retry. Carries `httpStatus`.                                            |
+| `unexpected-status`     | A status this SDK version does not map. Carries `httpStatus` and `message`.                              |
+| `network-error`         | The connection never came back within the retries.                                                       |
+| `invalid-response-body` | QA Wolf answered with a body the contract rejects.                                                       |
+
+`not-tested` is a separate answer from `passed` on purpose. A deployment that no trigger matched was not tested, which is a different fact from tests passing, and you decide what it is worth: exit 0 and keep the log line, or fail the build when you expect a run every time. `run-canceled` likewise means we cannot tell you.
+
+The shape is `deploymentVerdictSchema`, published in `@qawolf/api-contracts`, so the same answer parses the same way wherever you read it.
+
+### Options
+
+Every field below is optional and carries the default shown.
+
+| Option                 | Default | Meaning                                                                               |
+| ---------------------- | ------- | ------------------------------------------------------------------------------------- |
+| `timeout`              | `2h`    | Whole-operation budget. Set it below your CI job's ceiling.                           |
+| `runAppearanceTimeout` | `5min`  | Give up if no trigger has produced a run by then. Runs that did appear are waited on. |
+| `triggerPollInterval`  | `3s`    | Between polls while a trigger is still producing a run.                               |
+| `runPollInterval`      | `30s`   | Between polls while a run executes.                                                   |
+| `maxRetries`           | `10`    | Network and server-error retries before giving up.                                    |
+| `retryInterval`        | `10s`   | Between those retries.                                                                |
+| `onProgress`           | —       | Called on every stage change, for your build log.                                     |
+| `signal`               | —       | An `AbortSignal`. Aborting it yields `canceled-by-caller` instead of a rejection.     |
+
 <a id="notify-deployment"></a>
 
 ## Notify Deployment
 
+> ⚠️ **Deprecated.** This reports through the legacy `deploy_success` webhook, which triggers do not see. Use [Report a Deployment](#report-deployment) instead. It keeps working and there is no removal date.
+
 Notify us of a successful deployment to trigger a run.
 
 > ℹ️ [See the API documentation page for this endpoint](https://qawolf.notion.site/dd72e46ceb7f451dae4e9ef06f64a2cc).
@@ -135,22 +430,34 @@ const { attemptNotifyDeploy } = makeQaWolfSdk({
 
 > ⚠️ **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.
 
-Once enabled, to use PR/MR testing functionality:
+Once enabled, report the preview deployment with [`deployment.reportStatus`](#report-deployment) and name the pull or merge request in `metadata`. The code host comes from your QA Wolf integration, so there is no `hostingService` to pass:
 
-1. For `GitHub` repositories:
-   - Preferably, use our [GitHub Action](https://github.com/marketplace/actions/notify-qa-wolf-on-deploy)
-   - Pass `hostingService: "GitHub"`, `repository` information, and `pullRequestNumber` while notifying a deployment as described in the [Notify Deployment](#notify-deployment) section
+```ts
+await deployment.reportStatus({
+  deployTarget: previewUrl,
+  environment: { ephemeral: true, name: `pr-${pullRequestNumber}` },
+  metadata: {
+    commitSha: process.env.GITHUB_SHA,
+    pullRequestNumber,
+    ref: process.env.GITHUB_HEAD_REF,
+    repository: process.env.GITHUB_REPOSITORY,
+  },
+  providerDeploymentId: detected.id,
+  status: "success",
+  workspaceId: "your-workspace-id",
+});
+```
 
-2. For `GitLab` repositories:
-   - Pass `hostingService: "GitLab"`, `repository` information, and `mergeRequestNumber` while notifying a deployment as described in the [Notify Deployment](#notify-deployment) section
+`metadata.pullRequestNumber` names a GitLab merge request too. For a preview with no code hosting integration, pass `deployTarget` and an ephemeral `environment` and leave the repository fields out. `environment.baseEphemeralEnvironment` names the environment an ephemeral one inherits its configuration from.
 
-3. For `Ephemeral` deployments (no code hosting integration):
-   - Pass `ephemeralEnvironment: true` and `deploymentUrl` while notifying a deployment as described in the [Notify Deployment](#notify-deployment) section
+The [GitHub Action](https://github.com/marketplace/actions/notify-qa-wolf-on-deploy) and `attemptNotifyDeploy`'s `hostingService` / `mergeRequestNumber` / `ephemeralEnvironment` / `deploymentUrl` fields still work, but they report through the legacy `deploy_success` webhook that triggers do not see.
 
 <a id="ci-greenlight"></a>
 
 ## Poll for CI Greenlight Status
 
+> ⚠️ **Deprecated.** This polls a run id that only `attemptNotifyDeploy` returns, so it keeps your pipeline on the legacy `deploy_success` webhook. It keeps working and there is no removal date.
+
 > ℹ️ [See the API documentation page for this endpoint](https://qawolf.notion.site/1b170576efea411fa785842a71e7c99e).
 
 ```ts
@@ -407,6 +714,8 @@ const { generateSignedUrlForTempTeamStorage, attemptNotifyDeploy } =
 async function uploadRunArtifact(filePath: string): Promise<string> {
   const fileName = path.basename(filePath);
 
+  // Organization and user API keys must also pass `workspaceId` here, or the
+  // request fails with a 400. See "API Keys and Workspaces" above.
   const signedUrlResponse = await generateSignedUrlForTempTeamStorage({
     destinationFilePath: fileName,
   });
@@ -444,6 +753,10 @@ async function uploadRunArtifact(filePath: string): Promise<string> {
 `playgroundFileLocation` field with the same value as `interactiveRunFileLocation`. It is deprecated and
 will be removed in a future major version — use `interactiveRunFileLocation` instead.
 
+Both functions require `workspaceId` when you authenticate with an organization or user API key.
+See [API Keys and Workspaces](#api-keys) for details and for what a missing `workspaceId` looks
+like.
+
 <a name="requirements"></a>
 
 ## Requirements
@@ -485,6 +798,17 @@ This package follows the [SemVer](https://semver.org/) versioning scheme. Additi
 
 # Changelog
 
+## v3.2.0
+
+- New `deployment.waitForVerdict` function, which blocks until QA Wolf can say whether a deployment's tests passed. It takes the deployment id `deployment.reportStatus` returned and resolves that to runs internally, so no run id crosses the boundary. It answers `passed`, `failed`, `not-tested`, `run-canceled`, `timed-out`, `canceled-by-caller` or one of the transport outcomes, and never throws. `not-tested` is deliberately distinct from `passed`, and `run-canceled` means no verdict rather than a pass. The whole-operation budget stays at 2 hours, matching `pollCiGreenlightStatus`. See [Wait for a Verdict](#wait-for-verdict).
+
+## v3.1.0
+
+- New `deployment.reportStatus` function, which reports a deployment through the public `deployment.reportStatus` API — the one your triggers watch. A deployment's first `success` report is what starts a run. Its parameters are the API's own input, taken from the `@qawolf/api-contracts` package, so the SDK cannot drift from the API, and it returns `{ outcome: "reported", deployment }` carrying the deployment's `id`, `status` and `url`. A refusal comes back as one named outcome you can branch on — `invalid-request`, `unauthorized`, `not-found`, `conflict`, `server-error`, `unexpected-status`, `network-error` or `invalid-response-body` — so `if (result.outcome !== "reported")` is the whole check a CI gate needs. See [Report a Deployment](#report-deployment).
+- New `detectProviderDeploymentId` function, which works out the `providerDeploymentId` for you from the variables your CI already sets on GitHub Actions, GitLab CI, CircleCI, Buildkite, Jenkins and Bitbucket Pipelines. The id it builds is different for every job definition and every re-run, so a retried job and two jobs deploying side by side each get their own deployment instead of reporting into one that has already started its run. Where one job definition deploys more than once at a time — a GitHub Actions or Jenkins matrix, a CircleCI job with `parallelism`, a loop over environments — no variable tells the legs apart, so pass a `discriminator` and it is appended to the id. On any other CI it returns `{ outcome: "unsupported" }` rather than guess. Passing `providerDeploymentId` yourself is still required; this helper is optional.
+- Pull request and merge request testing is now documented on `deployment.reportStatus`: pass `metadata.repository` and `metadata.pullRequestNumber` instead of `hostingService`. See [Notify Preview Deployment](#notify-preview).
+- `attemptNotifyDeploy` and `pollCiGreenlightStatus` are deprecated in favour of `deployment.reportStatus`. They report through the legacy `deploy_success` webhook, which triggers do not see. Both keep working unchanged, print no warning, and have no removal date.
+
 ## v3.0.0
 
 - **Breaking**: this package is now published as ESM only. The CommonJS build (`dist/index.cjs`) and the `require` entry in `exports` are gone, so `require("@qawolf/ci-sdk")` no longer resolves. Import the package with `import` from an ESM module, or load it from CommonJS with a dynamic `await import("@qawolf/ci-sdk")`.
@@ -519,6 +843,10 @@ This package follows the [SemVer](https://semver.org/) versioning scheme. Additi
 - `attemptNotifyDeploy`: a failed suite result now carries `failureCode` and `failureMessage` alongside the existing `failureReason`. `failureCode` is a stable code to branch on, such as `billing-prevented`, `environment-terminated`, `environment-not-ready`, `test-configuration-error`, or `internal-error`; treat it as an open set, since new codes are added over time. Note that `environment-terminated` is permanent while `environment-not-ready` clears on its own, so retrying is worthwhile only for the second. `failureMessage` is human-readable copy for logs, and the SDK's own failure log line now prints it instead of the internal reason.
 - `attemptNotifyDeploy`: `failureReason` is deprecated. It still ships unchanged and is safe to keep reading, but it carries an internal diagnostic whose values change without notice. Branch on `failureCode` and display `failureMessage` instead. Both are `undefined` when the SDK talks to a backend that predates them.
 
+## v2.2.0
+
+- `generateSignedUrlForTempTeamStorage` and `generateSignedUrlForRunInputsExecutablesStorage`: both now accept an optional `workspaceId`, which names the workspace the signed URL is generated for. It is required when authenticating with an organization or user API key, since neither is tied to a single workspace, and without it the request fails with HTTP `400`. Omit it when authenticating with a workspace API key, which already implies one. This entry was missing from the changelog when 2.2.0 was released and is documented here retroactively; see [API Keys and Workspaces](#api-keys).
+
 ## v2.1.0
 
 - `attemptNotifyDeploy`: the `deploy_success` response is now validated at runtime instead of being trusted. A response with a non-JSON body, or a body that does not match the expected shape, returns `outcome: "aborted"` with the new `abortReason: "invalid-response-body"`. This is distinct from `"network-error"`, which now covers only transport and body-stream failures rather than also masking unparseable responses. A result the SDK does not recognize (for example a new result kind sent by a newer backend) returns `outcome: "failed"` with the new `failReason: "unknown-result"` instead of being reported as a success. Recognized results are unchanged, and older backends that omit newer fields remain fully supported.

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export type { CiGreenlightStatus, CiGreenlightStatusBase, } from "./lib/api/index.js";
 export * from "./lib/sdk/dependencies.js";
 export * from "./lib/sdk/domain/attemptDeploy/types.js";
+export * from "./lib/sdk/domain/detectProviderDeploymentId/index.js";
 export * from "./lib/sdk/index.js";