@zksecurity/zkao-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1278 @@
+/**
+ * Base-URL resolution for the SDK and CLI.
+ *
+ * One env var, `ZKAO_URL`, points at an environment. It accepts a bare host, an
+ * origin, or a full API URL (e.g. `staging.zkao.io`, `http://localhost:3000`, or
+ * `https://zkao.io/api/v1`) and is normalized to `<origin>[/path]/api/v1`. The
+ * normalization is idempotent: a value already ending in `/api/vN` is left as-is.
+ *
+ * An explicit `baseUrl` passed to the client (or the CLI `--base-url` flag) wins
+ * and is used verbatim, for the rare case that needs an exact, non-standard base.
+ */
+/** Production default; the `/api/v1` path is part of the base. */
+declare const DEFAULT_BASE_URL = "https://zkao.io/api/v1";
+/**
+ * Turn a host or origin (with or without scheme/path) into a full API base URL
+ * ending in `/api/v1`. Idempotent: an input already ending in `/api/v<n>` is
+ * left as-is. A bare host gets `https://` unless it is localhost (then `http://`).
+ * A path component is preserved (and `/api/v1` appended after it).
+ */
+declare function normalizeBaseUrl(value: string): string;
+/**
+ * Resolve a base URL from `ZKAO_URL`, or `undefined` if it is not set. The value
+ * (host, origin, or full API URL) is normalized to `<origin>[/path]/api/v1`.
+ */
+declare function resolveBaseUrlFromEnv(env?: Record<string, string | undefined>): string | undefined;
+
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+interface paths {
+    "/projects/{projectId}/repositories": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List repositories in the project
+         * @description Requires scope: `read`. Limited to the token's repo allowlist when set.
+         */
+        get: operations["listRepositories"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/projects/{projectId}/repositories/{repositoryId}/guidance": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get a repository's guidance
+         * @description Requires scope: `read`. Returns the per-repo guidance configured for this repository. Guidance is layered on top of any `zkao.md` committed in the repo at scan time; a per-scan `guidance` on launch replaces this layer for that one scan only.
+         */
+        get: operations["getRepositoryGuidance"];
+        /**
+         * Set or clear a repository's guidance
+         * @description Requires scope: `guidance:write`. Sets `content` as the repository's guidance (or clears it with `null`), recording a revision. Writing the same content that is already stored is a no-op (`unchanged: true`, no revision). Pass `expectedContent` for an optimistic compare-and-set: omit it for last-writer-wins, or send the content you last read (or `null` for "currently cleared") to get a `409` instead of clobbering a concurrent change.
+         */
+        put: operations["setRepositoryGuidance"];
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/projects/{projectId}/scans": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List scans (most recent first)
+         * @description Requires scope: `read`.
+         */
+        get: operations["listScans"];
+        put?: never;
+        /**
+         * Launch a scan
+         * @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.
+         */
+        post: operations["launchScan"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/projects/{projectId}/scans/{scanId}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get a single scan's status and detail
+         * @description Requires scope: `read`. Use for polling a launched scan. While the scan is not yet terminal the response carries an advisory `Retry-After` header telling you how long to wait before polling again; respect it (and back off on `429`) instead of polling in a tight loop.
+         */
+        get: operations["getScan"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/projects/{projectId}/scans/{scanId}/cancel": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Cancel a running or queued scan
+         * @description Requires scope: `scans:launch`. Signals any in-flight jobs to stop, marks the scan CANCELLED, and releases its reserved credits (in-flight jobs settle their actual spend as they wind down). A scan that already reached COMPLETED or FAILED cannot be cancelled (`400`).
+         */
+        post: operations["cancelScan"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/projects/{projectId}/findings": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List findings
+         * @description Requires scope: `read`. Optionally filter by `scanId`.
+         */
+        get: operations["listFindings"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/projects/{projectId}/findings/{findingId}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get a single finding (full detail)
+         * @description Requires scope: `read`. Includes description, PoC, recommended fix, and notes.
+         */
+        get: operations["getFinding"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/projects/{projectId}/findings/{findingId}/notes": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Add a comment (note) to a finding
+         * @description Requires scope: `findings:write`.
+         */
+        post: operations["addFindingNote"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/projects/{projectId}/findings/{findingId}/notes/{noteId}/pin": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Pin a note as the resolution note
+         * @description Requires scope: `findings:write`.
+         */
+        post: operations["pinFindingNote"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/projects/{projectId}/findings/{findingId}/severity": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        /**
+         * Override (or clear) a finding's severity
+         * @description Requires scope: `findings:write`. Set `severity` to null to clear the override.
+         */
+        patch: operations["updateFindingSeverity"];
+        trace?: never;
+    };
+    "/projects/{projectId}/findings/{findingId}/resolution": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        /**
+         * Change a finding's resolution status
+         * @description Requires scope: `findings:write`.
+         */
+        patch: operations["updateFindingResolution"];
+        trace?: never;
+    };
+    "/projects/{projectId}/findings/{findingId}/publish": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Publish a finding as a public artifact
+         * @description Requires scope: `publish`. Pin a note as the published note via `noteId`.
+         */
+        post: operations["publishFinding"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/projects/{projectId}/scans/{scanId}/publish": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Publish a scan as a public artifact
+         * @description Requires scope: `publish`. The scan must be COMPLETED.
+         */
+        post: operations["publishScan"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/projects/{projectId}/scan-presets": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List the scan presets (scan types) the project can launch
+         * @description Requires scope: `read`. Use a preset's `ref` as `presetRef` when launching.
+         */
+        get: operations["listScanPresets"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/projects/{projectId}/optional-flows": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List opt-in flows available at launch
+         * @description Requires scope: `read`. Pass the chosen ids as `optInFlowIds` when launching.
+         */
+        get: operations["listOptionalFlows"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+}
+interface components {
+    schemas: {
+        Error: {
+            error: {
+                /** @enum {string} */
+                code: "unauthorized" | "forbidden" | "not_found" | "bad_request" | "conflict" | "plan_inactive" | "rate_limited" | "internal";
+                message: string;
+            };
+        };
+        /** @enum {string} */
+        Severity: "CRITICAL" | "HIGH" | "MEDIUM" | "LOW" | "INFO";
+        /** @enum {string} */
+        ResolutionStatus: "NOT_STARTED" | "IN_PROGRESS" | "RESOLVED" | "WONT_FIX" | "MITIGATED" | "FALSE_POSITIVE" | "DUPLICATE";
+        /** @enum {string} */
+        TriageStatus: "PENDING" | "NEW" | "DUPLICATE" | "RECURRING" | "CONFIRMED" | "FALSE_POSITIVE" | "INCONCLUSIVE";
+        /** @enum {string} */
+        ScanStatus: "QUEUED" | "PROCESSING" | "COMPLETED" | "FAILED" | "CANCELLED";
+        Repository: {
+            id: string;
+            owner: string;
+            name: string;
+            url: string;
+            defaultBranch?: string | null;
+            /** @description ACTIVE | MARKED_FOR_DELETION */
+            status: string;
+        };
+        Scan: {
+            id: string;
+            status: components["schemas"]["ScanStatus"];
+            repositoryId: string;
+            commitHash?: string | null;
+            commitMessage?: string | null;
+            presetName?: string | null;
+            /** Format: date-time */
+            createdAt: string;
+            /** Format: date-time */
+            startedAt?: string | null;
+            /** Format: date-time */
+            completedAt?: string | null;
+        };
+        ScanDetail: components["schemas"]["Scan"] & {
+            branch?: string | null;
+            /** @description Reserved budget for the scan, in credits. */
+            creditBudget?: number | null;
+            findingsSummary?: {
+                total?: number;
+                bySeverity?: {
+                    [key: string]: number;
+                };
+            } | null;
+        };
+        Finding: {
+            id: string;
+            displayId: number;
+            title: string;
+            location: string;
+            /** @description Effective severity (user override if set, else AI severity). */
+            severity: components["schemas"]["Severity"];
+            category: string;
+            triageStatus: components["schemas"]["TriageStatus"];
+            resolutionStatus: components["schemas"]["ResolutionStatus"];
+            notesCount: number;
+        };
+        FindingNote: {
+            id: string;
+            body: string;
+            /** Format: date-time */
+            createdAt: string;
+            author?: {
+                id?: string;
+                name?: string | null;
+                email?: string;
+            } | null;
+        };
+        FindingDetail: components["schemas"]["Finding"] & {
+            description: string;
+            pocReport?: string | null;
+            recommendedFix?: string | null;
+            scanId: string;
+            commitHash?: string | null;
+            repo?: {
+                owner?: string;
+                name?: string;
+                url?: string;
+            } | null;
+            /** Format: date-time */
+            createdAt: string;
+            notes: components["schemas"]["FindingNote"][];
+        };
+        PaginatedScans: {
+            items: components["schemas"]["Scan"][];
+            page: number;
+            limit: number;
+            total: number;
+        };
+        PaginatedFindings: {
+            items: components["schemas"]["Finding"][];
+            page: number;
+            limit: number;
+            total: number;
+        };
+        ScanPreset: {
+            /** @description Pass as `presetRef` when launching. */
+            ref: string;
+            name: string;
+            description?: string | null;
+            /** @description 0 = use the default floor. */
+            minCredits: number;
+            modelTier: string;
+        };
+        OptionalFlow: {
+            /** @description Pass in `optInFlowIds` when launching. */
+            id: string;
+            flowId: string;
+            title: string;
+            description: string;
+        };
+        LaunchScanRequest: {
+            repositoryId: string;
+            /** @description Max budget for the scan, in credits. Reserved at launch. */
+            creditBudget: number;
+            /** @description A preset ref from /scan-presets. Defaults to the first active preset. */
+            presetRef?: string;
+            /** @description Branch to scan (resolved to its head commit server-side). Ignored if commitHash is set. */
+            branch?: string | null;
+            /** @description Pin a specific commit SHA (7-40 hex chars). */
+            commitHash?: string | null;
+            commitMessage?: string | null;
+            /** @description Optional-flow ids from /optional-flows. */
+            optInFlowIds?: 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;
+        };
+        LaunchScanResult: {
+            scanId: string;
+            queued: boolean;
+        };
+        RepositoryGuidance: {
+            repositoryId: string;
+            /** @description The configured guidance, or null when none is set. */
+            content: string | null;
+            /**
+             * Format: date-time
+             * @description When the guidance last changed. Null when the repo has no revision history (guidance never set, or set before revisions were tracked).
+             */
+            updatedAt: string | null;
+        };
+        SetGuidanceRequest: {
+            /** @description New guidance content; null clears it. */
+            content: string | null;
+            /** @description Optional compare-and-set. Omit for last-writer-wins. Send the content you last read (or null for "currently cleared") to receive a 409 if the guidance changed underneath you instead of overwriting it. */
+            expectedContent?: string | null;
+        };
+        SetGuidanceResult: {
+            repositoryId: string;
+            /** @description The recorded revision id, or null on a no-op write. */
+            revisionId: string | null;
+            /** @description True when the content already matched (no revision recorded). */
+            unchanged: boolean;
+        };
+        CancelScanResult: {
+            scanId: string;
+            /** @description Terminal status after cancellation (always CANCELLED). */
+            status: components["schemas"]["ScanStatus"];
+            /** @description Number of in-flight jobs signalled to stop. */
+            cancelledJobs: number;
+        };
+        /** @description Optionally attach or reuse a note alongside a resolution change. */
+        ChangeNote: {
+            /** @description Create a new note with this body. */
+            content?: string;
+            /** @description Reuse an existing note by id. */
+            existingNoteId?: string;
+        };
+        FindingNoteResult: {
+            noteId: string;
+            findingId: string;
+        };
+        FindingPinResult: {
+            findingId: string;
+            noteId: string | null;
+        };
+        FindingSeverityResult: {
+            findingId: string;
+            userSeverity?: components["schemas"]["Severity"] | null;
+            effectiveSeverity: components["schemas"]["Severity"];
+        };
+        FindingResolutionResult: {
+            findingId: string;
+            resolutionStatus: components["schemas"]["ResolutionStatus"];
+        };
+        PublishFindingRequest: {
+            /** @description A note id on the finding to pin as the published note. */
+            noteId?: string;
+            /** @description Generate a password to gate access to the public artifact. */
+            withPassword?: boolean;
+        };
+        PublishScanRequest: {
+            /** @description Generate a password to gate access to the public artifact. */
+            withPassword?: boolean;
+        };
+        PublishArtifactResult: {
+            artifactId: string;
+            /** @description Slug in /public/{scans,findings}/<publicId>. */
+            publicId: string;
+            /** @description The generated access password when withPassword was requested; otherwise null. */
+            accessPassword?: string | null;
+        };
+    };
+    responses: {
+        /** @description Invalid request */
+        BadRequest: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["Error"];
+            };
+        };
+        /** @description Missing, malformed, expired, or revoked token */
+        Unauthorized: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["Error"];
+            };
+        };
+        /** @description The token lacks the required scope */
+        Forbidden: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["Error"];
+            };
+        };
+        /** @description Resource not in this token's project or repo allowlist */
+        NotFound: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["Error"];
+            };
+        };
+        /** @description A compare-and-set (`expectedContent`) missed: the guidance changed since it was read. Re-read the current guidance and retry. */
+        Conflict: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["Error"];
+            };
+        };
+        /** @description Rate limited. Either the token's spend limit for the current period is reached (on launch), or the token is sending too many requests. Wait the number of seconds in the `Retry-After` header before retrying. */
+        RateLimited: {
+            headers: {
+                /** @description Seconds to wait before retrying. */
+                "Retry-After"?: number;
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["Error"];
+            };
+        };
+    };
+    parameters: {
+        ProjectId: string;
+        ScanId: string;
+        FindingId: string;
+        RepositoryId: string;
+        Page: number;
+        Limit: number;
+    };
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+interface operations {
+    listRepositories: {
+        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": {
+                        repositories: components["schemas"]["Repository"][];
+                    };
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+        };
+    };
+    getRepositoryGuidance: {
+        parameters: {
+            query?: never;
+            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"]["RepositoryGuidance"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+        };
+    };
+    setRepositoryGuidance: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                projectId: components["parameters"]["ProjectId"];
+                repositoryId: components["parameters"]["RepositoryId"];
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["SetGuidanceRequest"];
+            };
+        };
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["SetGuidanceResult"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+            409: components["responses"]["Conflict"];
+        };
+    };
+    listScans: {
+        parameters: {
+            query?: {
+                page?: components["parameters"]["Page"];
+                limit?: components["parameters"]["Limit"];
+            };
+            header?: never;
+            path: {
+                projectId: components["parameters"]["ProjectId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["PaginatedScans"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+        };
+    };
+    launchScan: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                projectId: components["parameters"]["ProjectId"];
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["LaunchScanRequest"];
+            };
+        };
+        responses: {
+            /** @description Scan accepted (queued) */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["LaunchScanResult"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+            429: components["responses"]["RateLimited"];
+        };
+    };
+    getScan: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                projectId: components["parameters"]["ProjectId"];
+                scanId: components["parameters"]["ScanId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    /** @description Advisory seconds to wait before polling again. Present only while the scan is still running (not for terminal scans). */
+                    "Retry-After"?: number;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        scan: components["schemas"]["ScanDetail"];
+                    };
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+            429: components["responses"]["RateLimited"];
+        };
+    };
+    cancelScan: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                projectId: components["parameters"]["ProjectId"];
+                scanId: components["parameters"]["ScanId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CancelScanResult"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+            429: components["responses"]["RateLimited"];
+        };
+    };
+    listFindings: {
+        parameters: {
+            query?: {
+                page?: components["parameters"]["Page"];
+                limit?: components["parameters"]["Limit"];
+                /** @description Only findings belonging to this scan. */
+                scanId?: string;
+            };
+            header?: never;
+            path: {
+                projectId: components["parameters"]["ProjectId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["PaginatedFindings"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+        };
+    };
+    getFinding: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                projectId: components["parameters"]["ProjectId"];
+                findingId: components["parameters"]["FindingId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        finding: components["schemas"]["FindingDetail"];
+                    };
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+        };
+    };
+    addFindingNote: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                projectId: components["parameters"]["ProjectId"];
+                findingId: components["parameters"]["FindingId"];
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    /** @description The comment body (markdown). */
+                    content: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Note created */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["FindingNoteResult"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+        };
+    };
+    pinFindingNote: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                projectId: components["parameters"]["ProjectId"];
+                findingId: components["parameters"]["FindingId"];
+                noteId: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    /** @enum {string} */
+                    kind: "resolution";
+                };
+            };
+        };
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["FindingPinResult"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+        };
+    };
+    updateFindingSeverity: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                projectId: components["parameters"]["ProjectId"];
+                findingId: components["parameters"]["FindingId"];
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    /** @description New severity override, or null to clear. */
+                    severity: components["schemas"]["Severity"] | null;
+                };
+            };
+        };
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["FindingSeverityResult"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+        };
+    };
+    updateFindingResolution: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                projectId: components["parameters"]["ProjectId"];
+                findingId: components["parameters"]["FindingId"];
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    resolutionStatus: components["schemas"]["ResolutionStatus"];
+                    note?: components["schemas"]["ChangeNote"];
+                };
+            };
+        };
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["FindingResolutionResult"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+        };
+    };
+    publishFinding: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                projectId: components["parameters"]["ProjectId"];
+                findingId: components["parameters"]["FindingId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": components["schemas"]["PublishFindingRequest"];
+            };
+        };
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["PublishArtifactResult"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+        };
+    };
+    publishScan: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                projectId: components["parameters"]["ProjectId"];
+                scanId: components["parameters"]["ScanId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": components["schemas"]["PublishScanRequest"];
+            };
+        };
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["PublishArtifactResult"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+        };
+    };
+    listScanPresets: {
+        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": {
+                        presets: components["schemas"]["ScanPreset"][];
+                    };
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+        };
+    };
+    listOptionalFlows: {
+        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": {
+                        optionalFlows: components["schemas"]["OptionalFlow"][];
+                    };
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+        };
+    };
+}
+
+type Schemas = components["schemas"];
+type Repository = Schemas["Repository"];
+type Scan = Schemas["Scan"];
+type ScanDetail = Schemas["ScanDetail"];
+type Finding = Schemas["Finding"];
+type FindingDetail = Schemas["FindingDetail"];
+type FindingNote = Schemas["FindingNote"];
+type ScanPreset = Schemas["ScanPreset"];
+type OptionalFlow = Schemas["OptionalFlow"];
+type LaunchScanRequest = Schemas["LaunchScanRequest"];
+type LaunchScanResult = Schemas["LaunchScanResult"];
+type CancelScanResult = Schemas["CancelScanResult"];
+type ChangeNote = Schemas["ChangeNote"];
+type Severity = Schemas["Severity"];
+type ResolutionStatus = Schemas["ResolutionStatus"];
+type TriageStatus = Schemas["TriageStatus"];
+type ScanStatus = Schemas["ScanStatus"];
+type PublishArtifactResult = Schemas["PublishArtifactResult"];
+type RepositoryGuidance = Schemas["RepositoryGuidance"];
+type SetGuidanceResult = Schemas["SetGuidanceResult"];
+type Paginated<T> = {
+    items: T[];
+    page: number;
+    limit: number;
+    total: number;
+};
+type ZkaoClientOptions = {
+    /** A project API token: `zkao_proj_<keyId>_<secret>`. */
+    token: string;
+    /** The id of the project the token belongs to. */
+    projectId: string;
+    /**
+     * API base URL, used verbatim. When omitted, resolved from `ZKAO_URL`
+     * (see {@link resolveBaseUrlFromEnv}), falling back to production
+     * (`https://zkao.io/api/v1`).
+     */
+    baseUrl?: string;
+    /** Optional custom fetch (e.g. for tests or proxies). */
+    fetch?: typeof fetch;
+};
+/** 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 WaitForScanOptions = {
+    /** 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 1h). Throws on timeout. */
+    timeoutMs?: number;
+    /** Abort the wait (e.g. on Ctrl-C). Rejects with the abort reason. */
+    signal?: AbortSignal;
+    /** Called with the latest detail on each non-terminal poll (for progress UI). */
+    onPoll?: (scan: ScanDetail) => void;
+};
+/** Thrown for any non-2xx response, carrying the API error envelope. */
+declare class ZkaoApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+/**
+ * Typed client for one zkao project. Every call is scoped to the project the
+ * token belongs to; see https://zkao.io/openapi/v1.yaml for the full contract.
+ */
+declare class ZkaoClient {
+    private readonly http;
+    private readonly projectId;
+    constructor(options: ZkaoClientOptions);
+    private get path();
+    listRepositories(): Promise<Repository[]>;
+    /** Read a repository's configured guidance (requires the `read` scope). */
+    getRepositoryGuidance(repositoryId: string): Promise<RepositoryGuidance>;
+    /**
+     * Set (or clear, with `null`) a repository's guidance (requires the
+     * `guidance:write` scope). Pass `expectedContent` for an optimistic
+     * compare-and-set: send the content you last read (or `null` for "currently
+     * cleared") to get a `409` instead of clobbering a concurrent change. Writing
+     * the same content that is already stored is a no-op (`unchanged: true`).
+     */
+    setRepositoryGuidance(repositoryId: string, content: string | null, opts?: {
+        expectedContent?: string | null;
+    }): Promise<SetGuidanceResult>;
+    listScans(opts?: {
+        page?: number;
+        limit?: number;
+    }): Promise<Paginated<Scan>>;
+    getScan(scanId: string): Promise<ScanDetail>;
+    /**
+     * Poll a scan until it reaches a terminal status (COMPLETED / FAILED /
+     * CANCELLED) and return the final detail. Honors the server's `Retry-After`
+     * header when present; otherwise backs off exponentially with jitter between
+     * `intervalMs` and `maxIntervalMs`. A `429` is treated as "slow down", not an
+     * error. Prefer this over a hand-rolled `getScan` loop so the server is not
+     * hammered.
+     */
+    waitForScan(scanId: string, opts?: WaitForScanOptions): Promise<ScanDetail>;
+    launchScan(body: LaunchScanRequest): Promise<LaunchScanResult>;
+    /**
+     * Cancel a running or queued scan. Signals in-flight jobs to stop, marks the
+     * scan CANCELLED, and releases its reserved credits. A scan already in a
+     * terminal COMPLETED/FAILED state cannot be cancelled.
+     */
+    cancelScan(scanId: string): Promise<CancelScanResult>;
+    publishScan(scanId: string, opts?: {
+        withPassword?: boolean;
+    }): Promise<PublishArtifactResult>;
+    listFindings(opts?: {
+        page?: number;
+        limit?: number;
+        scanId?: string;
+    }): Promise<Paginated<Finding>>;
+    getFinding(findingId: string): Promise<FindingDetail>;
+    addFindingNote(findingId: string, content: string): Promise<{
+        noteId: string;
+        findingId: string;
+    }>;
+    pinFindingNote(findingId: string, noteId: string, kind?: "resolution"): Promise<{
+        findingId: string;
+        noteId: string | null;
+    }>;
+    setFindingSeverity(findingId: string, severity: Severity | null): Promise<{
+        findingId: string;
+        userSeverity?: Severity | null;
+        effectiveSeverity: Severity;
+    }>;
+    setFindingResolution(findingId: string, resolutionStatus: ResolutionStatus, note?: ChangeNote): Promise<{
+        findingId: string;
+        resolutionStatus: ResolutionStatus;
+    }>;
+    publishFinding(findingId: string, opts?: {
+        noteId?: string;
+        withPassword?: boolean;
+    }): Promise<PublishArtifactResult>;
+    listScanPresets(): Promise<ScanPreset[]>;
+    listOptionalFlows(): Promise<OptionalFlow[]>;
+}
+
+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 };