@olib-ai/owl-browser-sdk 2.0.9 → 2.1.0

package/README.md

@@ -125,7 +125,9 @@ await browser.findElement({ context_id: ctx, description: 'login button' });
 
 ## Flow Execution
 
-Execute complex automation flows with variable resolution and expectations:
+Execute JSON-described automation flows with declarative assertions,
+variable resolution, conditional branching, loops, retries, and
+notifications.
 
 ```typescript
 import { OwlBrowser, FlowExecutor } from '@olib-ai/owl-browser-sdk';
@@ -136,7 +138,6 @@ await browser.connect();
 const ctx = await browser.createContext();
 const executor = new FlowExecutor(browser, ctx.context_id);
 
-// Load flow from JSON file
 const flow = FlowExecutor.loadFlow('test-flows/navigation.json');
 const result = await executor.execute(flow);
 
@@ -147,107 +148,12 @@ if (result.success) {
 }
 ```
 
-### Flow JSON Format
-
-```json
-{
-  "name": "Login Flow",
-  "description": "Automates login process",
-  "steps": [
-    {
-      "type": "browser_navigate",
-      "url": "https://example.com/login"
-    },
-    {
-      "type": "browser_type",
-      "selector": "#email",
-      "text": "user@example.com"
-    },
-    {
-      "type": "browser_type",
-      "selector": "#password",
-      "text": "secret123"
-    },
-    {
-      "type": "browser_click",
-      "selector": "#submit",
-      "expected": {
-        "notEmpty": true
-      }
-    },
-    {
-      "type": "browser_wait_for_selector",
-      "selector": ".dashboard",
-      "expected": {
-        "equals": true,
-        "field": "found"
-      }
-    }
-  ]
-}
-```
-
-### Variable Resolution
-
-Use `${prev}` to reference previous step results:
-
-```json
-{
-  "steps": [
-    {
-      "type": "browser_evaluate",
-      "script": "document.querySelector('.user-id').textContent"
-    },
-    {
-      "type": "browser_navigate",
-      "url": "https://example.com/users/${prev}"
-    }
-  ]
-}
-```
-
-Supported syntax:
-- `${prev}` - Entire previous result
-- `${prev.field}` - Field in previous result
-- `${prev[0]}` - Array element
-- `${prev[0].id}` - Nested access
-
-### Expectations
-
-Validate step results:
-
-```typescript
-const expectation = {
-  equals: 'expected value',     // Exact match
-  contains: 'substring',        // String contains
-  length: 5,                    // Array/string length
-  greaterThan: 10,              // Numeric comparison
-  lessThan: 100,                // Numeric comparison
-  notEmpty: true,               // Not null/empty
-  matches: '^[A-Z]+$',          // Regex pattern
-  field: 'data.items'           // Nested field to check
-};
-```
-
-### Conditional Branching
-
-```json
-{
-  "type": "condition",
-  "condition": {
-    "source": "previous",
-    "operator": "equals",
-    "field": "success",
-    "value": true
-  },
-  "onTrue": [
-    { "type": "browser_click", "selector": "#continue" }
-  ],
-  "onFalse": [
-    { "type": "browser_screenshot" }
-  ]
-}
-```
+For the full reference — flow file schema, every step-level field
+(`expected`, `condition`, `for_each`, `capture`, `optional`, `timeoutMs`,
+`retry`), variable scopes (`${prev}`, `${vars}`, `${params}`), the
+`FlowNotifier` API, troubleshooting, and ~30 worked examples drawn from
+`enterprise/test-flows/` — see
+[**docs/FLOW_EXECUTOR.md**](docs/FLOW_EXECUTOR.md).
 
 ## Playwright-Compatible API
 
@@ -413,10 +319,14 @@ for (const [name, tool] of loader.tools) {
 
 - `execute(flow): Promise<FlowResult>` - Execute a flow
 - `abort(): void` - Abort current execution
-- `reset(): void` - Reset abort flag
+- `reset(): void` - Reset abort flag and clear vars/params
+- `setParams(params): void` - Override flow `${params.NAME}` defaults
+- `setEventMetadata(metadata): void` - Attach metadata to every emitted FlowEvent
 - `static loadFlow(path): Flow` - Load flow from JSON file
 - `static parseFlow(data): Flow` - Parse flow from object
 
+Full reference: [docs/FLOW_EXECUTOR.md](docs/FLOW_EXECUTOR.md).
+
 ### Extractor
 
 - `goto(url, options?): Promise<void>` - Navigate to URL

package/dist/flow/conditions.d.ts

@@ -4,7 +4,7 @@
  * Provides condition evaluation logic for conditional branching
  * in flows.
  */
-import type { FlowCondition } from '../types.js';
+import type { FlowCondition, StepResult } from '../types.js';
 /**
  * Evaluate a condition against a value.
  *
@@ -30,5 +30,5 @@ import type { FlowCondition } from '../types.js';
  * evaluateCondition(cond2, result); // true
  * ```
  */
-export declare function evaluateCondition(condition: FlowCondition, value: unknown): boolean;
+export declare function evaluateCondition(condition: FlowCondition, value: unknown, priorResults?: readonly StepResult[]): boolean;
 //# sourceMappingURL=conditions.d.ts.map

package/dist/flow/conditions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"conditions.d.ts","sourceRoot":"","sources":["../../src/flow/conditions.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAIjD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,aAAa,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAmGnF"}
+{"version":3,"file":"conditions.d.ts","sourceRoot":"","sources":["../../src/flow/conditions.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAI7D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,aAAa,EACxB,KAAK,EAAE,OAAO,EACd,YAAY,CAAC,EAAE,SAAS,UAAU,EAAE,GACnC,OAAO,CAwHT"}

package/dist/flow/conditions.js

@@ -31,10 +31,20 @@ import { getValueAtPath } from './variables.js';
  * evaluateCondition(cond2, result); // true
  * ```
  */
-export function evaluateCondition(condition, value) {
-    let checkValue = value;
+export function evaluateCondition(condition, value, priorResults) {
+    // Source resolution: when source === 'step' + sourceStepId is set, look up
+    // the referenced step's result instead of using `value` (the prev result).
+    // Earlier code parsed sourceStepId off the JSON but never used it.
+    let sourceValue = value;
+    if (condition.source === 'step' && condition.sourceStepId && priorResults) {
+        const found = priorResults.find((r) => r.stepId === condition.sourceStepId);
+        if (found) {
+            sourceValue = found.result;
+        }
+    }
+    let checkValue = sourceValue;
     if (condition.field) {
-        checkValue = getValueAtPath(value, condition.field);
+        checkValue = getValueAtPath(sourceValue, condition.field);
     }
     switch (condition.operator) {
         case ConditionOperator.EQUALS:
@@ -88,7 +98,14 @@ export function evaluateCondition(condition, value) {
             if (typeof checkValue === 'string') {
                 return checkValue.length === 0;
             }
-            if (Array.isArray(checkValue) || typeof checkValue === 'object') {
+            // Arrays must be checked BEFORE the generic object branch — Object.keys on
+            // an Array returns ['0','1',…] for populated arrays but [] for typed arrays
+            // and would also return [] for arrays in some legacy engines, so .length
+            // is the only reliable signal.
+            if (Array.isArray(checkValue)) {
+                return checkValue.length === 0;
+            }
+            if (typeof checkValue === 'object') {
                 return Object.keys(checkValue).length === 0;
             }
             return false;
@@ -99,7 +116,10 @@ export function evaluateCondition(condition, value) {
             if (typeof checkValue === 'string') {
                 return checkValue.length > 0;
             }
-            if (Array.isArray(checkValue) || typeof checkValue === 'object') {
+            if (Array.isArray(checkValue)) {
+                return checkValue.length > 0;
+            }
+            if (typeof checkValue === 'object') {
                 return Object.keys(checkValue).length > 0;
             }
             return true;

package/dist/flow/conditions.js.map

@@ -1 +1 @@
-{"version":3,"file":"conditions.js","sourceRoot":"","sources":["../../src/flow/conditions.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"conditions.js","sourceRoot":"","sources":["../../src/flow/conditions.ts"],"names":[],"mappings":"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"}

package/dist/flow/executor.d.ts

@@ -5,6 +5,7 @@
  * expectation validation, and conditional branching support.
  */
 import type { Flow, FlowStep, FlowResult } from '../types.js';
+import { FlowNotifier } from './notifications.js';
 import type { OwlBrowser } from '../client.js';
 /**
  * Flow execution engine that runs a series of browser tool steps.
@@ -40,20 +41,61 @@ export declare class FlowExecutor {
     private readonly _client;
     private readonly _contextId;
     private _abortFlag;
-    constructor(client: OwlBrowser, contextId: string);
+    /**
+     * Flow-scoped variables captured by `step.capture = "name"`. Resolved via
+     * `${vars.NAME}` in any later step's params, regardless of how many
+     * steps separate the capture from the use.
+     */
+    private _vars;
+    /**
+     * Flow-scoped read-only parameters. Seeded from `flow.parameters`, may be
+     * overridden via setParams() (runner CLI). Resolved via `${params.NAME}`.
+     */
+    private _params;
+    private _notifier?;
+    private _eventMetadata;
+    constructor(client: OwlBrowser, contextId: string, options?: {
+        notifier?: FlowNotifier;
+    });
+    /** Attach metadata to every FlowEvent this executor emits. */
+    setEventMetadata(metadata: Record<string, unknown>): void;
+    /** Override flow parameters; merged with declared defaults at execute() time. */
+    setParams(params: Record<string, unknown>): void;
     /**
      * Signal to abort the current flow execution.
      */
     abort(): void;
     /**
-     * Reset the abort flag for a new execution.
+     * Reset the abort flag and clear flow-scoped vars for a new execution.
      */
     reset(): void;
     /**
      * Execute a flow and return the results.
+     *
+     * Honours the flow's top-level `requiredEnv` and `timeoutSeconds`
+     * directly — embedders that drive `FlowExecutor` from their own code
+     * get the same gates the bundled runner provides, without having to
+     * reimplement them. When `requiredEnv` is unmet, the executor returns
+     * `success: true, skipped: true` and emits `flow.skipped` (no
+     * `flow.started` is emitted in that case so subscribers never see a
+     * started event without a terminal counterpart).
      */
     execute(flow: Flow): Promise<FlowResult>;
+    private _emitStarted;
+    /** Emit `flow.skipped` when `requiredEnv` is unmet. */
+    private _emitSkipped;
+    private _emitTerminal;
     private _executeSteps;
+    /**
+     * Execute a `for_each` step: iterate an array source, run a body per item.
+     *
+     * Schema (under step.params):
+     *   source     `${...}` ref or literal array
+     *   body       array of step JSON to run per item
+     *   item_var   capture name for the current item (default 'item')
+     *   index_var  capture name for the index (default 'index')
+     */
+    private _executeForEachStep;
     private _executeConditionStep;
     private _executeToolStep;
     /**

package/dist/flow/executor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../src/flow/executor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EACV,IAAI,EACJ,QAAQ,EACR,UAAU,EAIX,MAAM,aAAa,CAAC;AAOrB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AA4D/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAa;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,UAAU,CAAS;gBAEf,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM;IAKjD;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACG,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,UAAU,CAAC;YA+BhC,aAAa;YA6Cb,qBAAqB;YAqErB,gBAAgB;IA6D9B;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAMnC;;OAEG;IACH,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAUrD;;OAEG;IACH,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,QAAQ;CA+E1D"}
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../src/flow/executor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAEV,IAAI,EACJ,QAAQ,EACR,UAAU,EAMX,MAAM,aAAa,CAAC;AAMrB,OAAO,EAAE,YAAY,EAAa,MAAM,oBAAoB,CAAC;AAG7D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AA+G/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAa;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,UAAU,CAAS;IAC3B;;;;OAIG;IACH,OAAO,CAAC,KAAK,CAA+B;IAC5C;;;OAGG;IACH,OAAO,CAAC,OAAO,CAA+B;IAC9C,OAAO,CAAC,SAAS,CAAC,CAAe;IACjC,OAAO,CAAC,cAAc,CAA+B;gBAGnD,MAAM,EAAE,UAAU,EAClB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,YAAY,CAAA;KAAE;IAOvC,8DAA8D;IAC9D,gBAAgB,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAIzD,iFAAiF;IACjF,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAIhD;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,KAAK,IAAI,IAAI;IAMb;;;;;;;;;;OAUG;IACG,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,UAAU,CAAC;YAgFhC,YAAY;IAU1B,uDAAuD;YACzC,YAAY;YAWZ,aAAa;YA2Bb,aAAa;IA4E3B;;;;;;;;OAQG;YACW,mBAAmB;YAoEnB,qBAAqB;YA6ErB,gBAAgB;IAuI9B;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAMnC;;OAEG;IACH,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IA+BrD;;OAEG;IACH,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,QAAQ;CA8G1D"}