instavm 0.11.0 → 0.13.0

package/dist/index.d.mts

@@ -15,7 +15,7 @@ interface HttpClientConfig {
     apiKey: string;
 }
 interface RequestConfig {
-    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS';
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS' | 'HEAD';
     url: string;
     headers?: Record<string, string>;
     data?: any;
@@ -336,6 +336,7 @@ interface VMCreateRequest extends JsonMap {
     share?: JsonMap | null;
     custom_domain?: JsonMap | null;
     image_variant?: string | null;
+    volumes?: VMVolumeMountRequest[] | null;
 }
 interface VMUpdateRequest extends JsonMap {
     memory_mb?: number | null;
@@ -370,6 +371,69 @@ interface SnapshotCreateRequest extends JsonMap {
 interface SnapshotQueryOptions {
     type?: 'user' | 'system';
 }
+interface VolumeCreateRequest extends JsonMap {
+    name: string;
+    quota_bytes: number;
+}
+interface VolumeUpdateRequest extends JsonMap {
+    name?: string | null;
+    quota_bytes?: number | null;
+}
+interface VolumeResponse extends JsonMap {
+    id: string;
+    name: string;
+    quota_bytes: number;
+    used_bytes: number;
+    status: string;
+    created_at?: string | null;
+    updated_at?: string | null;
+}
+interface VolumeCheckpointCreateRequest extends JsonMap {
+    name?: string | null;
+}
+interface VolumeCheckpointResponse extends JsonMap {
+    id: string;
+    volume_id: string;
+    name?: string | null;
+    status: string;
+    created_at?: string | null;
+}
+interface VolumeFileEntry extends JsonMap {
+    path: string;
+    filename: string;
+    size: number;
+}
+interface VolumeFileDownloadResponse extends JsonMap {
+    path: string;
+    filename: string;
+    size: number;
+    content: Buffer;
+}
+interface VolumeFileUploadRequest extends JsonMap {
+    path: string;
+    overwrite?: boolean;
+    filePath?: string;
+    fileContent?: Buffer | string;
+    filename?: string;
+}
+interface VolumeFileListQuery {
+    prefix?: string;
+    recursive?: boolean;
+    limit?: number;
+}
+interface VMVolumeMountRequest extends JsonMap {
+    volume_id: string;
+    mount_path: string;
+    mode?: string;
+    checkpoint_id?: string | null;
+}
+interface VMMountedVolumeResponse extends JsonMap {
+    volume_id: string;
+    mount_path: string;
+    mode: string;
+    checkpoint_id?: string | null;
+    status: string;
+}
 interface ShareCreateRequest extends JsonMap {
     session_id?: string | null;
     vm_id?: string | null;
@@ -397,7 +461,10 @@ interface APIKeyCreateRequest extends JsonMap {
 interface APIKey extends JsonMap {
     id?: number;
     description?: string | null;
+    /** @deprecated Use key_prefix instead */
     prefix?: string;
+    key_prefix?: string;
+    full_key?: string;
     created_at?: string;
     expires_at?: string | null;
 }
@@ -451,6 +518,9 @@ declare class VMsManager {
     delete(vmId: string): Promise<JsonMap>;
     clone(vmId: string, payload?: VMCloneRequest, wait?: boolean): Promise<JsonMap>;
     snapshot(vmId: string, payload?: VMSnapshotRequest, wait?: boolean): Promise<JsonMap>;
+    mountVolume(vmId: string, payload: VMVolumeMountRequest, wait?: boolean): Promise<VMMountedVolumeResponse>;
+    listVolumes(vmId: string): Promise<VMMountedVolumeResponse[]>;
+    unmountVolume(vmId: string, volumeId: string, mountPath: string, wait?: boolean): Promise<JsonMap>;
 }
 
 declare class SnapshotsManager {
@@ -486,7 +556,7 @@ declare class CustomDomainsManager {
     delete(domainId: number): Promise<JsonMap>;
 }
 
-type ProxyMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS';
+type ProxyMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS' | 'HEAD';
 declare class ComputerUseManager {
     private httpClient;
     private local;
@@ -500,6 +570,12 @@ declare class ComputerUseManager {
     patch(sessionId: string, path: string, body?: any): Promise<any>;
     delete(sessionId: string, path: string, params?: Record<string, any>): Promise<any>;
     options(sessionId: string, path: string, params?: Record<string, any>): Promise<any>;
+    head(sessionId: string, path: string, params?: Record<string, any>): Promise<any>;
+    /**
+     * Get the VNC WebSocket URL for a computer-use session.
+     * Returns the URL to connect to; the actual connection requires a WebSocket client.
+     */
+    vncWebsockify(sessionId: string): Promise<JsonMap>;
 }
 
 declare class APIKeysManager {
@@ -541,6 +617,25 @@ declare class WebhooksManager {
     replayDelivery(deliveryId: string): Promise<JsonMap>;
 }
 
+declare class VolumesManager {
+    private httpClient;
+    private local;
+    constructor(httpClient: HTTPClient, local?: boolean);
+    private ensureCloud;
+    create(payload: VolumeCreateRequest): Promise<VolumeResponse>;
+    list(refreshUsage?: boolean): Promise<VolumeResponse[]>;
+    get(volumeId: string, refreshUsage?: boolean): Promise<VolumeResponse>;
+    update(volumeId: string, payload: VolumeUpdateRequest): Promise<VolumeResponse>;
+    delete(volumeId: string): Promise<JsonMap>;
+    createCheckpoint(volumeId: string, payload?: VolumeCheckpointCreateRequest): Promise<VolumeCheckpointResponse>;
+    listCheckpoints(volumeId: string): Promise<VolumeCheckpointResponse[]>;
+    deleteCheckpoint(volumeId: string, checkpointId: string): Promise<JsonMap>;
+    uploadFile(volumeId: string, payload: VolumeFileUploadRequest): Promise<VolumeFileEntry>;
+    downloadFile(volumeId: string, path: string): Promise<VolumeFileDownloadResponse>;
+    listFiles(volumeId: string, options?: VolumeFileListQuery): Promise<VolumeFileEntry[]>;
+    deleteFile(volumeId: string, targetPath: string): Promise<JsonMap>;
+}
+
 interface ExecuteOptions {
     language?: 'python' | 'bash';
     timeout?: number;
@@ -661,6 +756,7 @@ declare class InstaVM {
     readonly apiKeys: APIKeysManager;
     readonly audit: AuditManager;
     readonly webhooks: WebhooksManager;
+    readonly volumes: VolumesManager;
     readonly local: boolean;
     private readonly timeout;
     readonly memory_mb?: number;
@@ -715,6 +811,23 @@ declare class InstaVM {
      * @returns true if session is active, false otherwise
      */
     isSessionActive(sessionId?: string): Promise<boolean>;
+    /**
+     * Get the app URL for a session
+     *
+     * @param sessionId - Session ID (uses current session if not provided)
+     * @param port - Port to expose (1-65535, default: 80)
+     */
+    getSessionAppUrl(sessionId?: string, port?: number): Promise<Record<string, any>>;
+    /**
+     * List sandbox records with optional filtering
+     *
+     * @param options.metadata - JSON-serializable metadata filters
+     * @param options.limit - Maximum number of results (1-1000, default: 100)
+     */
+    listSandboxes(options?: {
+        metadata?: Record<string, any>;
+        limit?: number;
+    }): Promise<Record<string, any>[]>;
     /**
      * Get usage statistics for a session
      */
@@ -877,4 +990,4 @@ declare class UnsupportedOperationError extends InstaVMError {
     constructor(message?: string, options?: any);
 }
 
-export { type APIKey, type APIKeyCreateRequest, APIKeysManager, type ApiResponse, type AsyncExecutionResult, type AuditEventQuery, AuditManager, AuthenticationError, BrowserError, BrowserInteractionError, BrowserManager, BrowserNavigationError, BrowserSession, BrowserSessionError, type BrowserSessionInfo, type BrowserSessionOptions, BrowserTimeoutError, type ClickOptions, ComputerUseManager, type ComputerUseProxyOptions, type ContentAnchor, type CustomDomainCreateRequest, CustomDomainsManager, type DownloadOptions, type DownloadResult, type EgressPolicy, type EgressPolicyOptions, ElementNotFoundError, type ExecuteOptions, ExecutionError, type ExecutionResult, type ExtractContentOptions, type ExtractOptions, type ExtractedContent, type ExtractedElement, type FileUpload, type FillOptions, type HttpClientConfig, InstaVM, InstaVMError, type InstaVMOptions, type InteractiveElement, type JsonMap, type NavigateOptions, type NavigationResult, NetworkError, QuotaExceededError, RateLimitError, type RequestConfig, type RetryConfig, type SSHKey, type ScreenshotOptions, type ScrollOptions, SessionError, type ShareCreateRequest, type ShareUpdateRequest, SharesManager, type SnapshotBuildArgs, type SnapshotCreateRequest, type SnapshotQueryOptions, SnapshotsManager, type TypeOptions, UnsupportedOperationError, type UploadOptions, type UploadResult, type UsageStats, type VMCloneRequest, type VMCreateRequest, type VMSnapshotRequest, type VMUpdateRequest, VMsManager, type WaitCondition, type WebhookDeliveryQuery, type WebhookEndpointCreateRequest, type WebhookEndpointUpdateRequest, WebhooksManager };
+export { type APIKey, type APIKeyCreateRequest, APIKeysManager, type ApiResponse, type AsyncExecutionResult, type AuditEventQuery, AuditManager, AuthenticationError, BrowserError, BrowserInteractionError, BrowserManager, BrowserNavigationError, BrowserSession, BrowserSessionError, type BrowserSessionInfo, type BrowserSessionOptions, BrowserTimeoutError, type ClickOptions, ComputerUseManager, type ComputerUseProxyOptions, type ContentAnchor, type CustomDomainCreateRequest, CustomDomainsManager, type DownloadOptions, type DownloadResult, type EgressPolicy, type EgressPolicyOptions, ElementNotFoundError, type ExecuteOptions, ExecutionError, type ExecutionResult, type ExtractContentOptions, type ExtractOptions, type ExtractedContent, type ExtractedElement, type FileUpload, type FillOptions, type HttpClientConfig, InstaVM, InstaVMError, type InstaVMOptions, type InteractiveElement, type JsonMap, type NavigateOptions, type NavigationResult, NetworkError, QuotaExceededError, RateLimitError, type RequestConfig, type RetryConfig, type SSHKey, type ScreenshotOptions, type ScrollOptions, SessionError, type ShareCreateRequest, type ShareUpdateRequest, SharesManager, type SnapshotBuildArgs, type SnapshotCreateRequest, type SnapshotQueryOptions, SnapshotsManager, type TypeOptions, UnsupportedOperationError, type UploadOptions, type UploadResult, type UsageStats, type VMCloneRequest, type VMCreateRequest, type VMMountedVolumeResponse, type VMSnapshotRequest, type VMUpdateRequest, type VMVolumeMountRequest, VMsManager, type VolumeCheckpointCreateRequest, type VolumeCheckpointResponse, type VolumeCreateRequest, type VolumeFileDownloadResponse, type VolumeFileEntry, type VolumeFileListQuery, type VolumeFileUploadRequest, type VolumeResponse, type VolumeUpdateRequest, VolumesManager, type WaitCondition, type WebhookDeliveryQuery, type WebhookEndpointCreateRequest, type WebhookEndpointUpdateRequest, WebhooksManager };

package/dist/index.d.ts

@@ -15,7 +15,7 @@ interface HttpClientConfig {
     apiKey: string;
 }
 interface RequestConfig {
-    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS';
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS' | 'HEAD';
     url: string;
     headers?: Record<string, string>;
     data?: any;
@@ -336,6 +336,7 @@ interface VMCreateRequest extends JsonMap {
     share?: JsonMap | null;
     custom_domain?: JsonMap | null;
     image_variant?: string | null;
+    volumes?: VMVolumeMountRequest[] | null;
 }
 interface VMUpdateRequest extends JsonMap {
     memory_mb?: number | null;
@@ -370,6 +371,69 @@ interface SnapshotCreateRequest extends JsonMap {
 interface SnapshotQueryOptions {
     type?: 'user' | 'system';
 }
+interface VolumeCreateRequest extends JsonMap {
+    name: string;
+    quota_bytes: number;
+}
+interface VolumeUpdateRequest extends JsonMap {
+    name?: string | null;
+    quota_bytes?: number | null;
+}
+interface VolumeResponse extends JsonMap {
+    id: string;
+    name: string;
+    quota_bytes: number;
+    used_bytes: number;
+    status: string;
+    created_at?: string | null;
+    updated_at?: string | null;
+}
+interface VolumeCheckpointCreateRequest extends JsonMap {
+    name?: string | null;
+}
+interface VolumeCheckpointResponse extends JsonMap {
+    id: string;
+    volume_id: string;
+    name?: string | null;
+    status: string;
+    created_at?: string | null;
+}
+interface VolumeFileEntry extends JsonMap {
+    path: string;
+    filename: string;
+    size: number;
+}
+interface VolumeFileDownloadResponse extends JsonMap {
+    path: string;
+    filename: string;
+    size: number;
+    content: Buffer;
+}
+interface VolumeFileUploadRequest extends JsonMap {
+    path: string;
+    overwrite?: boolean;
+    filePath?: string;
+    fileContent?: Buffer | string;
+    filename?: string;
+}
+interface VolumeFileListQuery {
+    prefix?: string;
+    recursive?: boolean;
+    limit?: number;
+}
+interface VMVolumeMountRequest extends JsonMap {
+    volume_id: string;
+    mount_path: string;
+    mode?: string;
+    checkpoint_id?: string | null;
+}
+interface VMMountedVolumeResponse extends JsonMap {
+    volume_id: string;
+    mount_path: string;
+    mode: string;
+    checkpoint_id?: string | null;
+    status: string;
+}
 interface ShareCreateRequest extends JsonMap {
     session_id?: string | null;
     vm_id?: string | null;
@@ -397,7 +461,10 @@ interface APIKeyCreateRequest extends JsonMap {
 interface APIKey extends JsonMap {
     id?: number;
     description?: string | null;
+    /** @deprecated Use key_prefix instead */
     prefix?: string;
+    key_prefix?: string;
+    full_key?: string;
     created_at?: string;
     expires_at?: string | null;
 }
@@ -451,6 +518,9 @@ declare class VMsManager {
     delete(vmId: string): Promise<JsonMap>;
     clone(vmId: string, payload?: VMCloneRequest, wait?: boolean): Promise<JsonMap>;
     snapshot(vmId: string, payload?: VMSnapshotRequest, wait?: boolean): Promise<JsonMap>;
+    mountVolume(vmId: string, payload: VMVolumeMountRequest, wait?: boolean): Promise<VMMountedVolumeResponse>;
+    listVolumes(vmId: string): Promise<VMMountedVolumeResponse[]>;
+    unmountVolume(vmId: string, volumeId: string, mountPath: string, wait?: boolean): Promise<JsonMap>;
 }
 
 declare class SnapshotsManager {
@@ -486,7 +556,7 @@ declare class CustomDomainsManager {
     delete(domainId: number): Promise<JsonMap>;
 }
 
-type ProxyMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS';
+type ProxyMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS' | 'HEAD';
 declare class ComputerUseManager {
     private httpClient;
     private local;
@@ -500,6 +570,12 @@ declare class ComputerUseManager {
     patch(sessionId: string, path: string, body?: any): Promise<any>;
     delete(sessionId: string, path: string, params?: Record<string, any>): Promise<any>;
     options(sessionId: string, path: string, params?: Record<string, any>): Promise<any>;
+    head(sessionId: string, path: string, params?: Record<string, any>): Promise<any>;
+    /**
+     * Get the VNC WebSocket URL for a computer-use session.
+     * Returns the URL to connect to; the actual connection requires a WebSocket client.
+     */
+    vncWebsockify(sessionId: string): Promise<JsonMap>;
 }
 
 declare class APIKeysManager {
@@ -541,6 +617,25 @@ declare class WebhooksManager {
     replayDelivery(deliveryId: string): Promise<JsonMap>;
 }
 
+declare class VolumesManager {
+    private httpClient;
+    private local;
+    constructor(httpClient: HTTPClient, local?: boolean);
+    private ensureCloud;
+    create(payload: VolumeCreateRequest): Promise<VolumeResponse>;
+    list(refreshUsage?: boolean): Promise<VolumeResponse[]>;
+    get(volumeId: string, refreshUsage?: boolean): Promise<VolumeResponse>;
+    update(volumeId: string, payload: VolumeUpdateRequest): Promise<VolumeResponse>;
+    delete(volumeId: string): Promise<JsonMap>;
+    createCheckpoint(volumeId: string, payload?: VolumeCheckpointCreateRequest): Promise<VolumeCheckpointResponse>;
+    listCheckpoints(volumeId: string): Promise<VolumeCheckpointResponse[]>;
+    deleteCheckpoint(volumeId: string, checkpointId: string): Promise<JsonMap>;
+    uploadFile(volumeId: string, payload: VolumeFileUploadRequest): Promise<VolumeFileEntry>;
+    downloadFile(volumeId: string, path: string): Promise<VolumeFileDownloadResponse>;
+    listFiles(volumeId: string, options?: VolumeFileListQuery): Promise<VolumeFileEntry[]>;
+    deleteFile(volumeId: string, targetPath: string): Promise<JsonMap>;
+}
+
 interface ExecuteOptions {
     language?: 'python' | 'bash';
     timeout?: number;
@@ -661,6 +756,7 @@ declare class InstaVM {
     readonly apiKeys: APIKeysManager;
     readonly audit: AuditManager;
     readonly webhooks: WebhooksManager;
+    readonly volumes: VolumesManager;
     readonly local: boolean;
     private readonly timeout;
     readonly memory_mb?: number;
@@ -715,6 +811,23 @@ declare class InstaVM {
      * @returns true if session is active, false otherwise
      */
     isSessionActive(sessionId?: string): Promise<boolean>;
+    /**
+     * Get the app URL for a session
+     *
+     * @param sessionId - Session ID (uses current session if not provided)
+     * @param port - Port to expose (1-65535, default: 80)
+     */
+    getSessionAppUrl(sessionId?: string, port?: number): Promise<Record<string, any>>;
+    /**
+     * List sandbox records with optional filtering
+     *
+     * @param options.metadata - JSON-serializable metadata filters
+     * @param options.limit - Maximum number of results (1-1000, default: 100)
+     */
+    listSandboxes(options?: {
+        metadata?: Record<string, any>;
+        limit?: number;
+    }): Promise<Record<string, any>[]>;
     /**
      * Get usage statistics for a session
      */
@@ -877,4 +990,4 @@ declare class UnsupportedOperationError extends InstaVMError {
     constructor(message?: string, options?: any);
 }
 
-export { type APIKey, type APIKeyCreateRequest, APIKeysManager, type ApiResponse, type AsyncExecutionResult, type AuditEventQuery, AuditManager, AuthenticationError, BrowserError, BrowserInteractionError, BrowserManager, BrowserNavigationError, BrowserSession, BrowserSessionError, type BrowserSessionInfo, type BrowserSessionOptions, BrowserTimeoutError, type ClickOptions, ComputerUseManager, type ComputerUseProxyOptions, type ContentAnchor, type CustomDomainCreateRequest, CustomDomainsManager, type DownloadOptions, type DownloadResult, type EgressPolicy, type EgressPolicyOptions, ElementNotFoundError, type ExecuteOptions, ExecutionError, type ExecutionResult, type ExtractContentOptions, type ExtractOptions, type ExtractedContent, type ExtractedElement, type FileUpload, type FillOptions, type HttpClientConfig, InstaVM, InstaVMError, type InstaVMOptions, type InteractiveElement, type JsonMap, type NavigateOptions, type NavigationResult, NetworkError, QuotaExceededError, RateLimitError, type RequestConfig, type RetryConfig, type SSHKey, type ScreenshotOptions, type ScrollOptions, SessionError, type ShareCreateRequest, type ShareUpdateRequest, SharesManager, type SnapshotBuildArgs, type SnapshotCreateRequest, type SnapshotQueryOptions, SnapshotsManager, type TypeOptions, UnsupportedOperationError, type UploadOptions, type UploadResult, type UsageStats, type VMCloneRequest, type VMCreateRequest, type VMSnapshotRequest, type VMUpdateRequest, VMsManager, type WaitCondition, type WebhookDeliveryQuery, type WebhookEndpointCreateRequest, type WebhookEndpointUpdateRequest, WebhooksManager };
+export { type APIKey, type APIKeyCreateRequest, APIKeysManager, type ApiResponse, type AsyncExecutionResult, type AuditEventQuery, AuditManager, AuthenticationError, BrowserError, BrowserInteractionError, BrowserManager, BrowserNavigationError, BrowserSession, BrowserSessionError, type BrowserSessionInfo, type BrowserSessionOptions, BrowserTimeoutError, type ClickOptions, ComputerUseManager, type ComputerUseProxyOptions, type ContentAnchor, type CustomDomainCreateRequest, CustomDomainsManager, type DownloadOptions, type DownloadResult, type EgressPolicy, type EgressPolicyOptions, ElementNotFoundError, type ExecuteOptions, ExecutionError, type ExecutionResult, type ExtractContentOptions, type ExtractOptions, type ExtractedContent, type ExtractedElement, type FileUpload, type FillOptions, type HttpClientConfig, InstaVM, InstaVMError, type InstaVMOptions, type InteractiveElement, type JsonMap, type NavigateOptions, type NavigationResult, NetworkError, QuotaExceededError, RateLimitError, type RequestConfig, type RetryConfig, type SSHKey, type ScreenshotOptions, type ScrollOptions, SessionError, type ShareCreateRequest, type ShareUpdateRequest, SharesManager, type SnapshotBuildArgs, type SnapshotCreateRequest, type SnapshotQueryOptions, SnapshotsManager, type TypeOptions, UnsupportedOperationError, type UploadOptions, type UploadResult, type UsageStats, type VMCloneRequest, type VMCreateRequest, type VMMountedVolumeResponse, type VMSnapshotRequest, type VMUpdateRequest, type VMVolumeMountRequest, VMsManager, type VolumeCheckpointCreateRequest, type VolumeCheckpointResponse, type VolumeCreateRequest, type VolumeFileDownloadResponse, type VolumeFileEntry, type VolumeFileListQuery, type VolumeFileUploadRequest, type VolumeResponse, type VolumeUpdateRequest, VolumesManager, type WaitCondition, type WebhookDeliveryQuery, type WebhookEndpointCreateRequest, type WebhookEndpointUpdateRequest, WebhooksManager };