@zksecurity/zkao-sdk 0.27.0-next.18 → 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;
@@ -850,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;
@@ -1868,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?: {
@@ -2550,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"];
@@ -2677,6 +2824,10 @@ 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;
@@ -2796,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
@@ -2994,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

@@ -407,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.27.0-next.18",
+  "version": "0.28.0-next.19",
   "description": "TypeScript SDK for the zkao Project API",
   "license": "MIT",
   "author": "zkSecurity",