instavm 0.8.1 → 0.11.0

package/dist/index.d.mts

@@ -15,7 +15,7 @@ interface HttpClientConfig {
     apiKey: string;
 }
 interface RequestConfig {
-    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS';
     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,15 +322,237 @@ 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;
+}
+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 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;
+    prefix?: 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>;
+}
+
+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';
+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>;
+}
+
+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>;
+}
+
 interface ExecuteOptions {
     language?: 'python' | 'bash';
     timeout?: number;
     sessionId?: string;
 }
 interface ExecutionResult {
-    output: string;
+    stdout: string;
+    stderr: string;
     success: boolean;
-    executionTime: number;
+    executionTime?: number;
+    cpuTime?: number;
+    createdAt?: string;
     sessionId?: string;
     error?: string;
 }
@@ -331,6 +565,13 @@ interface AsyncExecutionResult {
     sessionId?: string;
     error?: string;
 }
+interface TaskResult {
+    stdout: string;
+    stderr: string;
+    executionTime?: number;
+    cpuTime?: number;
+    createdAt?: string;
+}
 interface FileUpload {
     name: string;
     content: Buffer | string;
@@ -362,6 +603,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;
     /**
@@ -373,6 +637,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
@@ -381,8 +653,21 @@ 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 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
@@ -401,6 +686,16 @@ declare class InstaVM {
      * Execute code asynchronously
      */
     executeAsync(command: string, options?: ExecuteOptions): Promise<AsyncExecutionResult>;
+    /**
+     * Poll for async task result
+     *
+     * @param taskId - The task ID from executeAsync
+     * @param pollInterval - Seconds between polls (default: 1)
+     * @param timeout - Maximum seconds to wait (default: 60)
+     * @returns Task result with stdout, stderr, execution time, etc.
+     * @throws Error if task doesn't complete within timeout
+     */
+    getTaskResult(taskId: string, pollInterval?: number, timeout?: number): Promise<TaskResult>;
     /**
      * Upload files to the execution environment
      */
@@ -414,6 +709,12 @@ declare class InstaVM {
      * Note: Sessions auto-expire on the server side. This just clears local state.
      */
     closeSession(sessionId?: string): Promise<void>;
+    /**
+     * Check if current session is still active by checking VM status
+     *
+     * @returns true if session is active, false otherwise
+     */
+    isSessionActive(sessionId?: string): Promise<boolean>;
     /**
      * Get usage statistics for a session
      */
@@ -426,6 +727,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
      */
@@ -530,4 +877,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 VMSnapshotRequest, type VMUpdateRequest, VMsManager, type WaitCondition, type WebhookDeliveryQuery, type WebhookEndpointCreateRequest, type WebhookEndpointUpdateRequest, WebhooksManager };