@secureport/sdk 0.5.0

package/src/resources/runs.ts

@@ -0,0 +1,635 @@
+import type { Snapshot } from '@secureport/core';
+import { parseSnapshot } from '@secureport/core';
+import type { FetchBody, Requester } from '../client.js';
+import type { Severity } from './issues.js';
+import type { Page, PageQuery } from '../pagination.js';
+import { paginate } from '../pagination.js';
+
+/**
+ * What kind of run this was — `scan` (Secureport originated the traffic,
+ * subject to `POST /runs`'s terms/verification gate), `upload` (results
+ * brought from elsewhere) or `manual` (a human recorded a finding directly).
+ * Mirrors `@secureport/core`'s `RunKind`; SDK-local for the same reason as
+ * `Issue`/`Finding` — see the module doc in `issues.ts`.
+ */
+export type RunKind = 'scan' | 'upload' | 'manual';
+
+/** What set the run going. Never defaulted — see {@link NewRun.trigger}. */
+export type RunTrigger = 'github_action' | 'cli' | 'api' | 'scheduled' | 'web';
+
+/**
+ * Where a run is in its lifecycle. `failed` and `cancelled` are both terminal
+ * and neither reconciles — see {@link RunsResource.cancel} for the difference.
+ */
+export type RunStatus = 'running' | 'finished' | 'failed' | 'cancelled';
+
+/**
+ * How much a scan does — the S/M/L/XL catalogue, smallest to largest, each
+ * size a strict superset of the one below. Mirrors `@secureport/core`.
+ */
+export type ScanSize = 's' | 'm' | 'l' | 'xl';
+
+/** What a run actually exercised. */
+export interface Coverage {
+  /** Location patterns the run covered, as globs, e.g. `https://app.example.com/**`. */
+  readonly paths: readonly string[];
+
+  /** Ports exercised, where the run was port-aware. */
+  readonly ports?: readonly number[];
+
+  /**
+   * Severity classes whose checks the run exercised; absent means not
+   * severity-scoped. A scoped run cannot resolve issues outside its classes.
+   */
+  readonly severities?: readonly Severity[];
+
+  /** Engines that took part. */
+  readonly engines: readonly string[];
+}
+
+/**
+ * One execution against a target.
+ *
+ * Date fields are ISO 8601 strings, as the API sends them — see
+ * {@link RunsResource.snapshot} for the one method in this resource that
+ * returns real `Date`s instead.
+ */
+export interface Run {
+  readonly id: string;
+  readonly orgId: string;
+  readonly targetId: string;
+  readonly kind: RunKind;
+  readonly trigger: RunTrigger;
+  readonly status: RunStatus;
+
+  /** How much this run does. Present exactly when `kind` is `'scan'`. */
+  readonly size?: ScanSize;
+  readonly coverage: Coverage;
+
+  /** The verification evidence a `kind: 'scan'` run was authorised against. */
+  readonly verificationId?: string;
+  readonly startedAt: string;
+  readonly finishedAt?: string;
+}
+
+export type RunPage = Page<Run>;
+
+/** The filters `list`/`listAll` take, beside the page. Both optional and combinable. */
+export interface RunFilters {
+  readonly targetId?: string;
+  readonly status?: RunStatus;
+}
+
+export interface NewRun {
+  readonly targetId: string;
+  readonly kind: RunKind;
+
+  /**
+   * Required, never defaulted — `00-DOMAIN.md` says trigger is set on every
+   * run from the first line of code, and a default would be a way of not
+   * saying.
+   */
+  readonly trigger: RunTrigger;
+
+  /**
+   * Scans only, defaulting to `'m'`; refused on kinds that originate no
+   * traffic. Sizes the service cannot run yet are refused, never downgraded.
+   */
+  readonly size?: ScanSize;
+
+  /**
+   * Absent means the whole target. Engines arrive with the results. Uploads
+   * only: a scan's coverage is derived server-side, and a claim is refused.
+   */
+  readonly coverage?: Coverage;
+}
+
+export interface FinishRunInput {
+  /**
+   * **`'failed'` reconciles nothing** — a failed run is not a complete
+   * observation, so {@link RunsResource.summary} and
+   * {@link RunsResource.snapshot} will 409 forever after. Only `'finished'`
+   * triggers reconciliation.
+   */
+  readonly status: 'finished' | 'failed';
+}
+
+/** A scan's phase, as {@link ScanProgress.phase} reports it. */
+export type ScanPhase = 'queued' | 'launching' | 'scanning' | 'ended';
+
+/**
+ * Where a scan is — {@link RunsResource.progress}'s answer.
+ *
+ * @remarks Deliberately no percentage: the engine reports nothing until it finishes, so the honest estimate is the time bound, not an invented fraction.
+ */
+export interface ScanProgress {
+  readonly runId: string;
+  readonly status: RunStatus;
+
+  /**
+   * How far the scan has got: `'queued'` (accepted, not yet launched),
+   * `'launching'`, `'scanning'`, or `'ended'` — `status` says how.
+   */
+  readonly phase: ScanPhase;
+
+  /** Seconds since the run started — up to now, or to when it ended. */
+  readonly elapsedSeconds: number;
+
+  /** The size's time budget. The engine is stopped when it runs out. */
+  readonly budgetSeconds: number;
+
+  /**
+   * When the run will have ended by, one way or the other: the budget plus
+   * launch and upload grace. An ISO 8601 string, like every date here.
+   */
+  readonly expectedBy: string;
+}
+
+/** Every field in a {@link RunSummary} that counts issues by severity. */
+export interface SeverityCounts {
+  readonly critical: number;
+  readonly high: number;
+  readonly medium: number;
+  readonly low: number;
+  readonly advisory: number;
+}
+
+/**
+ * What a run did, in the terms a report opens with. Written by
+ * reconciliation — see {@link RunsResource.summary}.
+ */
+export interface RunSummary {
+  readonly runId: string;
+  readonly orgId: string;
+  readonly targetId: string;
+  readonly kind: RunKind;
+  readonly trigger: RunTrigger;
+  readonly engines: readonly string[];
+  readonly coverage: Coverage;
+  readonly durationMs: number;
+  readonly new: SeverityCounts;
+  readonly stillOpen: SeverityCounts;
+  readonly resolved: SeverityCounts;
+  readonly regressed: SeverityCounts;
+  readonly ignored: SeverityCounts;
+  readonly exposureScore: number;
+  readonly createdAt: string;
+}
+
+/** Where one upload's parse stands. */
+export type ArtifactProcessingStatus = 'queued' | 'processing' | 'done' | 'failed';
+
+/**
+ * A raw scanner artifact archived against a run — what {@link RunsResource.import}
+ * and {@link RunsResource.listArtifacts} both return.
+ *
+ * `findingCount`/`skippedLines` are present once `processingStatus` is
+ * `'done'`; absent while `'queued'` or `'processing'`, since the parse simply
+ * has not happened yet.
+ */
+export interface RunArtifact {
+  readonly id: string;
+  readonly orgId: string;
+  readonly runId: string;
+  readonly objectName: string;
+  readonly filename: string;
+  readonly contentType: string;
+  readonly byteSize: number;
+  readonly sha256: string;
+  readonly sourceEngine?: string;
+  readonly expiresAt: string;
+  readonly processingStatus: ArtifactProcessingStatus;
+
+  /** Findings parsed from this upload. Present once `processingStatus` is `'done'`. */
+  readonly findingCount?: number;
+
+  /** Unreadable lines dropped from a line-delimited upload. Present with `'done'`. */
+  readonly skippedLines?: number;
+  readonly createdAt: string;
+}
+
+/** `GET /runs/{id}/artifacts`'s body — not a {@link Page}, since a run holds only a handful of files. */
+export interface RunArtifactList {
+  readonly data: readonly RunArtifact[];
+}
+
+export interface NewRunImport {
+  /**
+   * The scanner's raw output, sent exactly as given — never JSON-encoded,
+   * whatever type it is. A `Buffer`, `Uint8Array`, `Blob` or `string` all work.
+   */
+  readonly body: FetchBody;
+
+  /**
+   * Sent verbatim as the request's `content-type` — chosen by the caller,
+   * never inferred from `body`. Must be one the API accepts (JSON, NDJSON,
+   * JSONL, XML or plain text/CSV); anything else is a `415`.
+   */
+  readonly contentType: string;
+
+  /** Which importer parses this file, e.g. `'nuclei'`, `'zap'`, `'burp'`, `'nessus'` or `'generic'`. */
+  readonly engine: string;
+
+  /** Recorded for the report; trusted for nothing. */
+  readonly filename?: string;
+}
+
+/**
+ * What {@link RunsResource.createUploadUrl} needs to mint a signed URL — the
+ * digest and size the caller already knows, having the whole file in hand to
+ * upload it. Computed client-side and not re-verified byte-for-byte by the
+ * API (see {@link RunsResource.createUploadUrl}'s own `@throws` and TSDoc):
+ * that is the entire point of a signed URL over {@link RunsResource.import} —
+ * the bytes never transit the API for it to check.
+ */
+export interface NewRunImportUrl {
+  /** Lowercase hex SHA-256 of the file about to be uploaded. */
+  readonly sha256: string;
+
+  /** The file's exact size. Refused above the API's signed-upload ceiling. */
+  readonly byteSize: number;
+
+  /** Sent verbatim as the signed URL's bound content-type — must match the `PUT`'s own header exactly. */
+  readonly contentType: string;
+
+  /** Recorded for the report; trusted for nothing. */
+  readonly filename?: string;
+}
+
+/**
+ * A signed URL to `PUT` a large scanner artifact to, straight to the
+ * artifacts bucket — what {@link RunsResource.createUploadUrl} returns for a
+ * file not already archived on this run.
+ */
+export interface RunUploadUrl {
+  /** `PUT` the file here — nothing else, no query string of your own. */
+  readonly uploadUrl: string;
+
+  /** Hand this back to {@link RunsResource.completeUpload} once the `PUT` succeeds. */
+  readonly objectName: string;
+
+  /**
+   * Every one of these must be sent verbatim as headers on the `PUT`, or the
+   * bucket refuses the upload — this is what carries the file's retention
+   * period through a path that never calls the API's own archiving code.
+   */
+  readonly requiredHeaders: Readonly<Record<string, string>>;
+
+  /** The URL itself stops accepting a `PUT` after this — independent of the artifact's own retention. */
+  readonly urlExpiresAt: string;
+}
+
+/**
+ * What {@link RunsResource.completeUpload} needs once a signed-URL `PUT`
+ * succeeded: the object it wrote to, and what to parse it as.
+ */
+export interface CompleteRunImport {
+  /** From {@link RunUploadUrl.objectName} — the exact value {@link RunsResource.createUploadUrl} returned. */
+  readonly objectName: string;
+
+  /** Which importer parses this file, e.g. `'nuclei'`, `'zap'`, `'burp'`, `'nessus'` or `'generic'`. */
+  readonly engine: string;
+
+  /** Recorded for the report; trusted for nothing. */
+  readonly filename?: string;
+}
+
+/** {@link RunsResource.waitUntilFinished}'s options. */
+export interface WaitUntilFinishedOptions {
+  /**
+   * How often to poll {@link RunsResource.get} while the run is still `running`.
+   *
+   * @defaultValue 5000
+   */
+  readonly pollIntervalMs?: number;
+
+  /**
+   * How long to poll before giving up and rejecting.
+   *
+   * Sized for a hosted scan, not an upload: a run behind a busy queue can take
+   * minutes, not seconds.
+   *
+   * @defaultValue 900000 (15 minutes)
+   */
+  readonly timeoutMs?: number;
+}
+
+/** {@link RunsResource.waitForArtifact}'s options — same shape as {@link WaitUntilFinishedOptions}. */
+export interface WaitForArtifactOptions {
+  /**
+   * How often to poll {@link RunsResource.listArtifacts} while the artifact is
+   * still `queued` or `processing`.
+   *
+   * @defaultValue 5000
+   */
+  readonly pollIntervalMs?: number;
+
+  /**
+   * How long to poll before giving up and rejecting.
+   *
+   * @defaultValue 900000 (15 minutes)
+   */
+  readonly timeoutMs?: number;
+}
+
+const DEFAULT_POLL_INTERVAL_MS = 5_000;
+const DEFAULT_WAIT_TIMEOUT_MS = 900_000;
+
+/**
+ * Runs — one execution against a target, and the scan lifecycle around it
+ * (`00-DOMAIN.md` §3): started, evidence attached, finished, then
+ * reconciled into a summary and a snapshot.
+ */
+export class RunsResource {
+  constructor(private readonly request: Requester) {}
+
+  list(query?: PageQuery & RunFilters): Promise<RunPage> {
+    return this.request({ method: 'GET', path: '/runs', query: { ...query } });
+  }
+
+  /** Every run matching `filters`, across every page, as an async iterator. */
+  listAll(filters?: RunFilters): AsyncIterable<Run> {
+    return paginate((page) => this.list({ ...filters, page }));
+  }
+
+  /**
+   * Starts a run against a target. It is created `running` and stays that way
+   * until {@link RunsResource.finish}: upload scanner output in between with
+   * {@link RunsResource.import}.
+   *
+   * @throws {SecureportError} `terms_required` for every kind if the
+   * organisation has not accepted the current terms — a human accepts them at
+   * `POST /orgs/{orgId}/terms`; an API key cannot. `verification_required` for
+   * `kind: 'scan'` if the target has no currently-passing verification,
+   * re-checked fresh as part of this same request rather than trusted from a
+   * stored flag. Neither is retried by the transport: both are settled
+   * refusals, not transient ones.
+   */
+  create(input: NewRun): Promise<Run> {
+    return this.request({ method: 'POST', path: '/runs', body: input });
+  }
+
+  /**
+   * One run by id. What it found is {@link RunsResource.summary}, once it has finished —
+   * this method never carries a summary or findings itself.
+   */
+  get(id: string): Promise<Run> {
+    return this.request({ method: 'GET', path: `/runs/${encodeURIComponent(id)}` });
+  }
+
+  /**
+   * Ends a run and, for `status: 'finished'`, reconciles it: the findings
+   * uploaded against it become new, still-open, resolved or regressed
+   * issues, and the run gets a summary. **`status: 'failed'` reconciles
+   * nothing** — see {@link FinishRunInput.status}.
+   *
+   * @remarks Uploads and manual runs only: a `kind: 'scan'` run is refused here — its engine reports its own end, with evidence this route cannot supply. Stop a scan early with {@link RunsResource.cancel} instead.
+   * @throws {SecureportError} `conflict` if any upload is still being
+   * parsed — poll {@link RunsResource.listArtifacts} and finish once every
+   * one is `done` or `failed` — or if the run had already ended;
+   * `validation` for a `kind: 'scan'` run.
+   */
+  finish(id: string, input: FinishRunInput): Promise<Run> {
+    return this.request({
+      method: 'POST',
+      path: `/runs/${encodeURIComponent(id)}/finish`,
+      body: input,
+    });
+  }
+
+  /**
+   * Stops a running scan: the run ends as `'cancelled'` immediately, and the
+   * scan job behind it is cancelled best-effort.
+   *
+   * @remarks If the job cancel fails, the engine simply runs out its time budget and its late reports are discarded, so `'cancelled'` is final either way. Nothing is reconciled — a cancelled run resolves no issues, and findings already ingested stay recorded as partial evidence. That intent is what distinguishes it from `'failed'`, which means the scan itself went wrong.
+   * @throws {SecureportError} `conflict` if the run had already ended;
+   * `validation` for a run that is not a `kind: 'scan'` — an upload is ended
+   * by its own caller via {@link RunsResource.finish}.
+   */
+  cancel(id: string): Promise<Run> {
+    return this.request({ method: 'POST', path: `/runs/${encodeURIComponent(id)}/cancel` });
+  }
+
+  /**
+   * Where a scan is: its phase, how long it has run, its time budget, and
+   * when it will have ended by — see {@link ScanProgress} for why no percentage.
+   *
+   * @remarks Combine with {@link RunsResource.waitUntilFinished} for a poll that also knows when to give up: `expectedBy` is the honest bound.
+   * @throws {SecureportError} `validation` for a run that is not a
+   * `kind: 'scan'` — an upload's progress is whatever its caller is doing.
+   */
+  progress(id: string): Promise<ScanProgress> {
+    return this.request({ method: 'GET', path: `/runs/${encodeURIComponent(id)}/progress` });
+  }
+
+  /**
+   * Archives a raw scanner artifact against a run. Nothing is parsed on the
+   * client side — the whole file is handed to the API as `input.body`, with
+   * `input.contentType` sent verbatim, and the API decides how (and when) to
+   * parse it.
+   *
+   * **The response shape depends on size, not just success or failure.** A
+   * file under 5 MiB is parsed inline and answers `201` with
+   * `processingStatus: 'done'` and `findingCount`/`skippedLines` filled in. At
+   * or over 5 MiB the parse is queued and the API answers `202` with
+   * `processingStatus: 'queued'` instead — poll {@link RunsResource.listArtifacts}
+   * for the outcome. Both are success: check `processingStatus` on the result rather
+   * than assuming the synchronous shape. **25 MiB is a hard cap**, refused
+   * with `payload_too_large` rather than accepted and truncated.
+   *
+   * **Idempotent by content, not by request.** Re-uploading the exact same
+   * bytes against the same run answers `200` with the original row, verbatim
+   * — no re-parse — so a retried upload after a flaky network is never
+   * double-counted.
+   *
+   * @throws {SecureportError} `conflict` if the run has already ended;
+   * `payload_too_large` over 25 MiB; `unsupported_media_type` for a
+   * `contentType` the API does not accept, or a compressed body.
+   */
+  import(id: string, input: NewRunImport): Promise<RunArtifact> {
+    return this.request({
+      method: 'POST',
+      path: `/runs/${encodeURIComponent(id)}/import`,
+      query: { engine: input.engine, filename: input.filename },
+      rawBody: { data: input.body, contentType: input.contentType },
+    });
+  }
+
+  /**
+   * The first half of the signed-URL upload path for a file too large for
+   * {@link RunsResource.import} — Cloud Run caps that route's request body at
+   * 32 MiB whatever the API wants, so a genuinely large scan (a big Nessus or
+   * Burp export) goes here instead: mint a URL, `PUT` the file straight to
+   * the bucket yourself, then {@link RunsResource.completeUpload}.
+   *
+   * **Returns one of two shapes, told apart structurally.** If the same
+   * `sha256` is already archived on this run, this resolves with the
+   * existing {@link RunArtifact} directly — nothing minted, nothing to
+   * upload. Otherwise it resolves with a {@link RunUploadUrl}. Check for
+   * `'uploadUrl' in result` (or any field {@link RunUploadUrl} has and
+   * {@link RunArtifact} does not) to tell them apart.
+   *
+   * **You must `PUT` the bytes yourself, with a plain `fetch` — not through
+   * this SDK's own transport.** `uploadUrl` is a signed Cloud Storage URL:
+   * this client's `request`/`requestRaw` always attach your API key as a
+   * bearer token and always resolve paths against the API's own base URL,
+   * neither of which belongs on a request to Cloud Storage. Send every
+   * header in `result.requiredHeaders` verbatim — the bucket's signature
+   * check refuses the upload otherwise, silently from this SDK's point of
+   * view (it never sees that request).
+   *
+   * @throws {SecureportError} `conflict` if the run has already ended;
+   * `unsupported_media_type` for a `contentType` the API does not accept.
+   */
+  createUploadUrl(id: string, input: NewRunImportUrl): Promise<RunArtifact | RunUploadUrl> {
+    return this.request({
+      method: 'POST',
+      path: `/runs/${encodeURIComponent(id)}/import-url`,
+      body: input,
+    });
+  }
+
+  /**
+   * The second half of the signed-URL upload path — call once your own
+   * `PUT` to {@link RunUploadUrl.uploadUrl} has succeeded. Archives the
+   * object as a run artifact and queues it for parsing; unlike
+   * {@link RunsResource.import}, the result is never parsed synchronously
+   * here — anything that needed a signed URL is already well past the size
+   * the API parses inline. Poll {@link RunsResource.listArtifacts} (or use
+   * {@link RunsResource.waitForArtifact}) the same way a `202` from
+   * {@link RunsResource.import} is polled.
+   *
+   * **Idempotent by content, same as {@link RunsResource.import}.** Calling
+   * this twice for the same object answers `200` with the original row the
+   * second time.
+   *
+   * @throws {SecureportError} `conflict` if the run has already ended, or if
+   * nothing was actually uploaded to the signed URL (it may have expired).
+   */
+  completeUpload(id: string, input: CompleteRunImport): Promise<RunArtifact> {
+    return this.request({
+      method: 'POST',
+      path: `/runs/${encodeURIComponent(id)}/import-url/complete`,
+      body: input,
+    });
+  }
+
+  /**
+   * The uploads archived against a run, with where each parse stands — what
+   * a client polls after a `202` from {@link RunsResource.import}. Not
+   * paginated: a run holds the handful of files one scan produced.
+   */
+  listArtifacts(id: string): Promise<RunArtifactList> {
+    return this.request({ method: 'GET', path: `/runs/${encodeURIComponent(id)}/artifacts` });
+  }
+
+  /**
+   * What the run did, in the terms a report opens with.
+   *
+   * @throws {SecureportError} `conflict` if the run has not been reconciled
+   * — still running, or ended `failed` — rather than a zeroed summary that
+   * would read as "nothing found".
+   */
+  summary(id: string): Promise<RunSummary> {
+    return this.request({ method: 'GET', path: `/runs/${encodeURIComponent(id)}/summary` });
+  }
+
+  /**
+   * The snapshot a report is rendered from: the run summary, the target,
+   * every issue with what this run changed about it, and the suppressed
+   * appendix.
+   *
+   * **Returns `@secureport/core`'s own `Snapshot` type, with real `Date`s —
+   * the one method in this resource that does.** Every other method here
+   * returns ISO 8601 strings, mirroring the wire exactly; this one instead
+   * runs the response text through core's own `parseSnapshot`, since that
+   * is the exact function a `Snapshot` written to disk is read back
+   * with, and the API's wire shape is asserted `Exact<>` against core's type
+   * server-side. That is what makes `@secureport/core` this package's first
+   * real dependency, rather than a structural mirror.
+   *
+   * @throws {SecureportError} `conflict` if the run has not been reconciled
+   * — still running, or ended `failed`.
+   */
+  async snapshot(id: string): Promise<Snapshot> {
+    const body = await this.request<unknown>({
+      method: 'GET',
+      path: `/runs/${encodeURIComponent(id)}/snapshot`,
+    });
+    return parseSnapshot(JSON.stringify(body));
+  }
+
+  /**
+   * Polls {@link RunsResource.get} until the run leaves `'running'`,
+   * resolving with whatever it finished as. **Does not itself call
+   * {@link RunsResource.summary} or {@link RunsResource.snapshot}** — those
+   * still 409 until reconciliation completes, which is why this only
+   * watches `status`.
+   *
+   * Shaped for a long-running hosted scan from the start: today an upload
+   * run is finished by the caller directly, so this helper's payoff is
+   * mostly forward-looking until scans actually execute.
+   *
+   * @throws {Error} if `status` is still `'running'` once `timeoutMs` elapses.
+   */
+  async waitUntilFinished(id: string, options?: WaitUntilFinishedOptions): Promise<Run> {
+    const pollIntervalMs = options?.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const timeoutMs = options?.timeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS;
+    const deadline = Date.now() + timeoutMs;
+
+    for (;;) {
+      const run = await this.get(id);
+      if (run.status !== 'running') return run;
+
+      if (Date.now() + pollIntervalMs > deadline) {
+        throw new Error(`run ${id} did not finish within ${String(timeoutMs)}ms (still running).`);
+      }
+      await sleep(pollIntervalMs);
+    }
+  }
+
+  /**
+   * Polls {@link RunsResource.listArtifacts} until one artifact's
+   * `processingStatus` leaves `'queued'`/`'processing'`, resolving with it —
+   * the artifact-level completion {@link RunsResource.finish} itself waits
+   * on (its own TSDoc: "poll listArtifacts and finish once every one is done
+   * or failed"). A large upload answers {@link RunsResource.import} with
+   * `202 queued` before the parse has even started; this is what a caller
+   * that started one polls instead of hand-rolling the same loop.
+   *
+   * @throws {Error} if the artifact never appears on the run (id mismatch),
+   * or if it is still `queued`/`processing` once `timeoutMs` elapses.
+   */
+  async waitForArtifact(
+    runId: string,
+    artifactId: string,
+    options?: WaitForArtifactOptions,
+  ): Promise<RunArtifact> {
+    const pollIntervalMs = options?.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const timeoutMs = options?.timeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS;
+    const deadline = Date.now() + timeoutMs;
+
+    for (;;) {
+      const { data } = await this.listArtifacts(runId);
+      const artifact = data.find((a) => a.id === artifactId);
+      if (artifact === undefined) {
+        throw new Error(`artifact ${artifactId} not found on run ${runId}.`);
+      }
+      if (artifact.processingStatus !== 'queued' && artifact.processingStatus !== 'processing') {
+        return artifact;
+      }
+
+      if (Date.now() + pollIntervalMs > deadline) {
+        throw new Error(
+          `artifact ${artifactId} did not finish processing within ${String(timeoutMs)}ms ` +
+            `(still ${artifact.processingStatus}).`,
+        );
+      }
+      await sleep(pollIntervalMs);
+    }
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}