@secureport/sdk 0.5.0

package/dist/resources/reports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reports.d.ts","sourceRoot":"","sources":["../../src/resources/reports.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C,oDAAoD;AACpD,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEtE;;;;;;;;;GASG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,UAAU,GAAG,KAAK,GAAG,OAAO,CAAC;AAEjE;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;AAE5D,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IAEnC;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,QAAQ,CAAC;IAElC;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IAEnC,8BAA8B;IAC9B,QAAQ,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;CAChD;AAID;;;;;;;GAOG;AACH,qBAAa,eAAe;IACd,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAAV,UAAU,EAAE,YAAY;IAErD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,QAAQ,CAAC;CAahE"}

package/dist/resources/reports.js

@@ -0,0 +1,50 @@
+const MACHINE_FORMATS = new Set(['json', 'markdown', 'csv', 'sarif']);
+/**
+ * Reports — the one resource whose response is never JSON. Every format
+ * `request` accepts is a raw, streamed body (`text/csv`,
+ * `application/sarif+json`, plain `application/json` text, …), so this
+ * resource is built on {@link SecureportClient.requestRaw} rather than the
+ * usual `request<T>()`, and hands the `Response` itself back to the caller
+ * to read as text, parse, or stream to a file.
+ */
+export class ReportsResource {
+    requestRaw;
+    constructor(requestRaw) {
+        this.requestRaw = requestRaw;
+    }
+    /**
+     * Renders a run into a report and streams it back. **Nothing is stored on
+     * the API side** — the bytes are produced from the run's snapshot on
+     * demand and exist only in this response; call this again for the same
+     * run and it renders again from whatever the run's snapshot is by then.
+     *
+     * **A failure partway through the stream cannot become an HTTP status.**
+     * The status and headers this method's `Response` carries are whatever was
+     * sent before the first byte of the body; nothing that goes wrong later in
+     * the stream can change them, so a truncated document looks identical to a
+     * complete one at this layer. Verify the body's own shape — that a JSON or
+     * SARIF document parses, that a CSV has the trailer row it expects — if a
+     * caller needs to be sure nothing was cut short.
+     *
+     * @throws {Error} synchronously, before any request is made, if
+     * `input.format` is `'pdf'` or `'html'` — this method exists only for
+     * `'json' | 'csv' | 'sarif' | 'markdown'`; a caller bypassing the type
+     * (plain JS, no type checker) is told so without spending a round trip.
+     * @throws {SecureportError} `conflict` if the run has not been reconciled
+     * — still running, or ended `failed`; `forbidden` should be unreachable
+     * given the format check above, but is still what the API itself would
+     * answer for `pdf`/`html`.
+     */
+    request(runId, input) {
+        if (!MACHINE_FORMATS.has(input.format)) {
+            throw new Error(`'${input.format}' reports are requested from the dashboard by a signed-in user — an ` +
+                'API key can export json, csv, sarif or markdown.');
+        }
+        return this.requestRaw({
+            method: 'POST',
+            path: `/runs/${encodeURIComponent(runId)}/reports`,
+            body: input,
+        });
+    }
+}
+//# sourceMappingURL=reports.js.map

package/dist/resources/reports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reports.js","sourceRoot":"","sources":["../../src/resources/reports.ts"],"names":[],"mappings":"AAsDA,MAAM,eAAe,GAAG,IAAI,GAAG,CAAe,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC;AAEpF;;;;;;;GAOG;AACH,MAAM,OAAO,eAAe;IACG;IAA7B,YAA6B,UAAwB;QAAxB,eAAU,GAAV,UAAU,CAAc;IAAG,CAAC;IAEzD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,OAAO,CAAC,KAAa,EAAE,KAAoB;QACzC,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;YACvC,MAAM,IAAI,KAAK,CACb,IAAI,KAAK,CAAC,MAAM,sEAAsE;gBACpF,kDAAkD,CACrD,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,CAAC,UAAU,CAAC;YACrB,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,SAAS,kBAAkB,CAAC,KAAK,CAAC,UAAU;YAClD,IAAI,EAAE,KAAK;SACZ,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/resources/runs.d.ts

@@ -0,0 +1,474 @@
+import type { Snapshot } from '@secureport/core';
+import type { FetchBody, Requester } from '../client.js';
+import type { Severity } from './issues.js';
+import type { Page, PageQuery } 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;
+}
+/**
+ * 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 declare class RunsResource {
+    private readonly request;
+    constructor(request: Requester);
+    list(query?: PageQuery & RunFilters): Promise<RunPage>;
+    /** Every run matching `filters`, across every page, as an async iterator. */
+    listAll(filters?: RunFilters): AsyncIterable<Run>;
+    /**
+     * 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>;
+    /**
+     * 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>;
+    /**
+     * 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>;
+    /**
+     * 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>;
+    /**
+     * 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>;
+    /**
+     * 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>;
+    /**
+     * 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>;
+    /**
+     * 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>;
+    /**
+     * 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>;
+    /**
+     * 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>;
+    /**
+     * 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`.
+     */
+    snapshot(id: string): Promise<Snapshot>;
+    /**
+     * 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.
+     */
+    waitUntilFinished(id: string, options?: WaitUntilFinishedOptions): Promise<Run>;
+    /**
+     * 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.
+     */
+    waitForArtifact(runId: string, artifactId: string, options?: WaitForArtifactOptions): Promise<RunArtifact>;
+}
+//# sourceMappingURL=runs.d.ts.map

package/dist/resources/runs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runs.d.ts","sourceRoot":"","sources":["../../src/resources/runs.ts"],"names":[],"mappings":"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"}