@virtbase/proxmox-api 3.0.0 → 4.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. package/CHANGELOG.md +10 -53
  2. package/LICENSE +22 -0
  3. package/README.md +81 -82
  4. package/dist/client.d.ts +13 -7
  5. package/dist/client.js +23 -23
  6. package/dist/errors.d.ts +364 -0
  7. package/dist/errors.js +372 -0
  8. package/dist/index.d.ts +5 -3
  9. package/dist/index.js +3 -18
  10. package/dist/model.d.ts +28408 -28157
  11. package/dist/model.js +4 -16
  12. package/dist/proxmox-engine.d.ts +273 -54
  13. package/dist/proxmox-engine.js +772 -248
  14. package/dist/proxy.d.ts +61 -19
  15. package/dist/proxy.js +118 -33
  16. package/dist/qm-monitor.d.ts +225 -25
  17. package/dist/qm-monitor.js +152 -52
  18. package/dist/schema-info.d.ts +12 -0
  19. package/dist/schema-info.js +13 -0
  20. package/dist/tasks.d.ts +129 -0
  21. package/dist/tasks.js +132 -0
  22. package/package.json +33 -34
  23. package/dist/client.d.ts.map +0 -1
  24. package/dist/client.js.map +0 -1
  25. package/dist/index.d.ts.map +0 -1
  26. package/dist/index.js.map +0 -1
  27. package/dist/model.d.ts.map +0 -1
  28. package/dist/model.js.map +0 -1
  29. package/dist/proxmox-engine.d.ts.map +0 -1
  30. package/dist/proxmox-engine.js.map +0 -1
  31. package/dist/proxy.d.ts.map +0 -1
  32. package/dist/proxy.js.map +0 -1
  33. package/dist/qm-monitor.d.ts.map +0 -1
  34. package/dist/qm-monitor.js.map +0 -1
  35. package/src/__tests__/helpers.ts +0 -39
  36. package/src/__tests__/proxmox-engine.test.ts +0 -393
  37. package/src/__tests__/proxy.test.ts +0 -190
  38. package/src/__tests__/qm-monitor.test.ts +0 -215
  39. package/src/client.ts +0 -58
  40. package/src/index.ts +0 -34
  41. package/src/model.ts +0 -32101
  42. package/src/proxmox-engine.ts +0 -452
  43. package/src/proxy.ts +0 -195
  44. package/src/qm-monitor.ts +0 -303
package/CHANGELOG.md CHANGED
@@ -14,59 +14,16 @@ commit conventions, so the sections below them were inferred from commit
14
14
  subjects and are approximate. Where the previous maintainer wrote release notes
15
15
  by hand, they are kept verbatim above the reconstructed sections.
16
16
 
17
- ## Unreleased
18
-
19
- Forked from [UrielCh/proxmox-api](https://github.com/UrielCh/proxmox-api) at v1.1.1
20
- and republished as `@virtbase/proxmox-api`.
21
-
22
- * **Breaking:** ESM only. The CommonJS build (`cjs/`, `tsconfig-cjs.json`) and the
23
- `require` condition in `exports` are gone; output moved from `esm/` to `dist/`.
24
- * **Breaking:** renamed to `@virtbase/proxmox-api`.
25
- * **Breaking:** the API model now targets **Proxmox VE 9** (was PVE 8): 678
26
- operations, +98 added and -3 removed. New surface includes SDN fabrics, HA
27
- rules, `cluster/bulk-action`, `cluster/qemu` custom CPU models, SDN
28
- prefix-lists and route-maps, webhook notification endpoints, and
29
- `cluster/metrics/export`. Gone: `nodes/{node}/hardware/pci/{pciid}`,
30
- `.../{pciid}/mdev` and `nodes/{node}/scan/glusterfs`.
31
- * **Breaking:** returned objects no longer carry a blanket
32
- `[key: string]: any`. It was applied to every response regardless of the
33
- schema, which defeated type checking on all of them; it is now emitted only
34
- where the schema permits extra keys.
35
- * Indexed parameters (`net[n]`, `scsi[n]`, `mp[n]`, ...) are expanded to the
36
- slots the API actually accepts - `scsi0`..`scsi30`, `ide0`..`ide3`,
37
- `net0`..`net31`, `usb0`..`usb13`, `mp0`..`mp255`, and so on - taken from the
38
- constants that generate them in qemu-server, pve-container, pve-cluster and
39
- pve-manager. Upstream capped them at a hand-picked `net0`..`net3`, which
40
- rejected valid configurations.
41
- * Enumerations are emitted as unions and named PVE formats as string aliases,
42
- both deduplicated across the whole model.
43
- * **Breaking:** `undici` is no longer a dependency - the client uses the
44
- platform `fetch`. The package now has no runtime dependencies and no `node:`
45
- imports.
46
- * Import via `node:` protocol in `ProxmoxEngine`.
47
- * **Breaking:** `ApiRequestable.doRequest` returns `Promise<unknown>` rather
48
- than `Promise<any>`, and takes `ApiParamType` for its parameters. Custom
49
- engines still satisfy it; direct callers of `doRequest` now need a cast.
50
- * **Breaking:** `USBInfo.product` and `USBInfo.id` are optional, matching the
51
- monitor output they are parsed from - the trailing `, Product ..., ID: ...`
52
- is not always present.
53
- * **Breaking:** `QmMonitor.infoUsb()` no longer takes a filter argument. It
54
- accepted one whose fields (`vendorId`, `productId`) did not exist on
55
- `USBInfo`, and never applied it.
56
- * **Breaking:** `QmMonitor.deviceAddMissing` returns the ids it attached and
57
- awaits each attach. It previously fired them without awaiting, so failures
58
- disappeared and the guest saw an unbounded burst of monitor commands.
59
- * Fixed `QmMonitor.infoUsbhost` filtering: `vendorId` and `productId` both
60
- tested the device *name*, so neither filter could ever match.
61
- * Fixed `String(proxmox)` recursing until the stack overflowed. Reserved
62
- methods were returned unbound, so `toString` read `this.path` back through
63
- the proxy and stringified the result forever.
64
- * Path segments passed to `$()` now escape `?` and `#` as well as `/`, so a
65
- value cannot truncate the path or start a query string.
66
- * Documentation moved to a VitePress site: hand-written guides, a client
67
- reference, and an endpoint reference generated from the same schema parse as
68
- the types. Replaces 63 MB of committed typedoc HTML that documented the PVE 8
69
- surface.
17
+ ## [4.0.0](https://github.com/virtbase/proxmox-api/compare/3.0.0...4.0.0) (2026-11-16)
18
+
19
+
20
+ ### ⚠ BREAKING CHANGES
21
+
22
+ * typed client errors, versioned Proxmox schema tracking and automated releases ([#9](https://github.com/virtbase/proxmox-api/issues/9))
23
+
24
+ ### Features
25
+
26
+ * typed client errors, versioned Proxmox schema tracking and automated releases ([#9](https://github.com/virtbase/proxmox-api/issues/9)) ([40a03b3](https://github.com/virtbase/proxmox-api/commit/40a03b3ef2e5b88fe66893fe29db7accf15a95e1))
70
27
 
71
28
  ## [3.0.0](https://github.com/virtbase/proxmox-api/compare/2.0.0...3.0.0) (2026-09-17)
72
29
 
package/LICENSE ADDED
@@ -0,0 +1,22 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2020-2022 Chemouni Uriel <uchemouni@gmail.com>
4
+ Copyright (c) 2026 BeastHost UG (haftungsbeschränkt) and contributors
5
+
6
+ Permission is hereby granted, free of charge, to any person obtaining a copy
7
+ of this software and associated documentation files (the "Software"), to deal
8
+ in the Software without restriction, including without limitation the rights
9
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10
+ copies of the Software, and to permit persons to whom the Software is
11
+ furnished to do so, subject to the following conditions:
12
+
13
+ The above copyright notice and this permission notice shall be included in all
14
+ copies or substantial portions of the Software.
15
+
16
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22
+ SOFTWARE.
package/README.md CHANGED
@@ -1,110 +1,109 @@
1
1
  # @virtbase/proxmox-api
2
2
 
3
- TypeScript API to manage Proxmox servers.
3
+ [![npm](https://img.shields.io/npm/v/@virtbase/proxmox-api)](https://www.npmjs.com/package/@virtbase/proxmox-api)
4
+ [![CI](https://github.com/virtbase/proxmox-api/actions/workflows/ci.yml/badge.svg)](https://github.com/virtbase/proxmox-api/actions/workflows/ci.yml)
5
+ [![license](https://img.shields.io/npm/l/@virtbase/proxmox-api)](https://github.com/virtbase/proxmox-api/blob/main/LICENSE)
4
6
 
5
- A fork of [UrielCh/proxmox-api](https://github.com/UrielCh/proxmox-api), maintained
6
- for [virtbase](https://virtbase.com). ESM-only; published as `@virtbase/proxmox-api`.
7
+ A fully typed client for the [Proxmox VE API](https://pve.proxmox.com/wiki/Proxmox_VE_API).
8
+ Every endpoint, parameter and response is generated from the schema Proxmox
9
+ publishes, so the API documentation shows up in your editor and mistakes are
10
+ caught at compile time.
7
11
 
8
- * [API Viewer](https://pve.proxmox.com/pve-docs/api-viewer/)
9
- * [API Docs](https://pve.proxmox.com/wiki/Proxmox_VE_API)
12
+ - **The whole API**, typed — nothing hand-maintained, nothing missing.
13
+ - **Zero dependencies.** Built on the platform `fetch`; runs on Node 22+, Bun,
14
+ Deno and edge runtimes. ESM only.
15
+ - **Useful errors.** Typed error classes with the status, Proxmox's reason and
16
+ the rejected parameters.
17
+ - **Tracks Proxmox automatically**, with a published
18
+ [API changelog](https://virtbase.github.io/proxmox-api/reference/api-changelog/).
10
19
 
11
- Mapping 100% of available calls, contains all api documentation in typing file.
12
- code size < 10Ko including docs
13
-
14
- ## Usage
15
-
16
- ### Overview
17
-
18
- to use this API take the Path you want to call, and replace:
19
- - the `/` by `.`
20
- - the `${variable}` by `.(variable)`
21
- - append the http method you want to call with a $ at the end (`.$get()`, `.$post()`, `.$put()` or `.$delete()`)
22
-
23
- that it.
24
-
25
- ### Example
26
-
27
- To call `GET /cluster/acme/account/{name}` you will call `proxmox.cluster.acme.account.$(name).$get()`
28
-
29
- To call `GET /api2/json/cluster/backup/{id}/included_volumes` you will call `proxmox.cluster.backup.{id}.included_volumes.$get()`
30
-
31
- To call `GET /api2/json/nodes` you will call `proxmox.nodes.$get()`
32
-
33
- The provided typing will assist you within intelisense, so you do not need to read any external doc.
34
-
35
- ## Code sample
20
+ **[Documentation](https://virtbase.github.io/proxmox-api/)** ·
21
+ [Compatibility](https://virtbase.github.io/proxmox-api/guide/compatibility) ·
22
+ [Endpoint reference](https://virtbase.github.io/proxmox-api/reference/endpoints/)
36
23
 
24
+ ## Install
37
25
 
38
26
  ```bash
39
- bun add @virtbase/proxmox-api
27
+ npm install @virtbase/proxmox-api
40
28
  ```
41
29
 
42
- ```typescript
43
- import proxmoxApi from "@virtbase/proxmox-api";
44
-
45
- // authorize self signed cert if you do not use a valid SSL certificat
46
- process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
47
-
48
- async function test() {
49
- // connect to proxmox
50
- const proxmox = proxmoxApi({host: '127.0.0.1', password: 'password', username: 'user1@pam'});
51
- // list nodes
52
- const nodes = await proxmox.nodes.$get();
53
- // iterate cluster nodes
54
- for (const node of nodes) {
55
- const theNode = proxmox.nodes.$(node.node);
56
- // list Qemu VMS
57
- const qemus = await theNode.qemu.$get({full:true});
58
- // iterate Qemu VMS
59
- for (const qemu of qemus) {
60
- // do some suff.
61
- const config = await theNode.qemu.$(qemu.vmid).config.$get();
62
- console.log(`vm: ${config.name}, memory: ${config.memory}`);
63
- // const vnc = await theNode.qemu.$(qemu.vmid).vncproxy.$post();
64
- // console.log('vnc:', vnc);
65
- // const spice = await theNode.qemu.$(qemu.vmid).spiceproxy.$post();
66
- // console.log('spice:', spice);
67
- }
68
- }
30
+ Each release is generated from one Proxmox VE version; see
31
+ [Compatibility](https://virtbase.github.io/proxmox-api/guide/compatibility) for
32
+ which release matches your cluster.
33
+
34
+ ## Usage
35
+
36
+ Take a path from the Proxmox API and read it as property access: `/` becomes
37
+ `.`, a `{placeholder}` becomes `.$(value)`, and the HTTP method goes on the end
38
+ as `.$get()`, `.$post()`, `.$put()` or `.$delete()`.
39
+
40
+ ```ts
41
+ import proxmoxApi, { waitForTask } from "@virtbase/proxmox-api";
42
+
43
+ const proxmox = proxmoxApi({
44
+ host: "192.0.2.10",
45
+ tokenID: "root@pam!automation",
46
+ tokenSecret: process.env.PVE_TOKEN_SECRET!,
47
+ });
48
+
49
+ // GET /nodes
50
+ for (const { node } of await proxmox.nodes.$get()) {
51
+ // GET /nodes/{node}/qemu
52
+ for (const vm of await proxmox.nodes.$(node).qemu.$get({ full: true })) {
53
+ console.log(node, vm.vmid, vm.name, vm.status);
54
+ }
69
55
  }
70
56
 
71
- test().catch(console.error);
57
+ // POST /nodes/{node}/qemu/{vmid}/status/start returns a task id;
58
+ // waitForTask resolves when the task succeeds and throws when it fails.
59
+ const upid = await proxmox.nodes.$("pve1").qemu.$(100).status.start.$post();
60
+ await waitForTask(proxmox, upid);
72
61
  ```
73
62
 
74
- ### Initialisation alternavives:
63
+ Path segments with a hyphen use bracket access:
75
64
 
76
- - keeping access to ProxmoxEngine object (that can be use to share a ticket, or to access it)
65
+ ```ts
66
+ await proxmox.nodes.$("pve1").qemu.$(100).agent["get-fsinfo"].$get();
67
+ ```
77
68
 
78
- ```typescript
79
- import proxmoxApi, { ProxmoxEngine } from "@virtbase/proxmox-api";
69
+ ### Authentication
80
70
 
81
- process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
71
+ ```ts
72
+ // API token (recommended for automation)
73
+ proxmoxApi({ host, tokenID: "user@pve!name", tokenSecret });
82
74
 
83
- async function test() {
84
- // connect to proxmox
85
- const engine = new ProxmoxEngine({host: '127.0.0.1', password: 'password', username: 'user1@pam'});
86
- const proxmox = proxmoxApi(engine);
87
- }
75
+ // Username and password; the ticket is obtained and renewed for you
76
+ proxmoxApi({ host, username: "user@pve", password });
88
77
  ```
89
78
 
90
- - Using Api token
91
-
79
+ The port defaults to `8006`. A stock Proxmox install uses a certificate signed
80
+ by its own CA; see
81
+ [Self-signed certificates](https://virtbase.github.io/proxmox-api/guide/getting-started#self-signed-certificates).
92
82
 
93
- ```typescript
94
- import proxmoxApi from "@virtbase/proxmox-api";
83
+ ### Errors
95
84
 
96
- process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
85
+ ```ts
86
+ import { ProxmoxApiError, ProxmoxParameterError } from "@virtbase/proxmox-api";
97
87
 
98
- async function test() {
99
- // connect to proxmox
100
- const proxmox = proxmoxApi({host: '127.0.0.1', tokenID: 'USER@REALM!TOKENID', tokenSecret: '12345678-1234-1234-1234-1234567890ab'});
88
+ try {
89
+ await proxmox.nodes.$("pve1").qemu.$(100).config.$put({ memory: "lots" });
90
+ } catch (error) {
91
+ if (error instanceof ProxmoxParameterError) {
92
+ console.error(error.errors); // { memory: "value is not an integer" }
93
+ } else if (error instanceof ProxmoxApiError) {
94
+ console.error(error.status, error.reason);
95
+ }
101
96
  }
102
97
  ```
103
98
 
104
- ## Notes
99
+ Only `GET` requests are retried. See
100
+ [Errors, retries and timeouts](https://virtbase.github.io/proxmox-api/guide/errors).
105
101
 
106
- - if the call path contains a hyphen, you will need to use the `['field']` syntax ex:
102
+ ## Credits
107
103
 
108
- ```typescript
109
- await theNode.qemu.$(vmid).agent['get-fsinfo'].$get()
110
- ```
104
+ Based on [`proxmox-api`](https://github.com/UrielCh/proxmox-api) by Uriel
105
+ Chemouni. Maintained by [virtbase](https://virtbase.com).
106
+
107
+ ## License
108
+
109
+ [MIT](https://github.com/virtbase/proxmox-api/blob/main/LICENSE)
package/dist/client.d.ts CHANGED
@@ -2,17 +2,25 @@ import type { Proxmox } from "./model.js";
2
2
  import type { ProxmoxEngineOptions } from "./proxmox-engine.js";
3
3
  import type { ApiRequestable } from "./proxy.js";
4
4
  /**
5
- * Build a typed Proxmox API client.
5
+ * Builds a typed Proxmox API client.
6
6
  *
7
- * @param options Connection options, or any {@link ApiRequestable} to send
8
- * requests through - a pre-built {@link ProxmoxEngine} whose session you
9
- * want to keep, or a stub for tests.
7
+ * @remarks
8
+ * Building the client sends nothing. The first request goes out when a
9
+ * `$get`, `$post`, `$put` or `$delete` method is called on the result, and
10
+ * with password authentication that request logs in first.
10
11
  *
12
+ * @param options - Connection options, from which a new {@link ProxmoxEngine}
13
+ * is built, or any {@link ApiRequestable} to send requests through instead:
14
+ * a pre-built {@link ProxmoxEngine} whose session you want to keep, or a
15
+ * stub for tests.
16
+ * @returns A proxy that turns property access into paths below `/api2/json`
17
+ * and `$`-prefixed method calls into requests.
18
+ * @throws A {@link ProxmoxConfigError} if connection options are given and
19
+ * are unusable, for example a malformed `tokenID` or a port in `host`.
11
20
  * @example
12
21
  * ```ts
13
22
  * const proxmox = proxmoxApi({
14
23
  * host: "192.0.2.10",
15
- * port: 8006,
16
24
  * tokenID: "root@pam!automation",
17
25
  * tokenSecret: "12345678-1234-1234-1234-1234567890ab",
18
26
  * });
@@ -21,5 +29,3 @@ import type { ApiRequestable } from "./proxy.js";
21
29
  * ```
22
30
  */
23
31
  export declare function proxmoxApi(options: ProxmoxEngineOptions | ApiRequestable): Proxmox.Api;
24
- export default proxmoxApi;
25
- //# sourceMappingURL=client.d.ts.map
package/dist/client.js CHANGED
@@ -1,37 +1,39 @@
1
- // Proxmox-API Interactive proxmox API for developpers how do not like reading docs
2
- // Copyright (C) 2020-2022 Chemouni Uriel <uchemouni@gmail.com>
3
- //
4
- // This program is free software: you can redistribute it and/or modify
5
- // it under the terms of the GNU General Public License as published by
6
- // the Free Software Foundation, either version 3 of the License, or
7
- // (at your option) any later version.
8
- //
9
- // This program is distributed in the hope that it will be useful,
10
- // but WITHOUT ANY WARRANTY; without even the implied warranty of
11
- // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12
- // GNU General Public License for more details.
13
- //
14
- // You should have received a copy of the GNU General Public License
15
- // along with this program. If not, see <http://www.gnu.org/licenses/>.
16
1
  import { ProxmoxEngine } from "./proxmox-engine.js";
17
2
  import { buildApiProxy } from "./proxy.js";
18
- /** Every path this client builds hangs off the JSON API root. */
3
+ /**
4
+ * Path prefix of the JSON API, under which every request is made.
5
+ */
19
6
  const BASE_PATH = "/api2/json";
7
+ /**
8
+ * Tells a ready-made transport apart from connection options.
9
+ *
10
+ * @param value - The argument given to {@link proxmoxApi}.
11
+ * @returns `true` when `value` has a `doRequest` member, which connection
12
+ * options never have.
13
+ */
20
14
  function isRequestable(value) {
21
15
  return "doRequest" in value;
22
16
  }
23
17
  /**
24
- * Build a typed Proxmox API client.
18
+ * Builds a typed Proxmox API client.
25
19
  *
26
- * @param options Connection options, or any {@link ApiRequestable} to send
27
- * requests through - a pre-built {@link ProxmoxEngine} whose session you
28
- * want to keep, or a stub for tests.
20
+ * @remarks
21
+ * Building the client sends nothing. The first request goes out when a
22
+ * `$get`, `$post`, `$put` or `$delete` method is called on the result, and
23
+ * with password authentication that request logs in first.
29
24
  *
25
+ * @param options - Connection options, from which a new {@link ProxmoxEngine}
26
+ * is built, or any {@link ApiRequestable} to send requests through instead:
27
+ * a pre-built {@link ProxmoxEngine} whose session you want to keep, or a
28
+ * stub for tests.
29
+ * @returns A proxy that turns property access into paths below `/api2/json`
30
+ * and `$`-prefixed method calls into requests.
31
+ * @throws A {@link ProxmoxConfigError} if connection options are given and
32
+ * are unusable, for example a malformed `tokenID` or a port in `host`.
30
33
  * @example
31
34
  * ```ts
32
35
  * const proxmox = proxmoxApi({
33
36
  * host: "192.0.2.10",
34
- * port: 8006,
35
37
  * tokenID: "root@pam!automation",
36
38
  * tokenSecret: "12345678-1234-1234-1234-1234567890ab",
37
39
  * });
@@ -43,5 +45,3 @@ export function proxmoxApi(options) {
43
45
  const engine = isRequestable(options) ? options : new ProxmoxEngine(options);
44
46
  return buildApiProxy(engine, BASE_PATH);
45
47
  }
46
- export default proxmoxApi;
47
- //# sourceMappingURL=client.js.map