plato-sandbox-sdk 1.1.3 → 1.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plato-sandbox-sdk",
-  "version": "1.1.3",
+  "version": "1.1.4",
   "description": "TypeScript SDK for interacting with the Plato platform - manage environments, VMs, simulators, and more",
   "author": "Plato AI",
   "repository": {

package/src/flow/README.md

@@ -0,0 +1,384 @@
+# Flow Executor
+
+The Flow Executor provides a powerful way to define and execute browser automation flows using Playwright. This is particularly useful for testing simulator interactions in the Plato platform.
+
+## Installation
+
+First, install Playwright as a peer dependency:
+
+```bash
+npm install playwright
+# or
+yarn add playwright
+```
+
+## Basic Usage
+
+```typescript
+import { chromium } from 'playwright';
+import { FlowExecutor, Flow } from '@plato-ai/sdk';
+
+async function runFlow() {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+
+  const flow: Flow = {
+    name: 'login',
+    description: 'Login to the application',
+    steps: [
+      {
+        type: 'navigate',
+        url: 'https://example.com/login',
+        description: 'Navigate to login page'
+      },
+      {
+        type: 'fill',
+        selector: '#username',
+        value: 'testuser',
+        description: 'Fill username'
+      },
+      {
+        type: 'fill',
+        selector: '#password',
+        value: 'password123',
+        description: 'Fill password'
+      },
+      {
+        type: 'click',
+        selector: 'button[type="submit"]',
+        description: 'Click login button'
+      },
+      {
+        type: 'wait_for_url',
+        urlContains: '/dashboard',
+        description: 'Wait for redirect to dashboard'
+      },
+      {
+        type: 'verify',
+        verifyType: 'page_title',
+        title: 'Dashboard',
+        contains: true,
+        description: 'Verify we are on the dashboard'
+      }
+    ]
+  };
+
+  const executor = new FlowExecutor({
+    page,
+    flow,
+    screenshotsDir: './screenshots'
+  });
+
+  const success = await executor.executeFlow();
+  console.log(`Flow ${success ? 'succeeded' : 'failed'}`);
+
+  await browser.close();
+}
+
+runFlow();
+```
+
+## Flow Step Types
+
+### Navigation Steps
+
+#### `navigate`
+Navigate to a URL.
+
+```typescript
+{
+  type: 'navigate',
+  url: 'https://example.com',
+  description: 'Navigate to homepage'
+}
+```
+
+#### `wait_for_url`
+Wait for URL to contain specific text.
+
+```typescript
+{
+  type: 'wait_for_url',
+  urlContains: '/dashboard',
+  timeout: 5000
+}
+```
+
+### Interaction Steps
+
+#### `click`
+Click on an element.
+
+```typescript
+{
+  type: 'click',
+  selector: 'button.submit',
+  description: 'Click submit button'
+}
+```
+
+#### `fill`
+Fill an input field.
+
+```typescript
+{
+  type: 'fill',
+  selector: '#email',
+  value: 'user@example.com',
+  description: 'Fill email field'
+}
+```
+
+### Wait Steps
+
+#### `wait`
+Wait for a specified duration.
+
+```typescript
+{
+  type: 'wait',
+  duration: 2000, // milliseconds
+  description: 'Wait for animation'
+}
+```
+
+#### `wait_for_selector`
+Wait for a selector to be present.
+
+```typescript
+{
+  type: 'wait_for_selector',
+  selector: '.loading-spinner',
+  timeout: 10000
+}
+```
+
+### Verification Steps
+
+#### `verify`
+Generic verification with multiple subtypes:
+
+**Element Exists**
+```typescript
+{
+  type: 'verify',
+  verifyType: 'element_exists',
+  selector: '.success-message'
+}
+```
+
+**Element Visible**
+```typescript
+{
+  type: 'verify',
+  verifyType: 'element_visible',
+  selector: '.modal'
+}
+```
+
+**Element Text**
+```typescript
+{
+  type: 'verify',
+  verifyType: 'element_text',
+  selector: '.welcome-message',
+  text: 'Welcome back',
+  contains: true
+}
+```
+
+**Element Count**
+```typescript
+{
+  type: 'verify',
+  verifyType: 'element_count',
+  selector: '.list-item',
+  count: 5
+}
+```
+
+**Page Title**
+```typescript
+{
+  type: 'verify',
+  verifyType: 'page_title',
+  title: 'Dashboard',
+  contains: true
+}
+```
+
+#### `verify_text`
+Verify text appears anywhere on the page.
+
+```typescript
+{
+  type: 'verify_text',
+  text: 'Success!',
+  shouldExist: true
+}
+```
+
+#### `verify_url`
+Verify the current URL.
+
+```typescript
+{
+  type: 'verify_url',
+  url: '/dashboard',
+  contains: true
+}
+```
+
+#### `verify_no_errors`
+Verify no error indicators are present.
+
+```typescript
+{
+  type: 'verify_no_errors',
+  errorSelectors: ['.error', '.alert-danger', '[role="alert"]']
+}
+```
+
+#### `check_element`
+Check if an element exists (non-blocking).
+
+```typescript
+{
+  type: 'check_element',
+  selector: '.optional-banner',
+  shouldExist: false
+}
+```
+
+### Utility Steps
+
+#### `screenshot`
+Take a screenshot for visual verification.
+
+```typescript
+{
+  type: 'screenshot',
+  filename: 'dashboard.png',
+  fullPage: true,
+  description: 'Capture dashboard state'
+}
+```
+
+## Custom Logger
+
+You can provide a custom logger implementation:
+
+```typescript
+import { FlowLogger } from '@plato-ai/sdk';
+
+class CustomLogger implements FlowLogger {
+  info(message: string): void {
+    // Custom info logging
+  }
+
+  error(message: string): void {
+    // Custom error logging
+  }
+
+  warn(message: string): void {
+    // Custom warning logging
+  }
+
+  debug(message: string): void {
+    // Custom debug logging
+  }
+}
+
+const executor = new FlowExecutor({
+  page,
+  flow,
+  logger: new CustomLogger()
+});
+```
+
+## Complete Example with Error Handling
+
+```typescript
+import { chromium } from 'playwright';
+import { FlowExecutor, Flow } from '@plato-ai/sdk';
+
+async function runCompleteFlow() {
+  let browser;
+  try {
+    browser = await chromium.launch({ headless: false });
+    const page = await browser.newPage();
+
+    const flow: Flow = {
+      name: 'e2e-test',
+      description: 'End-to-end test flow',
+      steps: [
+        {
+          type: 'navigate',
+          url: 'https://example.com',
+          description: 'Navigate to homepage'
+        },
+        {
+          type: 'screenshot',
+          filename: 'homepage.png',
+          fullPage: true,
+          description: 'Capture homepage'
+        },
+        {
+          type: 'verify',
+          verifyType: 'page_title',
+          title: 'Example Domain',
+          contains: false,
+          description: 'Verify page title'
+        },
+        {
+          type: 'verify_no_errors',
+          description: 'Ensure no errors on page'
+        }
+      ]
+    };
+
+    const executor = new FlowExecutor({
+      page,
+      flow,
+      screenshotsDir: './test-screenshots'
+    });
+
+    const success = await executor.executeFlow();
+    
+    if (success) {
+      console.log('✅ Flow completed successfully');
+    } else {
+      console.error('❌ Flow failed');
+      process.exit(1);
+    }
+  } catch (error) {
+    console.error('Fatal error:', error);
+    process.exit(1);
+  } finally {
+    if (browser) {
+      await browser.close();
+    }
+  }
+}
+
+runCompleteFlow();
+```
+
+## Features
+
+- ✅ Type-safe flow definitions with TypeScript
+- ✅ Comprehensive step types for common browser interactions
+- ✅ Built-in verification and validation steps
+- ✅ Automatic screenshot capture with timestamps
+- ✅ Customizable logging
+- ✅ Relative URL resolution
+- ✅ Password masking in logs
+- ✅ Detailed error messages
+
+## Notes
+
+- All timeouts are in milliseconds (default: 10000ms)
+- Screenshots are automatically timestamped for chronological sorting
+- Passwords in selectors containing "password" are automatically masked in logs
+- The flow executor is protected from OpenAPI generator overwrites
+

package/dist/apis/EnvApi.d.ts

@@ -1,308 +0,0 @@
-/**
- * Plato API
- * API for Plato platform - SDK routes only
- *
- * The version of the OpenAPI document: 1.0.0
- *
- *
- * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
- * https://openapi-generator.tech
- * Do not edit the class manually.
- */
-import * as runtime from '../runtime';
-import type { CreateSimulatorRequest, EvaluateRequest, JobStatusResponse, Log, MakeEnvRequest2, ResetEnvRequest, ScoreRequest, WorkerReadyResponse } from '../models/index';
-export interface BackupEnvironmentRequest {
-    jobGroupId: string;
-    authorization?: string;
-    xInternalService?: string;
-}
-export interface CloseEnvironmentRequest {
-    jobGroupId: string;
-    authorization?: string;
-    xInternalService?: string;
-}
-export interface CreateSimulatorOperationRequest {
-    createSimulatorRequest: CreateSimulatorRequest;
-    authorization?: string;
-    xInternalService?: string;
-}
-export interface EvaluateSessionRequest {
-    sessionId: string;
-    authorization?: string;
-    xInternalService?: string;
-    evaluateRequest?: EvaluateRequest;
-}
-export interface GetActiveSessionRequest {
-    jobGroupId: string;
-    authorization?: string;
-    xInternalService?: string;
-}
-export interface GetCdpUrlRequest {
-    jobGroupId: string;
-    authorization?: string;
-    xInternalService?: string;
-}
-export interface GetEnvironmentStateRequest {
-    jobGroupId: string;
-    authorization?: string;
-    xInternalService?: string;
-}
-export interface GetJobStatusRequest {
-    jobGroupId: string;
-    authorization?: string;
-    xInternalService?: string;
-}
-export interface GetProxyUrlRequest {
-    jobGroupId: string;
-    authorization?: string;
-    xInternalService?: string;
-}
-export interface GetSimulatorsRequest {
-    authorization?: string;
-    xInternalService?: string;
-}
-export interface GetWorkerReadyApiEnvJobIdWorkerReadyGetRequest {
-    jobId: string;
-    timeout?: number;
-    authorization?: string;
-    xInternalService?: string;
-}
-export interface LogStateMutationApiEnvSessionIdLogPostRequest {
-    sessionId: string;
-    log: Log;
-}
-export interface MakeEnvironmentRequest {
-    makeEnvRequest2: MakeEnvRequest2;
-    authorization?: string;
-    xInternalService?: string;
-}
-export interface ResetEnvironmentRequest {
-    jobGroupId: string;
-    resetEnvRequest: ResetEnvRequest;
-    authorization?: string;
-    xInternalService?: string;
-}
-export interface ScoreEnvApiEnvSessionSessionIdScorePostRequest {
-    sessionId: string;
-    scoreRequest: ScoreRequest;
-    authorization?: string;
-    xInternalService?: string;
-}
-export interface SendHeartbeatRequest {
-    jobId: string;
-    authorization?: string;
-    xInternalService?: string;
-}
-/**
- *
- */
-export declare class EnvApi extends runtime.BaseAPI {
-    /**
-     * Create a backup of the environment.
-     * Backup Env
-     */
-    backupEnvironmentRaw(requestParameters: BackupEnvironmentRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<{
-        [key: string]: any;
-    }>>;
-    /**
-     * Create a backup of the environment.
-     * Backup Env
-     */
-    backupEnvironment(requestParameters: BackupEnvironmentRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<{
-        [key: string]: any;
-    }>;
-    /**
-     * Close Env
-     */
-    closeEnvironmentRaw(requestParameters: CloseEnvironmentRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<{
-        [key: string]: any;
-    }>>;
-    /**
-     * Close Env
-     */
-    closeEnvironment(requestParameters: CloseEnvironmentRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<{
-        [key: string]: any;
-    }>;
-    /**
-     * Create a new simulator.
-     * Create Simulator
-     */
-    createSimulatorRaw(requestParameters: CreateSimulatorOperationRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<{
-        [key: string]: any;
-    }>>;
-    /**
-     * Create a new simulator.
-     * Create Simulator
-     */
-    createSimulator(requestParameters: CreateSimulatorOperationRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<{
-        [key: string]: any;
-    }>;
-    /**
-     * Evaluate the session.
-     * Evaluate Session
-     */
-    evaluateSessionRaw(requestParameters: EvaluateSessionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<{
-        [key: string]: any;
-    }>>;
-    /**
-     * Evaluate the session.
-     * Evaluate Session
-     */
-    evaluateSession(requestParameters: EvaluateSessionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<{
-        [key: string]: any;
-    }>;
-    /**
-     * Get the active session for a job group.
-     * Get Active Session
-     */
-    getActiveSessionRaw(requestParameters: GetActiveSessionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<{
-        [key: string]: any;
-    }>>;
-    /**
-     * Get the active session for a job group.
-     * Get Active Session
-     */
-    getActiveSession(requestParameters: GetActiveSessionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<{
-        [key: string]: any;
-    }>;
-    /**
-     * Get the CDP URL for the environment.
-     * Get Cdp Url
-     */
-    getCdpUrlRaw(requestParameters: GetCdpUrlRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<{
-        [key: string]: any;
-    }>>;
-    /**
-     * Get the CDP URL for the environment.
-     * Get Cdp Url
-     */
-    getCdpUrl(requestParameters: GetCdpUrlRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<{
-        [key: string]: any;
-    }>;
-    /**
-     * Get Env State
-     */
-    getEnvironmentStateRaw(requestParameters: GetEnvironmentStateRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<{
-        [key: string]: any;
-    }>>;
-    /**
-     * Get Env State
-     */
-    getEnvironmentState(requestParameters: GetEnvironmentStateRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<{
-        [key: string]: any;
-    }>;
-    /**
-     * Get Job Status
-     */
-    getJobStatusRaw(requestParameters: GetJobStatusRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<JobStatusResponse>>;
-    /**
-     * Get Job Status
-     */
-    getJobStatus(requestParameters: GetJobStatusRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<JobStatusResponse>;
-    /**
-     * Get the public URL for the environment.
-     * Get Proxy Url
-     */
-    getProxyUrlRaw(requestParameters: GetProxyUrlRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<{
-        [key: string]: any;
-    }>>;
-    /**
-     * Get the public URL for the environment.
-     * Get Proxy Url
-     */
-    getProxyUrl(requestParameters: GetProxyUrlRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<{
-        [key: string]: any;
-    }>;
-    /**
-     * Get all simulators with optimized queries.
-     * Get Simulators
-     */
-    getSimulatorsRaw(requestParameters: GetSimulatorsRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<Array<{
-        [key: string]: any;
-    }>>>;
-    /**
-     * Get all simulators with optimized queries.
-     * Get Simulators
-     */
-    getSimulators(requestParameters?: GetSimulatorsRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<Array<{
-        [key: string]: any;
-    }>>;
-    /**
-     * Check if the workers for this job group are ready and healthy.  Uses the persistent job ready notification service to wait for job readiness. Falls back to checking Redis if notification not received (in case we missed it). Raises 500 if job not ready after all checks.
-     * Get Worker Ready
-     */
-    getWorkerReadyApiEnvJobIdWorkerReadyGetRaw(requestParameters: GetWorkerReadyApiEnvJobIdWorkerReadyGetRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<WorkerReadyResponse>>;
-    /**
-     * Check if the workers for this job group are ready and healthy.  Uses the persistent job ready notification service to wait for job readiness. Falls back to checking Redis if notification not received (in case we missed it). Raises 500 if job not ready after all checks.
-     * Get Worker Ready
-     */
-    getWorkerReadyApiEnvJobIdWorkerReadyGet(requestParameters: GetWorkerReadyApiEnvJobIdWorkerReadyGetRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<WorkerReadyResponse>;
-    /**
-     * Log a state mutation or batch of mutations.
-     * Log State Mutation
-     */
-    logStateMutationApiEnvSessionIdLogPostRaw(requestParameters: LogStateMutationApiEnvSessionIdLogPostRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<{
-        [key: string]: any;
-    }>>;
-    /**
-     * Log a state mutation or batch of mutations.
-     * Log State Mutation
-     */
-    logStateMutationApiEnvSessionIdLogPost(requestParameters: LogStateMutationApiEnvSessionIdLogPostRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<{
-        [key: string]: any;
-    }>;
-    /**
-     * Make Env
-     */
-    makeEnvironmentRaw(requestParameters: MakeEnvironmentRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<{
-        [key: string]: any;
-    }>>;
-    /**
-     * Make Env
-     */
-    makeEnvironment(requestParameters: MakeEnvironmentRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<{
-        [key: string]: any;
-    }>;
-    /**
-     * Reset the environment with an optional task.
-     * Reset Env
-     */
-    resetEnvironmentRaw(requestParameters: ResetEnvironmentRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<{
-        [key: string]: any;
-    }>>;
-    /**
-     * Reset the environment with an optional task.
-     * Reset Env
-     */
-    resetEnvironment(requestParameters: ResetEnvironmentRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<{
-        [key: string]: any;
-    }>;
-    /**
-     * Score the environment.
-     * Score Env
-     */
-    scoreEnvApiEnvSessionSessionIdScorePostRaw(requestParameters: ScoreEnvApiEnvSessionSessionIdScorePostRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<{
-        [key: string]: any;
-    }>>;
-    /**
-     * Score the environment.
-     * Score Env
-     */
-    scoreEnvApiEnvSessionSessionIdScorePost(requestParameters: ScoreEnvApiEnvSessionSessionIdScorePostRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<{
-        [key: string]: any;
-    }>;
-    /**
-     * Send a heartbeat to keep the environment session alive.
-     * Send Heartbeat
-     */
-    sendHeartbeatRaw(requestParameters: SendHeartbeatRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<{
-        [key: string]: any;
-    }>>;
-    /**
-     * Send a heartbeat to keep the environment session alive.
-     * Send Heartbeat
-     */
-    sendHeartbeat(requestParameters: SendHeartbeatRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<{
-        [key: string]: any;
-    }>;
-}