fix(js-sdk): forward name param and expose names in createSnapshot

Adds SnapshotCreateOpts with an optional name field, threads it through
to the POST body, and adds names[] to SnapshotInfo so callers can create
named snapshots and read back their assigned aliases.

Also fixes SnapshotPaginator.nextItems() which had the same names omission.

Fixes #1249

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: FisherXZ

packages/js-sdk/src/sandbox/index.ts

@@ -20,8 +20,8 @@ import {
   SandboxListOpts,
   SandboxPaginator,
   SandboxBetaCreateOpts,
-  SandboxApiOpts,
   SnapshotListOpts,
+  SnapshotCreateOpts,
   SnapshotInfo,
   SnapshotPaginator,
 } from './sandboxApi'
@@ -621,7 +621,7 @@ export class Sandbox extends SandboxApi {
    * const newSandbox = await Sandbox.create(snapshot.snapshotId)
    * ```
    */
-  async createSnapshot(opts?: SandboxApiOpts): Promise<SnapshotInfo> {
+  async createSnapshot(opts?: SnapshotCreateOpts): Promise<SnapshotInfo> {
     return await SandboxApi.createSnapshot(
       this.sandboxId,
       this.resolveApiOpts(opts)

packages/js-sdk/src/sandbox/sandboxApi.ts

@@ -267,6 +267,22 @@ export interface SnapshotListOpts extends SandboxApiOpts {
   nextToken?: string
 }
 
+/**
+ * Options for creating a snapshot.
+ */
+export interface SnapshotCreateOpts extends SandboxApiOpts {
+  /**
+   * Optional human-readable name for the snapshot template.
+   *
+   * If a snapshot template with this name already exists, a new build will be
+   * assigned to the existing template instead of creating a new one.
+   *
+   * The name must be unique within your team. Once assigned, the snapshot can
+   * be used with {@link Sandbox.create} via `team-slug/name`.
+   */
+  name?: string
+}
+
 /**
  * Information about a snapshot.
  */
@@ -276,6 +292,13 @@ export interface SnapshotInfo {
    * Can be used with Sandbox.create() to create a new sandbox from this snapshot.
    */
   snapshotId: string
+
+  /**
+   * Full namespaced names assigned to this snapshot (e.g. `["team-slug/my-snapshot:default"]`).
+   * Present when the snapshot was created with a `name` option.
+   * Use any entry with {@link Sandbox.create} to start a sandbox from this snapshot by name.
+   */
+  names: string[]
 }
 
 /**
@@ -687,7 +710,7 @@ export class SandboxApi {
    */
   static async createSnapshot(
     sandboxId: string,
-    opts?: SandboxApiOpts
+    opts?: SnapshotCreateOpts
   ): Promise<SnapshotInfo> {
     const config = new ConnectionConfig(opts)
     const client = new ApiClient(config)
@@ -698,7 +721,9 @@ export class SandboxApi {
           sandboxID: sandboxId,
         },
       },
-      body: {},
+      body: {
+        ...(opts?.name && { name: opts.name }),
+      },
       signal: config.getSignal(opts?.requestTimeoutMs),
     })
 
@@ -713,6 +738,7 @@ export class SandboxApi {
 
     return {
       snapshotId: res.data!.snapshotID,
+      names: res.data!.names,
     }
   }
 
@@ -1038,6 +1064,7 @@ export class SnapshotPaginator extends BasePaginator<SnapshotInfo> {
     return (res.data ?? []).map(
       (snapshot: components['schemas']['SnapshotInfo']) => ({
         snapshotId: snapshot.snapshotID,
+        names: snapshot.names,
       })
     )
   }