@krovacloud/sdk 0.1.6 → 0.3.0

package/dist/index.d.cts

@@ -126,6 +126,187 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/auth/cli/start": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Begin a CLI device-authorization login (RFC 8628)
+         * @description Public, unauthenticated. Mints a device code (returned once) and a short human user code, and returns the verification URIs the user opens in a browser to approve. The CLI then polls /auth/cli/poll. Rate-limited per client IP.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Device-authorization request created */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @description High-entropy code the CLI keeps secret and presents on each poll. Only its hash is stored server-side. */
+                            deviceCode: string;
+                            /** @description Short human-readable code (KROVA-XXXX-XXXX) the user confirms in the browser. */
+                            userCode: string;
+                            /**
+                             * Format: uri
+                             * @description Browser URL where the user approves.
+                             */
+                            verificationUri: string;
+                            /**
+                             * Format: uri
+                             * @description verificationUri with the user code pre-filled.
+                             */
+                            verificationUriComplete: string;
+                            /** @description Seconds to wait between polls. */
+                            interval: number;
+                            /** @description Seconds until the device code expires (~600). */
+                            expiresIn: number;
+                        };
+                    };
+                };
+                429: components["responses"]["RateLimited"];
+                /** @description Could not allocate a login code; retry */
+                503: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/auth/cli/poll": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Poll for CLI device-authorization approval (RFC 8628)
+         * @description Public, unauthenticated. The CLI submits its deviceCode until the user approves or denies. On approval a real API key is minted ONCE, scoped to the approved Space and the approving user's membership, and returned a single time. Rate-limited per client IP.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody: {
+                content: {
+                    "application/json": {
+                        /** @description The device code from /auth/cli/start. */
+                        deviceCode: string;
+                    };
+                };
+            };
+            responses: {
+                /** @description Approved — API key minted (returned once) */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @description The full API key. Shown once and never returned again — store it securely. */
+                            apiKey: string;
+                            /** @description The Space the key is scoped to. */
+                            spaceId: string;
+                        };
+                    };
+                };
+                400: components["responses"]["BadRequest"];
+                /** @description The user denied the login request */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                /** @description The device code expired, was already consumed, or is unknown */
+                410: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                /** @description Authorization still pending — keep polling at the given interval */
+                428: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                429: components["responses"]["RateLimited"];
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/space": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Resolve the space this API key is scoped to
+         * @description Returns the single space the API key belongs to. Lets a client auto-resolve the space id from the key alone (no spaceId in the URL).
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description The key's space */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["Space"];
+                    };
+                };
+                401: components["responses"]["Unauthorized"];
+                404: components["responses"]["NotFound"];
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/spaces/{spaceId}/cubes": {
         parameters: {
             query?: never;
@@ -415,6 +596,49 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/spaces/{spaceId}/cubes/{cubeId}/ssh": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get a Cube's SSH connection info
+         * @description Host (server public IPv4), host SSH port, login user, and any captured SSH host public keys. `hostKeys` is empty until Krova captures cube host keys — clients fall back to trust-on-first-use until then.
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    spaceId: string;
+                    cubeId: string;
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description SSH connection info */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["CubeSshInfo"];
+                    };
+                };
+                404: components["responses"]["NotFound"];
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/spaces/{spaceId}/cubes/{cubeId}/domains": {
         parameters: {
             query?: never;
@@ -440,7 +664,11 @@ interface paths {
                     headers: {
                         [name: string]: unknown;
                     };
-                    content?: never;
+                    content: {
+                        "application/json": {
+                            domains: components["schemas"]["Domain"][];
+                        };
+                    };
                 };
             };
         };
@@ -511,7 +739,11 @@ interface paths {
                     headers: {
                         [name: string]: unknown;
                     };
-                    content?: never;
+                    content: {
+                        "application/json": {
+                            domain: components["schemas"]["Domain"];
+                        };
+                    };
                 };
                 400: components["responses"]["BadRequest"];
                 429: components["responses"]["RateLimited"];
@@ -552,7 +784,11 @@ interface paths {
                     headers: {
                         [name: string]: unknown;
                     };
-                    content?: never;
+                    content: {
+                        "application/json": {
+                            success: boolean;
+                        };
+                    };
                 };
                 404: components["responses"]["NotFound"];
             };
@@ -619,7 +855,11 @@ interface paths {
                     headers: {
                         [name: string]: unknown;
                     };
-                    content?: never;
+                    content: {
+                        "application/json": {
+                            domain: components["schemas"]["Domain"];
+                        };
+                    };
                 };
                 400: components["responses"]["BadRequest"];
                 404: components["responses"]["NotFound"];
@@ -653,7 +893,11 @@ interface paths {
                     headers: {
                         [name: string]: unknown;
                     };
-                    content?: never;
+                    content: {
+                        "application/json": {
+                            tcpMappings: components["schemas"]["TcpMapping"][];
+                        };
+                    };
                 };
             };
         };
@@ -686,7 +930,11 @@ interface paths {
                     headers: {
                         [name: string]: unknown;
                     };
-                    content?: never;
+                    content: {
+                        "application/json": {
+                            tcpMapping: components["schemas"]["TcpMapping"];
+                        };
+                    };
                 };
                 400: components["responses"]["BadRequest"];
                 429: components["responses"]["RateLimited"];
@@ -727,7 +975,11 @@ interface paths {
                     headers: {
                         [name: string]: unknown;
                     };
-                    content?: never;
+                    content: {
+                        "application/json": {
+                            success: boolean;
+                        };
+                    };
                 };
                 404: components["responses"]["NotFound"];
             };
@@ -762,7 +1014,11 @@ interface paths {
                     headers: {
                         [name: string]: unknown;
                     };
-                    content?: never;
+                    content: {
+                        "application/json": {
+                            snapshots: components["schemas"]["Snapshot"][];
+                        };
+                    };
                 };
             };
         };
@@ -794,7 +1050,11 @@ interface paths {
                     headers: {
                         [name: string]: unknown;
                     };
-                    content?: never;
+                    content: {
+                        "application/json": {
+                            snapshot: components["schemas"]["Snapshot"];
+                        };
+                    };
                 };
                 429: components["responses"]["RateLimited"];
             };
@@ -834,7 +1094,11 @@ interface paths {
                     headers: {
                         [name: string]: unknown;
                     };
-                    content?: never;
+                    content: {
+                        "application/json": {
+                            success: boolean;
+                        };
+                    };
                 };
                 404: components["responses"]["NotFound"];
             };
@@ -877,7 +1141,11 @@ interface paths {
                     headers: {
                         [name: string]: unknown;
                     };
-                    content?: never;
+                    content: {
+                        "application/json": {
+                            success: boolean;
+                        };
+                    };
                 };
                 404: components["responses"]["NotFound"];
             };
@@ -1098,7 +1366,11 @@ interface paths {
                     headers: {
                         [name: string]: unknown;
                     };
-                    content?: never;
+                    content: {
+                        "application/json": {
+                            success: boolean;
+                        };
+                    };
                 };
                 404: components["responses"]["NotFound"];
                 /** @description Cannot cancel an import past the 'uploading' state */
@@ -1377,6 +1649,22 @@ interface paths {
 }
 interface components {
     schemas: {
+        Space: {
+            id: string;
+            name: string;
+            tier: string;
+            /** Format: date-time */
+            createdAt: string;
+        };
+        CubeSshInfo: {
+            host: string | null;
+            port: number;
+            user: string;
+            hostKeys: {
+                type: string;
+                key: string;
+            }[];
+        };
         Cube: {
             id: string;
             name: string;
@@ -1571,6 +1859,22 @@ type Image = components["schemas"]["Image"];
 type PricingTier = components["schemas"]["PricingTier"];
 /** Pagination envelope returned alongside a Cube list. */
 type Pagination = components["schemas"]["Pagination"];
+/** A Space — the tenancy an API key is scoped to. */
+type Space = components["schemas"]["Space"];
+/** A Cube's SSH connection info (host, port, user, and pinned host keys). */
+type CubeSshInfo = components["schemas"]["CubeSshInfo"];
+/** A custom domain attached to a Cube. */
+type Domain = components["schemas"]["Domain"];
+/** A snapshot of a Cube's disk. */
+type Snapshot = components["schemas"]["Snapshot"];
+/** A TCP port mapping exposing a Cube port on the host. */
+type TcpMapping = components["schemas"]["TcpMapping"];
+/** Request body for attaching a custom domain to a Cube. */
+type CreateDomainInput = NonNullable<paths["/spaces/{spaceId}/cubes/{cubeId}/domains"]["post"]["requestBody"]>["content"]["application/json"];
+/** Request body for updating a custom domain's proxy settings. */
+type UpdateDomainInput = NonNullable<paths["/spaces/{spaceId}/cubes/{cubeId}/domains/{mappingId}"]["patch"]["requestBody"]>["content"]["application/json"];
+/** Request body for creating a TCP port mapping. */
+type CreateTcpMappingInput = NonNullable<paths["/spaces/{spaceId}/cubes/{cubeId}/tcp-mappings"]["post"]["requestBody"]>["content"]["application/json"];
 /** Default API base URL — the single `servers[0].url` from the OpenAPI spec. */
 declare const DEFAULT_BASE_URL = "https://krova.cloud/api/v1";
 /**
@@ -1685,6 +1989,120 @@ declare class KrovaClient {
         sleep: (spaceId: string, cubeId: string) => Promise<unknown>;
         /** Wake a sleeping Cube (asynchronous — wake is enqueued). */
         wake: (spaceId: string, cubeId: string) => Promise<unknown>;
+        /**
+         * Get a Cube's SSH connection info — host, port, login user, and (when
+         * available) the pinned host public keys for strict host-key verification.
+         */
+        ssh: (spaceId: string, cubeId: string) => Promise<CubeSshInfo>;
+        /**
+         * Restore a Cube's disk from one of its {@link Snapshot}s (asynchronous —
+         * the restore is enqueued). The Cube's current disk is replaced.
+         */
+        restore: (spaceId: string, cubeId: string, snapshotId: string) => Promise<{
+            success: boolean;
+        }>;
+    };
+    /**
+     * Resolve the {@link Space} this API key is scoped to — so you don't have to
+     * hardcode a `spaceId`. Handy right after constructing the client:
+     *
+     * @example
+     * ```ts
+     * const space = await krova.getSpace();
+     * const cubes = await krova.cubes.list(space.id);
+     * ```
+     */
+    getSpace(): Promise<Space>;
+    readonly domains: {
+        /** List the custom domains attached to a Cube. */
+        list: (spaceId: string, cubeId: string) => Promise<Domain[]>;
+        /** Attach a custom domain to a Cube. `domain` + `port` are required. */
+        create: (spaceId: string, cubeId: string, body: CreateDomainInput) => Promise<Domain>;
+        /** Update a domain's per-domain proxy settings. */
+        update: (spaceId: string, cubeId: string, mappingId: string, body: UpdateDomainInput) => Promise<Domain>;
+        /** Detach a custom domain from a Cube. */
+        delete: (spaceId: string, cubeId: string, mappingId: string) => Promise<{
+            success: boolean;
+        }>;
+    };
+    readonly snapshots: {
+        /** List a Cube's snapshots. */
+        list: (spaceId: string, cubeId: string) => Promise<Snapshot[]>;
+        /** Create a snapshot of a Cube's disk (asynchronous — enqueued). */
+        create: (spaceId: string, cubeId: string, body?: {
+            name?: string;
+        }) => Promise<Snapshot>;
+        /** Delete a snapshot. */
+        delete: (spaceId: string, cubeId: string, snapshotId: string) => Promise<{
+            success: boolean;
+        }>;
+    };
+    readonly tcpMappings: {
+        /** List a Cube's TCP port mappings. */
+        list: (spaceId: string, cubeId: string) => Promise<TcpMapping[]>;
+        /**
+         * Create a TCP port mapping exposing a Cube port on the host. `cubePort` is
+         * required; `whitelistIps` optionally restricts who can reach it.
+         */
+        create: (spaceId: string, cubeId: string, body: CreateTcpMappingInput) => Promise<TcpMapping>;
+        /** Delete a TCP port mapping. */
+        delete: (spaceId: string, cubeId: string, mappingId: string) => Promise<{
+            success: boolean;
+        }>;
+    };
+    readonly imports: {
+        /**
+         * Start importing a `.cube` archive into a new Cube. Returns the multipart
+         * upload target (`importId`, `uploadId`, presigned `parts`, …). Upload the
+         * archive to those URLs, then call {@link imports.complete}.
+         */
+        create: (spaceId: string, body: NonNullable<paths["/spaces/{spaceId}/cubes/imports"]["post"]["requestBody"]>["content"]["application/json"]) => Promise<{
+            importId?: string | undefined;
+            uploadId?: string | undefined;
+            key?: string | undefined;
+            chunkSizeBytes?: number | undefined;
+            parts?: {
+                partNumber?: number | undefined;
+                url?: string | undefined;
+            }[] | undefined;
+            expiresAt?: string | undefined;
+        } | undefined>;
+        /** Get an in-progress or completed import by id. */
+        get: (spaceId: string, importId: string) => Promise<{
+            import?: {
+                id?: string | undefined;
+                name?: string | undefined;
+                status?: "uploading" | "finalizing" | "provisioning" | "complete" | "failed" | "expired" | undefined;
+                cubeId?: string | null | undefined;
+                error?: string | null | undefined;
+                createdAt?: string | undefined;
+                updatedAt?: string | undefined;
+                completedAt?: string | null | undefined;
+            } | undefined;
+        }>;
+        /**
+         * Finish an import after the archive has been uploaded — provisions the
+         * Cube. Pass the uploaded `parts` (partNumber + etag) and the resolved
+         * `config`.
+         */
+        complete: (spaceId: string, importId: string, body: NonNullable<paths["/spaces/{spaceId}/cubes/imports/{importId}/complete"]["post"]["requestBody"]>["content"]["application/json"]) => Promise<{
+            importId?: string | undefined;
+            cubeId?: string | undefined;
+            status?: "provisioning" | undefined;
+        } | undefined>;
+        /** Cancel an in-progress import. */
+        cancel: (spaceId: string, importId: string) => Promise<{
+            success: boolean;
+        } | undefined>;
+    };
+    readonly backups: {
+        /** Get a time-limited download URL for a backup `.cube` archive. */
+        download: (spaceId: string, backupId: string) => Promise<{
+            url?: string | undefined;
+            filename?: string | undefined;
+            sizeBytes?: number | null | undefined;
+            expiresAt?: string | undefined;
+        } | undefined>;
     };
     readonly catalog: {
         /** List regions with available capacity. */
@@ -1773,4 +2191,4 @@ declare class KrovaError extends Error {
  */
 declare function krovaErrorFrom(response: Response, body: KrovaErrorBody | undefined): KrovaError;
 
-export { type AuthScheme, type Cube, DEFAULT_BASE_URL, type Image, KrovaClient, type KrovaClientOptions, KrovaError, type KrovaErrorBody, type Pagination, type PricingTier, type Region, type components, krovaErrorFrom, type paths };
+export { type AuthScheme, type CreateDomainInput, type CreateTcpMappingInput, type Cube, type CubeSshInfo, DEFAULT_BASE_URL, type Domain, type Image, KrovaClient, type KrovaClientOptions, KrovaError, type KrovaErrorBody, type Pagination, type PricingTier, type Region, type Snapshot, type Space, type TcpMapping, type UpdateDomainInput, type components, krovaErrorFrom, type paths };