Use params objects for service APIs

README.md

@@ -134,11 +134,10 @@ console.log(access.hostname, access.port, access.username);
 
 ### Presigned URLs
 
-Create a temporary public URL for a sandbox port. The optional second argument to
-`createPresignedUrl(port, expiresIn)` is `expiresIn` in seconds.
+Create a temporary public URL for a sandbox port. `expiresIn` is in seconds.
 
 ```ts
-const presigned = await sandbox.createPresignedUrl(8080, 900); // 15 minutes
+const presigned = await sandbox.createPresignedUrl({ port: 8080, expiresIn: 900 }); // 15 minutes
 console.log(presigned.url);
 
 await sandbox.deletePresignedUrl(presigned.id);

examples/desktop.ts

@@ -8,16 +8,16 @@ async function main(): Promise<void> {
   try {
     const sandbox = await client.sandboxes.create({ templateName: DEFAULT_DESKTOP_TEMPLATE_NAME });
     try {
-      await sandbox.desktop.waitUntilReady(60);
+      await sandbox.desktop.waitUntilReady({ timeout: 60 });
       console.log("Desktop:", sandbox.desktop.desktopUrl());
 
       const display = await sandbox.desktop.displayInfo();
       console.log("Display:", display);
 
-      await sandbox.desktop.movePointer(
-        Math.floor(display.width / 2),
-        Math.floor(display.height / 2),
-      );
+      await sandbox.desktop.movePointer({
+        x: Math.floor(display.width / 2),
+        y: Math.floor(display.height / 2),
+      });
       await sandbox.desktop.click({ button: 1 });
 
       const screenshot = await sandbox.desktop.screenshot();

examples/ssh.ts

@@ -9,10 +9,10 @@ async function main(): Promise<void> {
       const access = await sandbox.ssh.createAccess();
       console.log("ssh command:", access.sshCommand);
 
-      const validation = await sandbox.ssh.validateAccess(access.id, access.password);
+      const validation = await sandbox.ssh.validateAccess({ id: access.id, password: access.password });
       console.log("ssh valid:", validation.valid);
 
-      const rotated = await sandbox.ssh.regenerateAccess(access.id);
+      const rotated = await sandbox.ssh.regenerateAccess({ id: access.id });
       console.log("rotated ssh command:", rotated.sshCommand);
     } finally {
       await sandbox.delete();

src/client/sandbox.ts

@@ -212,17 +212,15 @@ export class Sandbox implements SandboxData {
   /**
    * Creates a temporary public URL for a specific sandbox port.
    *
-   * @param port Sandbox port to expose.
-   * @param expiresIn Optional expiration in seconds.
+   * @param params Presigned URL creation parameters.
    * @param options Optional request settings.
    * @returns The created presigned URL.
    */
   async createPresignedUrl(
-    port: number,
-    expiresIn?: number,
+    params: { port: number; expiresIn?: number },
     options?: { timeout?: number },
   ): Promise<PresignedUrl> {
-    return this.client.sandboxes.createPresignedUrl(this.id, { port, expiresIn }, options);
+    return this.client.sandboxes.createPresignedUrl(this.id, params, options);
   }
 
   /**

src/services/desktop.ts

@@ -216,22 +216,20 @@ export class DesktopClient {
    * Moves the desktop pointer to a coordinate.
    *
    * @param sandbox Sandbox ID or sandbox-like object.
-   * @param x Horizontal coordinate.
-   * @param y Vertical coordinate.
+   * @param params Pointer move parameters.
    * @param options Optional request settings such as timeout and query params.
    * @returns The updated pointer position.
    */
   async movePointer(
     sandbox: SandboxRef,
-    x: number,
-    y: number,
+    params: { x: number; y: number },
     options?: RequestOptions,
   ): Promise<DesktopPointerPosition> {
     return this.requestJson(
       sandbox,
       desktopPointerPositionSchema,
       "/api/input/move",
-      { method: "POST", body: jsonBody({ x, y }) },
+      { method: "POST", body: jsonBody({ x: params.x, y: params.y }) },
       options,
     );
   }
@@ -640,7 +638,7 @@ export class DesktopClient {
    * Waits until the desktop reports a running state or all tracked processes are up.
    *
    * @param sandbox Sandbox ID or sandbox-like object.
-   * @param timeout Timeout in seconds.
+   * @param params Wait parameters.
    * @param options Optional request settings such as timeout and query params.
    * @throws {Leap0Error} If the desktop never becomes ready or a non-retryable error occurs.
    *
@@ -649,7 +647,12 @@ export class DesktopClient {
    * await sandbox.desktop.waitUntilReady();
    * ```
    */
-  async waitUntilReady(sandbox: SandboxRef, timeout = 60, options: RequestOptions = {}): Promise<void> {
+  async waitUntilReady(
+    sandbox: SandboxRef,
+    params: { timeout?: number } = {},
+    options: RequestOptions = {},
+  ): Promise<void> {
+    const timeout = params.timeout ?? 60;
     const deadline = Date.now() + timeout * 1000;
     let lastError: unknown;
 

src/services/filesystem.ts

@@ -332,19 +332,17 @@ export class FilesystemClient {
    * Deletes a file or directory. Set `recursive` for non-empty directories.
    *
    * @param sandbox Sandbox ID or sandbox-like object.
-   * @param path File or directory path to delete.
-   * @param recursive Whether to delete directories recursively.
+   * @param params Delete parameters.
    * @param options Optional request settings such as timeout and query params.
    */
   async delete(
     sandbox: SandboxRef,
-    path: string,
-    recursive = false,
+    params: { path: string; recursive?: boolean },
     options: RequestOptions = {},
   ): Promise<void> {
     await this.transport.request(
       this.fsPath(sandbox, "delete"),
-      { method: "POST", body: jsonBody({ path, recursive }) },
+      { method: "POST", body: jsonBody({ path: params.path, recursive: params.recursive ?? false }) },
       options,
     );
   }
@@ -488,21 +486,24 @@ export class FilesystemClient {
    * Moves or renames a file or directory.
    *
    * @param sandbox Sandbox ID or sandbox-like object.
-   * @param srcPath Source path.
-   * @param dstPath Destination path.
-   * @param overwrite Whether to overwrite an existing destination.
+   * @param params Move parameters.
    * @param options Optional request settings such as timeout and query params.
    */
   async move(
     sandbox: SandboxRef,
-    srcPath: string,
-    dstPath: string,
-    overwrite = false,
+    params: { srcPath: string; dstPath: string; overwrite?: boolean },
     options: RequestOptions = {},
   ): Promise<void> {
     await this.transport.request(
       this.fsPath(sandbox, "move"),
-      { method: "POST", body: jsonBody({ src_path: srcPath, dst_path: dstPath, overwrite }) },
+      {
+        method: "POST",
+        body: jsonBody({
+          src_path: params.srcPath,
+          dst_path: params.dstPath,
+          overwrite: params.overwrite ?? false,
+        }),
+      },
       options,
     );
   }