virtualizorjs 1.0.5 → 2.0.0

package/README.md

@@ -1,126 +1,211 @@
-# VirtualizorJS
-
-Since there is no SDK's for Node.js for the Virtualizor API, I decided to create one, and one that is actually easy to use and useful with **0 Dependencies** keeping it `Lightweight` and `Fast`.
-
-VirtualizorJS simplifies the management of Virtualizor servers with a streamlined and developer-friendly API for Node.js. Perform actions such as creating, starting, stopping, and restarting virtual servers effortlessly. Ideal for seamless integration into your Node.js applications, providing a powerful toolkit for Virtualizor server management.
-
-
-[![GitHub stars](https://img.shields.io/github/stars/kkMihai/virtualizorjs.svg?style=social&label=Star&maxAge=2592000)](https://github.com/kkMihai/virtualizorjs)
-
-[![Npm package version](https://badgen.net/npm/v/virtualizorjs)](https://npmjs.com/package/virtualizorjs) [![Maintenance](https://img.shields.io/badge/Maintained%3F-Yes-green.svg)](https://github.com/kkMihai/virtualizorjs/graphs/commit-activity)
-
-## Important
- - This library is still in development and there is more to add but for now it's stable and ready to use, all the methods have been tested and work as expected.
-
-## Table of Contents
-- [Installation](#installation)
-- [Usage](#usage)
-- [Examples](#examples)
-- [API Documentation](#api-documentation)
-- [Roadmap](#roadmap)
-- [Contributing](#contributing)
-- [License](#license)
-
-## Installation
-
-```bash
-npm i virtualizorjs@latest
-```
-
-## Usage
-
-```javascript
-
-const VirtualizorClient = require('virtualizorjs');
-
-// Initialize VirtualizorClient
-const { ListVPS } = new VirtualizorClient({
-  host: '< IP or Hostname of Virtualizor Server >',
-  port: 4085, // or 4085 for SSL
-  adminapikey: "< Your API KEY >",
-  adminapipass: "< Your API PASS >",
-});
-
-// Using const client = new VirtualizorClient({ ... }) is also valid, but you will have to use client.ListVPS() instead of ListVPS() which just looks ugly.
-// Example: Get a list of all VPSs
-ListVPS().then((data) => {
-  console.log(data);
-}).catch((err) => {
-  console.log(err);
-});
-```
-
-# Event Handling Usage
-
-VirtualizorJS uses the [EventEmitter](https://nodejs.org/api/events.html) class to handle events. You can attach **`Event Listeners`** to different events provided by the VirtualizorClient.
-
-- Note: To use **`Event Listeners`** we need to define the **`VirtualizorClient`** as a `const` named preferably **`Client`** and then use **`Client.on()`** to attach **`Event Listeners`** to different events.
-
-```javascript
-const VirtualizorClient = require('virtualizorjs'); 
-
-const Client = new VirtualizorClient({
-  host: '< IP or Hostname of Virtualizor Server >',
-  port: 4085,
-  adminapikey: "< Your API KEY >",
-  adminapipass: "< Your API PASS >",
-});
-
-//Get the methods you need
-const { StartVPS } = Client;
-
-// - Event Types - :
-// 1. vpsCreated
-// 2. vpsStarted
-// 3. vpsStopped
-// 4. vpsRestarted
-
-// Event listener for when a virtual server is created
-Client.on('vpsCreated', (response) => {
-  console.log(`Virtual Server Created! Details:`, response);
-});
-
-// Event listener for when a virtual server is started
-Client.on('vpsStarted', (response) => {
-  console.log(`Virtual Server Started! Details:`, response);
-});
-
-// Event listener for when a virtual server is stopped
-Client.on('vpsStopped', (response) => {
-  console.log(`Virtual Server Stopped! Details:`, response);
-});
-
-// Event listener for when a virtual server is restarted
-Client.on('vpsRestarted', (response) => {
-  console.log(`Virtual Server Restarted! Details:`, response);
-});
-```
-
-## ❓ What's the point of using **`Event Listeners`**?
- - **`Event Listeners`** are useful when you want to perform an action when a certain event occurs without modifying the source code of the **`VirtualizorJS`** library to avoid breaking changes.
- - For example, you can use **`Event Listeners`** to send a notification to your `users` when a event is triggered.
- - You can also use **`Event Listeners`** to perform an action when a event is triggered.
-
-## Examples
-
-- [Get VPS's List](/examples/listvps.js)
-- [Create VPS](/examples/createvps.js)
-- [Using Event Handling](/examples/eventhandling.js)
-
-
-## Documentation
-
-- Check the [Wiki](https://github.com/kkMihai/virtualizorjs/wiki) for detailed documentation.
-- If you use frameworks such as [Next.js](https://nextjs.org/) make sure to use it only Server-Side for security reasons.
-
-## Roadmap
-  - [ ] Add Proxmox KVM Support
-  - [ ] Add Virtualization Types enums
-
-## Contributing
-
-- Feel free to contribute by opening issues or submitting pull requests. See [CONTRIBUTING](/CONTRIBUTING.md) for details.
-
-## License
-
-- This project is licensed under the MIT License - see the [LICENSE](/LICENSE) file for details.
+# VirtualizorJS
+
+[![npm version](https://img.shields.io/npm/v/virtualizorjs)](https://www.npmjs.com/package/virtualizorjs)
+[![CI Status](https://img.shields.io/github/actions/workflow/status/kkMihai/virtualizorjs/ci.yml?branch=main)](https://github.com/kkMihai/virtualizorjs/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A **TypeScript-first** SDK for the [Virtualizor](https://www.virtualizor.com/) server management API. Manage VPS instances, users, and plans with a clean, namespaced interface and zero production dependencies.
+
+## Features
+
+- ✅ **TypeScript-first**: Full type safety and IDE autocomplete
+- ✅ **Namespaced API**: Logical organization (`client.vps.*`, `client.users.*`, `client.plans.*`, `client.tasks.*`)
+- ✅ **SHA-256 Authentication**: Secure API communication
+- ✅ **Zero Production Dependencies**: Lightweight and fast
+- ✅ **Async Task Polling**: Built-in support for long-running operations
+- ✅ **Self-signed SSL Ready**: Pre-configured for Virtualizor's typical certificate setup
+- ✅ **Dual Output**: Outputs both CommonJS and ESM modules
+
+## Installation
+
+**npm:**
+```bash
+npm install virtualizorjs
+```
+
+**bun:**
+```bash
+bun add virtualizorjs
+```
+
+## Quick Start
+
+### Create a Client
+
+```typescript
+import { createVirtualizorClient } from 'virtualizorjs';
+
+const client = createVirtualizorClient({
+  host: 'virtualizor.example.com',
+  apiKey: 'your-api-key',
+  apiPass: 'your-api-pass',
+  // Optional: port (default 4085), https (default true), 
+  // rejectUnauthorized (default false), timeout (default 30000ms)
+});
+```
+
+### List All VPS
+
+```typescript
+const vpsList = await client.vps.list();
+
+for (const [vpsId, vps] of Object.entries(vpsList)) {
+  console.log(`${vpsId}: ${vps.hostname} (${vps.status})`);
+}
+```
+
+### Start a VPS and Wait for Completion
+
+Many Virtualizor operations are asynchronous. Use `client.tasks.wait()` to poll for completion:
+
+```typescript
+const result = await client.vps.start('123');
+const task = await client.tasks.wait(result.taskid!);
+
+console.log(`VPS started! Task status: ${task.status}`);
+```
+
+## Error Handling
+
+All SDK errors are instances of `VirtualizorApiError`. Catch and inspect them:
+
+```typescript
+import { VirtualizorApiError } from 'virtualizorjs';
+
+try {
+  await client.vps.start('invalid-id');
+} catch (err) {
+  if (err instanceof VirtualizorApiError) {
+    console.error(`API Error [${err.code}]: ${err.message}`);
+  } else {
+    console.error('Unexpected error:', err);
+  }
+}
+```
+
+## API Reference
+
+### VPS Management
+
+| Method | Parameters | Returns | Notes |
+|--------|-----------|---------|-------|
+| `list()` | — | `Record<string, VPS>` | List all VPS |
+| `get(vpsId)` | `vpsId: string` | `VPS` | Get a single VPS |
+| `create(params)` | `CreateVPSParams` | `AsyncTaskResult` | Async |
+| `delete(vpsId)` | `vpsId: string` | `AsyncTaskResult` | Async |
+| `start(vpsId)` | `vpsId: string` | `AsyncTaskResult` | Async |
+| `stop(vpsId)` | `vpsId: string` | `AsyncTaskResult` | Async |
+| `restart(vpsId)` | `vpsId: string` | `AsyncTaskResult` | Async |
+| `poweroff(vpsId)` | `vpsId: string` | `AsyncTaskResult` | Async |
+| `suspend(vpsId)` | `vpsId: string` | `AsyncTaskResult` | Async |
+| `unsuspend(vpsId)` | `vpsId: string` | `AsyncTaskResult` | Async |
+| `rebuild(vpsId, params)` | `vpsId: string, RebuildVPSParams` | `AsyncTaskResult` | Async |
+| `clone(vpsId, params)` | `vpsId: string, CloneVPSParams` | `AsyncTaskResult` | Async |
+| `migrate(vpsId, params)` | `vpsId: string, MigrateVPSParams` | `AsyncTaskResult` | Async |
+| `status(vpsId)` | `vpsId: string` | `unknown` | Current status snapshot |
+| `vnc(vpsId)` | `vpsId: string` | `VNCInfo` | Get VNC connection details |
+| `stats(vpsId)` | `vpsId: string` | `VPSStatsResponse` | Get resource usage statistics |
+
+### User Management
+
+| Method | Parameters | Returns | Notes |
+|--------|-----------|---------|-------|
+| `list()` | — | `Record<string, User>` | List all users |
+| `create(params)` | `CreateUserParams` | `AsyncTaskResult` | Async |
+| `delete(uid)` | `uid: string` | `AsyncTaskResult` | Async |
+| `suspend(uid)` | `uid: string` | `AsyncTaskResult` | Async |
+| `unsuspend(uid)` | `uid: string` | `AsyncTaskResult` | Async |
+
+### Plan Management
+
+| Method | Parameters | Returns | Notes |
+|--------|-----------|---------|-------|
+| `list()` | — | `Record<string, Plan>` | List all plans |
+| `create(params)` | `CreatePlanParams` | `AsyncTaskResult` | Async |
+| `delete(planId)` | `planId: string` | `AsyncTaskResult` | Async |
+
+### Task Polling
+
+| Method | Parameters | Returns | Notes |
+|--------|-----------|---------|-------|
+| `get(taskId)` | `taskId: string` | `Task \| undefined` | Get task status once |
+| `wait(taskId, options?)` | `taskId: string, { pollIntervalMs?, timeoutMs? }?` | `Promise<Task>` | Poll until complete or timeout |
+
+## Task Polling Pattern
+
+Many API calls return `AsyncTaskResult` with a `taskid` field. Poll for completion:
+
+```typescript
+// Example: Create a VPS and wait for it to be ready
+const createResult = await client.vps.create({
+  hostname: 'my-vps.example.com',
+  // ... other params
+});
+
+const completedTask = await client.tasks.wait(createResult.taskid!, {
+  pollIntervalMs: 5000,  // Check every 5 seconds (default: 2000ms)
+  timeoutMs: 300000,     // Give up after 5 minutes (default: 120000ms)
+});
+
+if (completedTask.status === '1' || completedTask.status === 'done') {
+  console.log('VPS creation completed successfully');
+}
+```
+
+## Configuration
+
+When creating a client, the following options are available:
+
+```typescript
+interface VirtualizorConfig {
+  host: string;                      // Virtualizor server hostname or IP
+  apiKey: string;                    // API key from Virtualizor panel
+  apiPass: string;                   // API password from Virtualizor panel
+  port?: number;                     // Server port (default: 4085)
+  https?: boolean;                   // Use HTTPS (default: true)
+  rejectUnauthorized?: boolean;      // Reject self-signed certs (default: false)
+  timeout?: number;                  // Request timeout in ms (default: 30000)
+}
+```
+
+### Self-Signed SSL Certificates
+
+Virtualizor typically uses self-signed SSL certificates. The SDK handles this by default with `rejectUnauthorized: false`. If you need to enforce certificate validation, set `rejectUnauthorized: true` and ensure your Virtualizor instance has a valid certificate.
+
+## TypeScript Types
+
+All resources are fully typed. Import types as needed:
+
+```typescript
+import type {
+  VPS,
+  CreateVPSParams,
+  RebuildVPSParams,
+  CloneVPSParams,
+  MigrateVPSParams,
+  User,
+  CreateUserParams,
+  Plan,
+  CreatePlanParams,
+  Task,
+  AsyncTaskResult,
+} from 'virtualizorjs';
+```
+
+## Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines on how to help.
+
+## Security
+
+Please report security vulnerabilities to the maintainers privately. See [SECURITY.md](./SECURITY.md) for more details.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.
+
+---
+
+**Author**: [kkMihai](https://github.com/kkMihai)  
+**Package**: [npm/virtualizorjs](https://www.npmjs.com/package/virtualizorjs)  
+**Repository**: [github.com/kkMihai/virtualizorjs](https://github.com/kkMihai/virtualizorjs)

package/dist/index.d.mts

@@ -0,0 +1,245 @@
+interface VirtualizorError {
+    code: number;
+    msg: string;
+}
+interface VirtualizorResponse {
+    title?: string;
+    timenow?: number;
+    time_taken?: string;
+    error?: VirtualizorError[];
+}
+interface AsyncTaskResult extends VirtualizorResponse {
+    done?: 1;
+    taskid?: string;
+}
+type VirtType = 'kvm' | 'xen' | 'openvz' | 'lxc' | 'proxmox' | 'virtuozzo' | 'xcp' | 'hyperv';
+
+interface VirtualizorConfig {
+    host: string;
+    apiKey: string;
+    apiPass?: string;
+    port?: number;
+    https?: boolean;
+    rejectUnauthorized?: boolean;
+    timeout?: number;
+}
+interface ResolvedConfig {
+    host: string;
+    apiKey: string;
+    apiPass: string;
+    port: number;
+    https: boolean;
+    rejectUnauthorized: boolean;
+    timeout: number;
+}
+
+declare class VirtualizorApiError extends Error {
+    readonly code: number;
+    constructor(message: string, code: number);
+}
+type Params = Record<string, string | number | undefined>;
+declare class HttpClient {
+    private readonly config;
+    constructor(config: ResolvedConfig);
+    parseResponse<T extends VirtualizorResponse>(data: T): T;
+    request<T extends VirtualizorResponse>(act: string, queryParams?: Params, bodyParams?: Params): Promise<T>;
+    private rawRequest;
+}
+
+interface Plan {
+    pid: string;
+    plan_name: string;
+    disk: string;
+    ram: string;
+    bandwidth: string;
+    cpu: string;
+    virt?: string;
+}
+interface CreatePlanParams {
+    plan_name: string;
+    disk: number;
+    ram: number;
+    bandwidth: number;
+    cpu: number;
+    virt?: string;
+}
+
+declare class PlansResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(): Promise<Record<string, Plan>>;
+    create(params: CreatePlanParams): Promise<AsyncTaskResult>;
+    delete(planId: string): Promise<AsyncTaskResult>;
+}
+
+interface Task {
+    id: string;
+    action: string;
+    status: string;
+    vpsid?: string;
+    data?: unknown;
+}
+
+declare class TasksResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    get(taskId: string): Promise<Task | undefined>;
+    wait(taskId: string, options?: {
+        pollIntervalMs?: number;
+        timeoutMs?: number;
+    }): Promise<Task>;
+}
+
+interface User {
+    uid: string;
+    email: string;
+    fname?: string;
+    lname?: string;
+    status: string;
+    type: string;
+}
+interface CreateUserParams {
+    email: string;
+    password: string;
+    fname?: string;
+    lname?: string;
+    acttype?: number;
+}
+
+declare class UsersResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(): Promise<Record<string, User>>;
+    create(params: CreateUserParams): Promise<AsyncTaskResult>;
+    delete(uid: string): Promise<AsyncTaskResult>;
+    suspend(uid: string): Promise<AsyncTaskResult>;
+    unsuspend(uid: string): Promise<AsyncTaskResult>;
+}
+
+interface VPS {
+    vpsid: string;
+    hostname: string;
+    status: string;
+    ram: string;
+    hdd: string;
+    bandwidth: string;
+    os_name: string;
+    ip: string;
+    serid?: string;
+    virt?: VirtType;
+    cpu?: string;
+}
+interface ListVPSParams {
+    user?: string | number;
+    vpsid?: string | number;
+    vpsname?: string;
+    vpsip?: string;
+    vpshostname?: string;
+    vsstatus?: string;
+    vstype?: VirtType;
+    serid?: number;
+    plid?: number;
+    bpid?: number;
+}
+interface CreateVPSParams {
+    hostname: string;
+    rootpass: string;
+    osid: number;
+    plid?: number;
+    user_email?: string;
+    ips?: number;
+    ips_int?: number;
+    space?: number;
+    ram?: number;
+    burst?: number;
+    bandwidth?: number;
+    cpu?: number;
+    cpu_percent?: number;
+    virt?: VirtType;
+    serid?: number;
+    node_select?: 0 | 1;
+    recipe?: number;
+    sshkey?: string;
+    nopassword?: 0 | 1;
+}
+interface RebuildVPSParams {
+    /** OS template ID to rebuild with */
+    osid: number;
+    /** New root password for the VPS */
+    newpass: string;
+    /** Must be set to 1 to confirm the rebuild */
+    conf: 1;
+    /** Format primary disk (0 = no, 1 = yes); defaults to 0 */
+    format_primary?: 0 | 1;
+    /** Send rebuild notification email (0 = no, 1 = yes) */
+    eu_send_rebuild_email?: 0 | 1;
+    /** Recipe ID to apply post-rebuild */
+    recipe?: number;
+    /** SSH key to inject */
+    sshkey?: string;
+}
+interface CloneVPSParams {
+    /** Hostname for the new cloned VPS */
+    hostname: string;
+    /** Root password for the new cloned VPS */
+    rootpass: string;
+    /** Source server ID (server where the VPS lives) */
+    from_server: number;
+    /** Destination server ID (server to clone into) */
+    to_server: number;
+}
+interface MigrateVPSParams {
+    /** Destination server ID */
+    serid: number;
+    /** Source server IP address */
+    from_ip: string;
+    /** Source server API/root password */
+    from_pass: string;
+    /** 0 = ignore VDF conflicts, 1 = error on conflict */
+    ignore_if_vdfconflict?: 0 | 1;
+    /** 0 = use gzip compression, 1 = disable gzip */
+    disable_gzip?: 0 | 1;
+    /** 0 = offline migration, 1 = live migration */
+    online?: 0 | 1;
+}
+interface VPSStatsResponse extends VirtualizorResponse {
+    vs_stats?: unknown;
+    vs_bandwidth?: unknown;
+    time_taken?: string;
+}
+interface VNCInfo extends VirtualizorResponse {
+    novnc?: string;
+    [key: string]: unknown;
+}
+
+declare class VpsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(filters?: ListVPSParams): Promise<Record<string, VPS>>;
+    get(vpsId: string): Promise<VPS>;
+    create(params: CreateVPSParams): Promise<AsyncTaskResult>;
+    delete(vpsId: string): Promise<AsyncTaskResult>;
+    start(vpsId: string): Promise<AsyncTaskResult>;
+    stop(vpsId: string): Promise<AsyncTaskResult>;
+    restart(vpsId: string): Promise<AsyncTaskResult>;
+    poweroff(vpsId: string): Promise<AsyncTaskResult>;
+    suspend(vpsId: string): Promise<AsyncTaskResult>;
+    unsuspend(vpsId: string): Promise<AsyncTaskResult>;
+    rebuild(vpsId: string, params: RebuildVPSParams): Promise<AsyncTaskResult>;
+    clone(vpsId: string, params: CloneVPSParams): Promise<AsyncTaskResult>;
+    migrate(vpsId: string, params: MigrateVPSParams): Promise<AsyncTaskResult>;
+    status(vpsId: string): Promise<unknown>;
+    vnc(vpsId: string): Promise<VNCInfo>;
+    stats(vpsId: string): Promise<VPSStatsResponse>;
+}
+
+declare class VirtualizorClient {
+    readonly vps: VpsResource;
+    readonly users: UsersResource;
+    readonly plans: PlansResource;
+    readonly tasks: TasksResource;
+    constructor(config: VirtualizorConfig);
+}
+declare function createVirtualizorClient(config: VirtualizorConfig): VirtualizorClient;
+
+export { type AsyncTaskResult, type CloneVPSParams, type CreatePlanParams, type CreateUserParams, type CreateVPSParams, type ListVPSParams, type MigrateVPSParams, type Plan, type RebuildVPSParams, type Task, type User, type VPS, type VirtType, VirtualizorApiError, VirtualizorClient, type VirtualizorConfig, createVirtualizorClient };