@zksecurity/zkao-sdk 0.25.0-next.16 → 0.27.0-next.18

package/dist/index.d.ts

@@ -165,6 +165,32 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/projects/{projectId}/repositories/{repositoryId}/reports": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * File a vulnerability report against a repository
+         * @description Requires scope: `reports:write`. Files a report into the programme that takes reports for this repository, as prose. It arrives exactly as a GitHub private vulnerability report does and is read and split into claims by the same step, so nothing downstream distinguishes them.
+         *
+         *     Returns with `intakeState: PENDING`. `investigateReport` refuses a report until that reaches `COMPLETE`, so poll `/projects/{projectId}/reports` before asking for an investigation.
+         *
+         *     Idempotent on content: the same title and body against the same repository name the same report, so a retried call returns the original with `200` rather than filing a second copy.
+         *
+         *     Free. The reading that follows is charged to the project, and the investigation is charged when someone asks for it.
+         */
+        post: operations["submitReport"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/projects/{projectId}/scans": {
         parameters: {
             query?: never;
@@ -736,8 +762,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} */
@@ -1044,7 +1072,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;
@@ -1053,7 +1081,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?: {
@@ -1078,6 +1106,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;
@@ -1211,6 +1241,29 @@ interface components {
             /** @description Claims queued for triage, or null when an investigation was already running and this call started nothing. */
             claimsQueued: number | null;
         };
+        SubmitReportRequest: {
+            /** @description One line naming the flaw. */
+            title: string;
+            /** @description What the flaw is, how to reach it, and what it costs. Prose: this is read and split into claims, so write it for a reader rather than as fields. Anything past the limit would be stored and never read. */
+            body: string;
+            /**
+             * @description What the reporter claims, which is not an assessment. It decides how closely the report is read, so an inflated claim costs the programme more.
+             * @enum {string|null}
+             */
+            claimedSeverity?: "CRITICAL" | "HIGH" | "MEDIUM" | "LOW" | "INFO" | null;
+            /** @description Who found it, all self-asserted. Used for attribution on the advisory, never for authorization. */
+            reporter?: {
+                name?: string | null;
+                email?: string | null;
+                githubLogin?: string | null;
+            };
+        };
+        SubmitReportResult: {
+            /** @description The identifier `investigateReport` takes. */
+            publicId: string;
+            /** @description Always PENDING here. The report is queued to be read and split into claims, and an investigation waits for COMPLETE. */
+            intakeState: string;
+        };
         /** @description Optionally attach or reuse a note alongside a resolution change. */
         ChangeNote: {
             /** @description Create a new note with this body. */
@@ -1652,6 +1705,48 @@ interface operations {
             404: components["responses"]["NotFound"];
         };
     };
+    submitReport: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                projectId: components["parameters"]["ProjectId"];
+                repositoryId: components["parameters"]["RepositoryId"];
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["SubmitReportRequest"];
+            };
+        };
+        responses: {
+            /** @description Already filed, by an identical earlier call */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["SubmitReportResult"];
+                };
+            };
+            /** @description Filed */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["SubmitReportResult"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+            409: components["responses"]["Conflict"];
+            429: components["responses"]["RateLimited"];
+        };
+    };
     listScans: {
         parameters: {
             query?: {
@@ -2478,6 +2573,8 @@ type UsageEventType = Schemas["UsageEventType"];
 type BillingSummary = Schemas["BillingSummary"];
 type InvestigateReportResult = Schemas["InvestigateReportResult"];
 type Report = Schemas["Report"];
+type SubmitReportRequest = Schemas["SubmitReportRequest"];
+type SubmitReportResult = Schemas["SubmitReportResult"];
 /** The triage statuses a report moves through. */
 type ReportStatus = "NEW" | "TRIAGING" | "NEEDS_INFO" | "ACCEPTED" | "DUPLICATE" | "REJECTED";
 type Advisory = Schemas["Advisory"];
@@ -2584,7 +2681,9 @@ type WaitForScanOptions = {
 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
@@ -2777,6 +2876,21 @@ declare class ZkaoClient {
      * confirmation mail is sent from the app.
      */
     addAdvisoryContact(contact: AdvisoryContactInput): Promise<AdvisoryContact>;
+    /**
+     * File a vulnerability report against one of the programme's repositories.
+     *
+     * Requires the `reports:write` scope. Send prose: this is read and split
+     * into claims for you, so write it for a reader rather than as fields.
+     *
+     * Comes back with `intakeState: "PENDING"`, because the reading is queued.
+     * {@link investigateReport} refuses the report until that reaches
+     * `COMPLETE`, so poll {@link listReports} before asking for one.
+     *
+     * Idempotent on content: the same title and body against the same
+     * repository name the same report, so a retry after a timeout returns the
+     * original rather than filing a second copy.
+     */
+    submitReport(repositoryId: string, report: SubmitReportRequest): Promise<SubmitReportResult>;
     /**
      * Reports the programme has received, newest first.
      *

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) {
@@ -529,6 +536,30 @@ var ZkaoClient = class {
     return unwrap(res).contact;
   }
   // --- Incoming reports ---------------------------------------------------
+  /**
+   * File a vulnerability report against one of the programme's repositories.
+   *
+   * Requires the `reports:write` scope. Send prose: this is read and split
+   * into claims for you, so write it for a reader rather than as fields.
+   *
+   * Comes back with `intakeState: "PENDING"`, because the reading is queued.
+   * {@link investigateReport} refuses the report until that reaches
+   * `COMPLETE`, so poll {@link listReports} before asking for one.
+   *
+   * Idempotent on content: the same title and body against the same
+   * repository name the same report, so a retry after a timeout returns the
+   * original rather than filing a second copy.
+   */
+  async submitReport(repositoryId, report) {
+    const res = await this.http.POST(
+      "/projects/{projectId}/repositories/{repositoryId}/reports",
+      {
+        params: { path: { ...this.path, repositoryId } },
+        body: report
+      }
+    );
+    return unwrap(res);
+  }
   /**
    * Reports the programme has received, newest first.
    *

package/package.json

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