@sailresearch/sdk 0.2.14

package/native/index.d.ts

@@ -0,0 +1,733 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+/**
+ * A pull-based reader over an exec stream. `next` returns the next decoded
+ * chunk, or `null` at end of stream.
+ */
+export declare class AsyncStreamReaderHandle {
+  /** The next decoded chunk, or `null` at EOF. */
+  next(): Promise<string | null>
+}
+
+/**
+ * One native client per config snapshot: env vars are read at construction, so
+ * callers reconstruct it to pick up env changes.
+ */
+export declare class CoreClient {
+  /** Build a client from the environment (`SAIL_API_KEY`, `SAIL_MODE`, ...). */
+  static fromEnv(): CoreClient
+  /** Build a client from an explicit configuration (`apiKey` required). */
+  static fromConfig(config: ClientConfig): CoreClient
+  /**
+   * Create a sailbox. `timeoutSecs <= 0` means no client-side create
+   * timeout.
+   */
+  createSailbox(req: CreateSailboxRequest, timeoutSecs: number): Promise<SailboxHandle>
+  /** Fetch one sailbox by id. */
+  getSailbox(sailboxId: string): Promise<SailboxInfo>
+  /** List one page of sailboxes. */
+  listSailboxes(query: ListSailboxesQuery): Promise<SailboxInfoPage>
+  /** Terminate a sailbox (idempotent). */
+  terminateSailbox(sailboxId: string): Promise<void>
+  /** Pause a sailbox in memory. */
+  pauseSailbox(sailboxId: string): Promise<void>
+  /** Sleep a sailbox to disk. */
+  sleepSailbox(sailboxId: string): Promise<void>
+  /** Resume a paused/sleeping sailbox. */
+  resumeSailbox(sailboxId: string): Promise<SailboxHandle>
+  /**
+   * Checkpoint a running sailbox. `name` sets the handle's display name;
+   * `ttlSeconds`, when given, must be positive and overrides the server's
+   * default retention window.
+   */
+  checkpointSailbox(sailboxId: string, name?: string | undefined | null, ttlSeconds?: number | undefined | null): Promise<SailboxCheckpoint>
+  /** Create a sailbox from a checkpoint. */
+  createFromCheckpoint(req: FromCheckpointRequest): Promise<SailboxHandle>
+  /** Upgrade the in-guest agent. */
+  upgradeSailbox(sailboxId: string): Promise<UpgradeResult>
+  /** Expose a guest port at runtime. */
+  exposeListener(sailboxId: string, guestPort: number, protocol: string, allowlist: Array<string>): Promise<Listener>
+  /** Remove a runtime ingress port. */
+  unexposeListener(sailboxId: string, guestPort: number): Promise<void>
+  /** List a sailbox's listeners without waking it. */
+  listListeners(sailboxId: string): Promise<Array<Listener>>
+  /** Fetch one listener by guest port without waking the box. */
+  getListener(sailboxId: string, guestPort: number): Promise<Listener>
+  /**
+   * Block until the listener on `guestPort` is reachable end to end (route
+   * ACTIVE and the endpoint accepting) and return it, or reject with a
+   * Timeout error after `timeoutSecs`. Polls every `pollIntervalSecs`.
+   */
+  waitForListener(sailboxId: string, guestPort: number, timeoutSecs: number, pollIntervalSecs: number): Promise<Listener>
+  /** Ingress-identity headers for this sailbox, as a name -> value map. */
+  ingressAuthHeaders(sailboxId: string): Promise<Record<string, string>>
+  /** Look up (optionally minting) an NFS volume by name. */
+  getVolume(name: string, mintIfMissing: boolean): Promise<VolumeInfo>
+  /** List NFS volumes. */
+  listVolumes(maxObjects?: number | undefined | null): Promise<Array<VolumeInfo>>
+  /**
+   * Delete a volume by id. Resolves `null` when `allowMissing` and it was
+   * already gone.
+   */
+  deleteVolume(volumeId: string, allowMissing: boolean): Promise<VolumeInfo | null>
+  /** Find an app by name, optionally minting it. */
+  findApp(name: string, mintIfMissing: boolean): Promise<AppInfo>
+  /** Every app the org owns, newest first. */
+  listApps(): Promise<Array<AppInfo>>
+  /** Run a command in a sailbox. Returns a live process handle. */
+  exec(sailboxId: string, argv: Array<string>, options: ExecStartOptions): Promise<ExecProcessHandle>
+  /**
+   * Interactive pty session bridged to the local terminal: raw keystrokes
+   * forward to the remote pty, output renders locally, resizes propagate.
+   * Resolves with the remote process's exit code when it ends. Requires an
+   * interactive terminal (stdin and stdout TTYs).
+   */
+  shell(sailboxId: string, command?: string | undefined | null, shell?: string | undefined | null, term?: string | undefined | null, cwd?: string | undefined | null, timeoutSeconds?: number | undefined | null): Promise<number>
+  /**
+   * Run a shell command in a sailbox via `/bin/sh -lc`, honoring the
+   * `cwd`/`background` conveniences. Returns a live process handle.
+   */
+  execShell(sailboxId: string, command: string, options: ExecStartOptions): Promise<ExecProcessHandle>
+  /** Open a streaming read of a guest file. Returns a reader handle. */
+  readStream(sailboxId: string, remotePath: string): Promise<FileReaderHandle>
+  /**
+   * Whether a spec is a bare builtin base the backend ships prebuilt (no
+   * build needed).
+   */
+  isBuiltinBaseSpec(spec: ImageSpec): boolean
+  /**
+   * Resolve an image definition into a content-addressed spec: walk local
+   * directories (gitignore-style `ignore`), hash every file, and upload
+   * content the server does not already have.
+   */
+  resolveImageDefinition(def: ImageDefinition): Promise<ImageSpec>
+  /**
+   * Resolve an image definition and build it to ready, returning the
+   * content-addressed spec to create sailboxes from. A bare builtin base
+   * skips the build. `timeoutSecs` bounds the whole pipeline (hashing,
+   * uploads, and the build).
+   */
+  buildImageDefinition(def: ImageDefinition, timeoutSecs: number): Promise<ImageSpec>
+  /**
+   * Build an already-resolved spec to ready (submit + poll). A deadline of
+   * `timeoutSecs` bounds the poll loop.
+   */
+  buildSpecToReady(spec: ImageSpec, timeoutSecs: number): Promise<ImageBuild>
+  /**
+   * Enable SSH on a sailbox: trust the org's SSH certificate authority,
+   * (re)start `sshd`, and expose guest port 22 as TCP once the CA-only
+   * daemon verifiably owns it. A non-empty `allowlist` restricts port 22 to
+   * those source CIDRs, replacing any existing restriction; empty leaves an
+   * existing restriction unchanged. With `wait` the call polls until the
+   * endpoint is reachable and returns it (a Timeout error if it is not
+   * within `timeoutSecs`); without `wait` it skips the probe and resolves
+   * `null`.
+   */
+  enableSsh(sailboxId: string, allowlist: Array<string>, wait: boolean, timeoutSecs: number): Promise<SshEndpoint | null>
+  /**
+   * Fetch (creating on first use) the org's SSH certificate authority public
+   * key. Called before `create({ ssh: true })` provisions a box so a CA
+   * outage fails before the VM exists.
+   */
+  orgSshCaPublicKey(): Promise<string>
+  /** Open a streaming write to a guest file. Returns a writer handle. */
+  writeStream(sailboxId: string, remotePath: string, createParents: boolean, mode?: number | undefined | null): Promise<FileWriterHandle>
+}
+
+/** A handle to a live server-side command. Dropping it detaches (does not kill). */
+export declare class ExecProcessHandle {
+  /** The durable exec request id (identifies the exec for wait/cancel/reattach). */
+  get execRequestId(): string
+  /** The idempotency key used to launch (empty means one was minted). */
+  get idempotencyKey(): string
+  /** A reader over stdout; drives the live stream, yielding decoded chunks. */
+  stdoutReader(): AsyncStreamReaderHandle
+  /** A reader over stderr. */
+  stderrReader(): AsyncStreamReaderHandle
+  /** Await the authoritative result. */
+  wait(): Promise<ExecResult>
+  /** Wait up to `timeoutSecs` for the streams to end; returns whether they did. */
+  waitStreamEnded(timeoutSecs: number): Promise<boolean>
+  /** Cancel the command: `force` sends SIGKILL, else SIGINT. */
+  cancel(force: boolean, retryTimeoutSecs: number): Promise<void>
+  /** Resize the pty (best effort; no-op without a pty). */
+  resize(cols: number, rows: number): Promise<void>
+  /** Write to the command's stdin. */
+  writeStdin(data: Buffer): Promise<void>
+  /** Close the command's stdin (send EOF). */
+  closeStdin(): Promise<void>
+  /**
+   * The exit code if the exit frame has arrived on the stream, else `null`.
+   * Errors for a worker-lost exec (no real exit code).
+   */
+  poll(): number | null
+  /** Stop the output pump and detach (also runs on drop). */
+  close(): void
+}
+
+/**
+ * A pull-based reader over a downloading guest file. `next` returns the next
+ * chunk of bytes, or `null` at end of file.
+ */
+export declare class FileReaderHandle {
+  /** The next chunk of bytes, or `null` at EOF (or after `close`). */
+  next(): Promise<Buffer | null>
+  /**
+   * Stop the download and release the underlying stream. Idempotent; safe to
+   * call when a consumer abandons the stream early.
+   */
+  close(): Promise<void>
+}
+
+/**
+ * A streaming writer to a guest file. Feed it with `write` and end with
+ * `finish` (which also creates an empty file if nothing was written).
+ */
+export declare class FileWriterHandle {
+  /**
+   * Write bytes to the file (the core splits them into transport-sized
+   * chunks). Rejects if the upload was already finished.
+   */
+  write(data: Buffer): Promise<void>
+  /**
+   * Abort the write: cancel the RPC so the server does not commit it.
+   * Idempotent; a no-op after `finish`.
+   */
+  abort(): void
+  /** Finish the write, flushing and closing the file. Idempotent. */
+  finish(): Promise<void>
+}
+
+/** A tree of local files copied into the image. */
+export interface AddLocalDir {
+  /** Absolute guest path of the directory root. */
+  remotePath?: string
+  /** The files to place under `remotePath`. */
+  files?: Array<AddLocalDirFile>
+}
+
+/** One file within an `addLocalDir` step. */
+export interface AddLocalDirFile {
+  /** Path relative to the directory root. */
+  relativePath?: string
+  /** SHA-256 of the (already uploaded) file content. */
+  contentSha256?: string
+  /** Permission bits (low 9). */
+  mode?: number
+}
+
+/** One local file copied into the image, referenced by content hash. */
+export interface AddLocalFile {
+  /** SHA-256 of the (already uploaded) file content. */
+  contentSha256?: string
+  /** Absolute guest path to place the file at. */
+  remotePath?: string
+  /** Permission bits (low 9); 0 means the builder default (0644). */
+  mode?: number
+}
+
+/** An app on the central API. */
+export interface AppInfo {
+  /** Stable app id. */
+  id: string
+  /** App name. */
+  name: string
+  /** Creation time (RFC 3339). */
+  createdAt: string
+}
+
+/** Explicit client configuration (an alternative to environment resolution). */
+export interface ClientConfig {
+  /** Bearer API key. Required. */
+  apiKey: string
+  /** Named environment selecting endpoint defaults (for example `prod`). */
+  mode?: string
+  /** Override the central public-API URL. */
+  apiUrl?: string
+  /** Override the sailbox-API URL. */
+  sailboxApiUrl?: string
+  /** Override the imagebuilder dispatcher URL. */
+  imagebuilderUrl?: string
+  /**
+   * Override the listener ingress base URL (what `SAILBOX_INGRESS_URL`
+   * sets from the environment), for custom or local sailbox stacks.
+   */
+  ingressUrl?: string
+}
+
+/** The create-sailbox request. */
+export interface CreateSailboxRequest {
+  /** Identifier of the owning app. */
+  appId: string
+  /** The sailbox name. */
+  name: string
+  /** Image to boot; defaults to a plain Debian base when omitted. */
+  image?: ImageSpec
+  /** Guest ports to reserve for ingress. */
+  ingressPorts?: Array<IngressPortInput>
+  /** NFS volumes to mount. */
+  volumeMounts?: Array<VolumeMountInput>
+  /**
+   * Requested resource size (`"s"` or `"m"`); the platform default when
+   * omitted. A ceiling, not a reservation: billing follows observed usage.
+   */
+  size?: string
+  /**
+   * Memory limit in whole GiB within the size's range; the size's default
+   * when omitted.
+   */
+  memoryGib?: number
+  /**
+   * Disk size in whole GiB within the size's range; the size's default
+   * when omitted.
+   */
+  diskGib?: number
+  /** Idle minutes (1-1440) after which the platform may sleep the box. */
+  autosleepTimeoutMinutes?: number
+  /**
+   * Enable SSH on the new sailbox after create: trust the org SSH CA, start
+   * `sshd`, and expose guest port 22 as TCP once the CA-only daemon owns it
+   * (an explicit port-22 ingress entry contributes just its allowlist).
+   */
+  ssh?: boolean
+}
+
+/**
+ * The authoritative result of a finished exec.
+ *
+ * The buffered `stdout`/`stderr` are a capped, drop-oldest tail (the server
+ * keeps a bounded ring). To capture the complete output of a large-output
+ * command, stream it live and consult the `*Truncated`/`*Complete` flags.
+ */
+export interface ExecResult {
+  /** Buffered stdout (a capped tail; see `stdoutTruncated`/`stdoutComplete`). */
+  stdout: string
+  /** Buffered stderr (a capped tail; see `stderrTruncated`/`stderrComplete`). */
+  stderr: string
+  /** The command's exit code. */
+  exitCode: number
+  /** Whether the command was killed for exceeding its timeout. */
+  timedOut: boolean
+  /** True if buffered `stdout` dropped its oldest bytes (ring overflow). */
+  stdoutTruncated: boolean
+  /** True if buffered `stderr` dropped its oldest bytes (ring overflow). */
+  stderrTruncated: boolean
+  /**
+   * True if the live stream delivered stdout through to exit: a consumer
+   * that streamed live already has the complete stdout even if `stdout` here
+   * is truncated.
+   */
+  stdoutComplete: boolean
+  /**
+   * True if the live stream delivered stderr through to exit (see
+   * `stdoutComplete`).
+   */
+  stderrComplete: boolean
+}
+
+/** Options for starting an exec. */
+export interface ExecStartOptions {
+  /** Working directory to run the command in (shell commands only). */
+  cwd?: string
+  /**
+   * Detach the command so it keeps running and the call returns
+   * immediately; output is discarded (shell commands only, incompatible
+   * with `openStdin`/`pty`).
+   */
+  background?: boolean
+  /** Wall-clock limit in seconds before the server kills the command. */
+  timeoutSeconds?: number
+  /** Leave stdin open for `writeStdin`. */
+  openStdin?: boolean
+  /** Allocate a pseudo-terminal. */
+  pty?: boolean
+  /** TERM value for the pty. */
+  term?: string
+  /** Initial pty width in columns. */
+  cols?: number
+  /** Initial pty height in rows. */
+  rows?: number
+  /** Stable key so a reconnect reattaches to the same command. */
+  idempotencyKey?: string
+  /** Budget in seconds for retrying transient RPC failures. */
+  retryTimeoutSeconds?: number
+}
+
+/** The create-from-checkpoint request. */
+export interface FromCheckpointRequest {
+  /** The checkpoint to restore from. */
+  checkpointId: string
+  /** Name for the new sailbox; defaults to the source box's name. */
+  name?: string
+  /**
+   * Restore timeout in whole seconds (positive); omitted uses the server
+   * default.
+   */
+  timeoutSeconds?: number
+}
+
+/** The state of a custom image build. */
+export interface ImageBuild {
+  /** The content-addressed image id. */
+  imageId: string
+  /** Build status: `queued`, `building`, `ready`, `failed`, or `unspecified`. */
+  status: string
+  /** Human-readable failure detail; present when `status` is `failed`. */
+  errorMessage?: string
+}
+
+/** One build step. Exactly one of the fields must be set. */
+export interface ImageBuildStep {
+  /** Install system packages with apt. */
+  aptInstall?: PackageInstall
+  /** Install Python packages with pip. */
+  pipInstall?: PackageInstall
+  /** Run a shell command. */
+  runCommand?: RunCommand
+  /** Copy one already-uploaded local file into the image. */
+  addLocalFile?: AddLocalFile
+  /** Copy a tree of already-uploaded local files into the image. */
+  addLocalDir?: AddLocalDir
+}
+
+/**
+ * A custom image definition: a base image plus ordered build steps, where
+ * local-file steps still reference paths on this machine.
+ */
+export interface ImageDefinition {
+  /** Base image to build on: `debian` or `devbox`. */
+  base?: string
+  /**
+   * Target CPU architecture: `amd64` or `arm64`; unset lets the backend
+   * choose.
+   */
+  architecture?: string
+  /** Environment variables baked into the image. */
+  env?: Record<string, string>
+  /**
+   * Exact Python version to install as `python3`; unset uses the builder
+   * default.
+   */
+  pythonVersion?: string
+  /** Ordered build steps. */
+  steps?: Array<ImageDefinitionStep>
+}
+
+/** One image-definition step. Exactly one of the fields must be set. */
+export interface ImageDefinitionStep {
+  /** Install system packages with apt. */
+  aptInstall?: Array<string>
+  /** Install Python packages with pip. */
+  pipInstall?: Array<string>
+  /** Run a shell command during the build. */
+  runCommand?: string
+  /** Bake one local file into the image. */
+  addLocalFile?: LocalFileInput
+  /** Bake a local directory tree into the image. */
+  addLocalDir?: LocalDirInput
+}
+
+/** A sailbox image: a base image plus ordered build steps. */
+export interface ImageSpec {
+  /** Base image to build on: `debian` or `devbox`. */
+  base?: string
+  /** Ordered build steps applied on top of the base image. */
+  buildSteps?: Array<ImageBuildStep>
+  /** Environment variables baked into the image. */
+  env?: Record<string, string>
+  /**
+   * Target CPU architecture: `amd64` or `arm64`; unset lets the backend
+   * choose.
+   */
+  architecture?: string
+  /**
+   * Exact Python version to install as `python3`; unset uses the builder
+   * default.
+   */
+  pythonVersion?: string
+}
+
+/**
+ * Guest-side: headers that authenticate this sailbox as an ingress
+ * allowlist source (only available inside a sailbox guest).
+ */
+export declare function ingressAuthHeaders(): Record<string, string>
+
+/** A guest port to reserve for ingress at create time. */
+export interface IngressPortInput {
+  /** The in-guest port to expose (1-65535). */
+  guestPort: number
+  /** `http` or `tcp`. */
+  protocol: string
+  /** Source addresses allowed to reach the port; empty allows all. */
+  allowlist?: Array<string>
+}
+
+/** An exposed guest port and how to reach it. */
+export interface Listener {
+  /** The in-guest port traffic is forwarded to. */
+  guestPort: number
+  /** Wire protocol exposed (`tcp` or `http`). */
+  protocol: string
+  /** Status of the listener's ingress route. */
+  routeStatus: string
+  /** Publicly reachable URL, else "". */
+  publicUrl: string
+  /** Public hostname, else "". */
+  publicHost: string
+  /** Public port, else 0. */
+  publicPort: number
+}
+
+/** Filters for listing sailboxes. */
+export interface ListSailboxesQuery {
+  /** Filter to one app by its id. */
+  appId?: string
+  /**
+   * Filter by lifecycle status (`running`, `paused`, `sleeping`, `failed`,
+   * or `terminated`).
+   */
+  status?: string
+  /** Substring filter on the sailbox name. */
+  search?: string
+  /** Only sailboxes at or below this guest schema version. */
+  maxGuestSchemaVersion?: number
+  /** Page size. */
+  limit?: number
+  /** Page offset. */
+  offset?: number
+}
+
+/**
+ * A local directory tree to bake into the image (walked, hashed, and
+ * uploaded at resolve; symlinks skipped, file modes preserved).
+ */
+export interface LocalDirInput {
+  /** Path on this machine. */
+  localPath: string
+  /** Absolute POSIX path of the directory root inside the image. */
+  remotePath: string
+  /** Gitignore-style patterns to skip. */
+  ignore?: Array<string>
+  /** A gitignore-style file whose patterns to skip (e.g. `.gitignore`). */
+  ignoreFile?: string
+}
+
+/** One local file to bake into the image (hashed and uploaded at resolve). */
+export interface LocalFileInput {
+  /** Path on this machine. */
+  localPath: string
+  /**
+   * Absolute POSIX path inside the image; a trailing `/` appends the
+   * source basename.
+   */
+  remotePath: string
+  /** Permission bits (low 9); omitted uses the builder default (0644). */
+  mode?: number
+}
+
+/** A set of packages to install (apt or pip). */
+export interface PackageInstall {
+  /** Package names. */
+  packages?: Array<string>
+}
+
+/**
+ * Resolve the SDK config from the environment and `~/.sail` (without requiring
+ * an API key). The core is the single source of truth for endpoint and mode
+ * resolution.
+ */
+export declare function resolvedConfig(): ResolvedConfig
+
+/** The SDK configuration resolved from the environment and `~/.sail`. */
+export interface ResolvedConfig {
+  /** The resolved API key; absent when none is configured. */
+  apiKey?: string
+  /** Central public-API URL. */
+  apiUrl: string
+  /** Sailbox-API URL. */
+  sailboxApiUrl: string
+  /** Imagebuilder dispatcher URL. */
+  imagebuilderUrl: string
+  /** Base host/URL public listeners are addressed under. */
+  ingressBase: string
+  /**
+   * How listener URLs are addressed under `ingressBase`: `path` or
+   * `subdomain`.
+   */
+  ingressScheme: string
+}
+
+/** A shell command to run during the build. */
+export interface RunCommand {
+  /** The command, run via the builder's shell. */
+  command?: string
+}
+
+/** A durable checkpoint handle. */
+export interface SailboxCheckpoint {
+  /** The checkpoint id. */
+  checkpointId: string
+  /** The sailbox the checkpoint was taken from. */
+  sailboxId: string
+  /** Checkpoint generation captured by this checkpoint. */
+  checkpointGeneration: number
+  /**
+   * When the handle expires and becomes eligible for garbage collection
+   * (RFC 3339); absent for a handle that carries no fresh retention bound
+   * (a paused or sleeping source).
+   */
+  expiresAt?: string
+  /** The source sailbox's status after checkpointing. */
+  status: string
+}
+
+/**
+ * Returned by create / resume / fromCheckpoint: identity plus the live
+ * endpoints of a running sailbox.
+ */
+export interface SailboxHandle {
+  /** The sailbox id. */
+  sailboxId: string
+  /** The sailbox name. */
+  name: string
+  /** Lifecycle status (for example `running`). */
+  status: string
+}
+
+/** A read snapshot of a sailbox (get / list). Timestamps are RFC 3339 strings. */
+export interface SailboxInfo {
+  /** The sailbox id. */
+  sailboxId: string
+  /** Identifier of the owning app. */
+  appId: string
+  /** Name of the owning app. */
+  appName: string
+  /** Identifier of the image the sailbox was created from. */
+  imageId: string
+  /** The sailbox name. */
+  name: string
+  /** Lifecycle status (for example `running`). */
+  status: string
+  /** Configured memory, in MiB. */
+  memoryMib: number
+  /** Configured number of vCPUs. */
+  vcpuCount: number
+  /** Configured state-disk size, in GiB. */
+  stateDiskSizeGib: number
+  /** Requested CPU, in vCPUs. */
+  cpuRequestedVcpu: number
+  /** Current CPU usage, in vCPUs. */
+  cpuUsedVcpu: number
+  /** Requested memory, in bytes. */
+  memoryRequestedBytes: number
+  /** Current memory usage, in bytes. */
+  memoryUsedBytes: number
+  /** Requested disk, in bytes. */
+  diskRequestedBytes: number
+  /** Current disk usage, in bytes. */
+  diskUsedBytes: number
+  /** CPU architecture (for example `arm64`). */
+  architecture: string
+  /**
+   * Guest schema version; absent for boxes created before it was recorded
+   * (treat as the oldest possible version).
+   */
+  guestSchemaVersion?: number
+  /** Human-readable error detail when the box is in an error state. */
+  errorMessage?: string
+  /** Monotonic checkpoint generation counter. */
+  checkpointGeneration: number
+  /** When the box last started, if it ever has (RFC 3339). */
+  startedAt?: string
+  /** When the most recent checkpoint was taken, if any (RFC 3339). */
+  lastCheckpointedAt?: string
+  /** When the sailbox was created (RFC 3339). */
+  createdAt: string
+  /** When the sailbox was last updated (RFC 3339). */
+  updatedAt: string
+}
+
+/** One page of list results plus the pagination envelope. */
+export interface SailboxInfoPage {
+  /** The sailboxes on this page. */
+  items: Array<SailboxInfo>
+  /** The page size that was applied. */
+  limit: number
+  /** The offset that was applied. */
+  offset: number
+  /** Total matching sailboxes across all pages. */
+  total: number
+  /** Whether more results exist past this page. */
+  hasMore: boolean
+}
+
+/** The public TCP endpoint a sailbox's SSH listener is reachable at. */
+export interface SshEndpoint {
+  /** Hostname to dial. */
+  host: string
+  /** Port to dial. */
+  port: number
+}
+
+/** The outcome of an in-guest agent upgrade. */
+export interface UpgradeResult {
+  /**
+   * True when applied immediately (running box); false when deferred to the
+   * next wake.
+   */
+  applied: boolean
+  /** Lifecycle status of the sailbox after the upgrade call. */
+  status: string
+}
+
+/**
+ * Validate an autosleep timeout against the core's shared range (1..=1440
+ * minutes when set), so create fails fast before an image build.
+ */
+export declare function validateAutosleepTimeout(minutes?: number | undefined | null): void
+
+/**
+ * Validate ingress ports against the core's reserved/duplicate/protocol/
+ * allowlist rules, so a wrapper fails fast before an image build.
+ */
+export declare function validateIngressPorts(ports: Array<IngressPortInput>): void
+
+/**
+ * Validate optional memory/disk ceilings (whole GiB) against the size's
+ * range, so create fails fast before an image build.
+ */
+export declare function validateSizeLimits(size?: string | undefined | null, memoryGib?: number | undefined | null, diskGib?: number | undefined | null): void
+
+/** Validate volume mounts against the core's path/overlap rules. */
+export declare function validateVolumeMounts(mounts: Array<VolumeMountInput>): void
+
+/**
+ * Guest-side: load the volume metadata for a path mounted into this sailbox
+ * (only available inside a sailbox guest).
+ */
+export declare function volumeFromMount(path: string): VolumeInfo
+
+/** A managed NFS volume. Timestamps are RFC 3339 strings. */
+export interface VolumeInfo {
+  /** The volume id. */
+  volumeId: string
+  /** The volume name. */
+  name: string
+  /** Storage backend serving the volume. */
+  backend: string
+  /** Lifecycle status. */
+  status: string
+  /** Creation time (RFC 3339), if reported. */
+  createdAt?: string
+  /** Last-update time (RFC 3339), if reported. */
+  updatedAt?: string
+}
+
+/** An NFS volume to mount at create time. */
+export interface VolumeMountInput {
+  /** The volume id (from `getVolume`/`listVolumes`). */
+  volumeId: string
+  /** Absolute guest path to mount at. */
+  mountPath: string
+}