@solarisdk/core 0.1.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 (47) hide show
  1. package/LICENSE +17 -0
  2. package/README.md +21 -0
  3. package/dist/desktop.d.ts +106 -0
  4. package/dist/desktop.d.ts.map +1 -0
  5. package/dist/desktop.js +170 -0
  6. package/dist/desktop.js.map +1 -0
  7. package/dist/errors.d.ts +50 -0
  8. package/dist/errors.d.ts.map +1 -0
  9. package/dist/errors.js +91 -0
  10. package/dist/errors.js.map +1 -0
  11. package/dist/handle.d.ts +169 -0
  12. package/dist/handle.d.ts.map +1 -0
  13. package/dist/handle.js +386 -0
  14. package/dist/handle.js.map +1 -0
  15. package/dist/http.d.ts +35 -0
  16. package/dist/http.d.ts.map +1 -0
  17. package/dist/http.js +106 -0
  18. package/dist/http.js.map +1 -0
  19. package/dist/image.d.ts +85 -0
  20. package/dist/image.d.ts.map +1 -0
  21. package/dist/image.js +126 -0
  22. package/dist/image.js.map +1 -0
  23. package/dist/index.d.ts +13 -0
  24. package/dist/index.d.ts.map +1 -0
  25. package/dist/index.js +9 -0
  26. package/dist/index.js.map +1 -0
  27. package/dist/sandbox.d.ts +8 -0
  28. package/dist/sandbox.d.ts.map +1 -0
  29. package/dist/sandbox.js +15 -0
  30. package/dist/sandbox.js.map +1 -0
  31. package/dist/template-client.d.ts +35 -0
  32. package/dist/template-client.d.ts.map +1 -0
  33. package/dist/template-client.js +95 -0
  34. package/dist/template-client.js.map +1 -0
  35. package/dist/transport.d.ts +108 -0
  36. package/dist/transport.d.ts.map +1 -0
  37. package/dist/transport.js +337 -0
  38. package/dist/transport.js.map +1 -0
  39. package/dist/types.d.ts +591 -0
  40. package/dist/types.d.ts.map +1 -0
  41. package/dist/types.js +8 -0
  42. package/dist/types.js.map +1 -0
  43. package/dist/ws.d.ts +18 -0
  44. package/dist/ws.d.ts.map +1 -0
  45. package/dist/ws.js +63 -0
  46. package/dist/ws.js.map +1 -0
  47. package/package.json +44 -0
package/LICENSE ADDED
@@ -0,0 +1,17 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ Copyright 2026 Solari Desktop
6
+
7
+ Licensed under the Apache License, Version 2.0 (the "License");
8
+ you may not use this file except in compliance with the License.
9
+ You may obtain a copy of the License at
10
+
11
+ http://www.apache.org/licenses/LICENSE-2.0
12
+
13
+ Unless required by applicable law or agreed to in writing, software
14
+ distributed under the License is distributed on an "AS IS" BASIS,
15
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16
+ See the License for the specific language governing permissions and
17
+ limitations under the License.
package/README.md ADDED
@@ -0,0 +1,21 @@
1
+ # @solarisdk/core
2
+
3
+ Shared runtime for the Solari SDK. Provides the transport, session handles
4
+ (`Desktop`, `Sandbox`, `SessionHandle`), image/template builders, error types,
5
+ and the shared TypeScript types used by
6
+ [`@solarisdk/desktop`](https://www.npmjs.com/package/@solarisdk/desktop) and
7
+ [`@solarisdk/sandbox`](https://www.npmjs.com/package/@solarisdk/sandbox).
8
+
9
+ You usually don't install this directly. Instead install a client package:
10
+
11
+ ```bash
12
+ npm install @solarisdk/desktop # managed virtual desktops
13
+ npm install @solarisdk/sandbox # ephemeral compute sandboxes
14
+ npm install @solarisdk/sdk # unified client + `pinetree` CLI
15
+ ```
16
+
17
+ `@solarisdk/core` is a dependency of all three and is installed automatically.
18
+
19
+ ## License
20
+
21
+ Apache-2.0
@@ -0,0 +1,106 @@
1
+ import { SessionHandle, type SessionConfig } from "./handle.js";
2
+ import type { ClickOptions, CreateDesktopResponse, ExecOptions, ExecResult, ExecStreamHandler, HealthResult, MouseButton, MoveOptions, PackageManager, PkgInstallResult, PortInfo, ProcessInfo, ProcessStartOptions, RecordStartResult, RecordStopResult, ScreenshotOptions, ScrollOptions } from "./types.js";
3
+ export interface DesktopConfig extends SessionConfig {
4
+ /**
5
+ * Pause hook wired by {@link DesktopClient} so `desktop.pause()` can call the
6
+ * gateway's `POST /desktops/:id/pause` without the Desktop holding an HTTP
7
+ * client. Back-compat shim — folded into {@link SessionHooks.pause}.
8
+ */
9
+ onPause?: (sessionId: string) => Promise<void>;
10
+ }
11
+ /** A live desktop session. Construct via {@link DesktopClient}. */
12
+ export declare class Desktop extends SessionHandle {
13
+ readonly streamUrl: string;
14
+ /** The session id (alias of {@link SessionHandle.id}; back-compat). */
15
+ get sessionId(): string;
16
+ constructor(session: CreateDesktopResponse, config?: DesktopConfig);
17
+ private guiCall;
18
+ /** `health` — readiness probe (display + VNC + agent). */
19
+ health(): Promise<HealthResult>;
20
+ exec(cmd: string, opts?: ExecOptions): Promise<ExecResult>;
21
+ execStream(cmd: string, onChunk: ExecStreamHandler, opts?: Omit<ExecOptions, "stream">): Promise<ExecResult>;
22
+ readonly fs: {
23
+ read: (path: string) => Promise<Uint8Array>;
24
+ readText: (path: string) => Promise<string>;
25
+ write: (path: string, data: Uint8Array | string, mode?: number) => Promise<void>;
26
+ list: (path: string) => Promise<import("./types.js").FsEntry[]>;
27
+ stat: (path: string) => Promise<import("./types.js").FsStat>;
28
+ remove: (path: string, recursive?: boolean) => Promise<void>;
29
+ mkdir: (path: string) => Promise<void>;
30
+ };
31
+ readonly mouse: {
32
+ move: (x: number, y: number, opts?: MoveOptions) => Promise<void>;
33
+ click: (x: number, y: number, opts?: ClickOptions) => Promise<void>;
34
+ doubleClick: (x: number, y: number, opts?: ClickOptions) => Promise<void>;
35
+ down: (x: number, y: number, button?: MouseButton) => Promise<void>;
36
+ up: (x: number, y: number, button?: MouseButton) => Promise<void>;
37
+ scroll: (x: number, y: number, opts?: ScrollOptions) => Promise<void>;
38
+ drag: (from: {
39
+ x: number;
40
+ y: number;
41
+ }, to: {
42
+ x: number;
43
+ y: number;
44
+ }, button?: MouseButton) => Promise<void>;
45
+ };
46
+ private mouseCall;
47
+ readonly keyboard: {
48
+ type: (text: string) => Promise<void>;
49
+ press: (keys: string | string[]) => Promise<void>;
50
+ /** Press a chord (alias of `press` for an array, e.g. `hotkey("ctrl","c")`). */
51
+ hotkey: (...keys: string[]) => Promise<void>;
52
+ down: (keys: string | string[]) => Promise<void>;
53
+ up: (keys: string | string[]) => Promise<void>;
54
+ };
55
+ private keyCall;
56
+ screenshot(opts?: ScreenshotOptions): Promise<Uint8Array>;
57
+ readonly display: {
58
+ set: (w: number, h: number) => Promise<void>;
59
+ /** Current display size. */
60
+ size: () => Promise<{
61
+ w: number;
62
+ h: number;
63
+ }>;
64
+ /** Current cursor position. */
65
+ cursor: () => Promise<{
66
+ x: number;
67
+ y: number;
68
+ }>;
69
+ };
70
+ readonly clipboard: {
71
+ get: () => Promise<string>;
72
+ set: (text: string) => Promise<void>;
73
+ };
74
+ /** Launch a GUI app by name (`app.open`); returns its pid. */
75
+ open(name: string, args?: string[]): Promise<number>;
76
+ readonly stream: {
77
+ /** Start/obtain the live VNC stream; returns the embeddable URL + token. */
78
+ start: () => Promise<{
79
+ streamUrl: string;
80
+ token?: string;
81
+ }>;
82
+ /** Stop the live stream (best-effort; the channel stays up). */
83
+ stop: () => Promise<void>;
84
+ };
85
+ readonly process: {
86
+ list: () => Promise<ProcessInfo[]>;
87
+ kill: (pid: number) => Promise<void>;
88
+ start: (cmd: string, opts?: ProcessStartOptions) => Promise<number>;
89
+ signal: (pid: number, signal?: number) => Promise<void>;
90
+ };
91
+ readonly ports: {
92
+ list: () => Promise<PortInfo[]>;
93
+ };
94
+ readonly pkg: {
95
+ install: (manager: PackageManager, packages: string[]) => Promise<PkgInstallResult>;
96
+ };
97
+ readonly record: {
98
+ start: (opts?: {
99
+ fps?: number;
100
+ format?: string;
101
+ path?: string;
102
+ }) => Promise<RecordStartResult>;
103
+ stop: () => Promise<RecordStopResult>;
104
+ };
105
+ }
106
+ //# sourceMappingURL=desktop.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"desktop.d.ts","sourceRoot":"","sources":["../src/desktop.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,170 @@
1
+ // `Desktop` — a handle to one live GUI session. Extends the shared
2
+ // {@link SessionHandle} (commands, pty, runCode, files, metrics, snapshot,
3
+ // revert, pause/resume, setTimeout, env, volumes, kill) and adds the
4
+ // computer-use GUI surface (CONTRACTS §4 + CONTRACTS-V2 §4): screenshot,
5
+ // mouse.*, keyboard.*, display.*, clipboard.*, open, stream.*, record.*.
6
+ //
7
+ // Back-compat: the v1 `DesktopClient` constructs `new Desktop(session, config)`
8
+ // where `config.onPause(sessionId)` calls `POST /desktops/:id/pause`. That path
9
+ // is preserved; the older convenience methods (`exec`, `execStream`, `health`,
10
+ // `process`, `ports`, `pkg`) are kept too.
11
+ import { SessionHandle } from "./handle.js";
12
+ import { base64ToBytes } from "./transport.js";
13
+ /** A live desktop session. Construct via {@link DesktopClient}. */
14
+ export class Desktop extends SessionHandle {
15
+ streamUrl;
16
+ /** The session id (alias of {@link SessionHandle.id}; back-compat). */
17
+ get sessionId() {
18
+ return this.id;
19
+ }
20
+ constructor(session, config = {}) {
21
+ // Fold the legacy onPause shim into the unified hooks.pause.
22
+ const hooks = { ...(config.hooks ?? {}) };
23
+ if (config.onPause && !hooks.pause) {
24
+ const onPause = config.onPause;
25
+ hooks.pause = (id) => onPause(id);
26
+ }
27
+ super(session.sessionId, session.controlUrl, session.expiresAt, {
28
+ ...config,
29
+ hooks,
30
+ });
31
+ this.streamUrl = session.streamUrl;
32
+ }
33
+ // GUI RPCs go over the shared control channel via the protected `rpc` hook.
34
+ guiCall(method, params) {
35
+ return this.rpc(method, params);
36
+ }
37
+ // --- readiness ------------------------------------------------------------
38
+ /** `health` — readiness probe (display + VNC + agent). */
39
+ health() {
40
+ return this.guiCall("health", {});
41
+ }
42
+ // --- exec (v1 convenience; prefer `commands.run`) -------------------------
43
+ exec(cmd, opts = {}) {
44
+ return this.guiCall("exec", {
45
+ cmd,
46
+ args: opts.args ?? [],
47
+ cwd: opts.cwd,
48
+ timeoutMs: opts.timeoutMs,
49
+ stream: opts.stream,
50
+ });
51
+ }
52
+ execStream(cmd, onChunk, opts = {}) {
53
+ return this.rpcStream("exec", { cmd, args: opts.args ?? [], cwd: opts.cwd, timeoutMs: opts.timeoutMs, stream: true }, (c) => {
54
+ const bytes = c.data ? base64ToBytes(c.data) : new Uint8Array();
55
+ onChunk({ stream: c.stream, text: new TextDecoder().decode(bytes), bytes });
56
+ });
57
+ }
58
+ // --- fs (v1 alias kept; `files` is the canonical surface) -----------------
59
+ fs = {
60
+ read: (path) => this.files.read(path),
61
+ readText: (path) => this.files.readText(path),
62
+ write: (path, data, mode) => this.files.write(path, data, mode),
63
+ list: (path) => this.files.list(path),
64
+ stat: (path) => this.files.stat(path),
65
+ remove: (path, recursive = false) => this.files.remove(path, recursive),
66
+ mkdir: (path) => this.files.mkdir(path),
67
+ };
68
+ // --- mouse ----------------------------------------------------------------
69
+ mouse = {
70
+ move: (x, y, opts = {}) => this.mouseCall(x, y, "move", undefined, opts.humanize),
71
+ click: (x, y, opts = {}) => this.mouseCall(x, y, "click", opts.button, opts.humanize),
72
+ doubleClick: (x, y, opts = {}) => this.guiCall("input.doubleClick", { x, y, button: opts.button }).then(() => undefined),
73
+ down: (x, y, button = "left") => this.mouseCall(x, y, "down", button),
74
+ up: (x, y, button = "left") => this.mouseCall(x, y, "up", button),
75
+ scroll: (x, y, opts = {}) => this.mouseCall(x, y, "scroll", opts.button, opts.humanize),
76
+ drag: (from, to, button = "left") => this.guiCall("input.drag", { from, to, button }).then(() => undefined),
77
+ };
78
+ mouseCall(x, y, action, button, humanize) {
79
+ return this.guiCall("input.mouse", { x, y, action, button, humanize }).then(() => undefined);
80
+ }
81
+ // --- keyboard -------------------------------------------------------------
82
+ keyboard = {
83
+ type: (text) => this.keyCall({ text, action: "press" }),
84
+ press: (keys) => this.keyCall({ keys: Array.isArray(keys) ? keys : [keys], action: "press" }),
85
+ /** Press a chord (alias of `press` for an array, e.g. `hotkey("ctrl","c")`). */
86
+ hotkey: (...keys) => this.keyCall({ keys, action: "press" }),
87
+ down: (keys) => this.keyCall({ keys: Array.isArray(keys) ? keys : [keys], action: "down" }),
88
+ up: (keys) => this.keyCall({ keys: Array.isArray(keys) ? keys : [keys], action: "up" }),
89
+ };
90
+ keyCall(params) {
91
+ return this.guiCall("input.key", params).then(() => undefined);
92
+ }
93
+ // --- screenshot -----------------------------------------------------------
94
+ async screenshot(opts = {}) {
95
+ const r = await this.guiCall("screenshot", {
96
+ format: opts.format ?? "png",
97
+ quality: opts.quality,
98
+ });
99
+ return base64ToBytes(r.base64);
100
+ }
101
+ // --- display --------------------------------------------------------------
102
+ display = {
103
+ set: (w, h) => this.guiCall("display.set", { w, h }).then(() => undefined),
104
+ /** Current display size. */
105
+ size: () => this.guiCall("display.size", {}),
106
+ /** Current cursor position. */
107
+ cursor: () => this.guiCall("display.cursor", {}),
108
+ };
109
+ // --- clipboard ------------------------------------------------------------
110
+ clipboard = {
111
+ get: async () => {
112
+ const r = await this.guiCall("clipboard.get", {});
113
+ return r.text ?? "";
114
+ },
115
+ set: (text) => this.guiCall("clipboard.set", { text }).then(() => undefined),
116
+ };
117
+ // --- open an app ----------------------------------------------------------
118
+ /** Launch a GUI app by name (`app.open`); returns its pid. */
119
+ async open(name, args) {
120
+ const r = await this.guiCall("app.open", { name, args });
121
+ return r.pid;
122
+ }
123
+ // --- live stream ----------------------------------------------------------
124
+ stream = {
125
+ /** Start/obtain the live VNC stream; returns the embeddable URL + token. */
126
+ start: async () => {
127
+ // The stream URL is minted at create time; expose it (+ any token) here so
128
+ // callers have a single `stream.start()` entry point.
129
+ return { streamUrl: this.streamUrl };
130
+ },
131
+ /** Stop the live stream (best-effort; the channel stays up). */
132
+ stop: async () => {
133
+ /* the RFB stream is a separate socket the caller owns; nothing to tear down here */
134
+ },
135
+ };
136
+ // --- process (v1 convenience) ---------------------------------------------
137
+ process = {
138
+ list: async () => {
139
+ const r = await this.guiCall("process.list", {});
140
+ return r.processes;
141
+ },
142
+ kill: (pid) => this.guiCall("process.kill", { pid }).then(() => undefined),
143
+ start: async (cmd, opts = {}) => {
144
+ const r = await this.guiCall("process.start", {
145
+ cmd,
146
+ args: opts.args ?? [],
147
+ cwd: opts.cwd,
148
+ });
149
+ return r.pid;
150
+ },
151
+ signal: (pid, signal) => this.guiCall("process.signal", { pid, signal }).then(() => undefined),
152
+ };
153
+ // --- ports (v1 convenience) -----------------------------------------------
154
+ ports = {
155
+ list: async () => {
156
+ const r = await this.guiCall("ports.list", {});
157
+ return r.ports;
158
+ },
159
+ };
160
+ // --- packages -------------------------------------------------------------
161
+ pkg = {
162
+ install: (manager, packages) => this.guiCall("pkg.install", { manager, packages }),
163
+ };
164
+ // --- recording ------------------------------------------------------------
165
+ record = {
166
+ start: (opts = {}) => this.guiCall("record.start", opts),
167
+ stop: () => this.guiCall("record.stop", {}),
168
+ };
169
+ }
170
+ //# sourceMappingURL=desktop.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"desktop.js","sourceRoot":"","sources":["../src/desktop.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,50 @@
1
+ import type { GatewayErrorBody } from "./types.js";
2
+ /** Base class for every error thrown by the SDK. */
3
+ export declare class PinetreeError extends Error {
4
+ constructor(message: string);
5
+ }
6
+ /** Any non-2xx response from the gateway that isn't otherwise specialized. */
7
+ export declare class GatewayError extends PinetreeError {
8
+ readonly status: number;
9
+ readonly code?: string;
10
+ readonly body?: GatewayErrorBody;
11
+ constructor(status: number, message: string, body?: GatewayErrorBody);
12
+ }
13
+ /** `401` — the API key was missing, malformed, or rejected. */
14
+ export declare class AuthError extends GatewayError {
15
+ constructor(message?: string, body?: GatewayErrorBody);
16
+ }
17
+ /** `402 {code:"FeatureRequiresPlan"}` — the plan doesn't allow this. */
18
+ export declare class PlanError extends GatewayError {
19
+ constructor(message?: string, body?: GatewayErrorBody);
20
+ }
21
+ /** `429 {code:"ConcurrencyLimitExceeded"}` — too many live desktops. */
22
+ export declare class ConcurrencyLimitError extends GatewayError {
23
+ constructor(message?: string, body?: GatewayErrorBody);
24
+ }
25
+ /** `503` — no desktop host currently available to serve the request. */
26
+ export declare class NoCapacityError extends GatewayError {
27
+ constructor(message?: string, body?: GatewayErrorBody);
28
+ }
29
+ /** A computer-use RPC returned `{ok:false}`. */
30
+ export declare class ActionError extends PinetreeError {
31
+ readonly method: string;
32
+ readonly code?: string;
33
+ constructor(method: string, message: string, code?: string);
34
+ }
35
+ /** An RPC did not receive a reply within the per-call timeout. */
36
+ export declare class TimeoutError extends PinetreeError {
37
+ readonly method: string;
38
+ readonly timeoutMs: number;
39
+ constructor(method: string, timeoutMs: number);
40
+ }
41
+ /** The control WebSocket is not open (never connected, or closed). */
42
+ export declare class ConnectionError extends PinetreeError {
43
+ constructor(message?: string);
44
+ }
45
+ /**
46
+ * Map a gateway HTTP response onto the appropriate typed error.
47
+ * Falls back to a generic {@link GatewayError} for unrecognized statuses.
48
+ */
49
+ export declare function mapGatewayError(status: number, body: GatewayErrorBody | undefined): GatewayError;
50
+ //# sourceMappingURL=errors.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,oDAAoD;AACpD,qBAAa,aAAc,SAAQ,KAAK;gBAC1B,OAAO,EAAE,MAAM;CAI5B;AAED,8EAA8E;AAC9E,qBAAa,YAAa,SAAQ,aAAa;IAC7C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,gBAAgB,CAAC;gBAErB,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,gBAAgB;CAMrE;AAED,+DAA+D;AAC/D,qBAAa,SAAU,SAAQ,YAAY;gBAC7B,OAAO,SAA+B,EAAE,IAAI,CAAC,EAAE,gBAAgB;CAG5E;AAED,wEAAwE;AACxE,qBAAa,SAAU,SAAQ,YAAY;gBAEvC,OAAO,SAA2C,EAClD,IAAI,CAAC,EAAE,gBAAgB;CAI1B;AAED,wEAAwE;AACxE,qBAAa,qBAAsB,SAAQ,YAAY;gBAEnD,OAAO,SAA+B,EACtC,IAAI,CAAC,EAAE,gBAAgB;CAI1B;AAED,wEAAwE;AACxE,qBAAa,eAAgB,SAAQ,YAAY;gBAE7C,OAAO,SAA8B,EACrC,IAAI,CAAC,EAAE,gBAAgB;CAI1B;AAED,gDAAgD;AAChD,qBAAa,WAAY,SAAQ,aAAa;IAC5C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;gBAEX,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM;CAK3D;AAED,kEAAkE;AAClE,qBAAa,YAAa,SAAQ,aAAa;IAC7C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAK9C;AAED,sEAAsE;AACtE,qBAAa,eAAgB,SAAQ,aAAa;gBACpC,OAAO,SAAqC;CAGzD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,gBAAgB,GAAG,SAAS,GACjC,YAAY,CAkBd"}
package/dist/errors.js ADDED
@@ -0,0 +1,91 @@
1
+ // Typed errors. Gateway HTTP status codes (§1) and control-channel RPC
2
+ // failures (§4) are mapped onto these so callers can branch on `instanceof`.
3
+ /** Base class for every error thrown by the SDK. */
4
+ export class PinetreeError extends Error {
5
+ constructor(message) {
6
+ super(message);
7
+ this.name = new.target.name;
8
+ }
9
+ }
10
+ /** Any non-2xx response from the gateway that isn't otherwise specialized. */
11
+ export class GatewayError extends PinetreeError {
12
+ status;
13
+ code;
14
+ body;
15
+ constructor(status, message, body) {
16
+ super(message);
17
+ this.status = status;
18
+ this.code = body?.code;
19
+ this.body = body;
20
+ }
21
+ }
22
+ /** `401` — the API key was missing, malformed, or rejected. */
23
+ export class AuthError extends GatewayError {
24
+ constructor(message = "Invalid or missing API key", body) {
25
+ super(401, message, body);
26
+ }
27
+ }
28
+ /** `402 {code:"FeatureRequiresPlan"}` — the plan doesn't allow this. */
29
+ export class PlanError extends GatewayError {
30
+ constructor(message = "This feature requires a different plan", body) {
31
+ super(402, message, body);
32
+ }
33
+ }
34
+ /** `429 {code:"ConcurrencyLimitExceeded"}` — too many live desktops. */
35
+ export class ConcurrencyLimitError extends GatewayError {
36
+ constructor(message = "Concurrency limit exceeded", body) {
37
+ super(429, message, body);
38
+ }
39
+ }
40
+ /** `503` — no desktop host currently available to serve the request. */
41
+ export class NoCapacityError extends GatewayError {
42
+ constructor(message = "No desktop host available", body) {
43
+ super(503, message, body);
44
+ }
45
+ }
46
+ /** A computer-use RPC returned `{ok:false}`. */
47
+ export class ActionError extends PinetreeError {
48
+ method;
49
+ code;
50
+ constructor(method, message, code) {
51
+ super(message);
52
+ this.method = method;
53
+ this.code = code;
54
+ }
55
+ }
56
+ /** An RPC did not receive a reply within the per-call timeout. */
57
+ export class TimeoutError extends PinetreeError {
58
+ method;
59
+ timeoutMs;
60
+ constructor(method, timeoutMs) {
61
+ super(`Action "${method}" timed out after ${timeoutMs}ms`);
62
+ this.method = method;
63
+ this.timeoutMs = timeoutMs;
64
+ }
65
+ }
66
+ /** The control WebSocket is not open (never connected, or closed). */
67
+ export class ConnectionError extends PinetreeError {
68
+ constructor(message = "Control channel is not connected") {
69
+ super(message);
70
+ }
71
+ }
72
+ /**
73
+ * Map a gateway HTTP response onto the appropriate typed error.
74
+ * Falls back to a generic {@link GatewayError} for unrecognized statuses.
75
+ */
76
+ export function mapGatewayError(status, body) {
77
+ const msg = body?.message ?? body?.error ?? body?.code;
78
+ switch (status) {
79
+ case 401:
80
+ return new AuthError(msg, body);
81
+ case 402:
82
+ return new PlanError(msg, body);
83
+ case 429:
84
+ return new ConcurrencyLimitError(msg, body);
85
+ case 503:
86
+ return new NoCapacityError(msg, body);
87
+ default:
88
+ return new GatewayError(status, msg ?? `Gateway request failed with status ${status}`, body);
89
+ }
90
+ }
91
+ //# sourceMappingURL=errors.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}