Add list and runtime APIs

[steven-passynkov]

Summary

• add sandbox and snapshot list APIs with exported request and response schemas/types
• add sandbox helpers for fetching the resolved user home directory and configured workdir
• cover the new client methods with targeted service and client tests

Testing

• pnpm vitest run tests/services/sandboxes-client.test.ts tests/services/snapshots.test.ts tests/client/client-sandbox.test.ts

Summary by CodeRabbit

• New Features
  • Sandbox listing with pagination, sorting, and filtering.
  • Snapshot listing with pagination, sorting, and filtering.
  • Methods to retrieve sandbox system info: user home directory and working directory.
• Tests
  • Added unit tests for sandbox/snapshot listing behavior and for the sandbox system-info methods.

[coderabbitai]

Warning

Rate limit exceeded

@steven-passynkov has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 1 minutes and 57 seconds before requesting another review.

Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 1 minutes and 57 seconds.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: adc54629-0d00-43b9-afa7-1fb35b336ee4

📥 Commits

Reviewing files that changed from the base of the PR and between 17a8848 and d49e13a.

📒 Files selected for processing (3)

• src/index.ts
• src/models/index.ts
• tests/client/client-sandbox.test.ts

📝 Walkthrough

Walkthrough

Adds sandbox and snapshot listing APIs with Zod schemas/types, new list methods on service clients, sandbox instance helpers for user home/workdir retrieval, and corresponding tests.

Changes

Cohort / File(s)	Summary
Model Schemas and Types src/models/sandbox.ts, src/models/snapshot.ts	Added Zod schemas and inferred types for listing: sandboxListItemSchema, listSandboxesResponseSchema, listSandboxesParamsSchema, listSnapshotsParamsSchema, and listSnapshotsResponseSchema (pagination, validation, passthrough/catchall).
Model Exports src/models/index.ts, src/index.ts	Re-exported new schemas and types to public API: listSandboxesParamsSchema, listSandboxesResponseSchema, SandboxListItem, ListSandboxesParams, ListSandboxesResponse, listSnapshotsParamsSchema, listSnapshotsResponseSchema, ListSnapshotsParams, ListSnapshotsResponse.
Service Client Methods src/services/sandboxes.ts	Added SandboxesClient.list(params, options) (validates params, maps query keys, normalizes response) and runtime-info methods getUserHomeDir(sandbox, options) and getWorkdir(sandbox, options) (call system endpoints, validate string fields).
Service Client Methods src/services/snapshots.ts	Added SnapshotsClient.list(params, options) (validates params, maps query keys, normalizes paginated response).
Sandbox Client Convenience Methods src/client/sandbox.ts	Added instance helpers getUserHomeDir(options?) and getWorkdir(options?) that delegate to this.client.sandboxes with the sandbox id.
Tests tests/client/client-sandbox.test.ts, tests/services/sandboxes-client.test.ts, tests/services/snapshots.test.ts	Added tests for new convenience methods, service runtime-info error handling, list query mapping, and response normalization to camelCase; updated type assertions for new methods.

Sequence Diagram(s)

sequenceDiagram
  participant SandboxInst as Sandbox (instance)
  participant SandboxesSvc as SandboxesClient
  participant Transport as Transport
  participant API as API Server

  SandboxInst->>SandboxesSvc: getWorkdir(id, options)
  SandboxesSvc->>Transport: GET /v1/sandbox/{id}/system/workdir (query/options)
  Transport->>API: HTTP request
  API-->>Transport: { "workdir": "/home/user" }
  Transport-->>SandboxesSvc: response JSON
  SandboxesSvc-->>SandboxInst: "/home/user"

Loading

sequenceDiagram
  participant Caller as Caller (app)
  participant SandboxesSvc as SandboxesClient
  participant Transport as Transport
  participant API as API Server

  Caller->>SandboxesSvc: list(params, options)
  SandboxesSvc->>SandboxesSvc: validate params (Zod)
  SandboxesSvc->>Transport: GET /v1/sandboxes?state=...&order-by=...&page-size=...
  Transport->>API: HTTP request
  API-->>Transport: { "items":[{...}], "total_items": 42 }
  Transport-->>SandboxesSvc: response JSON
  SandboxesSvc->>SandboxesSvc: normalize to ListSandboxesResponse (camelCase)
  SandboxesSvc-->>Caller: { items: [...], totalItems: 42 }

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• Initial JS SDK foundation #1: Adds sandbox list and runtime-info methods to SandboxesClient and Sandbox bindings — closely related to these changes.
• Init fixes #3: Modifies same sandbox/service codepaths (src/client/sandbox.ts, src/services/sandboxes.ts) with overlapping adjustments.
• Docs #6: Updates Sandbox class (JSDoc/methods) and touches the same convenience methods added here.

Poem

🐇 I hopped through schemas, neat and spry,
Listed sandboxes in the sky,
Home dirs and workdirs I fetch with glee,
CamelCase carrots for you and me,
🥕✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Add list and runtime APIs' directly and clearly describes the main changes: addition of list APIs (sandbox and snapshot listing) and runtime APIs (getUserHomeDir, getWorkdir methods).
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/list-runtime-apis

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@src/models/index.ts`:
- Around line 5-10: The models barrel is missing runtime schemas for list
responses; add exports for the runtime schema symbols (e.g.,
listSandboxesResponseSchema and listSnapshotsResponseSchema) alongside the
existing exports (createSandboxParamsSchema, listSandboxesParamsSchema,
NetworkPolicyMode, SandboxState) so consumers can import both types and runtime
validators from the public models barrel; update the export statement to include
the list response schema names that are defined in the sandbox module.

In `@src/services/sandboxes.ts`:
- Around line 214-223: The code assumes the JSON response is an object and
directly accesses data.user_home_dir, which can throw if the server returns null
or a primitive; update the code that calls this.transport.requestJson (the block
using sandboxIdOf(sandbox)/system/user-home-dir) to first verify that the
returned value is a non-null object (e.g., typeof data === "object" && data !==
null) before accessing properties and only then check typeof data.user_home_dir
=== "string", otherwise throw the Leap0Error; apply the same guard to the
analogous block around the later request (the one noted at lines 235-244) that
reads other response fields so both locations validate the response shape before
property access.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 975c429e-c79e-4b65-891a-3be7b55c1eb2

📥 Commits

Reviewing files that changed from the base of the PR and between c7dbcf3 and a967d4a.

📒 Files selected for processing (10)

• src/client/sandbox.ts
• src/index.ts
• src/models/index.ts
• src/models/sandbox.ts
• src/models/snapshot.ts
• src/services/sandboxes.ts
• src/services/snapshots.ts
• tests/client/client-sandbox.test.ts
• tests/services/sandboxes-client.test.ts
• tests/services/snapshots.test.ts

[steven-passynkov]

@CodeRabbit review?

[coderabbitai]

@steven-passynkov Sure! I'll start reviewing the PR right away.

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.