@zksecurity/zkao-sdk 0.1.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;
@@ -91,7 +135,12 @@ interface paths {
          * @description Requires scope: `scans:launch`. Reserves `creditBudget` credits from the
          *     project balance. The repo must be in the token's allowlist (when set) and
          *     ACTIVE. Discover valid `presetRef` / `optInFlowIds` via the discovery
-         *     endpoints. Per-token spend limits and the project plan are enforced.
+         *     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;
@@ -329,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;
@@ -340,13 +389,111 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/projects/{projectId}/billing/balance": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Current prepaid credit balance
+         * @description Requires scope: `read`. All amounts are in credits.
+         */
+        get: operations["getBillingBalance"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/projects/{projectId}/billing/usage": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Credit usage events
+         * @description Requires scope: `read`. Signed credit delta per ledger event. Defaults to the last 30 days; newest first; max 1000 rows.
+         */
+        get: operations["getBillingUsage"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/projects/{projectId}/billing/summary": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Monthly spend and purchase summary
+         * @description Requires scope: `read`. Per-month net scan spend and net purchases, in credits, newest first.
+         */
+        get: operations["getBillingSummary"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
 }
 interface components {
     schemas: {
+        BillingBalance: {
+            /** @description Total prepaid credit balance. */
+            balanceCredits: number;
+            /** @description Balance minus credits reserved by in-flight scans. */
+            availableCredits: number;
+            /** @description Credits held by queued/running scans. */
+            reservedCredits: number;
+        };
+        /** @enum {string} */
+        UsageEventType: "SCAN_DEDUCTION" | "SCAN_REFUND" | "PURCHASE" | "STRIPE_REFUND" | "ADMIN_ADJUSTMENT";
+        UsageEvent: {
+            id: string;
+            /** Format: date-time */
+            at: string;
+            type: components["schemas"]["UsageEventType"];
+            /** @description Signed credit delta: negative = spent/clawed back, positive = added/refunded. */
+            credits: number;
+            scanId: string | null;
+            description: string;
+        };
+        BillingUsage: {
+            /** Format: date-time */
+            from: string;
+            /** Format: date-time */
+            to: string;
+            events: components["schemas"]["UsageEvent"][];
+        };
+        UsageMonthSummary: {
+            /** @description YYYY-MM (UTC). */
+            month: string;
+            /** @description Net scan spend (deductions less refunds), in credits. */
+            spentCredits: number;
+            /** @description Net purchases (purchases less clawbacks), in credits. */
+            purchasedCredits: number;
+        };
+        BillingSummary: {
+            months: components["schemas"]["UsageMonthSummary"][];
+        };
         Error: {
             error: {
                 /** @enum {string} */
-                code: "unauthorized" | "forbidden" | "not_found" | "bad_request" | "conflict" | "plan_inactive" | "rate_limited" | "internal";
+                code: "unauthorized" | "forbidden" | "not_found" | "bad_request" | "conflict" | "insufficient_credits" | "repository_initializing" | "rate_limited" | "internal";
                 message: string;
             };
         };
@@ -366,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;
@@ -380,6 +532,17 @@ interface components {
             startedAt?: string | null;
             /** Format: date-time */
             completedAt?: string | null;
+            /** @description Phase progress while the scan is in flight. Null once the scan reaches a terminal state, and null before it has been dispatched (no phases exist yet). */
+            progress?: components["schemas"]["ScanProgress"] | null;
+        };
+        /** @description How far a running scan has got through its phases. Deliberately not a time estimate: a phase's duration moves with the guidance it was given, the repository, and the model that ran it. */
+        ScanProgress: {
+            /** @description Phases that reached a terminal state (completed, failed, or skipped). */
+            phasesCompleted: number;
+            /** @description Phases this scan will run, fixed when it was dispatched. */
+            phasesTotal: number;
+            /** @description Weighted completion. Each phase counts for its share of the scan budget, so this does not simply equal phasesCompleted / phasesTotal. */
+            percent: number;
         };
         ScanDetail: components["schemas"]["Scan"] & {
             branch?: string | null;
@@ -457,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;
@@ -469,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;
         };
@@ -501,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). */
@@ -532,6 +737,14 @@ interface components {
             findingId: string;
             resolutionStatus: components["schemas"]["ResolutionStatus"];
         };
+        /**
+         * @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.
+         *
+         *     Codes per status. `RESOLVED`: fixed_in_code, fixed_upstream, code_removed. `MITIGATED`: compensating_control, limited_exposure, monitored. `FALSE_POSITIVE`: not_reachable, guarded_elsewhere, intended_behavior, misread_code, bad_assumption. `WONT_FIX`: risk_accepted, out_of_scope, not_worth_fixing, code_being_removed. `DUPLICATE`: duplicate_of_finding, same_root_cause.
+         * @example not_reachable
+         * @enum {string}
+         */
+        ResolutionReason: "fixed_in_code" | "fixed_upstream" | "code_removed" | "compensating_control" | "limited_exposure" | "monitored" | "not_reachable" | "guarded_elsewhere" | "intended_behavior" | "misread_code" | "bad_assumption" | "risk_accepted" | "out_of_scope" | "not_worth_fixing" | "code_being_removed" | "duplicate_of_finding" | "same_root_cause";
         PublishFindingRequest: {
             /** @description A note id on the finding to pin as the published note. */
             noteId?: string;
@@ -569,6 +782,24 @@ interface components {
                 "application/json": components["schemas"]["Error"];
             };
         };
+        /** @description The project does not have enough prepaid credits to cover the scan budget. Top up credits and retry. (code `insufficient_credits`) */
+        InsufficientCredits: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "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: {
@@ -706,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?: {
@@ -760,8 +1082,10 @@ interface operations {
             };
             400: components["responses"]["BadRequest"];
             401: components["responses"]["Unauthorized"];
+            402: components["responses"]["InsufficientCredits"];
             403: components["responses"]["Forbidden"];
             404: components["responses"]["NotFound"];
+            409: components["responses"]["RepositoryInitializing"];
             429: components["responses"]["RateLimited"];
         };
     };
@@ -1000,6 +1324,7 @@ interface operations {
                 "application/json": {
                     resolutionStatus: components["schemas"]["ResolutionStatus"];
                     note?: components["schemas"]["ChangeNote"];
+                    reason?: components["schemas"]["ResolutionReason"];
                 };
             };
         };
@@ -1135,6 +1460,88 @@ interface operations {
             404: components["responses"]["NotFound"];
         };
     };
+    getBillingBalance: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                projectId: components["parameters"]["ProjectId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["BillingBalance"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+        };
+    };
+    getBillingUsage: {
+        parameters: {
+            query?: {
+                from?: string;
+                to?: string;
+                limit?: number;
+            };
+            header?: never;
+            path: {
+                projectId: components["parameters"]["ProjectId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["BillingUsage"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+        };
+    };
+    getBillingSummary: {
+        parameters: {
+            query?: {
+                months?: number;
+            };
+            header?: never;
+            path: {
+                projectId: components["parameters"]["ProjectId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["BillingSummary"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+        };
+    };
 }
 
 type Schemas = components["schemas"];
@@ -1152,11 +1559,21 @@ type CancelScanResult = Schemas["CancelScanResult"];
 type ChangeNote = Schemas["ChangeNote"];
 type Severity = Schemas["Severity"];
 type ResolutionStatus = Schemas["ResolutionStatus"];
+type ResolutionReason = Schemas["ResolutionReason"];
 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"];
+type UsageEvent = Schemas["UsageEvent"];
+type UsageEventType = Schemas["UsageEventType"];
+type BillingSummary = Schemas["BillingSummary"];
+type UsageMonthSummary = Schemas["UsageMonthSummary"];
 type Paginated<T> = {
     items: T[];
     page: number;
@@ -1180,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;
@@ -1208,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>;
     /**
@@ -1220,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;
@@ -1263,7 +1723,19 @@ declare class ZkaoClient {
         userSeverity?: Severity | null;
         effectiveSeverity: Severity;
     }>;
-    setFindingResolution(findingId: string, resolutionStatus: ResolutionStatus, note?: ChangeNote): Promise<{
+    /**
+     * Change a finding's resolution status (requires the `findings:write` scope).
+     *
+     * `note` attaches free text in the same call. `reason` picks a catalog code
+     * instead, recorded as a generated comment; the codes offered depend on the
+     * status, and a code from another status is rejected with 400. A `note` takes
+     * precedence: pass one or the other. Both are ignored for the open statuses
+     * (`NOT_STARTED`, `IN_PROGRESS`).
+     */
+    setFindingResolution(findingId: string, resolutionStatus: ResolutionStatus, opts?: {
+        note?: ChangeNote;
+        reason?: ResolutionReason;
+    }): Promise<{
         findingId: string;
         resolutionStatus: ResolutionStatus;
     }>;
@@ -1273,6 +1745,31 @@ declare class ZkaoClient {
     }): Promise<PublishArtifactResult>;
     listScanPresets(): Promise<ScanPreset[]>;
     listOptionalFlows(): Promise<OptionalFlow[]>;
+    /**
+     * Get the project's prepaid credit balance (requires the `read` scope). zkao
+     * is pay-as-you-go: `balanceCredits` is the total, `reservedCredits` is held
+     * by active scans, and `availableCredits` is what remains for new scans.
+     */
+    getBillingBalance(): Promise<BillingBalance>;
+    /**
+     * List credit-ledger movements for reconciliation (requires the `read`
+     * scope). `credits` on each event is signed (negative = spent). Defaults to
+     * the last 30 days when `from`/`to` are omitted; the range actually used is
+     * echoed back on the response.
+     */
+    getBillingUsage(opts?: {
+        from?: string;
+        to?: string;
+        limit?: number;
+    }): Promise<BillingUsage>;
+    /**
+     * Per-calendar-month (UTC) totals of net credits spent on scans and net
+     * credits purchased (requires the `read` scope). Quiet months are returned as
+     * zeros; newest month first.
+     */
+    getBillingSummary(opts?: {
+        months?: number;
+    }): Promise<UsageMonthSummary[]>;
 }
 
-export { 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 ResolutionStatus, type Scan, type ScanDetail, type ScanPreset, type ScanStatus, type Severity, TERMINAL_SCAN_STATUSES, type TriageStatus, 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", {
@@ -263,10 +361,19 @@ var ZkaoClient = class {
     });
     return unwrap(res);
   }
-  async setFindingResolution(findingId, resolutionStatus, note) {
+  /**
+   * Change a finding's resolution status (requires the `findings:write` scope).
+   *
+   * `note` attaches free text in the same call. `reason` picks a catalog code
+   * instead, recorded as a generated comment; the codes offered depend on the
+   * status, and a code from another status is rejected with 400. A `note` takes
+   * precedence: pass one or the other. Both are ignored for the open statuses
+   * (`NOT_STARTED`, `IN_PROGRESS`).
+   */
+  async setFindingResolution(findingId, resolutionStatus, opts = {}) {
     const res = await this.http.PATCH("/projects/{projectId}/findings/{findingId}/resolution", {
       params: { path: { ...this.path, findingId } },
-      body: { resolutionStatus, note }
+      body: { resolutionStatus, note: opts.note, reason: opts.reason }
     });
     return unwrap(res);
   }
@@ -290,6 +397,44 @@ var ZkaoClient = class {
     });
     return unwrap(res).optionalFlows;
   }
+  // --- Billing ------------------------------------------------------------
+  /**
+   * Get the project's prepaid credit balance (requires the `read` scope). zkao
+   * is pay-as-you-go: `balanceCredits` is the total, `reservedCredits` is held
+   * by active scans, and `availableCredits` is what remains for new scans.
+   */
+  async getBillingBalance() {
+    const res = await this.http.GET("/projects/{projectId}/billing/balance", {
+      params: { path: this.path }
+    });
+    return unwrap(res);
+  }
+  /**
+   * List credit-ledger movements for reconciliation (requires the `read`
+   * scope). `credits` on each event is signed (negative = spent). Defaults to
+   * the last 30 days when `from`/`to` are omitted; the range actually used is
+   * echoed back on the response.
+   */
+  async getBillingUsage(opts = {}) {
+    const res = await this.http.GET("/projects/{projectId}/billing/usage", {
+      params: {
+        path: this.path,
+        query: { from: opts.from, to: opts.to, limit: opts.limit }
+      }
+    });
+    return unwrap(res);
+  }
+  /**
+   * Per-calendar-month (UTC) totals of net credits spent on scans and net
+   * credits purchased (requires the `read` scope). Quiet months are returned as
+   * zeros; newest month first.
+   */
+  async getBillingSummary(opts = {}) {
+    const res = await this.http.GET("/projects/{projectId}/billing/summary", {
+      params: { path: this.path, query: { months: opts.months } }
+    });
+    return unwrap(res).months;
+  }
 };
 function throwIfAborted(signal) {
   if (signal?.aborted) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zksecurity/zkao-sdk",
-  "version": "0.1.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"
   },