truenas-client 1.0.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) Daury Guzman <me@dauryguzman.com>
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,143 @@
+# truenas-client
+
+A lightweight TypeScript client for interacting with the [TrueNAS WebSocket API](https://api.truenas.com/v25.10/jsonrpc.html) using JSON-RPC 2.0.
+
+## Installation
+
+```sh
+npm install truenas-client
+```
+
+> **Note:** Requires Node.js >= 21 (for native `WebSocket` support).
+
+## Usage
+
+### Setup
+
+```ts
+import { TrueNASClient } from "truenas-client";
+
+const client = new TrueNASClient("wss://your-truenas-host/websocket", "your-api-key");
+```
+
+### Single Request
+
+Use `sendRequest` to send a single API call. The client handles authentication automatically before forwarding your request.
+
+```ts
+const response = await client.sendRequest("system.info");
+console.log(response.result);
+```
+
+You can also pass parameters:
+
+```ts
+const response = await client.sendRequest("pool.dataset.query", [[], { limit: 10 }]);
+console.log(response.result);
+```
+
+### Error Handling
+
+Each response may include an `error` object instead of a `result`. Always check for errors:
+
+```ts
+const response = await client.sendRequest("system.info");
+
+if (response.error) {
+  console.error(`Error ${response.error.code}: ${response.error.message}`);
+} else {
+  console.log(response.result);
+}
+```
+
+Requests will reject with an `Error` in the following cases:
+
+- **Authentication failure** — invalid API key or denied access.
+- **Timeout** — no response received within 30 seconds (default).
+- **WebSocket error** — connection-level error.
+- **WebSocket closed** — server closes the connection before a response is received.
+
+## API
+
+### `new TrueNASClient(wsURL: string, apiKey: string)`
+
+Creates a new client instance.
+
+| Parameter | Type     | Description                                                                     |
+| --------- | -------- | ------------------------------------------------------------------------------- |
+| `wsURL`   | `string` | The WebSocket URL of your TrueNAS server (e.g. `ws://192.168.1.100/websocket`) |
+| `apiKey`  | `string` | A TrueNAS API key for authentication                                           |
+
+> For TrueNAS servers with HTTPS enabled, use `wss://` instead of `ws://`.
+
+### `client.sendRequest(method: string, params?: any, timeoutMs?: number): Promise<JSONRPCResponse>`
+
+Sends a single JSON-RPC 2.0 request. Opens a WebSocket connection, authenticates with the provided API key, sends the request, and closes the connection.
+
+| Parameter   | Type     | Default | Description                                              |
+| ----------- | -------- | ------- | -------------------------------------------------------- |
+| `method`    | `string` | —       | The JSON-RPC method to call (e.g. `"system.info"`)      |
+| `params`    | `any`    | —       | Optional parameters to pass with the request             |
+| `timeoutMs` | `number` | `30000` | Timeout in milliseconds for each underlying WebSocket call (auth + request) |
+
+### Types
+
+#### `JSONRPCRequest`
+
+```ts
+interface JSONRPCRequest {
+  jsonrpc: "2.0";
+  method: string;
+  params?: any;
+  id: number | string;
+}
+```
+
+#### `JSONRPCResponse`
+
+```ts
+interface JSONRPCResponse {
+  jsonrpc: "2.0";
+  result?: any;
+  error?: {
+    code: number;
+    message: string;
+    data?: any;
+  };
+  id: number | string;
+}
+```
+
+The `result` field is typed as `any` to match the [TrueNAS JSON-RPC API](https://api.truenas.com/v25.10/jsonrpc.html), which returns varied response shapes depending on the method called.
+
+## Security
+
+Never hardcode your API key. Use environment variables:
+
+```ts
+const client = new TrueNASClient(
+  process.env.TRUENAS_URL!,
+  process.env.TRUENAS_API_KEY!
+);
+```
+
+## How It Works
+
+1. A new WebSocket connection is opened to the TrueNAS server.
+2. The client authenticates using `auth.login_with_api_key` with your API key.
+3. If authentication succeeds, your request is sent over the same connection.
+4. The connection is closed after the response is received.
+
+Each call to `sendRequest` opens and closes its own WebSocket connection.
+
+## Building
+
+```sh
+npm run build
+```
+
+This compiles the TypeScript source from `src/` into JavaScript in `dist/` using [tsup](https://tsup.egoist.dev/), producing both ESM and CJS outputs with type declarations.
+
+## License
+
+[ISC](LICENSE) © Daury Guzman <me@dauryguzman.com>

package/dist/index.cjs

@@ -0,0 +1,122 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  TrueNASClient: () => TrueNASClient,
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var TrueNASClient = class {
+  wsURL;
+  apiKey;
+  constructor(wsURL, apiKey) {
+    const url = new URL(wsURL);
+    if (url.protocol !== "wss:" && url.protocol !== "ws:")
+      throw new Error("Invalid url protocol. Expect wss: or ws:");
+    this.wsURL = wsURL;
+    this.apiKey = apiKey;
+  }
+  async sendRequest(method, params, timeoutMs = 3e4) {
+    let id = 0;
+    const socket = new WebSocket(this.wsURL);
+    try {
+      const authRequest = this.request(id++, "auth.login_with_api_key", [this.apiKey]);
+      const apiRequest = this.request(id++, method, params);
+      const authResponse = await this.call(socket, authRequest, timeoutMs);
+      if (authResponse.result !== true) {
+        throw new Error("Authentication failed");
+      }
+      return await this.call(socket, apiRequest, timeoutMs);
+    } finally {
+      socket.close();
+    }
+  }
+  request(id, method, params) {
+    return {
+      jsonrpc: "2.0",
+      method,
+      params: params ?? [],
+      id
+    };
+  }
+  async parseMessageData(data) {
+    if (typeof data === "string") return data;
+    if (data instanceof Blob) return await data.text();
+    if (data instanceof ArrayBuffer) return new TextDecoder().decode(data);
+    return String(data);
+  }
+  call(socket, req, timeoutMs) {
+    return new Promise((resolve, reject) => {
+      const cleanup = () => {
+        clearTimeout(timer);
+        socket.removeEventListener("message", onMessage);
+        socket.removeEventListener("error", onError);
+        socket.removeEventListener("close", onClose);
+        socket.removeEventListener("open", onOpen);
+      };
+      const timer = setTimeout(() => {
+        cleanup();
+        reject(new Error(`Request timed out for id ${req.id}`));
+      }, timeoutMs);
+      const onMessage = async (event) => {
+        try {
+          const raw = await this.parseMessageData(event.data);
+          const response = JSON.parse(raw);
+          if (response.id === req.id) {
+            cleanup();
+            resolve(response);
+          }
+        } catch (error) {
+          cleanup();
+          reject(new Error(`Error parsing response for id ${req.id}: ${String(error)}`));
+        }
+      };
+      const onError = (event) => {
+        cleanup();
+        reject(new Error(`WebSocket error ${event}`));
+      };
+      const onClose = (event) => {
+        cleanup();
+        reject(new Error(`WebSocket closed before response received (code: ${event.code})`));
+      };
+      const onOpen = () => {
+        socket.send(JSON.stringify(req));
+      };
+      socket.addEventListener("message", onMessage);
+      socket.addEventListener("error", onError);
+      socket.addEventListener("close", onClose);
+      if (socket.readyState === socket.OPEN) {
+        socket.send(JSON.stringify(req));
+      } else {
+        socket.addEventListener("open", onOpen);
+      }
+    });
+  }
+};
+
+// src/index.ts
+var index_default = TrueNASClient;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  TrueNASClient
+});

package/dist/index.d.cts

@@ -0,0 +1,27 @@
+declare class TrueNASClient {
+    private wsURL;
+    private apiKey;
+    constructor(wsURL: string, apiKey: string);
+    sendRequest(method: string, params?: any, timeoutMs?: number): Promise<JSONRPCResponse>;
+    private request;
+    private parseMessageData;
+    private call;
+}
+interface JSONRPCRequest {
+    jsonrpc: "2.0";
+    method: string;
+    params?: any;
+    id: number | string;
+}
+interface JSONRPCResponse {
+    jsonrpc: "2.0";
+    result?: any;
+    error?: {
+        code: number;
+        message: string;
+        data?: any;
+    };
+    id: number | string;
+}
+
+export { type JSONRPCRequest, type JSONRPCResponse, TrueNASClient, TrueNASClient as default };

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+declare class TrueNASClient {
+    private wsURL;
+    private apiKey;
+    constructor(wsURL: string, apiKey: string);
+    sendRequest(method: string, params?: any, timeoutMs?: number): Promise<JSONRPCResponse>;
+    private request;
+    private parseMessageData;
+    private call;
+}
+interface JSONRPCRequest {
+    jsonrpc: "2.0";
+    method: string;
+    params?: any;
+    id: number | string;
+}
+interface JSONRPCResponse {
+    jsonrpc: "2.0";
+    result?: any;
+    error?: {
+        code: number;
+        message: string;
+        data?: any;
+    };
+    id: number | string;
+}
+
+export { type JSONRPCRequest, type JSONRPCResponse, TrueNASClient, TrueNASClient as default };

package/dist/index.js

@@ -0,0 +1,95 @@
+// src/client.ts
+var TrueNASClient = class {
+  wsURL;
+  apiKey;
+  constructor(wsURL, apiKey) {
+    const url = new URL(wsURL);
+    if (url.protocol !== "wss:" && url.protocol !== "ws:")
+      throw new Error("Invalid url protocol. Expect wss: or ws:");
+    this.wsURL = wsURL;
+    this.apiKey = apiKey;
+  }
+  async sendRequest(method, params, timeoutMs = 3e4) {
+    let id = 0;
+    const socket = new WebSocket(this.wsURL);
+    try {
+      const authRequest = this.request(id++, "auth.login_with_api_key", [this.apiKey]);
+      const apiRequest = this.request(id++, method, params);
+      const authResponse = await this.call(socket, authRequest, timeoutMs);
+      if (authResponse.result !== true) {
+        throw new Error("Authentication failed");
+      }
+      return await this.call(socket, apiRequest, timeoutMs);
+    } finally {
+      socket.close();
+    }
+  }
+  request(id, method, params) {
+    return {
+      jsonrpc: "2.0",
+      method,
+      params: params ?? [],
+      id
+    };
+  }
+  async parseMessageData(data) {
+    if (typeof data === "string") return data;
+    if (data instanceof Blob) return await data.text();
+    if (data instanceof ArrayBuffer) return new TextDecoder().decode(data);
+    return String(data);
+  }
+  call(socket, req, timeoutMs) {
+    return new Promise((resolve, reject) => {
+      const cleanup = () => {
+        clearTimeout(timer);
+        socket.removeEventListener("message", onMessage);
+        socket.removeEventListener("error", onError);
+        socket.removeEventListener("close", onClose);
+        socket.removeEventListener("open", onOpen);
+      };
+      const timer = setTimeout(() => {
+        cleanup();
+        reject(new Error(`Request timed out for id ${req.id}`));
+      }, timeoutMs);
+      const onMessage = async (event) => {
+        try {
+          const raw = await this.parseMessageData(event.data);
+          const response = JSON.parse(raw);
+          if (response.id === req.id) {
+            cleanup();
+            resolve(response);
+          }
+        } catch (error) {
+          cleanup();
+          reject(new Error(`Error parsing response for id ${req.id}: ${String(error)}`));
+        }
+      };
+      const onError = (event) => {
+        cleanup();
+        reject(new Error(`WebSocket error ${event}`));
+      };
+      const onClose = (event) => {
+        cleanup();
+        reject(new Error(`WebSocket closed before response received (code: ${event.code})`));
+      };
+      const onOpen = () => {
+        socket.send(JSON.stringify(req));
+      };
+      socket.addEventListener("message", onMessage);
+      socket.addEventListener("error", onError);
+      socket.addEventListener("close", onClose);
+      if (socket.readyState === socket.OPEN) {
+        socket.send(JSON.stringify(req));
+      } else {
+        socket.addEventListener("open", onOpen);
+      }
+    });
+  }
+};
+
+// src/index.ts
+var index_default = TrueNASClient;
+export {
+  TrueNASClient,
+  index_default as default
+};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "truenas-client",
+  "version": "1.0.0",
+  "description": "A lightweight TypeScript client for the TrueNAS WebSocket API (JSON-RPC 2.0)",
+  "main": "dist/index.cjs",
+  "type": "module",
+  "module": "dist/index.js",
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:dauryg/truenas-client.git"
+  },
+  "keywords": [
+    "truenas"
+  ],
+  "author": "daury guzman <me@dauryguzman.com>",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/dauryg/truenas-client/issues"
+  },
+  "homepage": "https://github.com/dauryg/truenas-client#readme",
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=21"
+  }
+}