@krovacloud/sdk 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to `@krovacloud/sdk` are documented here. This project adher
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html) and the
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format.
 
+## 0.1.2
+
+### Changed
+
+- **Documentation & packaging polish** — no runtime behavior change.
+  - Rewrote the README to a complete public reference: npm/license/types
+    badges, a runnable Quickstart traced against the shipped API, a per-export
+    reference for `KrovaClient`, every `client.cubes.*` and `client.catalog.*`
+    helper, `client.raw`, and `KrovaError` (with its full field table), plus
+    Auth, Error-handling, Configuration, TypeScript, Requirements, and a
+    **Related packages** section linking `@krovacloud/cli`,
+    `@krovacloud/webhook`, `@krovacloud/mcp`, and `n8n-nodes-krova`.
+  - Sharpened the `package.json` `description`, expanded `keywords`
+    (added `api`, `api-client`, `cubes`, `openapi`), and pointed `homepage`
+    at [krova.cloud](https://krova.cloud).
+  - Added a top-level `"types"` fallback and a `"./package.json"` entry to the
+    `exports` map for broader tooling compatibility.
+
 ## 0.1.1
 
 ### Fixed

package/README.md

@@ -1,23 +1,29 @@
 # @krovacloud/sdk
 
-The official TypeScript SDK for the [Krova Cloud](https://krova.cloud) API — a fully typed client generated directly from the Krova Cloud OpenAPI specification.
+[![npm version](https://img.shields.io/npm/v/@krovacloud/sdk?color=cb3837&logo=npm)](https://www.npmjs.com/package/@krovacloud/sdk)
+[![npm downloads](https://img.shields.io/npm/dm/@krovacloud/sdk?color=cb3837&logo=npm)](https://www.npmjs.com/package/@krovacloud/sdk)
+[![license: MIT](https://img.shields.io/npm/l/@krovacloud/sdk?color=blue)](./LICENSE)
+[![types: included](https://img.shields.io/npm/types/@krovacloud/sdk?logo=typescript)](https://www.typescriptlang.org/)
 
-Krova Cloud is a self-service platform for lightweight **Cubes** (Firecracker microVMs) on dedicated bare-metal servers. This SDK gives you typed access to every endpoint plus ergonomic helpers for the common Cube and catalog operations.
+The official TypeScript SDK for the [Krova Cloud](https://krova.cloud) API — a fully typed client for provisioning and managing **Cubes** (Firecracker microVMs) on dedicated bare-metal servers.
 
-- **Fully typed** — request bodies, responses, and path params are typed from the OpenAPI spec via [`openapi-typescript`](https://github.com/openapi-ts/openapi-typescript) + [`openapi-fetch`](https://github.com/openapi-ts/openapi-typescript/tree/main/packages/openapi-fetch).
-- **ESM + CJS** — ships both, with `.d.ts` types.
-- **Ergonomic helpers** — `client.cubes.*` and `client.catalog.*` unwrap the response and throw on errors.
-- **Escape hatch** — `client.raw` exposes the underlying typed client for every operation in the spec (31 operations across 22 resource paths).
+## Highlights
+
+- **Fully typed** — request bodies, responses, and path params are generated from the Krova Cloud OpenAPI spec via [`openapi-typescript`](https://github.com/openapi-ts/openapi-typescript) + [`openapi-fetch`](https://github.com/openapi-ts/openapi-typescript/tree/main/packages/openapi-fetch).
+- **Ergonomic helpers** — `client.cubes.*` and `client.catalog.*` unwrap the response body and throw a typed `KrovaError` on failure.
+- **Full escape hatch** — `client.raw` exposes the underlying typed client for *every* operation in the spec (31 operations across 22 resource paths).
+- **Zero-config resilience** — automatic retries on `429` / `503`, honoring `Retry-After`.
+- **ESM + CJS** — ships both, with bundled `.d.ts` declarations. No runtime dependencies beyond `openapi-fetch`.
 
 ## Install
 
 ```sh
-pnpm add @krovacloud/sdk
-# or: npm install @krovacloud/sdk
+npm i @krovacloud/sdk
+# or: pnpm add @krovacloud/sdk
 # or: yarn add @krovacloud/sdk
 ```
 
-Requires Node.js 18+ (uses the global `fetch`).
+Requires **Node.js ≥ 18** (uses the global `fetch`).
 
 ## Quickstart
 
@@ -32,13 +38,14 @@ const krova = new KrovaClient({
 const cubes = await krova.cubes.list("space_123");
 console.log(cubes);
 
-// Create a Cube
+// Create a Cube (sshPublicKey is required)
 const cube = await krova.cubes.create("space_123", {
   name: "web-server",
   image: "ubuntu-24.04",
   resources: { vcpu: 2, ramGb: 4, diskGb: 40 },
   sshPublicKey: "ssh-ed25519 AAAA...your-key... you@host",
 });
+
 console.log(`Created cube ${cube.id} (${cube.state})`);
 console.log(`  ${cube.resources.vcpu} vCPU / ${cube.resources.ramGb} GB RAM, image ${cube.image}`);
 
@@ -47,60 +54,139 @@ await krova.cubes.sleep("space_123", cube.id);
 await krova.cubes.wake("space_123", cube.id);
 ```
 
-### Public catalog
+## Authentication
+
+Get an API key at **[krova.cloud](https://krova.cloud)** → your Space settings. Keys are **scoped per Space**, inherit the permissions of the membership that created them, and look like `kro_...`.
 
-The catalog endpoints do not require authentication, but the client sends your key harmlessly:
+By default the client sends the key as the `X-API-KEY` header (the API's security scheme). If your gateway expects a bearer token instead, pass `authScheme: "bearer"`:
 
 ```ts
-const regions = await krova.catalog.regions();
-const images = await krova.catalog.images();
-const pricing = await krova.catalog.pricing();
+const krova = new KrovaClient({ apiKey: "kro_...", authScheme: "bearer" });
+```
+
+> **Keep keys secret.** Never commit a key or embed it in a browser bundle. Load it from an environment variable or a secrets manager.
+
+## API reference
+
+Every public export, with its real signature and a short example.
+
+### `new KrovaClient(options)`
+
+```ts
+new KrovaClient({
+  apiKey: string,               // required — your "kro_..." token
+  baseUrl?: string,             // default: "https://krova.cloud/api/v1"
+  authScheme?: "x-api-key" | "bearer", // default: "x-api-key"
+  maxRetries?: number,          // default: 2 — retries 429/503 (honors Retry-After); 0 disables
+  fetch?: typeof fetch,         // optional fetch override (proxy, tests)
+});
 ```
 
-### The raw client (every endpoint)
+Throws if `apiKey` is missing. Exposes `client.baseUrl` (the resolved base URL), `client.cubes`, `client.catalog`, and `client.raw`.
 
-The ergonomic helpers cover Cubes and the catalog. For everything else — Domains, TCP mappings, Snapshots, Backups, Imports, Webhooks — use `krova.raw`, the fully typed [`openapi-fetch`](https://github.com/openapi-ts/openapi-typescript/tree/main/packages/openapi-fetch) client. It returns `{ data, error, response }` and never throws:
+### `client.cubes`
+
+Ergonomic helpers for the Cube lifecycle. Each unwraps the response body and throws `KrovaError` on a non-2xx status.
+
+| Method | Signature | Returns |
+| --- | --- | --- |
+| `list` | `(spaceId: string)` | the Cube list body |
+| `create` | `(spaceId, body, opts?)` | the created `Cube` |
+| `get` | `(spaceId, cubeId)` | the Cube body |
+| `update` | `(spaceId, cubeId, body)` | updates the Cube's SSH port |
+| `delete` | `(spaceId, cubeId)` | enqueues deletion |
+| `sleep` | `(spaceId, cubeId)` | enqueues sleep |
+| `wake` | `(spaceId, cubeId)` | enqueues wake |
 
 ```ts
-const { data, error } = await krova.raw.POST(
-  "/spaces/{spaceId}/webhooks",
+// create — sshPublicKey is required; region + userData (cloud-init) are optional.
+// opts.idempotencyKey (≤255 chars, per-space) makes retries safe.
+const cube = await krova.cubes.create(
+  "space_123",
   {
-    params: { path: { spaceId: "space_123" } },
-    body: { url: "https://example.com/hook", events: ["cube.running"] },
+    name: "web-server",
+    image: "ubuntu-24.04",
+    resources: { vcpu: 2, ramGb: 4, diskGb: 40 },
+    sshPublicKey: "ssh-ed25519 AAAA... you@host",
+    region: "us-east",           // optional — slug from catalog.regions()
+    userData: "#cloud-config\n",  // optional — cloud-init (max 16 KB)
   },
+  { idempotencyKey: "deploy-2026-07-01" },
 );
-if (error) {
-  console.error("Webhook create failed:", error.error);
-} else {
-  console.log(data);
-}
+
+// get / list
+const one = await krova.cubes.get("space_123", cube.id);
+const all = await krova.cubes.list("space_123");
+
+// update — the only mutable Cube field over the public API is the SSH port
+await krova.cubes.update("space_123", cube.id, { cubePort: 2222 });
+
+// lifecycle — sleep, wake, delete are asynchronous (enqueued)
+await krova.cubes.sleep("space_123", cube.id);
+await krova.cubes.wake("space_123", cube.id);
+await krova.cubes.delete("space_123", cube.id);
 ```
 
-## Authentication
+The `Cube` type is exported for your own signatures:
 
-Create an API key from your Space settings in the [Krova Cloud dashboard](https://krova.cloud). Keys are **scoped per Space** and inherit the permissions of the membership that created them; they look like `kro_...`.
+```ts
+import type { Cube } from "@krovacloud/sdk";
+// {
+//   id: string; name: string;
+//   state: "pending" | "booting" | "running" | "sleeping" | "stopping" | "error" | "deleted";
+//   publicIpv4: string | null;
+//   resources: { vcpu: number; ramGb: number; diskGb: number };
+//   image: string; costPerHour: number;
+//   createdAt: string; updatedAt: string;
+// }
+```
 
-By default the client sends the key as the `X-API-KEY` header, matching the API's security scheme. If your gateway expects a bearer token instead, pass `authScheme: "bearer"`:
+### `client.catalog`
+
+Public catalog endpoints (no auth required by the API; the client sends your key harmlessly).
 
 ```ts
-const krova = new KrovaClient({ apiKey: "kro_...", authScheme: "bearer" });
+const regions = await krova.catalog.regions(); // regions with available capacity
+const images = await krova.catalog.images();   // available OS images
+const pricing = await krova.catalog.pricing(); // per-resource hourly rates + volume tiers
 ```
 
-### Options
+### `client.raw` — every endpoint
+
+The helpers cover Cubes and the catalog. For everything else — Domains, TCP mappings, Snapshots, Backups, Imports, Webhooks — use `client.raw`, the fully typed [`openapi-fetch`](https://github.com/openapi-ts/openapi-typescript/tree/main/packages/openapi-fetch) client. It returns `{ data, error, response }` and **never throws**:
 
 ```ts
-new KrovaClient({
-  apiKey: "kro_...",           // required
-  baseUrl: "https://krova.cloud/api/v1", // default
-  authScheme: "x-api-key",     // "x-api-key" (default) | "bearer"
-  maxRetries: 2,               // retries on 429/503 (honors Retry-After); 0 disables
-  fetch: customFetch,          // optional fetch override
+const { data, error } = await krova.raw.POST("/spaces/{spaceId}/webhooks", {
+  params: { path: { spaceId: "space_123" } },
+  body: { url: "https://example.com/hook", events: ["cube.running"] },
 });
+
+if (error) {
+  console.error("Webhook create failed:", error.error);
+} else {
+  console.log(data);
+}
 ```
 
-## Error handling
+Path, method, params, and body are all type-checked against the spec. The generated `paths` and `components` types are also exported for advanced use:
+
+```ts
+import type { paths, components } from "@krovacloud/sdk";
+type Domain = components["schemas"]["Domain"];
+```
+
+### `KrovaError`
+
+Thrown by the `cubes.*` / `catalog.*` helpers on any non-2xx response. (`client.raw` never throws — it returns the error in `{ error }`.)
 
-The ergonomic helpers throw a `KrovaError` on any non-2xx response. It carries the HTTP `status`, the API's error `message`, and — when the API sends them — a `code` (`X-Error-Code`), a `requestId` (`X-Request-Id`), and the parsed `body`:
+| Field | Type | Source |
+| --- | --- | --- |
+| `status` | `number` | HTTP status code |
+| `message` | `string` | the API's `error` string, else `statusText` |
+| `code` | `string \| undefined` | `X-Error-Code` response header |
+| `requestId` | `string \| undefined` | `X-Request-Id` response header |
+| `body` | `object \| undefined` | the parsed JSON error body |
+| `response` | `Response \| undefined` | the raw `Response` |
 
 ```ts
 import { KrovaError } from "@krovacloud/sdk";
@@ -110,29 +196,49 @@ try {
 } catch (err) {
   if (err instanceof KrovaError) {
     console.error(`[${err.status}] ${err.message}`);
-    if (err.requestId) console.error("request id:", err.requestId);
+    if (err.code) console.error("code:", err.code);
+    if (err.requestId) console.error("request id:", err.requestId); // quote this to support
   } else {
     throw err;
   }
 }
 ```
 
-Mutating `POST` / `DELETE` endpoints are rate-limited (10 requests / 60s per client IP). The client automatically retries `429` and `503` responses (up to `maxRetries`, honoring the `Retry-After` header).
+Mutating `POST` / `DELETE` endpoints are rate-limited (10 requests / 60s per client IP). The client automatically retries `429` and `503` up to `maxRetries` times, honoring the `Retry-After` header.
 
-## API reference
-
-The full Krova Cloud API is documented in the OpenAPI spec vendored in this repo ([`openapi.json`](./openapi.json)). See [krova.cloud](https://krova.cloud) for the hosted docs and to obtain a key.
+## Configuration
 
-## Development
+Point the client at a different base URL (self-hosted gateway, staging, a proxy):
 
-```sh
-pnpm install
-pnpm gen        # regenerate src/generated/types.ts from openapi.json
-pnpm typecheck
-pnpm build      # ESM + CJS + d.ts into dist/
-pnpm test       # node:test via tsx (no network)
+```ts
+const krova = new KrovaClient({
+  apiKey: "kro_...",
+  baseUrl: "https://gateway.internal/krova/api/v1",
+});
 ```
 
+## TypeScript
+
+The package ships its own type declarations — no `@types/*` install needed. `Cube`, `KrovaError`, `KrovaClientOptions`, `AuthScheme`, and the generated `paths` / `components` are all exported.
+
+## Related packages
+
+| Package | What it is |
+| --- | --- |
+| [`@krovacloud/cli`](https://www.npmjs.com/package/@krovacloud/cli) | Command-line interface for Krova Cloud |
+| [`@krovacloud/webhook`](https://www.npmjs.com/package/@krovacloud/webhook) | Verify and parse Krova Cloud webhook events |
+| [`@krovacloud/mcp`](https://www.npmjs.com/package/@krovacloud/mcp) | Model Context Protocol server for Krova Cloud |
+| [`n8n-nodes-krova`](https://www.npmjs.com/package/n8n-nodes-krova) | n8n community nodes for Krova Cloud |
+
+## Requirements
+
+- **Node.js ≥ 18** (global `fetch`).
+- Works in any modern runtime with a WHATWG `fetch` (Deno, Bun, edge). Pass a custom `fetch` if the global isn't available.
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md). Report security issues privately per [SECURITY.md](./SECURITY.md).
+
 ## License
 
 [MIT](./LICENSE) © 2026 Krova Inc.

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@krovacloud/sdk",
-  "version": "0.1.1",
-  "description": "Official TypeScript SDK for the Krova Cloud API — a typed client generated from the Krova Cloud OpenAPI spec.",
+  "version": "0.1.2",
+  "description": "Official TypeScript SDK for Krova Cloud — a typed client for provisioning and managing Cubes (Firecracker microVMs) on bare-metal.",
   "license": "MIT",
   "type": "module",
   "author": "Krova Inc.",
-  "homepage": "https://github.com/krovacloud/krova-js#readme",
+  "homepage": "https://krova.cloud",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/krovacloud/krova-js.git"
@@ -16,12 +16,16 @@
   "keywords": [
     "krova",
     "krova-cloud",
+    "sdk",
+    "api",
+    "api-client",
     "firecracker",
-    "cube",
     "microvm",
+    "cube",
+    "cubes",
     "cloud",
-    "sdk",
-    "typescript"
+    "typescript",
+    "openapi"
   ],
   "publishConfig": {
     "access": "public"
@@ -31,6 +35,7 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": {
         "types": "./dist/index.d.ts",
         "default": "./dist/index.js"
@@ -39,7 +44,8 @@
         "types": "./dist/index.d.cts",
         "default": "./dist/index.cjs"
       }
-    }
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",
@@ -50,6 +56,13 @@
   "engines": {
     "node": ">=18"
   },
+  "scripts": {
+    "gen": "openapi-typescript openapi.json -o src/generated/types.ts",
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test tests/*.test.ts",
+    "prepublishOnly": "pnpm build"
+  },
   "dependencies": {
     "openapi-fetch": "^0.17.0"
   },
@@ -59,11 +72,5 @@
     "tsup": "^8.5.1",
     "tsx": "^4.22.4",
     "typescript": "^5.9.3"
-  },
-  "scripts": {
-    "gen": "openapi-typescript openapi.json -o src/generated/types.ts",
-    "build": "tsup",
-    "typecheck": "tsc --noEmit",
-    "test": "tsx --test tests/*.test.ts"
   }
-}
+}