@zksecurity/zkao-sdk 0.20.0-next.15 → 0.25.0-next.17

package/dist/index.d.ts

@@ -145,18 +145,18 @@ interface paths {
             cookie?: never;
         };
         /**
-         * Get a repository's Continuous Testing schedule
-         * @description Requires scope: `read`. Continuous Testing scans one branch on a schedule paid from a monthly budget. With no schedule on the branch, `enabled` is false and the schedule fields are null. The recommended monthly budget funds a run about every three days at the repository's recommended per-run budget; the minimum funds a run every week at it.
+         * Get a repository's Continuous Security schedule
+         * @description Requires scope: `read`. Continuous Security scans one branch on a schedule paid from a monthly budget. With no schedule on the branch, `enabled` is false and the schedule fields are null. The recommended monthly budget supports ongoing analysis. The minimum funds one useful analysis step. Scheduling adapts to the available allocation.
          */
         get: operations["getContinuousTesting"];
         /**
-         * Turn Continuous Testing on, change it, or pause it
+         * Turn Continuous Security on, change it, or pause it
          * @description Requires scope: `automations:write`. Every field is optional. With no schedule on the branch, the request creates one at the recommended monthly budget unless `monthlyBudgetCredits` is given; `enabled: false` then changes nothing. The budget sets the interval smoothly from once a week to twice a day. The recommended budget funds a run about every three days. A budget outside the returned minimum and maximum is refused with `400`. Administrators can raise the maximum monthly budget. `areaKeys` replaces the audit areas runs rotate through, one per run. `enabled: false` pauses the schedule and keeps it. A change re-arms a schedule that had stopped. Each run still needs spendable credits when it launches.
          */
         put: operations["setContinuousTesting"];
         post?: never;
         /**
-         * Remove a repository's Continuous Testing schedule
+         * Remove a repository's Continuous Security schedule
          * @description Requires scope: `automations:write`. Scans the schedule already ran stay. Responds `404` when the branch has no schedule.
          */
         delete: operations["removeContinuousTesting"];
@@ -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;
@@ -196,6 +222,16 @@ interface paths {
          *     it. A malformed, unknown, or misplaced base is a `400` with code
          *     `diff_base_required`, `diff_base_not_allowed`, or `diff_base_invalid`.
          *     A diff scan also needs a change to audit (otherwise `422`).
+         *
+         *     The builtin presets come in two tiers. Flash runs fewer techniques on
+         *     a flash model. Max runs every technique on flagship models. Each tier
+         *     has a preset for the code (`builtin:Flash`, `builtin:Max`), a change
+         *     (`builtin:Flash Diff`, `builtin:Max Diff`), open findings
+         *     (`builtin:Flash Retriage`, `builtin:Max Retriage`) and resolved
+         *     findings (`builtin:Flash Regression Check`,
+         *     `builtin:Max Regression Check`). Earlier names, such as
+         *     `builtin:Rapid Review`, `builtin:Deep Audit` and `builtin:Diff Scan`,
+         *     still resolve.
          */
         post: operations["launchScan"];
         delete?: never;
@@ -528,6 +564,8 @@ interface paths {
         /**
          * Change a finding's resolution status
          * @description Requires scope: `findings:write`.
+         *
+         *     On a finding triage dismissed (`triageStatus` `FALSE_POSITIVE`), any status other than `FALSE_POSITIVE` or `DUPLICATE` reopens it: its `triageStatus` becomes `CONFIRMED` and the override fields record who did it. `NOT_STARTED` reopens it even when that is already its resolution. Setting `FALSE_POSITIVE` on a reopened finding undoes the reopen: the triage verdict comes back, the override is cleared, and the resolution returns to `NOT_STARTED`. The response carries the stored statuses.
          */
         patch: operations["updateFindingResolution"];
         trace?: never;
@@ -837,6 +875,14 @@ interface components {
             confirmationEvidence?: "POC" | "ANALYSIS" | null;
             resolutionStatus: components["schemas"]["ResolutionStatus"];
             notesCount: number;
+            /** @description Why triage dismissed the finding as a false positive. Null when triage did not dismiss it or gave no reason. */
+            dismissalReason: string | null;
+            /** @description The triage verdict a member replaced, kept from the first override. Null when nobody overrode triage. */
+            triageOverriddenFrom: components["schemas"]["TriageStatus"] | null;
+            /** Format: date-time */
+            triageOverriddenAt: string | null;
+            /** @description Name, or email when there is no name, of the member who overrode triage. */
+            triageOverriddenByName: string | null;
         };
         FindingNote: {
             id: string;
@@ -1024,7 +1070,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. */
+            /** @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. */
             creditBudget?: number;
             /** @description A preset ref from /scan-presets. Defaults to the first active preset. */
             presetRef?: string;
@@ -1035,10 +1081,21 @@ interface components {
             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. */
             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?: {
+                /** @description Also include In progress findings. Defaults to false. */
+                includeInProgress?: boolean;
+                /** @description Restrict the recheck to these findings. Eligibility is still checked against the selected repository and branch. Omit to include all eligible findings. Cannot be combined with resumeScanId. */
+                findingIds?: string[];
+                /** @description Continue a finished recheck's unassessed findings on the same repository. Uses that scan's branch, commit, and status selection. */
+                resumeScanId?: string;
+            };
             /** @description Where this launch came from, shown on the scan page. Optional, and display only: nothing in the pipeline reads it. */
             trigger?: components["schemas"]["ScanTrigger"] | null;
             /** @description Area keys from /audit-areas to scope this scan to. Omit or send an empty array to scan the whole repository. A key the repository's current map no longer names fails the launch rather than being dropped, so a scan budgeted for one subsystem never silently runs against everything. */
             auditAreaKeys?: string[];
+            /** @description The code to audit, described in your own words, instead of `auditAreaKeys`. Send one or the other, not both. */
+            auditScope?: string | null;
             /** @description Guidance for this scan only, replacing the repository's configured guidance layer (it is still layered over any committed zkao.md). Omit the field to inherit the repository's guidance; send null to scan with no guidance layer. */
             guidance?: string | null;
         };
@@ -1111,7 +1168,7 @@ interface components {
         };
         ContinuousTesting: {
             repositoryId: string;
-            /** @description False when Continuous Testing is not offered. */
+            /** @description False when Continuous Security is not offered. */
             available: boolean;
             /** @description False when there is no schedule or it is paused. */
             enabled: boolean;
@@ -1144,9 +1201,9 @@ interface components {
              * @description When the next run becomes due. A past time means within the hour. Null when paused or stopped.
              */
             nextRunAt: string | null;
-            /** @description A month that funds a run about every three days at the recommended per-run budget. */
+            /** @description A suggested allocation for ongoing work, based on the repository's estimated analysis budget. */
             recommendedMonthlyCredits: number | null;
-            /** @description A month that funds a weekly run at that budget. Less is refused. */
+            /** @description The smallest month that funds one analysis step. Less is refused. */
             minimumMonthlyCredits: number | null;
             /** @description The largest monthly budget currently allowed for the repository. Administrators can raise it. */
             maximumMonthlyCredits: number | null;
@@ -1180,6 +1237,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. */
@@ -1203,6 +1283,8 @@ interface components {
         FindingResolutionResult: {
             findingId: string;
             resolutionStatus: components["schemas"]["ResolutionStatus"];
+            /** @description The triage status after the change. It moves when the change reopens a finding triage dismissed, or undoes that reopen. */
+            triageStatus: components["schemas"]["TriageStatus"];
         };
         /**
          * @description Short code for why a finding is being closed, chosen from the set offered for the `resolutionStatus` it is sent with; a code belonging to a different status is rejected with 400. Ignored for the open statuses (`NOT_STARTED`, `IN_PROGRESS`) and when `note` is also given. It is not stored as a field: it is recorded as a comment on the finding stating what was chosen, which is returned by the notes endpoints.
@@ -1619,6 +1701,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?: {
@@ -2445,6 +2569,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"];
@@ -2744,6 +2870,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

@@ -529,6 +529,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.20.0-next.15",
+  "version": "0.25.0-next.17",
   "description": "TypeScript SDK for the zkao Project API",
   "license": "MIT",
   "author": "zkSecurity",