@zksecurity/zkao-sdk 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -91,7 +91,8 @@ 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`).
          */
         post: operations["launchScan"];
         delete?: never;
@@ -340,13 +341,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" | "rate_limited" | "internal";
                 message: string;
             };
         };
@@ -380,6 +479,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;
@@ -532,6 +642,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 +687,15 @@ 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 token lacks the required scope */
         Forbidden: {
             headers: {
@@ -760,6 +887,7 @@ interface operations {
             };
             400: components["responses"]["BadRequest"];
             401: components["responses"]["Unauthorized"];
+            402: components["responses"]["InsufficientCredits"];
             403: components["responses"]["Forbidden"];
             404: components["responses"]["NotFound"];
             429: components["responses"]["RateLimited"];
@@ -1000,6 +1128,7 @@ interface operations {
                 "application/json": {
                     resolutionStatus: components["schemas"]["ResolutionStatus"];
                     note?: components["schemas"]["ChangeNote"];
+                    reason?: components["schemas"]["ResolutionReason"];
                 };
             };
         };
@@ -1135,6 +1264,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 +1363,18 @@ 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 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;
@@ -1263,7 +1481,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 +1503,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 WaitForScanOptions, ZkaoApiError, ZkaoClient, type ZkaoClientOptions, type components, isTerminalScanStatus, normalizeBaseUrl, type paths, resolveBaseUrlFromEnv };

package/dist/index.js

@@ -263,10 +263,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 +299,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.2.0",
   "description": "TypeScript SDK for the zkao Project API",
   "license": "MIT",
   "author": "zkSecurity",