refactor(sandbox): migrate client and sandbox classes to object-based API parameters

This commit refactors the SandboxClient and Sandbox classes to use object-based
API parameters instead of the legacy string-based parameters. The changes include
updating method signatures, parameter handling, and maintaining backward
compatibility for deprecated APIs. Additionally, the template tests have been
updated to use direct SandboxControlAPI mocking instead of client mocking.

The parameter migration affects listTemplates, deleteSandbox, stopSandbox, and
listSandboxes methods to accept object parameters for better type safety and
flexibility while maintaining support for legacy string parameter usage.

refactor(sandbox): 将客户端和沙箱类迁移到基于对象的 API 参数

此提交重构了 SandboxClient 和 Sandbox 类，以使用基于对象的 API 参数，
而不是传统的基于字符串的参数。更改包括更新方法签名、参数处理，
并维护对已弃用 API 的向后兼容性。此外，模板测试已更新为直接使用
SandboxControlAPI 模拟，而不是客户端模拟。

参数迁移影响了 listTemplates、deleteSandbox、stopSandbox 和
listSandboxes 方法，使其接受对象参数以实现更好的类型安全性和灵活性，
同时保持对传统字符串参数用法的支持。

Change-Id: I9d1b8be721a41b38851d1280727b892590d085c5
Signed-off-by: OhYee <oyohyee@oyohyee.com>

Author: OhYee

src/sandbox/client.ts

@@ -11,8 +11,10 @@ import { HTTPError } from '../utils/exception';
 import { logger } from '../utils/log';
 import { SandboxControlAPI } from './api/control';
 
+import { AioSandbox } from './aio-sandbox';
 import { BrowserSandbox } from './browser-sandbox';
 import { CodeInterpreterSandbox } from './code-interpreter-sandbox';
+import { CustomSandbox } from './custom-sandbox';
 import {
   NASConfig,
   OSSMountConfig,
@@ -28,8 +30,6 @@ import {
 } from './model';
 import { Sandbox } from './sandbox';
 import { Template } from './template';
-import { AioSandbox } from './aio-sandbox';
-import { CustomSandbox } from './custom-sandbox';
 
 /**
  * Sandbox Client
@@ -268,7 +268,7 @@ export class SandboxClient {
     if (
       arg2 ||
       (arg1 &&
-        ('maxResults' in arg1 || 'nextToken' in arg1 || 'templateType' in arg1))
+        ('pageNumber' in arg1 || 'pageSize' in arg1 || 'templateType' in arg1))
     ) {
       logger.warn(
         'Deprecated: listTemplates(input, config) is deprecated. Use listTemplates({ input, config }) instead.',
@@ -483,24 +483,19 @@ export class SandboxClient {
     (params: { id: string; config?: Config }): Promise<Sandbox>;
     /** @deprecated Use stopSandbox({ id, config }) instead. */
     (id: string, config?: Config): Promise<Sandbox>;
-  } = async (
-    arg1: { id: string; config?: Config } | string,
-    arg2?: Config,
-  ): Promise<Sandbox> => {
-    let id: string;
-    let config: Config | undefined;
+  } = async (...args: any[]): Promise<Sandbox> => {
+    let params: { id: string; config?: Config } = args?.[0];
 
-    if (typeof arg1 === 'string') {
+    if (typeof args[0] === 'string') {
       logger.warn(
         'Deprecated: stopSandbox(id, config) is deprecated. Use stopSandbox({ id, config }) instead.',
       );
-      id = arg1;
-      config = arg2;
-    } else {
-      id = arg1.id;
-      config = arg1.config;
+
+      params = { id: args[0], config: args[1] };
     }
 
+    const { id, config } = params;
+
     const cfg = Config.withConfigs(this.config, config);
 
     try {

src/sandbox/sandbox.ts

@@ -9,7 +9,6 @@ import { ClientError, HTTPError } from '@/utils';
 import { logger } from '../utils/log';
 import { Config } from '../utils/config';
 import { ResourceBase, updateObjectProperties } from '../utils/resource';
-import type { SandboxClient } from './client';
 
 import {
   SandboxCreateInput,
@@ -23,6 +22,7 @@ import type { AioSandbox } from './aio-sandbox';
 import type { BrowserSandbox } from './browser-sandbox';
 import type { CodeInterpreterSandbox } from './code-interpreter-sandbox';
 import type { CustomSandbox } from './custom-sandbox';
+import type { SandboxClient } from './client';
 
 /**
  * Base Sandbox resource class
@@ -122,12 +122,12 @@ export class Sandbox extends ResourceBase implements SandboxData {
     );
   }
 
-  private static getClient() {
+  private static getClient(): SandboxClient {
     // lazy-require to avoid circular runtime import between sandbox <-> client
     // keep this dynamic require so module initialization order doesn't break
     // eslint-disable-next-line @typescript-eslint/no-var-requires
-    const { SandboxClient: SandboxClientCtor } = require('./client');
-    return new SandboxClientCtor();
+    const { SandboxClient } = require('./client') as { SandboxClient: new () => SandboxClient };
+    return new SandboxClient();
   }
 
   /**
@@ -191,7 +191,12 @@ export class Sandbox extends ResourceBase implements SandboxData {
     arg1: { id: string; config?: Config } | string,
     arg2?: Config,
   ): Promise<Sandbox> {
-    return await Sandbox.getClient().deleteSandbox(arg1 as any, arg2);
+    if (typeof arg1 === 'string') {
+      // Legacy API: delete(id, config?)
+      return await Sandbox.getClient().deleteSandbox(arg1, arg2);
+    }
+    // New API: delete({ id, config })
+    return await Sandbox.getClient().deleteSandbox(arg1);
   }
 
   /**
@@ -204,7 +209,12 @@ export class Sandbox extends ResourceBase implements SandboxData {
     arg1: { id: string; config?: Config } | string,
     arg2?: Config,
   ): Promise<Sandbox> {
-    return await Sandbox.getClient().stopSandbox(arg1 as any, arg2);
+    if (typeof arg1 === 'string') {
+      // Legacy API: stop(id, config?)
+      return await Sandbox.getClient().stopSandbox(arg1, arg2);
+    }
+    // New API: stop({ id, config })
+    return await Sandbox.getClient().stopSandbox(arg1);
   }
 
   /**
@@ -330,7 +340,25 @@ export class Sandbox extends ResourceBase implements SandboxData {
     arg1?: SandboxListInput | { input?: SandboxListInput; config?: Config },
     arg2?: Config,
   ): Promise<Sandbox[]> {
-    return await Sandbox.getClient().listSandboxes(arg1 as any, arg2);
+    // Check if using legacy API (arg1 is input object with list params)
+    if (
+      arg2 !== undefined ||
+      (arg1 &&
+        ('maxResults' in arg1 ||
+          'nextToken' in arg1 ||
+          'status' in arg1 ||
+          'templateName' in arg1))
+    ) {
+      // Legacy API: list(input, config?)
+      return await Sandbox.getClient().listSandboxes(
+        arg1 as SandboxListInput,
+        arg2,
+      );
+    }
+    // New API: list({ input, config }) or list()
+    return await Sandbox.getClient().listSandboxes(
+      arg1 as { input?: SandboxListInput; config?: Config },
+    );
   }
 
   get = async (params?: { config?: Config }) => {

tests/unittests/sandbox/sandbox.test.ts

@@ -188,8 +188,7 @@ describe('Sandbox', () => {
       expect(result.sandboxId).toBe('sandbox-123');
       expect(mockClientDeleteSandbox).toHaveBeenCalledWith({
         id: 'sandbox-123',
-        config: undefined,
-      }, undefined);
+      });
     });
 
     it('should throw ClientError when deletion fails', async () => {
@@ -216,8 +215,7 @@ describe('Sandbox', () => {
       expect(result.sandboxId).toBe('sandbox-123');
       expect(mockClientStopSandbox).toHaveBeenCalledWith({
         id: 'sandbox-123',
-        config: undefined,
-      }, undefined);
+      });
     });
 
     it('should throw ClientError when stop fails', async () => {