@qawolf/ci-sdk 3.0.0 → 3.1.0

package/README.md

@@ -11,9 +11,11 @@ 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)
+- [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 +23,240 @@ 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, so a pipeline that waits for a verdict stays on the legacy pair until the successor to polling ships.
+
 <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 +367,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 +651,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 +690,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 +735,13 @@ This package follows the [SemVer](https://semver.org/) versioning scheme. Additi
 
 # Changelog
 
+## 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 +776,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";

package/dist/index.js

@@ -2,6 +2,88 @@
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 
+// src/lib/sdk/domain/detectProviderDeploymentId/index.ts
+var ciSystems = [
+  {
+    ci: "github",
+    isActive: /* @__PURE__ */ __name((env) => env.GITHUB_ACTIONS === "true", "isActive"),
+    // GITHUB_RUN_ID is stable across re-runs and GITHUB_RUN_ATTEMPT increments,
+    // and both are shared by every job in the workflow, so GITHUB_JOB separates
+    // jobs that deploy in parallel. GITHUB_JOB names the job definition, which
+    // every leg of a matrix shares, so those legs need a discriminator.
+    variables: ["GITHUB_RUN_ID", "GITHUB_RUN_ATTEMPT", "GITHUB_JOB"]
+  },
+  {
+    ci: "gitlab",
+    isActive: /* @__PURE__ */ __name((env) => env.GITLAB_CI === "true", "isActive"),
+    // Retrying a job keeps the pipeline id and mints a new job id.
+    variables: ["CI_PIPELINE_ID", "CI_JOB_ID"]
+  },
+  {
+    ci: "circleci",
+    isActive: /* @__PURE__ */ __name((env) => env.CIRCLECI === "true", "isActive"),
+    // A rerun keeps the workflow id and allocates a new build number. A job
+    // run with `parallelism` shares both across its containers, so those need
+    // a discriminator.
+    variables: ["CIRCLE_WORKFLOW_ID", "CIRCLE_BUILD_NUM"]
+  },
+  {
+    ci: "buildkite",
+    isActive: /* @__PURE__ */ __name((env) => env.BUILDKITE === "true", "isActive"),
+    // BUILDKITE_BUILD_ID covers the whole build, so BUILDKITE_JOB_ID separates
+    // the jobs within it and BUILDKITE_RETRY_COUNT separates a job's retries.
+    variables: [
+      "BUILDKITE_BUILD_ID",
+      "BUILDKITE_JOB_ID",
+      "BUILDKITE_RETRY_COUNT"
+    ]
+  },
+  {
+    ci: "jenkins",
+    // JENKINS_URL is unset on some agent configurations.
+    isActive: /* @__PURE__ */ __name((env) => env.JENKINS_URL !== void 0 || env.JENKINS_HOME !== void 0, "isActive"),
+    // BUILD_TAG is `jenkins-${JOB_NAME}-${BUILD_NUMBER}`, and Jenkins allocates
+    // a fresh BUILD_NUMBER for every externally visible re-run — Rebuild,
+    // Naginator, Replay and Restart from Stage — so it needs no attempt
+    // counter. An in-pipeline `retry {}` reuses it, but reports nothing new.
+    // A declarative `matrix` or `parallel` block runs its branches inside one
+    // build and so shares BUILD_TAG; those branches need a discriminator.
+    variables: ["BUILD_TAG"]
+  },
+  {
+    ci: "bitbucket",
+    isActive: /* @__PURE__ */ __name((env) => env.BITBUCKET_WORKSPACE !== void 0 || env.BITBUCKET_BUILD_NUMBER !== void 0, "isActive"),
+    // Rerunning a whole pipeline mints a new build number, but rerunning only
+    // the failed steps keeps it and increments the step's run number instead.
+    // Parallel steps share both, so BITBUCKET_STEP_UUID separates them.
+    variables: [
+      "BITBUCKET_BUILD_NUMBER",
+      "BITBUCKET_STEP_UUID",
+      "BITBUCKET_STEP_RUN_NUMBER"
+    ]
+  }
+];
+function detectProviderDeploymentId({
+  discriminator,
+  env = process.env
+} = {}) {
+  const system = ciSystems.find((candidate) => candidate.isActive(env));
+  if (!system) return { outcome: "unsupported" };
+  const missingVariables = system.variables.filter((name) => !env[name]);
+  if (missingVariables.length > 0)
+    return { ci: system.ci, missingVariables, outcome: "missing-variables" };
+  const composed = system.variables.map((name) => env[name]).join("-");
+  return {
+    ci: system.ci,
+    // A colon separates the discriminator because a job id can itself contain
+    // a hyphen, so joining with one would let job "deploy-web" collide with
+    // job "deploy" discriminated by "web".
+    id: discriminator ? `${composed}:${discriminator}` : composed,
+    outcome: "detected"
+  };
+}
+__name(detectProviderDeploymentId, "detectProviderDeploymentId");
+
 // src/lib/other.ts
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
@@ -38,7 +120,7 @@ var defaultServiceBase = "https://app.qawolf.com/";
 // package.json
 var package_default = {
   name: "@qawolf/ci-sdk",
-  version: "3.0.0",
+  version: "3.1.0",
   private: false,
   description: "A simple SDK for interacting with QAWolf in CI scripts.",
   keywords: [],
@@ -61,18 +143,20 @@ var package_default = {
     "lint:ci": "npm run lint:first-half; FIRST_HALF_EXIT=$?; npm run lint:second-half && exit $FIRST_HALF_EXIT",
     "lint:dev": "npm run lint:first-half",
     "lint:first-half": "oxlint . --fix --quiet --report-unused-disable-directives --type-aware && oxfmt --write .",
-    "lint:second-half": "dpdm --exit-code circular:1 --no-tree --no-warning --transform --include='.*' --exclude='/(dist|node_modules)/' '**/*'",
+    "lint:second-half": "rev-dep config run",
     prepublishOnly: "nx run ci-sdk:build",
     test: 'NODE_OPTIONS="--experimental-vm-modules" NODE_NO_WARNINGS=1 jest',
     "tsc:check": "tsc --noEmit"
   },
   dependencies: {
+    "@qawolf/api-contracts": ">=0.68.0",
     "@qawolf/ci-utils": "^2.0.0",
     "@sinonjs/fake-timers": "^10.3.0",
-    tslib: "^2.6.2"
+    tslib: "^2.6.2",
+    zod: "^4.1.11"
   },
   devDependencies: {
-    "@qawolf/platform-builder": "^1.2.3",
+    "@qawolf/platform-builder": "^1.2.7",
     tsx: "^4.19.4",
     typescript: "^5.9.3"
   },
@@ -1111,6 +1195,127 @@ async function pollCiGreenlightStatus(deps, apiConfig, {
 }
 __name(pollCiGreenlightStatus, "pollCiGreenlightStatus");
 
+// src/lib/sdk/domain/reportDeployment/index.ts
+import { publicContractsV1 } from "@qawolf/api-contracts";
+
+// src/lib/sdk/publicApi/callContract.ts
+function isRecord2(value) {
+  return typeof value === "object" && value !== null;
+}
+__name(isRecord2, "isRecord");
+function isSuperJsonEnvelope(data) {
+  return "json" in data && Object.keys(data).every((key) => key === "json" || key === "meta");
+}
+__name(isSuperJsonEnvelope, "isSuperJsonEnvelope");
+function unwrapTrpcEnvelope(body) {
+  if (!isRecord2(body) || !isRecord2(body.result)) return void 0;
+  const data = body.result.data;
+  return isRecord2(data) && isSuperJsonEnvelope(data) ? data.json : data;
+}
+__name(unwrapTrpcEnvelope, "unwrapTrpcEnvelope");
+function readTrpcError(body) {
+  const wrapped = isRecord2(body) ? body.error : void 0;
+  const error = isRecord2(wrapped) && isRecord2(wrapped.json) ? wrapped.json : wrapped;
+  if (!isRecord2(error)) return { eventId: void 0, message: void 0 };
+  const data = isRecord2(error.data) ? error.data : void 0;
+  return {
+    eventId: typeof data?.eventId === "string" ? data.eventId : void 0,
+    message: typeof error.message === "string" ? error.message : void 0
+  };
+}
+__name(readTrpcError, "readTrpcError");
+function parseJson(text) {
+  if (text === void 0) return void 0;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return void 0;
+  }
+}
+__name(parseJson, "parseJson");
+async function readHttpError(response, contractName, log) {
+  const bodyText = await response.text().catch(() => void 0);
+  const { eventId, message } = readTrpcError(parseJson(bodyText));
+  const statusText = response.status >= 500 ? "Server Error" : response.statusText || "Unknown Error";
+  const eventIdSuffix = eventId ? ` (Event ID: ${eventId})` : "";
+  const messageSuffix = message ? `: ${message}` : "";
+  log.error(
+    `\u274C [${contractName}] ${response.status} ${statusText}${eventIdSuffix}${messageSuffix}`
+  );
+  return {
+    eventId,
+    httpStatus: response.status,
+    message,
+    outcome: "http-error"
+  };
+}
+__name(readHttpError, "readHttpError");
+async function callPublicContract({ fetch: localFetch, log }, apiConfig, {
+  contract,
+  input
+}) {
+  const procedurePath = `public.${contract.name}`;
+  let bodyText;
+  try {
+    const response = await localFetch(
+      new URL(`/api/trpc/${procedurePath}`, apiConfig.serviceBase),
+      {
+        // The server's superjson transformer reads the input from `json`.
+        body: JSON.stringify({ json: input }),
+        headers: {
+          Authorization: `Bearer ${apiConfig.apiKey}`,
+          "Content-Type": "application/json",
+          "User-Agent": apiConfig.userAgent
+        },
+        method: "POST"
+      }
+    );
+    if (!response.ok) return readHttpError(response, contract.name, log);
+    bodyText = await response.text();
+  } catch {
+    log.error(`\u{1F6AB} Network error from ${contract.name}, aborting.`);
+    return { outcome: "network-error" };
+  }
+  const parsed = contract.output.safeParse(
+    unwrapTrpcEnvelope(parseJson(bodyText))
+  );
+  if (!parsed.success) {
+    log.error(
+      `\u{1F6AB} Invalid response from ${contract.name} (${parsed.error.issues[0]?.message ?? "the response body did not match the contract"}), aborting.`
+    );
+    return { outcome: "invalid-response-body" };
+  }
+  return { data: parsed.data, outcome: "ok" };
+}
+__name(callPublicContract, "callPublicContract");
+
+// src/lib/sdk/domain/reportDeployment/index.ts
+async function reportDeployment(deps, apiConfig, params) {
+  const result = await callPublicContract(deps, apiConfig, {
+    contract: publicContractsV1.deployment.reportStatus,
+    input: params
+  });
+  if (result.outcome !== "ok") return mapFailure(result);
+  const { deployment } = result.data;
+  deps.log.info(
+    `\u2705 Deployment ${deployment.id} reported as ${deployment.status}: ${deployment.url}`
+  );
+  return { deployment, outcome: "reported" };
+}
+__name(reportDeployment, "reportDeployment");
+function mapFailure(result) {
+  if (result.outcome !== "http-error") return { outcome: result.outcome };
+  const { httpStatus, message } = result;
+  if (httpStatus === 400) return { message, outcome: "invalid-request" };
+  if (httpStatus === 401 || httpStatus === 403)
+    return { message, outcome: "unauthorized" };
+  if (httpStatus === 404) return { message, outcome: "not-found" };
+  if (httpStatus === 409) return { message, outcome: "conflict" };
+  if (httpStatus >= 500) return { httpStatus, outcome: "server-error" };
+  return { httpStatus, message, outcome: "unexpected-status" };
+}
+__name(mapFailure, "mapFailure");
+
 // src/lib/sdk/index.ts
 function makeQaWolfSdk({
   apiKey,
@@ -1135,7 +1340,14 @@ We recommend 'undici' package for that purpose. See the Requirement section of o
   };
   const apiConfig = { apiKey, serviceBase, userAgent };
   return {
+    /**
+     * @deprecated Reports through the legacy `deploy_success` webhook, which
+     * triggers do not see. Use `deployment.reportStatus` instead.
+     */
     attemptNotifyDeploy: attemptNotifyDeploy.bind(null, deps, apiConfig),
+    deployment: {
+      reportStatus: reportDeployment.bind(null, deps, apiConfig)
+    },
     generateSignedUrlForRunInputsExecutablesStorage: generateSignedUrlForRunInputsExecutablesStorage.bind(
       null,
       deps,
@@ -1148,11 +1360,16 @@ We recommend 'undici' package for that purpose. See the Requirement section of o
       apiConfig
     ),
     notifyTerminatedEphemeralEnvironment: notifyTerminatedEphemeralEnvironment.bind(null, deps, apiConfig),
+    /**
+     * @deprecated Polls a run id that only `attemptNotifyDeploy` returns, so it
+     * keeps the pipeline on the legacy `deploy_success` webhook.
+     */
     pollCiGreenlightStatus: pollCiGreenlightStatus.bind(null, deps, apiConfig)
   };
 }
 __name(makeQaWolfSdk, "makeQaWolfSdk");
 export {
+  detectProviderDeploymentId,
   makeQaWolfSdk
 };
 //# sourceMappingURL=index.js.map