@cloudfleet/sdk 0.0.1-0010e2d → 0.0.1-019156c

package/README.md

@@ -1,9 +1,63 @@
-# Cloudfleet TypeScript API client
+# Cloudfleet SDK for TypeScript & JavaScript
 
-TypeScript client for the Cloudfleet API.
+Official TypeScript/JavaScript SDK for the [Cloudfleet](https://cloudfleet.ai) API.
+
+[Cloudfleet](https://cloudfleet.ai) is a managed Kubernetes platform that runs your clusters across any cloud and your own bare-metal servers. This SDK is a fully typed client for automating clusters, fleets, nodes, and billing from Node.js, the browser, or any TypeScript project.
+
+- 🌐 Homepage: [cloudfleet.ai](https://cloudfleet.ai)
+- 📚 Docs: [cloudfleet.ai/docs](https://cloudfleet.ai/docs)
 
 ## Installation
 
 ```bash
 npm install @cloudfleet/sdk
 ```
+
+## Usage
+
+```ts
+import { client } from "@cloudfleet/sdk";
+
+client.setConfig({
+    baseUrl: "https://api.cloudfleet.ai/v1",
+    headers: {
+        Authorization: "Bearer <your-token>",
+    },
+});
+```
+
+## Errors
+
+Failed requests throw (or return as `error` when `throwOnError` is `false`) `Error` subclasses:
+
+- `CloudfleetApiError`: the API answered with a non-2xx status. Carries `status`, `method`, `path` (the route template, e.g. `/clusters/{cluster_id}`), `url`, `requestId`, `code`, `reason` (Kubernetes `Status.reason` for cluster proxy calls), and the parsed response `body`. `message` is the body's `message`, or the response text when the body is not JSON. Other body fields, such as Kubernetes `details`, are on `body`.
+- `CloudfleetNetworkError`: no response was received. Carries `method`, `path`, `url`, and the original `fetch` error as `cause`.
+
+Aborted requests and request or response validation errors are thrown unchanged.
+
+`message` is the server's text and can contain personal data, such as the user's email in Kubernetes RBAC errors. When reporting errors to telemetry, title and group them by `method`, `path` and `status`, which never contain IDs or names.
+
+`KubernetesService` calls always throw on failure, regardless of the client's `throwOnError` setting.
+
+```ts
+import { CloudfleetApiError, ClustersService } from "@cloudfleet/sdk";
+
+try {
+    await ClustersService.getCluster({
+        path: { cluster_id: id },
+        throwOnError: true,
+    });
+} catch (err) {
+    if (err instanceof CloudfleetApiError && err.status === 404) {
+        // cluster does not exist
+    }
+}
+```
+
+The default `client` converts errors automatically. For a client made with `createClient`, register the conversion with `registerCloudfleetErrors(myClient)`.
+
+The package ships full TypeScript types and an optional [`@tanstack/react-query`](https://tanstack.com/query) integration via `@cloudfleet/sdk/@tanstack/react-query`. See the [Cloudfleet docs](https://cloudfleet.ai/docs) for the full API reference and authentication details.
+
+## License
+
+MIT