@krovacloud/sdk 0.4.5 → 0.4.7

package/README.md

@@ -54,6 +54,13 @@ console.log(`  ${cube.resources.vcpu} vCPU / ${cube.resources.ramGb} GB RAM, ima
 // Cubes from images that ship a default user (both with passwordless sudo)
 // and "root" on Cubes created before that change, so the image id cannot
 // tell you. `cube.sshUser` on the Cube object carries the same value.
+//
+// `ssh.host` is the Cube's own stable SSH hostname — it survives migration
+// to another server, falling back to the server's public IPv4 only when the
+// Cube has no DNS record yet. If you pin host keys in your own known_hosts
+// (as the CLI does), expect a one-time re-pin for any Cube you'd previously
+// connected to by IP: the host string changes from an IP to a name, so it's
+// a new known_hosts entry, not a compromised host.
 const ssh = await krova.cubes.ssh("space_123", cube.id);
 console.log(`ssh ${ssh.user}@${ssh.host} -p ${ssh.port}`);
 
@@ -115,7 +122,7 @@ Ergonomic helpers for the Cube lifecycle. Each unwraps the response body and thr
 | `delete` | `(spaceId, cubeId)` | enqueues deletion |
 | `powerOff` | `(spaceId, cubeId)` | enqueues a power-off |
 | `wake` | `(spaceId, cubeId)` | enqueues a start |
-| `ssh` | `(spaceId, cubeId)` | the Cube's SSH connection info (`host`, `port`, `user`, `hostKeys`) |
+| `ssh` | `(spaceId, cubeId)` | the Cube's SSH connection info — `host` is its stable SSH hostname (falls back to the server's public IPv4 with no DNS record yet), plus `port`, `user`, `hostKeys` |
 | `restore` | `(spaceId, cubeId, snapshotId)` | enqueues a restore — replaces the Cube's disk from a snapshot |
 
 ```ts
@@ -204,6 +211,11 @@ const mapping = await krova.tcpMappings.create("space_123", "cube_123", {
   cubePort: 5432,
   whitelistedIps: ["203.0.113.4/32"],
 });
+// `mapping.host` is where to connect — the Cube's OWN stable hostname, which
+// survives migration to another server. Use it rather than the Cube's
+// `serverDomain`, which is the current physical host and changes when the
+// Cube moves. Null only when the Cube has no server assigned.
+console.log(`psql -h ${mapping.host} -p ${mapping.hostPort}`);
 await krova.tcpMappings.list("space_123", "cube_123");
 await krova.tcpMappings.delete("space_123", "cube_123", mapping.id);
 ```

package/dist/index.d.cts

@@ -654,7 +654,7 @@ interface paths {
     };
     /**
      * Get a Cube's SSH connection info
-     * @description Host (server public IPv4), host SSH port, login user, and the Cube's captured SSH host public keys. **Use `user` rather than assuming a username** — it is `ubuntu` or `debian` on Cubes created from images that ship a default user, and `root` on Cubes created before that change or imported from a rootfs without one. `hostKeys` is empty only until the reachability cron makes its first capture; clients fall back to trust-on-first-use until then, and pin strictly afterwards.
+     * @description `host` is the Cube's own stable SSH hostname, which survives migration to another server — it falls back to the server's public IPv4 when the Cube has no DNS record yet. Also returns the host SSH port, login user, and the Cube's captured SSH host public keys. **Use `user` rather than assuming a username** — it is `ubuntu` or `debian` on Cubes created from images that ship a default user, and `root` on Cubes created before that change or imported from a rootfs without one. `hostKeys` is empty only until the reachability cron makes its first capture; clients fall back to trust-on-first-use until then, and pin strictly afterwards.
      */
     get: {
       parameters: {
@@ -1072,13 +1072,17 @@ interface paths {
             cubePort: number;
             /** @description Optional human label for the mapping. */
             label?: string;
-            /** @description Whether the mapping also forwards UDP traffic on the same host port, in addition to TCP. Optional; defaults to true when omitted.
-             *     @default true */
+            /**
+             * @description Whether the mapping also forwards UDP traffic on the same host port, in addition to TCP. Optional; defaults to true when omitted.
+             * @default true
+             */
             udpEnabled?: boolean;
             /** @description IPs/CIDRs allowed to reach the published port. Omit or send an empty array to leave the port open to the internet. */
             whitelistedIps?: string[];
-            /** @deprecated
-             *     @description DEPRECATED alias for `whitelistedIps`, accepted for backwards compatibility. `whitelistedIps` wins if both are sent. Use `whitelistedIps` in new code. */
+            /**
+             * @deprecated
+             * @description DEPRECATED alias for `whitelistedIps`, accepted for backwards compatibility. `whitelistedIps` wins if both are sent. Use `whitelistedIps` in new code.
+             */
             whitelistIps?: string[];
           };
         };
@@ -1840,6 +1844,8 @@ interface components {
       image: string;
       sshUser: string;
       costPerHour: number;
+      /** @description The hostname of the server currently hosting this Cube (e.g. `mango.krova.cloud`). This is NOT the Cube's own SSH target — use `host` from GET .../ssh for that, which is the Cube's own stable hostname and survives migration to another server. Null when the Cube has no server assigned. Only present on the single-Cube GET; list and create responses omit it. */
+      serverDomain?: string | null;
       /** Format: date-time */
       createdAt: string;
       /** Format: date-time */
@@ -1941,6 +1947,8 @@ interface components {
       id: string;
       cubeId: string;
       cubePort: number;
+      /** @description Where to connect for this mapping: `host:hostPort`. The Cube's own stable hostname, which survives migration to another server, falling back to the server's public IP when the Cube has no DNS record yet. Identical to `host` from GET .../ssh, and the same value for every mapping on a Cube. Null only when the Cube has no server assigned, in which case there is nowhere to connect. Do NOT use `serverDomain` from the Cube object — that is the current physical host and changes when the Cube moves. */
+      host: string | null;
       hostPort: number;
       label: string | null;
       status: string;
@@ -2171,6 +2179,7 @@ declare class KrovaClient {
         image: string;
         sshUser: string;
         costPerHour: number;
+        serverDomain?: string | null;
         createdAt: string;
         updatedAt: string;
       }[];

package/dist/index.d.ts

@@ -654,7 +654,7 @@ interface paths {
     };
     /**
      * Get a Cube's SSH connection info
-     * @description Host (server public IPv4), host SSH port, login user, and the Cube's captured SSH host public keys. **Use `user` rather than assuming a username** — it is `ubuntu` or `debian` on Cubes created from images that ship a default user, and `root` on Cubes created before that change or imported from a rootfs without one. `hostKeys` is empty only until the reachability cron makes its first capture; clients fall back to trust-on-first-use until then, and pin strictly afterwards.
+     * @description `host` is the Cube's own stable SSH hostname, which survives migration to another server — it falls back to the server's public IPv4 when the Cube has no DNS record yet. Also returns the host SSH port, login user, and the Cube's captured SSH host public keys. **Use `user` rather than assuming a username** — it is `ubuntu` or `debian` on Cubes created from images that ship a default user, and `root` on Cubes created before that change or imported from a rootfs without one. `hostKeys` is empty only until the reachability cron makes its first capture; clients fall back to trust-on-first-use until then, and pin strictly afterwards.
      */
     get: {
       parameters: {
@@ -1072,13 +1072,17 @@ interface paths {
             cubePort: number;
             /** @description Optional human label for the mapping. */
             label?: string;
-            /** @description Whether the mapping also forwards UDP traffic on the same host port, in addition to TCP. Optional; defaults to true when omitted.
-             *     @default true */
+            /**
+             * @description Whether the mapping also forwards UDP traffic on the same host port, in addition to TCP. Optional; defaults to true when omitted.
+             * @default true
+             */
             udpEnabled?: boolean;
             /** @description IPs/CIDRs allowed to reach the published port. Omit or send an empty array to leave the port open to the internet. */
             whitelistedIps?: string[];
-            /** @deprecated
-             *     @description DEPRECATED alias for `whitelistedIps`, accepted for backwards compatibility. `whitelistedIps` wins if both are sent. Use `whitelistedIps` in new code. */
+            /**
+             * @deprecated
+             * @description DEPRECATED alias for `whitelistedIps`, accepted for backwards compatibility. `whitelistedIps` wins if both are sent. Use `whitelistedIps` in new code.
+             */
             whitelistIps?: string[];
           };
         };
@@ -1840,6 +1844,8 @@ interface components {
       image: string;
       sshUser: string;
       costPerHour: number;
+      /** @description The hostname of the server currently hosting this Cube (e.g. `mango.krova.cloud`). This is NOT the Cube's own SSH target — use `host` from GET .../ssh for that, which is the Cube's own stable hostname and survives migration to another server. Null when the Cube has no server assigned. Only present on the single-Cube GET; list and create responses omit it. */
+      serverDomain?: string | null;
       /** Format: date-time */
       createdAt: string;
       /** Format: date-time */
@@ -1941,6 +1947,8 @@ interface components {
       id: string;
       cubeId: string;
       cubePort: number;
+      /** @description Where to connect for this mapping: `host:hostPort`. The Cube's own stable hostname, which survives migration to another server, falling back to the server's public IP when the Cube has no DNS record yet. Identical to `host` from GET .../ssh, and the same value for every mapping on a Cube. Null only when the Cube has no server assigned, in which case there is nowhere to connect. Do NOT use `serverDomain` from the Cube object — that is the current physical host and changes when the Cube moves. */
+      host: string | null;
       hostPort: number;
       label: string | null;
       status: string;
@@ -2171,6 +2179,7 @@ declare class KrovaClient {
         image: string;
         sshUser: string;
         costPerHour: number;
+        serverDomain?: string | null;
         createdAt: string;
         updatedAt: string;
       }[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krovacloud/sdk",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "description": "Official TypeScript SDK for Krova Cloud — a typed client for provisioning and managing Cubes (Firecracker microVMs) with dedicated resources.",
   "license": "MIT",
   "type": "module",