@zksecurity/zkao-sdk 0.2.0 → 0.5.0

package/dist/index.d.ts

@@ -73,6 +73,50 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/projects/{projectId}/repositories/{repositoryId}/audit-areas": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List a repository's audit areas
+         * @description Requires scope: `read`. Audit areas are the named subsystems a scan can be scoped to (`auditAreaKeys` on launch). Each scan that maps the repository keeps the list current; sizes come from one branch's map, so an area that map no longer names is returned without one.
+         */
+        get: operations["listAuditAreas"];
+        put?: never;
+        /**
+         * Add a custom audit area
+         * @description Requires scope: `guidance:write`. An area is a name and a description, never a file list: a scan resolves it against the code at the commit it runs on. The `key` is derived from the name and disambiguated on collision.
+         */
+        post: operations["createAuditArea"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/projects/{projectId}/repositories/{repositoryId}/audit-areas/{areaKey}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post?: never;
+        /**
+         * Delete a custom audit area
+         * @description Requires scope: `guidance:write`. Only an area with `source: custom` can be deleted; a discovered one is the map's own account of the repository and is refused with `409`. Scans that already ran keep the scope they ran with.
+         */
+        delete: operations["deleteAuditArea"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/projects/{projectId}/scans": {
         parameters: {
             query?: never;
@@ -93,6 +137,10 @@ interface paths {
          *     ACTIVE. Discover valid `presetRef` / `optInFlowIds` via the discovery
          *     endpoints. Per-token spend limits are enforced, and the project must have
          *     enough prepaid credits to cover the budget (otherwise `402`).
+         *
+         *     A repository added moments ago may still be analyzing, in which case
+         *     this returns `409 repository_initializing`. Wait for its `readiness` to
+         *     be `ready` in `GET /repositories` and launch again.
          */
         post: operations["launchScan"];
         delete?: never;
@@ -330,7 +378,7 @@ interface paths {
         };
         /**
          * List opt-in flows available at launch
-         * @description Requires scope: `read`. Pass the chosen ids as `optInFlowIds` when launching.
+         * @description Requires scope: `read`. Pass the chosen ids as `optInFlowIds` when launching. A flow marked `rotating` may run without being asked for.
          */
         get: operations["listOptionalFlows"];
         put?: never;
@@ -445,7 +493,7 @@ interface components {
         Error: {
             error: {
                 /** @enum {string} */
-                code: "unauthorized" | "forbidden" | "not_found" | "bad_request" | "conflict" | "insufficient_credits" | "rate_limited" | "internal";
+                code: "unauthorized" | "forbidden" | "not_found" | "bad_request" | "conflict" | "insufficient_credits" | "repository_initializing" | "rate_limited" | "internal";
                 message: string;
             };
         };
@@ -465,6 +513,11 @@ interface components {
             defaultBranch?: string | null;
             /** @description ACTIVE | MARKED_FOR_DELETION */
             status: string;
+            /**
+             * @description Whether a scan can start on this repository. A newly added repository is `analyzing` until a one-time pass over it finishes; launching a scan meanwhile fails with `repository_initializing`. Poll this endpoint rather than retrying the launch blind.
+             * @enum {string}
+             */
+            readiness: "ready" | "analyzing";
         };
         Scan: {
             id: string;
@@ -567,6 +620,8 @@ interface components {
             flowId: string;
             title: string;
             description: string;
+            /** @description True when this flow belongs to a group the preset rotates through. Some of the group runs on every scan without being asked for, and which members depends on the repository. Naming it in `optInFlowIds` adds it whether or not the rotation picked it, and raises the scan's minimum budget. */
+            rotating: boolean;
         };
         LaunchScanRequest: {
             repositoryId: string;
@@ -579,8 +634,10 @@ interface components {
             /** @description Pin a specific commit SHA (7-40 hex chars). */
             commitHash?: string | null;
             commitMessage?: string | null;
-            /** @description Optional-flow ids from /optional-flows. */
+            /** @description Optional-flow ids from /optional-flows, added to the scan on top of whatever a rotating group already contributes. */
             optInFlowIds?: string[];
+            /** @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 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;
         };
@@ -611,6 +668,44 @@ interface components {
             /** @description True when the content already matched (no revision recorded). */
             unchanged: boolean;
         };
+        AuditArea: {
+            /** @description Stable slug, unique per repository. Pass it in `auditAreaKeys` when launching a scan. */
+            key: string;
+            name: string;
+            description: string | null;
+            /**
+             * @description `discovered` was named by a scan's map of the repository; `custom` was added through this API or the app.
+             * @enum {string}
+             */
+            source: "discovered" | "custom";
+            /** @description Whether the branch's latest map still names this area. */
+            inLatestMap: boolean;
+            /** @description Files this area covers at that map. Null when the map does not name it. */
+            files: number | null;
+            /** @description Lines this area covers at that map. Null when the map does not name it. */
+            lines: number | null;
+        };
+        AuditAreaList: {
+            repositoryId: string;
+            /** @description Branch the sizes were read from. */
+            branch: string | null;
+            /** @description Whether that branch has a stored map at all. */
+            mapped: boolean;
+            totalFiles: number | null;
+            totalLines: number | null;
+            /** @description The map's own audit order first, then the areas it no longer names. */
+            areas: components["schemas"]["AuditArea"][];
+        };
+        CreateAuditAreaRequest: {
+            name: string;
+            /** @description What this part of the code does. */
+            description?: string | null;
+        };
+        DeleteAuditAreaResult: {
+            repositoryId: string;
+            key: string;
+            deleted: boolean;
+        };
         CancelScanResult: {
             scanId: string;
             /** @description Terminal status after cancellation (always CANCELLED). */
@@ -696,6 +791,15 @@ interface components {
                 "application/json": components["schemas"]["Error"];
             };
         };
+        /** @description The repository is still being analyzed and cannot be scanned yet. The same request succeeds once `GET /repositories` reports its `readiness` as `ready`. (code `repository_initializing`) */
+        RepositoryInitializing: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["Error"];
+            };
+        };
         /** @description The token lacks the required scope */
         Forbidden: {
             headers: {
@@ -833,6 +937,97 @@ interface operations {
             409: components["responses"]["Conflict"];
         };
     };
+    listAuditAreas: {
+        parameters: {
+            query?: {
+                /** @description Branch whose map the sizes come from. Defaults to the repository's default branch. */
+                branch?: string;
+            };
+            header?: never;
+            path: {
+                projectId: components["parameters"]["ProjectId"];
+                repositoryId: components["parameters"]["RepositoryId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AuditAreaList"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+        };
+    };
+    createAuditArea: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                projectId: components["parameters"]["ProjectId"];
+                repositoryId: components["parameters"]["RepositoryId"];
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["CreateAuditAreaRequest"];
+            };
+        };
+        responses: {
+            /** @description Created */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        area: components["schemas"]["AuditArea"];
+                    };
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+            409: components["responses"]["Conflict"];
+        };
+    };
+    deleteAuditArea: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                projectId: components["parameters"]["ProjectId"];
+                repositoryId: components["parameters"]["RepositoryId"];
+                areaKey: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["DeleteAuditAreaResult"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+            409: components["responses"]["Conflict"];
+        };
+    };
     listScans: {
         parameters: {
             query?: {
@@ -890,6 +1085,7 @@ interface operations {
             402: components["responses"]["InsufficientCredits"];
             403: components["responses"]["Forbidden"];
             404: components["responses"]["NotFound"];
+            409: components["responses"]["RepositoryInitializing"];
             429: components["responses"]["RateLimited"];
         };
     };
@@ -1368,6 +1564,9 @@ type TriageStatus = Schemas["TriageStatus"];
 type ScanStatus = Schemas["ScanStatus"];
 type PublishArtifactResult = Schemas["PublishArtifactResult"];
 type RepositoryGuidance = Schemas["RepositoryGuidance"];
+type AuditArea = Schemas["AuditArea"];
+type AuditAreaList = Schemas["AuditAreaList"];
+type DeleteAuditAreaResult = Schemas["DeleteAuditAreaResult"];
 type SetGuidanceResult = Schemas["SetGuidanceResult"];
 type BillingBalance = Schemas["BillingBalance"];
 type BillingUsage = Schemas["BillingUsage"];
@@ -1398,6 +1597,16 @@ type ZkaoClientOptions = {
 /** Terminal scan statuses: polling can stop once a scan reaches one of these. */
 declare const TERMINAL_SCAN_STATUSES: readonly ScanStatus[];
 declare function isTerminalScanStatus(status: ScanStatus): boolean;
+type WaitForRepositoryReadyOptions = {
+    /** First poll delay, in ms (default 5000). Grows with backoff up to maxIntervalMs. */
+    intervalMs?: number;
+    /** Cap on the poll delay, in ms (default 30000). */
+    maxIntervalMs?: number;
+    /** Give up after this long, in ms (default 30m). Throws on timeout. */
+    timeoutMs?: number;
+    /** Abort the wait (e.g. on Ctrl-C). Rejects with the abort reason. */
+    signal?: AbortSignal;
+};
 type WaitForScanOptions = {
     /** First poll delay, in ms (default 5000). Grows with backoff up to maxIntervalMs. */
     intervalMs?: number;
@@ -1426,6 +1635,15 @@ declare class ZkaoClient {
     constructor(options: ZkaoClientOptions);
     private get path();
     listRepositories(): Promise<Repository[]>;
+    /**
+     * Block until a repository is ready to scan, then return it.
+     *
+     * A repository added moments ago is still being analyzed, and launching a
+     * scan against it fails with `repository_initializing`. Call this between
+     * adding a repository and launching its first scan rather than retrying the
+     * launch and swallowing the error.
+     */
+    waitForRepositoryReady(repositoryId: string, opts?: WaitForRepositoryReadyOptions): Promise<Repository>;
     /** Read a repository's configured guidance (requires the `read` scope). */
     getRepositoryGuidance(repositoryId: string): Promise<RepositoryGuidance>;
     /**
@@ -1438,6 +1656,30 @@ declare class ZkaoClient {
     setRepositoryGuidance(repositoryId: string, content: string | null, opts?: {
         expectedContent?: string | null;
     }): Promise<SetGuidanceResult>;
+    /**
+     * List a repository's audit areas (requires the `read` scope).
+     *
+     * An area is a named subsystem a scan can be scoped to: pass its `key` in
+     * `auditAreaKeys` when launching. Sizes come from one branch's map, so an
+     * area that map no longer names is returned without one. Defaults to the
+     * repository's default branch.
+     */
+    listAuditAreas(repositoryId: string, opts?: {
+        branch?: string;
+    }): Promise<AuditAreaList>;
+    /**
+     * Add a custom audit area (requires the `guidance:write` scope).
+     *
+     * An area is a name and a description, never a file list: a scan resolves it
+     * against the code at the commit it runs on. The returned `key` is derived
+     * from the name.
+     */
+    createAuditArea(repositoryId: string, name: string, description?: string | null): Promise<AuditArea>;
+    /**
+     * Delete a custom audit area (requires the `guidance:write` scope). An area
+     * a scan's map named is refused with a `409`.
+     */
+    deleteAuditArea(repositoryId: string, areaKey: string): Promise<DeleteAuditAreaResult>;
     listScans(opts?: {
         page?: number;
         limit?: number;
@@ -1530,4 +1772,4 @@ declare class ZkaoClient {
     }): Promise<UsageMonthSummary[]>;
 }
 
-export { type BillingBalance, type BillingSummary, type BillingUsage, type CancelScanResult, type ChangeNote, DEFAULT_BASE_URL, type Finding, type FindingDetail, type FindingNote, type LaunchScanRequest, type LaunchScanResult, type OptionalFlow, type Paginated, type PublishArtifactResult, type Repository, type RepositoryGuidance, type ResolutionReason, type ResolutionStatus, type Scan, type ScanDetail, type ScanPreset, type ScanStatus, type SetGuidanceResult, type Severity, TERMINAL_SCAN_STATUSES, type TriageStatus, type UsageEvent, type UsageEventType, type UsageMonthSummary, type WaitForScanOptions, ZkaoApiError, ZkaoClient, type ZkaoClientOptions, type components, isTerminalScanStatus, normalizeBaseUrl, type paths, resolveBaseUrlFromEnv };
+export { type BillingBalance, type BillingSummary, type BillingUsage, type CancelScanResult, type ChangeNote, DEFAULT_BASE_URL, type Finding, type FindingDetail, type FindingNote, type LaunchScanRequest, type LaunchScanResult, type OptionalFlow, type Paginated, type PublishArtifactResult, type Repository, type RepositoryGuidance, type ResolutionReason, type ResolutionStatus, type Scan, type ScanDetail, type ScanPreset, type ScanStatus, type SetGuidanceResult, type Severity, TERMINAL_SCAN_STATUSES, type TriageStatus, type UsageEvent, type UsageEventType, type UsageMonthSummary, type WaitForRepositoryReadyOptions, type WaitForScanOptions, ZkaoApiError, ZkaoClient, type ZkaoClientOptions, type components, isTerminalScanStatus, normalizeBaseUrl, type paths, resolveBaseUrlFromEnv };

package/dist/index.js

@@ -120,6 +120,55 @@ var ZkaoClient = class {
     });
     return unwrap(res).repositories;
   }
+  /**
+   * Block until a repository is ready to scan, then return it.
+   *
+   * A repository added moments ago is still being analyzed, and launching a
+   * scan against it fails with `repository_initializing`. Call this between
+   * adding a repository and launching its first scan rather than retrying the
+   * launch and swallowing the error.
+   */
+  async waitForRepositoryReady(repositoryId, opts = {}) {
+    const intervalMs = opts.intervalMs ?? 5e3;
+    const maxIntervalMs = opts.maxIntervalMs ?? 3e4;
+    const timeoutMs = opts.timeoutMs ?? 30 * 60 * 1e3;
+    const deadline = Date.now() + timeoutMs;
+    for (let attempt = 0; ; attempt++) {
+      throwIfAborted(opts.signal);
+      const res = await this.http.GET("/projects/{projectId}/repositories", {
+        params: { path: this.path },
+        signal: opts.signal
+      });
+      const retryAfterMs = parseRetryAfterMs(
+        res.response.headers.get("retry-after")
+      );
+      if (res.response.status !== 429) {
+        const repository = unwrap(res).repositories.find(
+          (candidate) => candidate.id === repositoryId
+        );
+        if (!repository) {
+          throw new Error(
+            `Repository ${repositoryId} is not in this project (or this token's allowlist)`
+          );
+        }
+        if (repository.readiness === "ready") {
+          return repository;
+        }
+      }
+      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 repository ${repositoryId} to be ready after ${timeoutMs}ms`
+        );
+      }
+      await sleep(delayMs, opts.signal);
+    }
+  }
   /** Read a repository's configured guidance (requires the `read` scope). */
   async getRepositoryGuidance(repositoryId) {
     const res = await this.http.GET(
@@ -145,6 +194,55 @@ var ZkaoClient = class {
     );
     return unwrap(res);
   }
+  // --- Audit areas --------------------------------------------------------
+  /**
+   * List a repository's audit areas (requires the `read` scope).
+   *
+   * An area is a named subsystem a scan can be scoped to: pass its `key` in
+   * `auditAreaKeys` when launching. Sizes come from one branch's map, so an
+   * area that map no longer names is returned without one. Defaults to the
+   * repository's default branch.
+   */
+  async listAuditAreas(repositoryId, opts = {}) {
+    const res = await this.http.GET(
+      "/projects/{projectId}/repositories/{repositoryId}/audit-areas",
+      {
+        params: {
+          path: { ...this.path, repositoryId },
+          query: opts.branch === void 0 ? {} : { branch: opts.branch }
+        }
+      }
+    );
+    return unwrap(res);
+  }
+  /**
+   * Add a custom audit area (requires the `guidance:write` scope).
+   *
+   * An area is a name and a description, never a file list: a scan resolves it
+   * against the code at the commit it runs on. The returned `key` is derived
+   * from the name.
+   */
+  async createAuditArea(repositoryId, name, description) {
+    const res = await this.http.POST(
+      "/projects/{projectId}/repositories/{repositoryId}/audit-areas",
+      {
+        params: { path: { ...this.path, repositoryId } },
+        body: { name, description: description ?? null }
+      }
+    );
+    return unwrap(res).area;
+  }
+  /**
+   * Delete a custom audit area (requires the `guidance:write` scope). An area
+   * a scan's map named is refused with a `409`.
+   */
+  async deleteAuditArea(repositoryId, areaKey) {
+    const res = await this.http.DELETE(
+      "/projects/{projectId}/repositories/{repositoryId}/audit-areas/{areaKey}",
+      { params: { path: { ...this.path, repositoryId, areaKey } } }
+    );
+    return unwrap(res);
+  }
   // --- Scans --------------------------------------------------------------
   async listScans(opts = {}) {
     const res = await this.http.GET("/projects/{projectId}/scans", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zksecurity/zkao-sdk",
-  "version": "0.2.0",
+  "version": "0.5.0",
   "description": "TypeScript SDK for the zkao Project API",
   "license": "MIT",
   "author": "zkSecurity",
@@ -29,7 +29,11 @@
       "import": "./dist/index.js"
     }
   },
-  "files": ["dist", "LICENSE", "README.md"],
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
   "engines": {
     "node": ">=18"
   },