refactor(sandbox): migrate API methods to object-based parameters with backward compatibility

This commit refactors the sandbox client and template classes to use object-based API parameters instead of positional arguments. The changes maintain backward compatibility by supporting both the new object-based API and legacy parameter formats, while adding deprecation warnings for the old usage patterns.

The client methods now accept parameters as objects ({ input, config }) rather than positional arguments (input, config), improving type safety and parameter clarity. The template class numeric field normalization was also improved to properly handle invalid numeric values by setting them to undefined.

Additionally, the test suite was updated to mock the SandboxClient directly instead of the lower-level control API, providing better test isolation and more accurate testing of the actual API usage patterns.

refactor(sandbox): 将API方法迁移到基于对象的参数并保持向后兼容性

此提交重构了sandbox客户端和模板类，使用基于对象的API参数而不是位置参数。这些更改通过支持新的基于对象的API和旧的参数格式来保持向后兼容性，同时为旧的使用模式添加弃用警告。

客户端方法现在接受参数作为对象({ input, config})而不是位置参数(input, config)，提高了类型安全性和参数清晰度。模板类数值字段规范化也得到了改进，通过将无效的数值设置为undefined来正确处理它们。

此外，测试套件已更新为直接模拟SandboxClient而不是底层控制API，提供更好的测试隔离和更准确的实际API使用模式测试。

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

Author: OhYee

src/sandbox/client.ts

@@ -340,13 +340,8 @@ export class SandboxClient {
     let templateType: TemplateType | undefined;
     let config: Config | undefined;
 
-    if ('templateName' in arg1) {
-      logger.warn(
-        'Deprecated: createSandbox(input, config) is deprecated. Use createSandbox({ input, config }) instead.',
-      );
-      input = arg1 as SandboxCreateInput;
-      config = arg2;
-    } else {
+    if ('input' in arg1) {
+      // New API: createSandbox({ input, templateType?, config? })
       const params = arg1 as {
         input: SandboxCreateInput;
         templateType?: TemplateType;
@@ -355,6 +350,13 @@ export class SandboxClient {
       input = params.input;
       templateType = params.templateType;
       config = params.config;
+    } else {
+      // Legacy API: createSandbox(input, config?)
+      logger.warn(
+        'Deprecated: createSandbox(input, config) is deprecated. Use createSandbox({ input, config }) instead.',
+      );
+      input = arg1 as SandboxCreateInput;
+      config = arg2;
     }
 
     const cfg = Config.withConfigs(this.config, config);
@@ -483,19 +485,24 @@ export class SandboxClient {
     (params: { id: string; config?: Config }): Promise<Sandbox>;
     /** @deprecated Use stopSandbox({ id, config }) instead. */
     (id: string, config?: Config): Promise<Sandbox>;
-  } = async (...args: any[]): Promise<Sandbox> => {
-    let params: { id: string; config?: Config } = args?.[0];
+  } = async (
+    arg1: { id: string; config?: Config } | string,
+    arg2?: Config,
+  ): Promise<Sandbox> => {
+    let id: string;
+    let config: Config | undefined;
 
-    if (typeof args[0] === 'string') {
+    if (typeof arg1 === 'string') {
       logger.warn(
         'Deprecated: stopSandbox(id, config) is deprecated. Use stopSandbox({ id, config }) instead.',
       );
-
-      params = { id: args[0], config: args[1] };
+      id = arg1;
+      config = arg2;
+    } else {
+      id = arg1.id;
+      config = arg1.config;
     }
 
-    const { id, config } = params;
-
     const cfg = Config.withConfigs(this.config, config);
 
     try {

src/sandbox/sandbox.ts

@@ -175,7 +175,15 @@ export class Sandbox extends ResourceBase implements SandboxData {
       | SandboxCreateInput,
     arg2?: Config,
   ): Promise<Sandbox> {
-    return await Sandbox.getClient().createSandbox(arg1 as any, arg2);
+    if (typeof arg1 === 'object' && arg1 !== null && 'input' in arg1) {
+      // New API: create({ input, templateType?, config? })
+      return await Sandbox.getClient().createSandbox(arg1);
+    }
+    // Legacy API: create(input, config?)
+    logger.warn(
+      'Deprecated: Sandbox.create(input, config) is deprecated. Use Sandbox.create({ input, config }) instead.',
+    );
+    return await Sandbox.getClient().createSandbox(arg1 as SandboxCreateInput, arg2);
   }
 
   /**
@@ -193,6 +201,9 @@ export class Sandbox extends ResourceBase implements SandboxData {
   ): Promise<Sandbox> {
     if (typeof arg1 === 'string') {
       // Legacy API: delete(id, config?)
+      logger.warn(
+        'Sandbox.delete(id, config) is deprecated. Use Sandbox.delete({ id, config }) instead.',
+      );
       return await Sandbox.getClient().deleteSandbox(arg1, arg2);
     }
     // New API: delete({ id, config })
@@ -211,6 +222,9 @@ export class Sandbox extends ResourceBase implements SandboxData {
   ): Promise<Sandbox> {
     if (typeof arg1 === 'string') {
       // Legacy API: stop(id, config?)
+      logger.warn(
+        'Sandbox.stop(id, config) is deprecated. Use Sandbox.stop({ id, config }) instead.',
+      );
       return await Sandbox.getClient().stopSandbox(arg1, arg2);
     }
     // New API: stop({ id, config })
@@ -347,9 +361,13 @@ export class Sandbox extends ResourceBase implements SandboxData {
         ('maxResults' in arg1 ||
           'nextToken' in arg1 ||
           'status' in arg1 ||
-          'templateName' in arg1))
+          'templateName' in arg1 ||
+          'templateType' in arg1))
     ) {
       // Legacy API: list(input, config?)
+      logger.warn(
+        'Deprecated: Sandbox.list(input, config) is deprecated. Use Sandbox.list({ input, config }) instead.',
+      );
       return await Sandbox.getClient().listSandboxes(
         arg1 as SandboxListInput,
         arg2,

src/sandbox/template.ts

@@ -251,16 +251,15 @@ export class Template extends ResourceBase implements TemplateData {
       return undefined;
     };
 
-    this.sandboxIdleTimeoutInSeconds =
-      toNumber(this.sandboxIdleTimeoutInSeconds) ??
-      this.sandboxIdleTimeoutInSeconds;
-    this.sandboxTtlInSeconds =
-      toNumber(this.sandboxTtlInSeconds) ?? this.sandboxTtlInSeconds;
-    this.shareConcurrencyLimitPerSandbox =
-      toNumber(this.shareConcurrencyLimitPerSandbox) ??
-      this.shareConcurrencyLimitPerSandbox;
-    this.cpu = toNumber(this.cpu) ?? this.cpu;
-    this.memory = toNumber(this.memory) ?? this.memory;
-    this.diskSize = toNumber(this.diskSize) ?? this.diskSize;
+    this.sandboxIdleTimeoutInSeconds = toNumber(
+      this.sandboxIdleTimeoutInSeconds,
+    );
+    this.sandboxTtlInSeconds = toNumber(this.sandboxTtlInSeconds);
+    this.shareConcurrencyLimitPerSandbox = toNumber(
+      this.shareConcurrencyLimitPerSandbox,
+    );
+    this.cpu = toNumber(this.cpu);
+    this.memory = toNumber(this.memory);
+    this.diskSize = toNumber(this.diskSize);
   }
 }