@zksecurity/zkao-sdk 0.25.0-next.17 → 0.28.0-next.19

package/README.md

@@ -28,6 +28,13 @@ Every method is fully typed from the OpenAPI spec. Non-2xx responses throw
 Cancel a running or queued scan with `zkao.cancelScan(scanId)`; you are charged
 only for analysis already done and the rest of the reserved budget is released.
 
+Check `scan.triage` before relying on the results of a completed scan.
+Its `resume` offer provides the allowed credit budgets when triage stopped on budget.
+Resume with `resumeTriage(scanId, { creditBudget }, { idempotencyKey })`.
+Reuse the same key and budget when retrying that request.
+Track the returned run with `getTriageRun` or `waitForTriageRun`.
+Read the scan's `triage` again afterward to check for unfinished findings.
+
 Full docs, the CLI (`@zksecurity/zkao-cli`), and the OpenAPI contract:
 **https://github.com/zksecurity/zkao-sdk**
 

package/dist/index.d.ts

@@ -280,6 +280,46 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/projects/{projectId}/scans/{scanId}/triage/resume": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Resume triage after a budget stop
+         * @description Requires scope: `scans:launch`. The scan must be completed and settled, with unfinished findings and a latest triage run that stopped on budget. Uses the scan's settings and reserves the explicit budget in credits. The token's repository restrictions and spend allowance apply. Reusing the same idempotency key and budget returns the original run, including after it finishes, without reserving or spending again. A different budget with the same key returns 409. A new attempt requires a new key. Poll getTriageRun because the parent scan remains COMPLETED.
+         */
+        post: operations["resumeTriage"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/projects/{projectId}/scans/{scanId}/triage/runs/{runId}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get one triage run
+         * @description Requires scope: `read`. Follows this run independently of the scan status. A COMPLETED run can still leave findings unfinished. Check scan.triage after it ends. Failed attempts awaiting retry remain QUEUED.
+         */
+        get: operations["getTriageRun"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/projects/{projectId}/reports": {
         parameters: {
             query?: never;
@@ -762,8 +802,10 @@ interface components {
         Error: {
             error: {
                 /** @enum {string} */
-                code: "unauthorized" | "forbidden" | "not_found" | "bad_request" | "conflict" | "insufficient_credits" | "repository_initializing" | "diff_base_required" | "diff_base_not_allowed" | "diff_base_invalid" | "diff_empty" | "rate_limited" | "internal";
+                code: "unauthorized" | "forbidden" | "not_found" | "bad_request" | "conflict" | "insufficient_credits" | "budget_below_minimum" | "repository_initializing" | "diff_base_required" | "diff_base_not_allowed" | "diff_base_invalid" | "diff_empty" | "rate_limited" | "internal";
                 message: string;
+                /** @description budget_below_minimum only: the least the launch could have reserved, in credits. A diff scan's first scan of a repository also builds its overview, so its minimum is higher. */
+                minimumCredits?: number;
             };
         };
         /** @enum {string} */
@@ -848,7 +890,35 @@ interface components {
             /** @description Weighted completion. Each phase counts for its share of the scan budget, so this does not simply equal phasesCompleted / phasesTotal. */
             percent: number;
         };
+        TriageResumeBudget: {
+            minCredits: number;
+            recommendedCredits: number;
+            maxCredits: number;
+        };
+        /** @description Completeness of triage, independent of whether the scan succeeded. */
+        ScanTriage: {
+            /** @enum {string} */
+            status: "pending" | "running" | "complete" | "budget_exhausted" | "blocked";
+            untriagedCount: number;
+            activeRunId: string | null;
+            resume: components["schemas"]["TriageResumeBudget"] | null;
+        };
+        TriageRun: {
+            id: string;
+            scanId: string;
+            /** @enum {string} */
+            status: "QUEUED" | "RUNNING" | "COMPLETED" | "FAILED" | "CANCELLED";
+            /** @description Number of findings selected when this run started. */
+            findingCount: number;
+            /** Format: date-time */
+            createdAt: string;
+            /** Format: date-time */
+            completedAt: string | null;
+            /** @description Whether this run reached its budget cap. Check scan.triage for remaining work. */
+            budgetExhausted: boolean;
+        };
         ScanDetail: components["schemas"]["Scan"] & {
+            triage: components["schemas"]["ScanTriage"];
             branch?: string | null;
             /** @description Reserved budget for the scan, in credits. */
             creditBudget?: number | null;
@@ -1070,7 +1140,7 @@ interface components {
         };
         LaunchScanRequest: {
             repositoryId: string;
-            /** @description Max budget for the scan, in credits. Reserved at launch. Omit it to launch at the budget zkao recommends for this scan type and scope on this repository. That is the last such scan's budget, or half again when that scan ran short of it, never above twice the scan type's minimum. A first scan starts at twice the minimum. A diff scan is sized from its change instead: the minimum for up to 500 changed lines, then in proportion, up to three times the minimum. */
+            /** @description Max budget for the scan, in credits. Reserved at launch. Omit it to launch at the budget zkao recommends for this scan type and scope on this repository. A Flash or Max scan of the code is sized from the audit areas it reads: the selected areas, or every area in the repository map. One area gets the minimum, and the budget grows with the square root of the area count. With no map, or with `auditScope`, it is twice the minimum. It is half again the last budget when the last scan of the same scope ran short of it. A diff scan is sized from its change instead: the minimum for up to 500 changed lines, then in proportion, up to three times the minimum. Other scan types use the last such scan's budget, or half again when that scan ran short of it, and a first scan starts at twice the minimum. Except for a diff, the recommendation never exceeds twice the minimum. A budget below the minimum is refused with `400` `budget_below_minimum`, whose `minimumCredits` names it. */
             creditBudget?: number;
             /** @description A preset ref from /scan-presets. Defaults to the first active preset. */
             presetRef?: string;
@@ -1079,7 +1149,7 @@ interface components {
             /** @description Pin a specific commit SHA (7-40 hex chars). */
             commitHash?: string | null;
             commitMessage?: string | null;
-            /** @description What a diff scan's change is measured from: a commit SHA, branch, or tag. Required by a diff scan preset and refused by every other. The scan records the merge base of this and the scanned commit. */
+            /** @description What a diff scan's change is measured from: a commit SHA, branch, or tag. Required by a diff scan preset and refused by every other. The scan records the merge base of this and the scanned commit. When no earlier scan of the repository built its overview, the diff scan builds one first, and its minimum and recommended budgets rise. */
             baseCommit?: string | null;
             /** @description Options for Recheck open findings. Omit to reassess eligible Not started findings on the selected branch. Fresh rechecks require the branch's latest commit and reject a pinned commit or audit scope. */
             backlogRecheck?: {
@@ -1104,6 +1174,8 @@ interface components {
             queued: boolean;
             /** @description The budget the scan was launched with, in credits. */
             creditBudget: number;
+            /** @description True when no earlier scan of the repository built its overview, so this diff scan builds one first. It takes longer, and its minimum and recommended budgets are higher. */
+            buildsOverview: boolean;
         };
         RepositoryGuidance: {
             repositoryId: string;
@@ -1864,6 +1936,80 @@ interface operations {
             429: components["responses"]["RateLimited"];
         };
     };
+    resumeTriage: {
+        parameters: {
+            query?: never;
+            header: {
+                /** @description Stable request key. Reuse it with the same budget when retrying. */
+                "Idempotency-Key": string;
+            };
+            path: {
+                projectId: components["parameters"]["ProjectId"];
+                scanId: components["parameters"]["ScanId"];
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    creditBudget: number;
+                };
+            };
+        };
+        responses: {
+            /** @description The new or previously created triage run. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        run: components["schemas"]["TriageRun"];
+                        replayed: boolean;
+                    };
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            402: components["responses"]["InsufficientCredits"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+            409: components["responses"]["Conflict"];
+            429: components["responses"]["RateLimited"];
+        };
+    };
+    getTriageRun: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                projectId: components["parameters"]["ProjectId"];
+                scanId: components["parameters"]["ScanId"];
+                runId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    /** @description Advisory seconds before polling an active run again. */
+                    "Retry-After"?: number;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        run: components["schemas"]["TriageRun"];
+                    };
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+            429: components["responses"]["RateLimited"];
+        };
+    };
     listReports: {
         parameters: {
             query?: {
@@ -2546,6 +2692,11 @@ type ScanPreset = Schemas["ScanPreset"];
 type LaunchScanRequest = Schemas["LaunchScanRequest"];
 type LaunchScanResult = Schemas["LaunchScanResult"];
 type CancelScanResult = Schemas["CancelScanResult"];
+type ScanTriage = Schemas["ScanTriage"];
+type TriageRun = Schemas["TriageRun"];
+type ResumeTriageOperation = paths["/projects/{projectId}/scans/{scanId}/triage/resume"]["post"];
+type ResumeTriageRequest = ResumeTriageOperation["requestBody"]["content"]["application/json"];
+type ResumeTriageResult = ResumeTriageOperation["responses"][200]["content"]["application/json"];
 type ChangeNote = Schemas["ChangeNote"];
 type Severity = Schemas["Severity"];
 type ResolutionStatus = Schemas["ResolutionStatus"];
@@ -2673,11 +2824,17 @@ type WaitForScanOptions = {
     /** Called with the latest detail on each non-terminal poll (for progress UI). */
     onPoll?: (scan: ScanDetail) => void;
 };
+type WaitForTriageRunOptions = Omit<WaitForScanOptions, "onPoll"> & {
+    /** Called with the requested triage run on each non-terminal poll. */
+    onPoll?: (run: TriageRun) => void;
+};
 /** Thrown for any non-2xx response, carrying the API error envelope. */
 declare class ZkaoApiError extends Error {
     readonly status: number;
     readonly code: string;
-    constructor(status: number, code: string, message: string);
+    /** `budget_below_minimum` only: the least the launch could reserve, in credits. */
+    readonly minimumCredits?: number;
+    constructor(status: number, code: string, message: string, minimumCredits?: number);
 }
 /**
  * Typed client for one zkao project. Every call is scoped to the project the
@@ -2790,6 +2947,13 @@ declare class ZkaoClient {
      */
     waitForScan(scanId: string, opts?: WaitForScanOptions): Promise<ScanDetail>;
     launchScan(body: LaunchScanRequest): Promise<LaunchScanResult>;
+    /** Resume budget-stopped triage. Reuse the key and budget when retrying. */
+    resumeTriage(scanId: string, body: ResumeTriageRequest, opts: {
+        idempotencyKey: string;
+    }): Promise<ResumeTriageResult>;
+    getTriageRun(scanId: string, runId: string): Promise<TriageRun>;
+    /** Wait for one run. Read scan.triage afterward to check result completeness. */
+    waitForTriageRun(scanId: string, runId: string, opts?: WaitForTriageRunOptions): Promise<TriageRun>;
     /**
      * Cancel a running or queued scan. Signals in-flight jobs to stop, marks the
      * scan CANCELLED, and releases its reserved credits. A scan already in a
@@ -2988,4 +3152,4 @@ declare class ZkaoClient {
     }): Promise<UsageMonthSummary[]>;
 }
 
-export { type Advisory, type AdvisoryAffected, type AdvisoryAffectedInput, type AdvisoryContact, type AdvisoryContactInput, type AdvisoryDetail, type AdvisoryNotice, type AdvisoryStatus, type BillingBalance, type BillingSummary, type BillingUsage, type CancelScanResult, type ChangeNote, type ContactStatus, type ContactTier, type ContinuousTesting, DEFAULT_BASE_URL, type Finding, type FindingDetail, type FindingNote, type LaunchScanRequest, type LaunchScanResult, type ManualAuditRequest, type ManualAuditResult, type Paginated, type PublishArtifactResult, type RemoveContinuousTestingResult, type Report, type ReportStatus, type Repository, type RepositoryGuidance, type ResolutionReason, type ResolutionStatus, type Scan, type ScanDetail, type ScanPreset, type ScanStatus, type SetContinuousTestingRequest, type SetGuidanceResult, type Severity, TERMINAL_SCAN_STATUSES, type TokenInfo, type TriageStatus, type UsageEvent, type UsageEventType, type UsageMonthSummary, type WaitForRepositoryReadyOptions, type WaitForScanOptions, ZkaoApiError, ZkaoClient, type ZkaoClientOptions, type components, getTokenInfo, isTerminalScanStatus, normalizeBaseUrl, type paths, resolveBaseUrlFromEnv };
+export { type Advisory, type AdvisoryAffected, type AdvisoryAffectedInput, type AdvisoryContact, type AdvisoryContactInput, type AdvisoryDetail, type AdvisoryNotice, type AdvisoryStatus, type BillingBalance, type BillingSummary, type BillingUsage, type CancelScanResult, type ChangeNote, type ContactStatus, type ContactTier, type ContinuousTesting, DEFAULT_BASE_URL, type Finding, type FindingDetail, type FindingNote, type LaunchScanRequest, type LaunchScanResult, type ManualAuditRequest, type ManualAuditResult, type Paginated, type PublishArtifactResult, type RemoveContinuousTestingResult, type Report, type ReportStatus, type Repository, type RepositoryGuidance, type ResolutionReason, type ResolutionStatus, type ResumeTriageRequest, type ResumeTriageResult, type Scan, type ScanDetail, type ScanPreset, type ScanStatus, type ScanTriage, type SetContinuousTestingRequest, type SetGuidanceResult, type Severity, TERMINAL_SCAN_STATUSES, type TokenInfo, type TriageRun, type TriageStatus, type UsageEvent, type UsageEventType, type UsageMonthSummary, type WaitForRepositoryReadyOptions, type WaitForScanOptions, type WaitForTriageRunOptions, ZkaoApiError, ZkaoClient, type ZkaoClientOptions, type components, getTokenInfo, isTerminalScanStatus, normalizeBaseUrl, type paths, resolveBaseUrlFromEnv };

package/dist/index.js

@@ -81,11 +81,16 @@ function isTerminalScanStatus(status) {
 var ZkaoApiError = class extends Error {
   status;
   code;
-  constructor(status, code, message) {
+  /** `budget_below_minimum` only: the least the launch could reserve, in credits. */
+  minimumCredits;
+  constructor(status, code, message, minimumCredits) {
     super(message);
     this.name = "ZkaoApiError";
     this.status = status;
     this.code = code;
+    if (minimumCredits !== void 0) {
+      this.minimumCredits = minimumCredits;
+    }
   }
 };
 function unwrap(result) {
@@ -93,10 +98,12 @@ function unwrap(result) {
     return result.data;
   }
   const envelope = result.error;
+  const minimumCredits = envelope?.error?.minimumCredits;
   throw new ZkaoApiError(
     result.response.status,
     envelope?.error?.code ?? "error",
-    envelope?.error?.message ?? result.response.statusText
+    envelope?.error?.message ?? result.response.statusText,
+    typeof minimumCredits === "number" ? minimumCredits : void 0
   );
 }
 async function getTokenInfo(options) {
@@ -400,6 +407,52 @@ var ZkaoClient = class {
     });
     return unwrap(res);
   }
+  /** Resume budget-stopped triage. Reuse the key and budget when retrying. */
+  async resumeTriage(scanId, body, opts) {
+    const res = await this.http.POST("/projects/{projectId}/scans/{scanId}/triage/resume", {
+      params: {
+        path: { ...this.path, scanId },
+        header: { "Idempotency-Key": opts.idempotencyKey }
+      },
+      body
+    });
+    return unwrap(res);
+  }
+  async getTriageRun(scanId, runId) {
+    const res = await this.http.GET("/projects/{projectId}/scans/{scanId}/triage/runs/{runId}", {
+      params: { path: { ...this.path, scanId, runId } }
+    });
+    return unwrap(res).run;
+  }
+  /** Wait for one run. Read scan.triage afterward to check result completeness. */
+  async waitForTriageRun(scanId, runId, opts = {}) {
+    const intervalMs = opts.intervalMs ?? 5e3;
+    const maxIntervalMs = opts.maxIntervalMs ?? 3e4;
+    const timeoutMs = opts.timeoutMs ?? 60 * 60 * 1e3;
+    const deadline = Date.now() + timeoutMs;
+    for (let attempt = 0; ; attempt++) {
+      throwIfAborted(opts.signal);
+      const res = await this.http.GET("/projects/{projectId}/scans/{scanId}/triage/runs/{runId}", {
+        params: { path: { ...this.path, scanId, runId } },
+        signal: opts.signal
+      });
+      const retryAfterMs = parseRetryAfterMs(res.response.headers.get("retry-after"));
+      if (res.response.status !== 429) {
+        const run = unwrap(res).run;
+        if (run.status === "COMPLETED" || run.status === "FAILED" || run.status === "CANCELLED") {
+          return run;
+        }
+        opts.onPoll?.(run);
+      }
+      const backoffMs = Math.min(maxIntervalMs, Math.round(intervalMs * 1.5 ** attempt));
+      const baseMs = retryAfterMs ?? backoffMs;
+      const delayMs = baseMs + Math.round(Math.random() * baseMs * 0.2);
+      if (Date.now() + delayMs > deadline) {
+        throw new Error(`Timed out waiting for triage run ${runId} to finish after ${timeoutMs}ms`);
+      }
+      await sleep(delayMs, opts.signal);
+    }
+  }
   /**
    * Cancel a running or queued scan. Signals in-flight jobs to stop, marks the
    * scan CANCELLED, and releases its reserved credits. A scan already in a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zksecurity/zkao-sdk",
-  "version": "0.25.0-next.17",
+  "version": "0.28.0-next.19",
   "description": "TypeScript SDK for the zkao Project API",
   "license": "MIT",
   "author": "zkSecurity",