@qawolf/ci-sdk 3.0.0 → 3.2.0

package/dist/lib/sdk/domain/pollCiGreenlight/index.d.ts

@@ -1,4 +1,8 @@
 import type { ApiConfig } from "../../../api-types.js";
 import type { SdkDependencies } from "../../dependencies.js";
 import type { PollCiGreenlightParams, PollCiGreenlightStatus } from "./types.js";
+/**
+ * @deprecated Polls a run id that only `attemptNotifyDeploy` returns, so it
+ * keeps the pipeline on the legacy `deploy_success` webhook.
+ */
 export declare function pollCiGreenlightStatus(deps: SdkDependencies, apiConfig: ApiConfig, { onRunStageChanged, runId, ...pollConfig }: PollCiGreenlightParams): Promise<PollCiGreenlightStatus>;

package/dist/lib/sdk/domain/reportDeployment/index.d.ts

@@ -0,0 +1,4 @@
+import type { ApiConfig } from "../../../api-types.js";
+import type { SdkDependencies } from "../../dependencies.js";
+import type { ReportDeploymentParams, ReportDeploymentResult } from "./types.js";
+export declare function reportDeployment(deps: SdkDependencies, apiConfig: ApiConfig, params: ReportDeploymentParams): Promise<ReportDeploymentResult>;

package/dist/lib/sdk/domain/reportDeployment/types.d.ts

@@ -0,0 +1,50 @@
+import type { PublicApiInput, PublicApiOutput, publicContractsV1 } from "@qawolf/api-contracts";
+export type ReportDeploymentParams = PublicApiInput<typeof publicContractsV1.deployment.reportStatus>;
+/**
+ * The deployment the report created or updated, exactly as the
+ * `deployment.reportStatus` contract describes it.
+ */
+export type ReportedDeployment = PublicApiOutput<typeof publicContractsV1.deployment.reportStatus>["deployment"];
+export type ReportDeploymentResult = {
+    deployment: ReportedDeployment;
+    outcome: "reported";
+}
+/** The report did not satisfy the contract. HTTP 400. */
+ | {
+    message: string | undefined;
+    outcome: "invalid-request";
+}
+/** The API key is unknown, or may not act on this workspace. HTTP 401 and 403. */
+ | {
+    message: string | undefined;
+    outcome: "unauthorized";
+}
+/** The workspace or environment named in the report does not exist. HTTP 404. */
+ | {
+    message: string | undefined;
+    outcome: "not-found";
+}
+/** The providerDeploymentId is already bound to a different environment. HTTP 409. */
+ | {
+    message: string | undefined;
+    outcome: "conflict";
+}
+/** QA Wolf failed to record the report; retrying is reasonable. HTTP 5XX. */
+ | {
+    httpStatus: number;
+    outcome: "server-error";
+}
+/** A status this SDK version does not map, carrying what the server sent. */
+ | {
+    httpStatus: number;
+    message: string | undefined;
+    outcome: "unexpected-status";
+}
+/** The request never reached QA Wolf, or the connection dropped. */
+ | {
+    outcome: "network-error";
+}
+/** The server answered 2xx with a body the contract's output rejects. */
+ | {
+    outcome: "invalid-response-body";
+};

package/dist/lib/sdk/domain/waitForVerdict/awaitRuns.d.ts

@@ -0,0 +1,14 @@
+import type { DeploymentVerdict, MatchedRun, WaitContext } from "./types.js";
+export type RunsFound = {
+    kind: "runs";
+    runs: MatchedRun[];
+};
+type Phase = DeploymentVerdict | RunsFound;
+/**
+ * Polls the deployment's trigger evaluations until they name the runs that
+ * answer for it, or until it is clear nothing will run. Bounded by
+ * `runAppearanceTimeout`: a trigger that never resolves does not hold up the
+ * runs that did start.
+ */
+export declare function awaitRuns(ctx: WaitContext): Promise<Phase>;
+export {};

package/dist/lib/sdk/domain/waitForVerdict/awaitVerdict.d.ts

@@ -0,0 +1,12 @@
+import type { DeploymentVerdict, MatchedRun, VerdictRun, WaitContext } from "./types.js";
+/**
+ * The whole-deployment answer: one failing run fails the deployment, and a
+ * cancellation means QA Wolf reached no verdict rather than that it passed.
+ *
+ * A deployment is expected to resolve to exactly one run; the fold over several
+ * is a guard, so that a violation of that expectation cannot be reported as
+ * passing. It assumes superseded runs have already been resolved away to the
+ * run that replaced them, because an abandoned run can itself report failed.
+ */
+export declare function aggregateRuns(deploymentId: string, runs: VerdictRun[]): DeploymentVerdict;
+export declare function awaitVerdict(ctx: WaitContext, matched: MatchedRun[]): Promise<DeploymentVerdict>;

package/dist/lib/sdk/domain/waitForVerdict/consts.d.ts

@@ -0,0 +1,13 @@
+/**
+ * If you change these, update the JSDoc on `WaitForVerdictConfig` with them.
+ * The whole-operation budget matches the legacy `pollCiGreenlightStatus`
+ * `pollTimeout`, so moving off that function does not also move the default.
+ */
+export declare const waitForVerdictDefaults: {
+    maxRetries: number;
+    retryInterval: number;
+    runAppearanceTimeout: number;
+    runPollInterval: number;
+    timeout: number;
+    triggerPollInterval: number;
+};

package/dist/lib/sdk/domain/waitForVerdict/failures.d.ts

@@ -0,0 +1,14 @@
+import type { PublicApiCallFailure } from "../../publicApi/callContract.js";
+import type { DeploymentVerdict } from "./types.js";
+/**
+ * How the wait should answer a failed call: retry it until the budget runs
+ * out, or stop on a refusal that retrying cannot change.
+ */
+export type FailureHandling = {
+    exhaustedVerdict: DeploymentVerdict;
+    kind: "retry";
+} | {
+    kind: "stop";
+    verdict: DeploymentVerdict;
+};
+export declare function handleCallFailure(failure: PublicApiCallFailure, deploymentId: string): FailureHandling;

package/dist/lib/sdk/domain/waitForVerdict/index.d.ts

@@ -0,0 +1,12 @@
+import type { ApiConfig } from "../../../api-types.js";
+import type { SdkDependencies } from "../../dependencies.js";
+import type { DeploymentVerdict, WaitForVerdictParams } from "./types.js";
+/**
+ * Blocks until QA Wolf can say whether a deployment's tests passed.
+ *
+ * It takes only the deployment id the report gave back: resolving that to the
+ * runs its triggers created, and those runs to a status, stays inside. Nothing
+ * throws — a refusal, a dead network, a cancellation and an exhausted budget
+ * are all arms of the returned verdict.
+ */
+export declare function waitForVerdict(deps: SdkDependencies, apiConfig: ApiConfig, { deploymentId, maxRetries, onProgress, retryInterval, runAppearanceTimeout, runPollInterval, signal, timeout, triggerPollInterval, }: WaitForVerdictParams): Promise<DeploymentVerdict>;

package/dist/lib/sdk/domain/waitForVerdict/logVerdict.d.ts

@@ -0,0 +1,3 @@
+import type { LogDriver } from "@qawolf/ci-utils";
+import type { DeploymentVerdict } from "./types.js";
+export declare function logVerdict(log: LogDriver, verdict: DeploymentVerdict): void;

package/dist/lib/sdk/domain/waitForVerdict/poll.d.ts

@@ -0,0 +1,20 @@
+import type { PublicApiCallResult } from "../../publicApi/callContract.js";
+import type { DeploymentVerdict, WaitContext } from "./types.js";
+export type PollStep<Result> = {
+    intervalMs: number;
+    kind: "continue";
+} | {
+    kind: "done";
+    result: Result;
+};
+/**
+ * Repeats one public API call until it answers something terminal, the caller
+ * hangs up, or the deadline passes. Nothing here throws: a refusal, a dead
+ * network and an exhausted budget are all verdicts the caller receives.
+ */
+export declare function pollUntil<Data, Result>(ctx: WaitContext, { deadlineAt, onData, onDeadline, request, }: {
+    deadlineAt: number;
+    onData: (data: Data) => Promise<PollStep<Result>>;
+    onDeadline: () => DeploymentVerdict | Result;
+    request: () => Promise<PublicApiCallResult<Data>>;
+}): Promise<DeploymentVerdict | Result>;

package/dist/lib/sdk/domain/waitForVerdict/progress.d.ts

@@ -0,0 +1,7 @@
+import type { VerdictStage, WaitContext } from "./types.js";
+/**
+ * Reports a stage once, when it differs from the one before it. The log line
+ * is the identity of a stage, so a run that keeps executing does not repeat
+ * itself in the build log.
+ */
+export declare function reportStage(ctx: WaitContext, previousDescription: string | undefined, stage: VerdictStage): Promise<string>;

package/dist/lib/sdk/domain/waitForVerdict/readEvaluations.d.ts

@@ -0,0 +1,20 @@
+import type { PublicApiOutput, publicContractsV1 } from "@qawolf/api-contracts";
+import type { MatchedRun, NotTestedReason, TriggerNote } from "./types.js";
+export type TriggerEvaluations = PublicApiOutput<typeof publicContractsV1.deployment.listTriggerEvaluations>;
+export type EvaluationReading = {
+    kind: "not-evaluated";
+}
+/** Some trigger is still creating a run; `runs` are the ones already known. */
+ | {
+    kind: "awaiting-run";
+    matchedTriggerCount: number;
+    runs: MatchedRun[];
+} | {
+    kind: "runs";
+    runs: MatchedRun[];
+} | {
+    kind: "not-tested";
+    reason: NotTestedReason;
+    triggers: TriggerNote[];
+};
+export declare function readEvaluations(evaluations: TriggerEvaluations): EvaluationReading;

package/dist/lib/sdk/domain/waitForVerdict/testHarness.d.ts

@@ -0,0 +1,53 @@
+import type { ApiConfig } from "../../../api-types.js";
+import type { SdkDependencies } from "../../dependencies.js";
+export type Reply = {
+    body: unknown;
+    status: number;
+} | {
+    kind: "network-error";
+};
+export declare function ok(payload: unknown): Reply;
+export declare function httpError(status: number, message: string): Reply;
+export declare const networkError: Reply;
+export declare function evaluated(evaluations: unknown[]): Reply;
+export declare const notEvaluated: Reply;
+export declare function matchedTrigger(run: unknown, triggerName?: string): unknown;
+export declare function unmatchedTrigger(reason: string, triggerName?: string): {
+    triggerName: string;
+    verdict: {
+        conditionSets: {
+            conditions: {
+                kind: string;
+                outcome: string;
+                reason: string;
+            }[];
+            outcome: string;
+        }[];
+        outcome: string;
+    };
+};
+export declare function runPayload({ blockingBugCount, runId, status, }: {
+    blockingBugCount?: number;
+    runId?: string;
+    status: string;
+}): unknown;
+/**
+ * A fetch that answers each contract from its own queue, holding on the last
+ * reply once a queue runs out, plus a clock that only moves when the SDK
+ * sleeps. Together they let a test walk a two-hour poll in milliseconds and
+ * count exactly how many times the SDK asked. `runs` is one queue shared by
+ * every run, or a queue per requested run id when a test needs to tell two
+ * runs apart.
+ */
+export declare function makeHarness({ evaluations, runs, }: {
+    evaluations?: Reply[];
+    runs?: Record<string, Reply[]> | Reply[];
+}): {
+    apiConfig: ApiConfig;
+    calls: {
+        evaluations: number;
+        runs: number;
+    };
+    deps: SdkDependencies;
+    fetch: import("jest-mock").Mock<(url: unknown, init: unknown) => Promise<Response>>;
+};

package/dist/lib/sdk/domain/waitForVerdict/types.d.ts

@@ -0,0 +1,48 @@
+import type { DeploymentVerdict, NotTestedReason, TriggerNote, VerdictRun, VerdictStage } from "@qawolf/api-contracts";
+import type { ApiConfig } from "../../../api-types.js";
+import type { SdkDependencies } from "../../dependencies.js";
+export type { DeploymentVerdict, NotTestedReason, TriggerNote, VerdictRun, VerdictStage, };
+export type WaitForVerdictConfig = {
+    /** Network and server-error retries before giving up. @default 10 */
+    maxRetries: number;
+    /** Fired on every stage change, for CI logs. */
+    onProgress: (stage: VerdictStage) => unknown | Promise<unknown>;
+    /** Between retries of a failed call. @default 10s */
+    retryInterval: number;
+    /**
+     * Give up if no trigger has produced a run by then. Runs that did appear are
+     * still waited on. @default 5min
+     */
+    runAppearanceTimeout: number;
+    /** Between polls while a run executes. @default 30s */
+    runPollInterval: number;
+    /** Cancels the wait; yields `outcome: "canceled-by-caller"`. */
+    signal: AbortSignal;
+    /**
+     * Whole-operation budget. Set it below the CI job's own ceiling, so the wait
+     * ends with a run URL and a stage instead of the job being killed.
+     * @default 2h
+     */
+    timeout: number;
+    /** Between polls while a trigger is still producing a run. @default 3s */
+    triggerPollInterval: number;
+};
+export type WaitForVerdictParams = {
+    deploymentId: string;
+} & Partial<WaitForVerdictConfig>;
+export type ResolvedWaitConfig = Omit<WaitForVerdictConfig, "onProgress" | "signal"> & {
+    onProgress: ((stage: VerdictStage) => unknown | Promise<unknown>) | undefined;
+    signal: AbortSignal | undefined;
+};
+export type WaitContext = {
+    apiConfig: ApiConfig;
+    config: ResolvedWaitConfig;
+    deploymentId: string;
+    deps: SdkDependencies;
+    startedAt: number;
+};
+/** A run one trigger created, before its status is known. */
+export type MatchedRun = {
+    runId: string;
+    triggerName: string;
+};

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

@@ -3,8 +3,131 @@ export declare function makeQaWolfSdk({ apiKey, serviceBase, userAgent, }: {
     apiKey: string;
     serviceBase?: string;
     userAgent?: string;
-}, { fetch, log, }?: Partial<SdkDependencies>): {
+}, { clock, fetch, log, }?: Partial<SdkDependencies>): {
+    /**
+     * @deprecated Reports through the legacy `deploy_success` webhook, which
+     * triggers do not see. Use `deployment.reportStatus` instead.
+     */
     attemptNotifyDeploy: (config: Partial<import("./domain/attemptDeploy/deployConfig.js").DeployConfig>) => Promise<import("./domain/attemptDeploy/types.js").NotifyDeployStatus>;
+    deployment: {
+        reportStatus: (params: {
+            providerDeploymentId: string;
+            status: "success" | "pending" | "failure" | "inactive";
+            workspaceId: string;
+            deployTarget?: string | undefined;
+            environment?: {
+                id: string;
+            } | {
+                name: string;
+                baseEphemeralEnvironment?: string | undefined;
+                ephemeral?: boolean | undefined;
+            } | undefined;
+            environmentVariables?: Record<string, string> | undefined;
+            metadata?: {
+                commitAuthorName?: string | undefined;
+                commitMessage?: string | undefined;
+                commitSha?: string | undefined;
+                commitUrl?: string | undefined;
+                pullRequestNumber?: number | undefined;
+                ref?: string | undefined;
+                repository?: string | undefined;
+            } | undefined;
+            service?: string | undefined;
+        }) => Promise<import("./domain/reportDeployment/types.js").ReportDeploymentResult>;
+        waitForVerdict: (args_0: import("./domain/waitForVerdict/types.js").WaitForVerdictParams) => Promise<{
+            deploymentId: string;
+            outcome: "passed";
+            runs: {
+                blockingBugCount: number;
+                runId: string;
+                runUrl: string;
+                status: "canceled" | "failed" | "passed" | "queued" | "running";
+                triggerName: string;
+            }[];
+        } | {
+            blockingBugCount: number;
+            deploymentId: string;
+            outcome: "failed";
+            runs: {
+                blockingBugCount: number;
+                runId: string;
+                runUrl: string;
+                status: "canceled" | "failed" | "passed" | "queued" | "running";
+                triggerName: string;
+            }[];
+        } | {
+            deploymentId: string;
+            outcome: "not-tested";
+            reason: "no-trigger-matched" | "no-run-created";
+            triggers: {
+                message: string;
+                triggerName: string;
+                reason?: "skipped" | "billing-prevented" | "branch-still-syncing" | "deployment-no-longer-live" | "duplicate-run" | "environment-not-linked-to-branch" | "environment-not-ready" | "environment-terminated" | "internal-error" | "low-risk-change" | "no-flows-to-run" | "no-matching-trigger" | "no-pull-request" | "no-relevant-flows" | "rate-limited" | "run-not-created" | "test-configuration-error" | "trigger-not-found" | "workspace-inactive" | "workspace-not-ready" | undefined;
+            }[];
+        } | {
+            deploymentId: string;
+            outcome: "run-canceled";
+            runs: {
+                blockingBugCount: number;
+                runId: string;
+                runUrl: string;
+                status: "canceled" | "failed" | "passed" | "queued" | "running";
+                triggerName: string;
+            }[];
+        } | {
+            deploymentId: string;
+            elapsedMs: number;
+            lastStage: {
+                stage: "waiting-for-evaluation";
+            } | {
+                matchedTriggerCount: number;
+                stage: "waiting-for-run";
+            } | {
+                runs: {
+                    blockingBugCount: number;
+                    runId: string;
+                    runUrl: string;
+                    status: "canceled" | "failed" | "passed" | "queued" | "running";
+                    triggerName: string;
+                }[];
+                stage: "waiting-for-verdict";
+            };
+            outcome: "timed-out";
+            runs: {
+                blockingBugCount: number;
+                runId: string;
+                runUrl: string;
+                status: "canceled" | "failed" | "passed" | "queued" | "running";
+                triggerName: string;
+            }[];
+        } | {
+            deploymentId: string;
+            outcome: "canceled-by-caller";
+        } | {
+            deploymentId: string;
+            outcome: "unauthorized";
+            message?: string | undefined;
+        } | {
+            deploymentId: string;
+            outcome: "not-found";
+            message?: string | undefined;
+        } | {
+            deploymentId: string;
+            httpStatus: number;
+            outcome: "server-error";
+        } | {
+            deploymentId: string;
+            httpStatus: number;
+            outcome: "unexpected-status";
+            message?: string | undefined;
+        } | {
+            deploymentId: string;
+            outcome: "network-error";
+        } | {
+            deploymentId: string;
+            outcome: "invalid-response-body";
+        }>;
+    };
     generateSignedUrlForRunInputsExecutablesStorage: (config: import("./domain/generateSignedUrls/types.js").GenerateSignedUrlConfig) => Promise<import("./domain/generateSignedUrls/types.js").GenerateSignedUrlStatus>;
     generateSignedUrlForTempTeamStorage: (config: import("./domain/generateSignedUrls/types.js").GenerateSignedUrlConfig) => Promise<{
         fileLocation?: string;
@@ -19,9 +142,15 @@ export declare function makeQaWolfSdk({ apiKey, serviceBase, userAgent, }: {
     }>;
     makePollCiGreenlightStatusIterator: (args_0: import("./domain/pollCiGreenlight/types.js").MakePollCiGreenlightStatusIteratorParams) => AsyncGenerator<import("./domain/pollCiGreenlight/types.js").PollCiGreenlightIteration, void, unknown>;
     notifyTerminatedEphemeralEnvironment: (config: import("./domain/notifyTerminatedEphemeralEnvironment/types.js").NotifyTerminatedEphemeralEnvironmentInput) => Promise<import("./domain/notifyTerminatedEphemeralEnvironment/types.js").NotifyTerminatedEphemeralEnvironmentResult>;
+    /**
+     * @deprecated Polls a run id that only `attemptNotifyDeploy` returns, so it
+     * keeps the pipeline on the legacy `deploy_success` webhook.
+     */
     pollCiGreenlightStatus: (args_0: import("./domain/pollCiGreenlight/types.js").PollCiGreenlightParams) => Promise<import("./domain/pollCiGreenlight/types.js").PollCiGreenlightStatus>;
 };
 export type * from "./domain/attemptDeploy/index.js";
 export type * from "./domain/generateSignedUrls/types.js";
 export type * from "./domain/notifyTerminatedEphemeralEnvironment/types.js";
 export type * from "./domain/pollCiGreenlight/types.js";
+export type * from "./domain/reportDeployment/types.js";
+export type * from "./domain/waitForVerdict/types.js";

package/dist/lib/sdk/publicApi/callContract.d.ts

@@ -0,0 +1,39 @@
+import type { z } from "zod";
+import type { ApiConfig } from "../../api-types.js";
+import type { SdkDependencies } from "../dependencies.js";
+/**
+ * The structural shape of a `@qawolf/api-contracts` contract. Declared here
+ * because the package exports the contracts but not the type describing them.
+ */
+export type PublicApiContract<InputData = unknown, OutputData = unknown> = {
+    input: z.ZodType<unknown, InputData>;
+    name: string;
+    output: z.ZodType<OutputData>;
+};
+export type PublicApiCallFailure = {
+    /** The QA Wolf incident id to quote to support, when the server sent one. */
+    eventId: string | undefined;
+    httpStatus: number;
+    /** The server's explanation of the refusal, when it sent one. */
+    message: string | undefined;
+    outcome: "http-error";
+} | {
+    outcome: "network-error";
+}
+/** The server answered 2xx with a body the contract's output rejects. */
+ | {
+    outcome: "invalid-response-body";
+};
+export type PublicApiCallResult<Data> = {
+    data: Data;
+    outcome: "ok";
+} | PublicApiCallFailure;
+/**
+ * Calls one public API contract and validates the answer with that contract's
+ * own output schema, so a caller reads the contract's types rather than a
+ * hand-written copy of them.
+ */
+export declare function callPublicContract<InputData, OutputData>({ fetch: localFetch, log }: SdkDependencies, apiConfig: ApiConfig, { contract, input, }: {
+    contract: PublicApiContract<InputData, OutputData>;
+    input: InputData;
+}): Promise<PublicApiCallResult<OutputData>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qawolf/ci-sdk",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "private": false,
   "description": "A simple SDK for interacting with QAWolf in CI scripts.",
   "keywords": [],
@@ -23,18 +23,20 @@
     "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.71.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"
   },