feat(api): new process, fs, and log endpoints

New endpoints for executing processes on browser instances, uploading / downloading whole directories as zip files, and streaming any log file on a browser instance

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 31
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-b55c3e0424fa7733487139488b9fff00ad8949ff02ee3160ee36b9334e84b134.yml
-openapi_spec_hash: 17f36677e3dc0a3aeb419654c8d5cae3
-config_hash: f67e4b33b2fb30c1405ee2fff8096320
+configured_endpoints: 41
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-a7c1df5070fe59642d7a1f168aa902a468227752bfc930cbf38930f7c205dbb6.yml
+openapi_spec_hash: eab65e39aef4f0a0952b82adeecf6b5b
+config_hash: 5de78bc29ac060562575cb54bb26826c

api.md

@@ -97,11 +97,14 @@ Methods:
 - <code title="put /browsers/{id}/fs/create_directory">client.browsers.fs.<a href="./src/resources/browsers/fs/fs.ts">createDirectory</a>(id, { ...params }) -> void</code>
 - <code title="put /browsers/{id}/fs/delete_directory">client.browsers.fs.<a href="./src/resources/browsers/fs/fs.ts">deleteDirectory</a>(id, { ...params }) -> void</code>
 - <code title="put /browsers/{id}/fs/delete_file">client.browsers.fs.<a href="./src/resources/browsers/fs/fs.ts">deleteFile</a>(id, { ...params }) -> void</code>
+- <code title="get /browsers/{id}/fs/download_dir_zip">client.browsers.fs.<a href="./src/resources/browsers/fs/fs.ts">downloadDirZip</a>(id, { ...params }) -> Response</code>
 - <code title="get /browsers/{id}/fs/file_info">client.browsers.fs.<a href="./src/resources/browsers/fs/fs.ts">fileInfo</a>(id, { ...params }) -> FFileInfoResponse</code>
 - <code title="get /browsers/{id}/fs/list_files">client.browsers.fs.<a href="./src/resources/browsers/fs/fs.ts">listFiles</a>(id, { ...params }) -> FListFilesResponse</code>
 - <code title="put /browsers/{id}/fs/move">client.browsers.fs.<a href="./src/resources/browsers/fs/fs.ts">move</a>(id, { ...params }) -> void</code>
 - <code title="get /browsers/{id}/fs/read_file">client.browsers.fs.<a href="./src/resources/browsers/fs/fs.ts">readFile</a>(id, { ...params }) -> Response</code>
 - <code title="put /browsers/{id}/fs/set_file_permissions">client.browsers.fs.<a href="./src/resources/browsers/fs/fs.ts">setFilePermissions</a>(id, { ...params }) -> void</code>
+- <code title="post /browsers/{id}/fs/upload">client.browsers.fs.<a href="./src/resources/browsers/fs/fs.ts">upload</a>(id, { ...params }) -> void</code>
+- <code title="post /browsers/{id}/fs/upload_zip">client.browsers.fs.<a href="./src/resources/browsers/fs/fs.ts">uploadZip</a>(id, { ...params }) -> void</code>
 - <code title="put /browsers/{id}/fs/write_file">client.browsers.fs.<a href="./src/resources/browsers/fs/fs.ts">writeFile</a>(id, contents, { ...params }) -> void</code>
 
 ### Watch
@@ -116,3 +119,29 @@ Methods:
 - <code title="get /browsers/{id}/fs/watch/{watch_id}/events">client.browsers.fs.watch.<a href="./src/resources/browsers/fs/watch.ts">events</a>(watchID, { ...params }) -> WatchEventsResponse</code>
 - <code title="post /browsers/{id}/fs/watch">client.browsers.fs.watch.<a href="./src/resources/browsers/fs/watch.ts">start</a>(id, { ...params }) -> WatchStartResponse</code>
 - <code title="delete /browsers/{id}/fs/watch/{watch_id}">client.browsers.fs.watch.<a href="./src/resources/browsers/fs/watch.ts">stop</a>(watchID, { ...params }) -> void</code>
+
+## Process
+
+Types:
+
+- <code><a href="./src/resources/browsers/process.ts">ProcessExecResponse</a></code>
+- <code><a href="./src/resources/browsers/process.ts">ProcessKillResponse</a></code>
+- <code><a href="./src/resources/browsers/process.ts">ProcessSpawnResponse</a></code>
+- <code><a href="./src/resources/browsers/process.ts">ProcessStatusResponse</a></code>
+- <code><a href="./src/resources/browsers/process.ts">ProcessStdinResponse</a></code>
+- <code><a href="./src/resources/browsers/process.ts">ProcessStdoutStreamResponse</a></code>
+
+Methods:
+
+- <code title="post /browsers/{id}/process/exec">client.browsers.process.<a href="./src/resources/browsers/process.ts">exec</a>(id, { ...params }) -> ProcessExecResponse</code>
+- <code title="post /browsers/{id}/process/{process_id}/kill">client.browsers.process.<a href="./src/resources/browsers/process.ts">kill</a>(processID, { ...params }) -> ProcessKillResponse</code>
+- <code title="post /browsers/{id}/process/spawn">client.browsers.process.<a href="./src/resources/browsers/process.ts">spawn</a>(id, { ...params }) -> ProcessSpawnResponse</code>
+- <code title="get /browsers/{id}/process/{process_id}/status">client.browsers.process.<a href="./src/resources/browsers/process.ts">status</a>(processID, { ...params }) -> ProcessStatusResponse</code>
+- <code title="post /browsers/{id}/process/{process_id}/stdin">client.browsers.process.<a href="./src/resources/browsers/process.ts">stdin</a>(processID, { ...params }) -> ProcessStdinResponse</code>
+- <code title="get /browsers/{id}/process/{process_id}/stdout/stream">client.browsers.process.<a href="./src/resources/browsers/process.ts">stdoutStream</a>(processID, { ...params }) -> ProcessStdoutStreamResponse</code>
+
+## Logs
+
+Methods:
+
+- <code title="get /browsers/{id}/logs/stream">client.browsers.logs.<a href="./src/resources/browsers/logs.ts">stream</a>(id, { ...params }) -> LogEvent</code>

src/resources/browsers/browsers.ts

@@ -2,6 +2,24 @@
 
 import { APIResource } from '../../core/resource';
 import * as BrowsersAPI from './browsers';
+import * as LogsAPI from './logs';
+import { LogStreamParams, Logs } from './logs';
+import * as ProcessAPI from './process';
+import {
+  Process,
+  ProcessExecParams,
+  ProcessExecResponse,
+  ProcessKillParams,
+  ProcessKillResponse,
+  ProcessSpawnParams,
+  ProcessSpawnResponse,
+  ProcessStatusParams,
+  ProcessStatusResponse,
+  ProcessStdinParams,
+  ProcessStdinResponse,
+  ProcessStdoutStreamParams,
+  ProcessStdoutStreamResponse,
+} from './process';
 import * as ReplaysAPI from './replays';
 import {
   ReplayDownloadParams,
@@ -16,13 +34,16 @@ import {
   FCreateDirectoryParams,
   FDeleteDirectoryParams,
   FDeleteFileParams,
+  FDownloadDirZipParams,
   FFileInfoParams,
   FFileInfoResponse,
   FListFilesParams,
   FListFilesResponse,
   FMoveParams,
   FReadFileParams,
   FSetFilePermissionsParams,
+  FUploadParams,
+  FUploadZipParams,
   FWriteFileParams,
   Fs,
 } from './fs/fs';
@@ -34,6 +55,8 @@ import { path } from '../../internal/utils/path';
 export class Browsers extends APIResource {
   replays: ReplaysAPI.Replays = new ReplaysAPI.Replays(this._client);
   fs: FsAPI.Fs = new FsAPI.Fs(this._client);
+  process: ProcessAPI.Process = new ProcessAPI.Process(this._client);
+  logs: LogsAPI.Logs = new LogsAPI.Logs(this._client);
 
   /**
    * Create a new browser session from within an action.
@@ -296,6 +319,8 @@ export interface BrowserDeleteParams {
 
 Browsers.Replays = Replays;
 Browsers.Fs = Fs;
+Browsers.Process = Process;
+Browsers.Logs = Logs;
 
 export declare namespace Browsers {
   export {
@@ -323,11 +348,32 @@ export declare namespace Browsers {
     type FCreateDirectoryParams as FCreateDirectoryParams,
     type FDeleteDirectoryParams as FDeleteDirectoryParams,
     type FDeleteFileParams as FDeleteFileParams,
+    type FDownloadDirZipParams as FDownloadDirZipParams,
     type FFileInfoParams as FFileInfoParams,
     type FListFilesParams as FListFilesParams,
     type FMoveParams as FMoveParams,
     type FReadFileParams as FReadFileParams,
     type FSetFilePermissionsParams as FSetFilePermissionsParams,
+    type FUploadParams as FUploadParams,
+    type FUploadZipParams as FUploadZipParams,
     type FWriteFileParams as FWriteFileParams,
   };
+
+  export {
+    Process as Process,
+    type ProcessExecResponse as ProcessExecResponse,
+    type ProcessKillResponse as ProcessKillResponse,
+    type ProcessSpawnResponse as ProcessSpawnResponse,
+    type ProcessStatusResponse as ProcessStatusResponse,
+    type ProcessStdinResponse as ProcessStdinResponse,
+    type ProcessStdoutStreamResponse as ProcessStdoutStreamResponse,
+    type ProcessExecParams as ProcessExecParams,
+    type ProcessKillParams as ProcessKillParams,
+    type ProcessSpawnParams as ProcessSpawnParams,
+    type ProcessStatusParams as ProcessStatusParams,
+    type ProcessStdinParams as ProcessStdinParams,
+    type ProcessStdoutStreamParams as ProcessStdoutStreamParams,
+  };
+
+  export { Logs as Logs, type LogStreamParams as LogStreamParams };
 }

src/resources/browsers/fs/fs.ts

@@ -11,8 +11,10 @@ import {
   WatchStopParams,
 } from './watch';
 import { APIPromise } from '../../../core/api-promise';
+import { type Uploadable } from '../../../core/uploads';
 import { buildHeaders } from '../../../internal/headers';
 import { RequestOptions } from '../../../internal/request-options';
+import { multipartFormRequestOptions } from '../../../internal/uploads';
 import { path } from '../../../internal/utils/path';
 
 export class Fs extends APIResource {
@@ -70,6 +72,29 @@ export class Fs extends APIResource {
     });
   }
 
+  /**
+   * Returns a ZIP file containing the contents of the specified directory.
+   *
+   * @example
+   * ```ts
+   * const response = await client.browsers.fs.downloadDirZip(
+   *   'id',
+   *   { path: '/J!' },
+   * );
+   *
+   * const content = await response.blob();
+   * console.log(content);
+   * ```
+   */
+  downloadDirZip(id: string, query: FDownloadDirZipParams, options?: RequestOptions): APIPromise<Response> {
+    return this._client.get(path`/browsers/${id}/fs/download_dir_zip`, {
+      query,
+      ...options,
+      headers: buildHeaders([{ Accept: 'application/zip' }, options?.headers]),
+      __binaryResponse: true,
+    });
+  }
+
   /**
    * Get information about a file or directory
    *
@@ -162,6 +187,52 @@ export class Fs extends APIResource {
     });
   }
 
+  /**
+   * Allows uploading single or multiple files to the remote filesystem.
+   *
+   * @example
+   * ```ts
+   * await client.browsers.fs.upload('id', {
+   *   files: [
+   *     {
+   *       dest_path: '/J!',
+   *       file: fs.createReadStream('path/to/file'),
+   *     },
+   *   ],
+   * });
+   * ```
+   */
+  upload(id: string, body: FUploadParams, options?: RequestOptions): APIPromise<void> {
+    return this._client.post(
+      path`/browsers/${id}/fs/upload`,
+      multipartFormRequestOptions(
+        { body, ...options, headers: buildHeaders([{ Accept: '*/*' }, options?.headers]) },
+        this._client,
+      ),
+    );
+  }
+
+  /**
+   * Upload a zip file and extract its contents to the specified destination path.
+   *
+   * @example
+   * ```ts
+   * await client.browsers.fs.uploadZip('id', {
+   *   dest_path: '/J!',
+   *   zip_file: fs.createReadStream('path/to/file'),
+   * });
+   * ```
+   */
+  uploadZip(id: string, body: FUploadZipParams, options?: RequestOptions): APIPromise<void> {
+    return this._client.post(
+      path`/browsers/${id}/fs/upload_zip`,
+      multipartFormRequestOptions(
+        { body, ...options, headers: buildHeaders([{ Accept: '*/*' }, options?.headers]) },
+        this._client,
+      ),
+    );
+  }
+
   /**
    * Write or create a file
    *
@@ -290,6 +361,13 @@ export interface FDeleteFileParams {
   path: string;
 }
 
+export interface FDownloadDirZipParams {
+  /**
+   * Absolute directory path to archive and download.
+   */
+  path: string;
+}
+
 export interface FFileInfoParams {
   /**
    * Absolute path of the file or directory.
@@ -345,6 +423,30 @@ export interface FSetFilePermissionsParams {
   owner?: string;
 }
 
+export interface FUploadParams {
+  files: Array<FUploadParams.File>;
+}
+
+export namespace FUploadParams {
+  export interface File {
+    /**
+     * Absolute destination path to write the file.
+     */
+    dest_path: string;
+
+    file: Uploadable;
+  }
+}
+
+export interface FUploadZipParams {
+  /**
+   * Absolute destination directory to extract the archive to.
+   */
+  dest_path: string;
+
+  zip_file: Uploadable;
+}
+
 export interface FWriteFileParams {
   /**
    * Query param: Destination absolute file path.
@@ -366,11 +468,14 @@ export declare namespace Fs {
     type FCreateDirectoryParams as FCreateDirectoryParams,
     type FDeleteDirectoryParams as FDeleteDirectoryParams,
     type FDeleteFileParams as FDeleteFileParams,
+    type FDownloadDirZipParams as FDownloadDirZipParams,
     type FFileInfoParams as FFileInfoParams,
     type FListFilesParams as FListFilesParams,
     type FMoveParams as FMoveParams,
     type FReadFileParams as FReadFileParams,
     type FSetFilePermissionsParams as FSetFilePermissionsParams,
+    type FUploadParams as FUploadParams,
+    type FUploadZipParams as FUploadZipParams,
     type FWriteFileParams as FWriteFileParams,
   };
 

src/resources/browsers/fs/index.ts

@@ -7,11 +7,14 @@ export {
   type FCreateDirectoryParams,
   type FDeleteDirectoryParams,
   type FDeleteFileParams,
+  type FDownloadDirZipParams,
   type FFileInfoParams,
   type FListFilesParams,
   type FMoveParams,
   type FReadFileParams,
   type FSetFilePermissionsParams,
+  type FUploadParams,
+  type FUploadZipParams,
   type FWriteFileParams,
 } from './fs';
 export {

src/resources/browsers/index.ts

@@ -16,13 +16,32 @@ export {
   type FCreateDirectoryParams,
   type FDeleteDirectoryParams,
   type FDeleteFileParams,
+  type FDownloadDirZipParams,
   type FFileInfoParams,
   type FListFilesParams,
   type FMoveParams,
   type FReadFileParams,
   type FSetFilePermissionsParams,
+  type FUploadParams,
+  type FUploadZipParams,
   type FWriteFileParams,
 } from './fs/index';
+export { Logs, type LogStreamParams } from './logs';
+export {
+  Process,
+  type ProcessExecResponse,
+  type ProcessKillResponse,
+  type ProcessSpawnResponse,
+  type ProcessStatusResponse,
+  type ProcessStdinResponse,
+  type ProcessStdoutStreamResponse,
+  type ProcessExecParams,
+  type ProcessKillParams,
+  type ProcessSpawnParams,
+  type ProcessStatusParams,
+  type ProcessStdinParams,
+  type ProcessStdoutStreamParams,
+} from './process';
 export {
   Replays,
   type ReplayListResponse,

src/resources/browsers/logs.ts

@@ -0,0 +1,50 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as Shared from '../shared';
+import { APIPromise } from '../../core/api-promise';
+import { Stream } from '../../core/streaming';
+import { buildHeaders } from '../../internal/headers';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+
+export class Logs extends APIResource {
+  /**
+   * Stream log files on the browser instance via SSE
+   *
+   * @example
+   * ```ts
+   * const logEvent = await client.browsers.logs.stream('id', {
+   *   source: 'path',
+   * });
+   * ```
+   */
+  stream(id: string, query: LogStreamParams, options?: RequestOptions): APIPromise<Stream<Shared.LogEvent>> {
+    return this._client.get(path`/browsers/${id}/logs/stream`, {
+      query,
+      ...options,
+      headers: buildHeaders([{ Accept: 'text/event-stream' }, options?.headers]),
+      stream: true,
+    }) as APIPromise<Stream<Shared.LogEvent>>;
+  }
+}
+
+export interface LogStreamParams {
+  source: 'path' | 'supervisor';
+
+  follow?: boolean;
+
+  /**
+   * only required if source is path
+   */
+  path?: string;
+
+  /**
+   * only required if source is supervisor
+   */
+  supervisor_process?: string;
+}
+
+export declare namespace Logs {
+  export { type LogStreamParams as LogStreamParams };
+}