instavm 0.8.3 → 0.13.0

package/dist/index.d.ts

@@ -15,7 +15,7 @@ interface HttpClientConfig {
     apiKey: string;
 }
 interface RequestConfig {
-    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS' | 'HEAD';
     url: string;
     headers?: Record<string, string>;
     data?: any;
@@ -65,6 +65,18 @@ declare class HTTPClient {
      * DELETE request
      */
     delete<T = any>(url: string, headers?: Record<string, string>): Promise<T>;
+    /**
+     * PUT request
+     */
+    put<T = any>(url: string, data?: any, headers?: Record<string, string>): Promise<T>;
+    /**
+     * PATCH request
+     */
+    patch<T = any>(url: string, data?: any, headers?: Record<string, string>): Promise<T>;
+    /**
+     * OPTIONS request
+     */
+    options<T = any>(url: string, headers?: Record<string, string>, params?: Record<string, any>): Promise<T>;
     /**
      * POST request that returns raw binary data (for file downloads)
      */
@@ -310,6 +322,320 @@ declare class BrowserManager {
     dispose(): Promise<void>;
 }
 
+type JsonMap = Record<string, any>;
+interface VMCreateRequest extends JsonMap {
+    session_id?: string | null;
+    vm_lifetime_seconds?: number | null;
+    memory_mb?: number | null;
+    vcpu_count?: number | null;
+    metadata?: JsonMap | null;
+    egress_policy?: JsonMap | null;
+    snapshot_id?: string | null;
+    snapshot_on_terminate?: boolean | null;
+    snapshot_name?: string | null;
+    share?: JsonMap | null;
+    custom_domain?: JsonMap | null;
+    image_variant?: string | null;
+    volumes?: VMVolumeMountRequest[] | null;
+}
+interface VMUpdateRequest extends JsonMap {
+    memory_mb?: number | null;
+    egress_policy?: JsonMap | null;
+    snapshot_on_terminate?: boolean | null;
+    snapshot_name?: string | null;
+}
+interface VMCloneRequest extends JsonMap {
+    snapshot_name?: string | null;
+}
+interface VMSnapshotRequest extends JsonMap {
+    name?: string | null;
+}
+interface SnapshotBuildArgs extends JsonMap {
+    extra_apt_packages?: string | null;
+    extra_pip_packages?: string | null;
+    extra_npm_packages?: string | null;
+    git_clone_url?: string | null;
+    git_clone_branch?: string | null;
+    disk_size_gb?: number | null;
+    envs?: Record<string, string> | null;
+    post_build_cmd?: string | null;
+}
+interface SnapshotCreateRequest extends JsonMap {
+    oci_image: string;
+    name?: string | null;
+    vcpu_count?: number;
+    memory_mb?: number;
+    build_args?: SnapshotBuildArgs | null;
+    type?: 'user' | 'system';
+}
+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;
+    port: number;
+    is_public?: boolean;
+}
+interface ShareUpdateRequest extends JsonMap {
+    is_public?: boolean | null;
+    revoke?: boolean | null;
+}
+interface CustomDomainCreateRequest extends JsonMap {
+    domain: string;
+    share_id: string;
+    dns_provider: string;
+    dns_credentials?: Record<string, string> | null;
+}
+interface ComputerUseProxyOptions {
+    params?: Record<string, any>;
+    body?: any;
+}
+interface APIKeyCreateRequest extends JsonMap {
+    description?: string | null;
+    expires_at?: string | null;
+}
+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;
+}
+interface AuditEventQuery {
+    event_group?: string;
+    event_type?: string;
+    status?: string;
+    user_id?: number;
+    vm_id?: string;
+    session_id?: string;
+    cursor?: string;
+    limit?: number;
+}
+interface WebhookEndpointCreateRequest extends JsonMap {
+    url: string;
+    description?: string | null;
+    event_patterns?: string[] | null;
+    timeout_seconds?: number;
+    max_retries?: number;
+}
+interface WebhookEndpointUpdateRequest extends JsonMap {
+    url?: string | null;
+    description?: string | null;
+    enabled?: boolean | null;
+    event_patterns?: string[] | null;
+    timeout_seconds?: number | null;
+    max_retries?: number | null;
+}
+interface WebhookDeliveryQuery {
+    endpoint_id?: string;
+    status?: string;
+    event_type?: string;
+    cursor?: string;
+    limit?: number;
+}
+
+declare class VMsManager {
+    private httpClient;
+    private local;
+    constructor(httpClient: HTTPClient, local?: boolean);
+    private ensureCloud;
+    create(payload?: VMCreateRequest, wait?: boolean): Promise<JsonMap>;
+    list(): Promise<JsonMap[]>;
+    listAll(): Promise<JsonMap[]>;
+    /**
+     * Calls GET /v1/vms/ (trailing slash), a distinct route from GET /v1/vms.
+     */
+    listAllRecords(): Promise<JsonMap[]>;
+    get(itemId: string | number): Promise<JsonMap>;
+    update(vmId: string, payload?: VMUpdateRequest): Promise<JsonMap>;
+    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 {
+    private httpClient;
+    private local;
+    constructor(httpClient: HTTPClient, local?: boolean);
+    private ensureCloud;
+    create(payload: SnapshotCreateRequest): Promise<JsonMap>;
+    list(options?: SnapshotQueryOptions): Promise<JsonMap[]>;
+    get(snapshotId: string): Promise<JsonMap>;
+    delete(snapshotId: string): Promise<JsonMap>;
+}
+
+declare class SharesManager {
+    private httpClient;
+    private local;
+    private getSessionId;
+    constructor(httpClient: HTTPClient, local?: boolean, getSessionId?: () => string | null);
+    private ensureCloud;
+    create(payload: ShareCreateRequest): Promise<JsonMap>;
+    update(shareId: string, payload: ShareUpdateRequest): Promise<JsonMap>;
+}
+
+declare class CustomDomainsManager {
+    private httpClient;
+    private local;
+    constructor(httpClient: HTTPClient, local?: boolean);
+    private ensureCloud;
+    create(payload: CustomDomainCreateRequest): Promise<JsonMap>;
+    list(): Promise<JsonMap[]>;
+    health(domainId: number): Promise<JsonMap>;
+    verify(domainId: number): Promise<JsonMap>;
+    delete(domainId: number): Promise<JsonMap>;
+}
+
+type ProxyMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS' | 'HEAD';
+declare class ComputerUseManager {
+    private httpClient;
+    private local;
+    constructor(httpClient: HTTPClient, local?: boolean);
+    private ensureCloud;
+    viewerUrl(sessionId: string): Promise<JsonMap>;
+    proxy(sessionId: string, path: string, method?: ProxyMethod, options?: ComputerUseProxyOptions): Promise<any>;
+    get(sessionId: string, path: string, params?: Record<string, any>): Promise<any>;
+    post(sessionId: string, path: string, body?: any): Promise<any>;
+    put(sessionId: string, path: string, body?: any): Promise<any>;
+    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 {
+    private httpClient;
+    private local;
+    constructor(httpClient: HTTPClient, local?: boolean);
+    private ensureCloud;
+    create(payload?: APIKeyCreateRequest): Promise<APIKey>;
+    list(): Promise<APIKey[]>;
+    get(itemId: number): Promise<APIKey>;
+    update(itemId: number, payload: APIKeyCreateRequest): Promise<APIKey>;
+    delete(itemId: number): Promise<JsonMap>;
+}
+
+declare class AuditManager {
+    private httpClient;
+    private local;
+    constructor(httpClient: HTTPClient, local?: boolean);
+    private ensureCloud;
+    catalog(): Promise<JsonMap>;
+    events(query?: AuditEventQuery): Promise<JsonMap>;
+    getEvent(eventId: string): Promise<JsonMap>;
+}
+
+declare class WebhooksManager {
+    private httpClient;
+    private local;
+    constructor(httpClient: HTTPClient, local?: boolean);
+    private ensureCloud;
+    createEndpoint(payload: WebhookEndpointCreateRequest): Promise<JsonMap>;
+    listEndpoints(): Promise<JsonMap[]>;
+    getEndpoint(endpointId: string): Promise<JsonMap>;
+    updateEndpoint(endpointId: string, payload: WebhookEndpointUpdateRequest): Promise<JsonMap>;
+    deleteEndpoint(endpointId: string): Promise<JsonMap>;
+    rotateSecret(endpointId: string): Promise<JsonMap>;
+    sendTestEvent(endpointId: string): Promise<JsonMap>;
+    verifyEndpoint(endpointId: string): Promise<JsonMap>;
+    listDeliveries(query?: WebhookDeliveryQuery): Promise<JsonMap>;
+    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;
@@ -372,6 +698,29 @@ interface DownloadResult {
     size: number;
 }
 
+interface EgressPolicy {
+    allowPackageManagers: boolean;
+    allowHttp: boolean;
+    allowHttps: boolean;
+    allowedDomains: string[];
+    allowedCidrs: string[];
+}
+interface EgressPolicyOptions {
+    allowPackageManagers?: boolean;
+    allowHttp?: boolean;
+    allowHttps?: boolean;
+    allowedDomains?: string[];
+    allowedCidrs?: string[];
+}
+
+interface SSHKey {
+    id: number;
+    fingerprint: string;
+    keyType: string;
+    comment: string | null;
+    createdAt: string;
+}
+
 interface InstaVMOptions {
     baseURL?: string;
     /**
@@ -383,6 +732,14 @@ interface InstaVMOptions {
     retryDelay?: number;
     local?: boolean;
     localURL?: string;
+    /** VM memory in megabytes (optional). Range: 128-8192 MB */
+    memory_mb?: number;
+    /** VM vCPU count (optional). Valid values: 1, 2, 4, 6, 8 */
+    cpu_count?: number;
+    /** Optional user-defined metadata for filtering */
+    metadata?: Record<string, any>;
+    /** Optional environment variables to set in the VM */
+    env?: Record<string, any>;
 }
 /**
  * Main InstaVM client class
@@ -391,8 +748,22 @@ declare class InstaVM {
     private httpClient;
     private _sessionId;
     readonly browser: BrowserManager;
+    readonly vms: VMsManager;
+    readonly snapshots: SnapshotsManager;
+    readonly shares: SharesManager;
+    readonly customDomains: CustomDomainsManager;
+    readonly computerUse: ComputerUseManager;
+    readonly apiKeys: APIKeysManager;
+    readonly audit: AuditManager;
+    readonly webhooks: WebhooksManager;
+    readonly volumes: VolumesManager;
     readonly local: boolean;
     private readonly timeout;
+    readonly memory_mb?: number;
+    readonly cpu_count?: number;
+    readonly metadata?: Record<string, any>;
+    readonly env?: Record<string, any>;
+    private _vmUsed;
     constructor(apiKey: string, options?: InstaVMOptions);
     /**
      * Ensure operation is not called in local mode
@@ -440,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
      */
@@ -452,6 +840,52 @@ declare class InstaVM {
      * Get the current session ID
      */
     get sessionId(): string | null;
+    /**
+     * Kill the VM associated with a session
+     *
+     * @param sessionId - The session UUID whose VM should be killed. If not provided, uses current sessionId
+     * @returns Result containing success message and killed VM ID
+     */
+    kill(sessionId?: string): Promise<{
+        success: boolean;
+        killed: string;
+    }>;
+    /**
+     * Set egress policy for a session
+     */
+    setSessionEgress(options?: EgressPolicyOptions, sessionId?: string): Promise<{
+        status: string;
+        sessionId: string;
+    }>;
+    /**
+     * Get egress policy for a session
+     */
+    getSessionEgress(sessionId?: string): Promise<EgressPolicy>;
+    /**
+     * Set egress policy for a specific VM
+     */
+    setVmEgress(vmId: string, options?: EgressPolicyOptions): Promise<{
+        status: string;
+        vmId: string;
+    }>;
+    /**
+     * Get egress policy for a specific VM
+     */
+    getVmEgress(vmId: string): Promise<EgressPolicy>;
+    /**
+     * Add an SSH public key
+     */
+    addSshKey(publicKey: string): Promise<SSHKey>;
+    /**
+     * List all active SSH keys
+     */
+    listSshKeys(): Promise<SSHKey[]>;
+    /**
+     * Delete an SSH key by ID
+     */
+    deleteSshKey(keyId: number): Promise<{
+        status: string;
+    }>;
     /**
      * Clean up resources
      */
@@ -556,4 +990,4 @@ declare class UnsupportedOperationError extends InstaVMError {
     constructor(message?: string, options?: any);
 }
 
-export { type ApiResponse, type AsyncExecutionResult, AuthenticationError, BrowserError, BrowserInteractionError, BrowserManager, BrowserNavigationError, BrowserSession, BrowserSessionError, type BrowserSessionInfo, type BrowserSessionOptions, BrowserTimeoutError, type ClickOptions, type ContentAnchor, type DownloadOptions, type DownloadResult, 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 NavigateOptions, type NavigationResult, NetworkError, QuotaExceededError, RateLimitError, type RequestConfig, type RetryConfig, type ScreenshotOptions, type ScrollOptions, SessionError, type TypeOptions, UnsupportedOperationError, type UploadOptions, type UploadResult, type UsageStats, type WaitCondition };
+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 };