donobu 2.20.1 → 2.21.0

package/dist/esm/apis/FlowsApi.d.ts

@@ -1,49 +1,293 @@
 import { Request, Response } from 'express';
 import { DonobuFlowsManager } from '../managers/DonobuFlowsManager';
+/**
+ * API controller for managing Donobu flows throughout their lifecycle.
+ *
+ * The FlowsApi provides endpoints for creating, querying, controlling, and managing
+ * Donobu flows. It handles flow metadata operations, code generation, project export,
+ * and runtime control operations like pause/resume/cancel.
+ *
+ * @remarks
+ * This class serves as the HTTP API layer for the {@link DonobuFlowsManager}, translating
+ * REST requests into appropriate manager method calls. All methods are designed to be
+ * used as Express.js route handlers.
+ *
+ * Flow States:
+ * - UNSTARTED: Flow created but not yet initialized
+ * - INITIALIZING: Setting up browser context and initial state
+ * - RUNNING_ACTION: Executing a tool call
+ * - QUERYING_LLM_FOR_NEXT_ACTION: AI determining next action (AUTONOMOUS mode)
+ * - WAITING_ON_USER_FOR_NEXT_ACTION: Waiting for user input (INSTRUCT mode)
+ * - PAUSED: Flow execution temporarily suspended
+ * - RESUMING: Transitioning from paused to active state
+ * - FAILED: Flow terminated unsuccessfully
+ * - SUCCESS: Flow completed successfully
+ */
 export declare class FlowsApi {
     private readonly donobuFlowsManager;
     constructor(donobuFlowsManager: DonobuFlowsManager);
     /**
-     * Attempts to create a Node.js Microsoft Playwright script to replay the
-     * given flow.
+     * Generates Playwright code that can replay a completed flow.
+     *
+     * Creates a Node.js Microsoft Playwright script that reproduces the actions
+     * taken during the specified flow. The generated code uses the Donobu Playwright
+     * extension and can be executed independently.
+     *
+     * @throws {@link FlowNotFoundException} When the specified flow doesn't exist
+     *
+     * @example
+     * ```http
+     * GET /api/flows/abc123/code
+     *
+     * Response:
+     * {
+     *   "script": "import { test } from 'donobu';\n\ntest('My Flow', async ({ page }) => {\n  await page.goto('https://example.com');\n  // ... more actions\n});"
+     * }
+     * ```
      */
     getFlowAsCode(req: Request, res: Response): Promise<void>;
     /**
-     * Generates a complete Playwright project structure for multiple flows with dependency management
+     * Generates a complete Playwright project structure for multiple flows.
+     *
+     * Creates a full Playwright project with proper dependency management, configuration,
+     * and test files. Automatically resolves and includes flow dependencies to ensure
+     * a complete, runnable project.
+     *
+     * @throws {@link FlowNotFoundException} When any specified flow doesn't exist
+     *
+     * @example
+     * ```http
+     * POST /api/flows/project
+     * Content-Type: application/json
+     *
+     * {
+     *   "flowIds": ["flow1", "flow2", "flow3"]
+     * }
+     *
+     * Response:
+     * {
+     *   "files": [
+     *     {
+     *       "path": "tests/login-flow.spec.ts",
+     *       "content": "import { test } from 'donobu';\n..."
+     *     },
+     *     {
+     *       "path": "playwright.config.ts",
+     *       "content": "import { defineConfig } from 'donobu';\n..."
+     *     }
+     *   ]
+     * }
+     * ```
      */
     getFlowsAsProject(req: Request, res: Response): Promise<void>;
     /**
-     * Get a given flow by ID as an appropriately formatted
-     * {@link CreateDonobuFlow} object fit for direct replay by calling the
-     * {@link FlowsApi.createFlow} endpoint.
+     * Converts a flow into a rerunnable format.
+     *
+     * Returns a {@link CreateDonobuFlow} object that can be used to replay the specified
+     * flow deterministically. The returned parameters include all original tool calls
+     * configured for deterministic execution.
+     *
+     * @throws {@link FlowNotFoundException} When the specified flow doesn't exist
+     *
+     * @example
+     * ```http
+     * GET /api/flows/abc123/rerun
+     *
+     * Response: CreateDonobuFlow object ready for POST to /api/flows
+     * ```
+     *
+     * @public
      */
     getFlowAsRerun(req: Request, res: Response): Promise<void>;
     /**
-     * Serves up flows' metadata as JSON with optional filtering.
+     * Retrieves paginated flows with optional filtering.
+     *
+     * Returns a list of flow metadata objects matching the specified criteria.
+     * Supports pagination, filtering by name/state/runMode, and time-based filtering.
+     * Results are ordered by startedAt timestamp in descending order (newest first).
+     *
+     * @throws {@link InvalidParamValueException} When query parameters are invalid
+     *
+     * @example
+     * ```http
+     * GET /api/flows?limit=10&state=SUCCESS&startedAfter=1640995200000
+     *
+     * Response:
+     * {
+     *   "flows": [
+     *     {
+     *       "id": "abc123",
+     *       "name": "Login Test",
+     *       "state": "SUCCESS",
+     *       "startedAt": 1641000000000,
+     *       // ... other metadata
+     *     }
+     *   ],
+     *   "nextPageToken": "eyJ..."
+     * }
+     * ```
+     *
+     * Query Parameters:
+     * - `pageToken`: Pagination token for subsequent pages
+     * - `limit`: Maximum results per page (1-100, default varies)
+     * - `name`: Filter by exact flow name
+     * - `runMode`: Filter by execution mode (AUTONOMOUS|INSTRUCT|DETERMINISTIC)
+     * - `state`: Filter by current state
+     * - `startedAfter`: Unix timestamp - flows started after this time
+     * - `startedBefore`: Unix timestamp - flows started before this time
      */
     getFlows(req: Request, res: Response): Promise<void>;
     /**
-     * Creates a new DonobuFlow flow.
+     * Creates and starts a new Donobu flow.
+     *
+     * Validates the provided parameters, creates a new flow instance, and begins
+     * execution according to the specified run mode. The flow runs asynchronously
+     * after this method returns.
+     *
+     * @throws {@link InvalidParamValueException} When flow parameters are invalid
+     * @throws {@link ToolRequiresGptException} When tools require GPT but none configured
+     *
+     * @example
+     * ```http
+     * POST /api/flows
+     * Content-Type: application/json
+     *
+     * {
+     *   "targetWebsite": "https://example.com",
+     *   "overallObjective": "Sign up for an account",
+     *   "initialRunMode": "AUTONOMOUS",
+     *   "maxIterations": 20
+     * }
+     *
+     * Response: FlowMetadata object with state "UNSTARTED" or "INITIALIZING"
+     * ```
      */
     createFlow(req: Request, res: Response): Promise<void>;
     /**
-     * Rename a flow.
+     * Updates the name of an existing flow.
+     *
+     * Changes the display name of the specified flow. The name is used for
+     * identification and organization purposes and can be null to clear the name.
+     *
+     * @throws {@link FlowNotFoundException} When the specified flow doesn't exist
+     * @throws {@link InvalidParamValueException} When the name exceeds 255 characters
+     *
+     * @example
+     * ```http
+     * POST /api/flows/abc123/rename
+     * Content-Type: application/json
+     *
+     * {
+     *   "name": "Updated Flow Name"
+     * }
+     * ```
      */
     renameFlow(req: Request, res: Response): Promise<void>;
     /**
-     * Delete a given flow by ID.
+     * Permanently deletes a flow and all associated data.
+     *
+     * Removes the flow from storage including metadata, tool calls, screenshots,
+     * and video recordings. This operation cannot be undone.
+     *
+     * @throws {@link FlowNotFoundException} When the specified flow doesn't exist
+     * @throws {@link CannotDeleteRunningFlowException} When attempting to delete an active flow
+     *
+     * @example
+     * ```http
+     * DELETE /api/flows/abc123
+     *
+     * Response: HTTP 200 OK
+     * ```
      */
     deleteFlow(req: Request, res: Response): Promise<void>;
+    /**
+     * Retrieves complete metadata for a specific flow.
+     *
+     * Returns the full {@link FlowMetadata} object containing current state,
+     * configuration, execution history, and results.
+     *
+     * @throws {@link FlowNotFoundException} When the specified flow doesn't exist
+     *
+     * @example
+     * ```http
+     * GET /api/flows/abc123
+     *
+     * Response: Complete FlowMetadata object
+     * ```
+     *
+     * @public
+     */
     getFlowMetadata(req: Request, res: Response): Promise<void>;
     /**
-     * Pause the active flow by ID.
+     * Pauses execution of an active flow.
+     *
+     * Signals the flow to pause after completing its current action. The flow
+     * will transition to PAUSED state and can be resumed later. Only works
+     * for flows that are not already in a terminal state.
+     *
+     * @throws {@link ActiveFlowNotFoundException} When the flow is not active locally
+     *
+     * @example
+     * ```http
+     * POST /api/flows/abc123/pause
+     *
+     * Response: FlowMetadata with nextState set to "PAUSED"
+     * ```
+     *
+     * @remarks
+     * This endpoint is only available in LOCAL deployment environments for security.
+     * The flow will complete its current action before pausing.
      */
     pauseFlow(req: Request, res: Response): Promise<void>;
     /**
-     * Resume the paused active flow by ID.
+     * Resumes execution of a paused flow.
+     *
+     * Signals a paused flow to continue execution. The flow will transition
+     * from PAUSED to RESUMING state and then continue normal operation.
+     *
+     * @throws {@link ActiveFlowNotFoundException} When the flow is not active locally
+     *
+     * @example
+     * ```http
+     * POST /api/flows/abc123/resume
+     *
+     * Response: FlowMetadata with nextState set to "RESUMING"
+     * ```
+     *
+     * @remarks
+     * This endpoint is only available in LOCAL deployment environments for security.
+     * Only works on flows currently in PAUSED state.
      */
     resumeFlow(req: Request, res: Response): Promise<void>;
+    /**
+     * Cancels and terminates an active flow.
+     *
+     * Forcibly stops flow execution and sets the state to FAILED. For active
+     * flows, this closes the browser context and terminates the execution thread.
+     *
+     * @throws {@link FlowNotFoundException} When the specified flow doesn't exist
+     *
+     * @example
+     * ```http
+     * POST /api/flows/abc123/cancel
+     *
+     * Response: FlowMetadata with state "FAILED"
+     * ```
+     *
+     * @remarks
+     * This endpoint is only available in LOCAL deployment environments for security.
+     * Cannot be undone - the flow will need to be recreated to retry.
+     */
     cancelFlow(req: Request, res: Response): Promise<void>;
+    /**
+     * Parses and validates the limit query parameter.
+     *
+     * Converts the limit string to a number with appropriate defaults and bounds.
+     * Returns Number.MAX_SAFE_INTEGER if parsing fails to avoid artificial limits.
+     *
+     * @param limit - The limit query parameter value
+     * @returns Parsed limit number or maximum safe integer
+     */
     private parseLimit;
 }
 //# sourceMappingURL=FlowsApi.d.ts.map

package/dist/esm/apis/FlowsApi.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FlowsApi.d.ts","sourceRoot":"","sources":["../../../src/apis/FlowsApi.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAapE,qBAAa,QAAQ;IACP,OAAO,CAAC,QAAQ,CAAC,kBAAkB;gBAAlB,kBAAkB,EAAE,kBAAkB;IAEnE;;;OAGG;IACU,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAOtE;;OAEG;IACU,iBAAiB,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAoB1E;;;;OAIG;IACU,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAOvE;;OAEG;IACU,QAAQ,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAqDjE;;OAEG;IACU,UAAU,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAOnE;;OAEG;IACU,UAAU,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAoCnE;;OAEG;IACU,UAAU,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAMtD,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAMxE;;OAEG;IACU,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAWlE;;OAEG;IACU,UAAU,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAWtD,UAAU,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAMnE,OAAO,CAAC,UAAU;CAOnB"}
+{"version":3,"file":"FlowsApi.d.ts","sourceRoot":"","sources":["../../../src/apis/FlowsApi.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAapE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,QAAQ;IACA,OAAO,CAAC,QAAQ,CAAC,kBAAkB;gBAAlB,kBAAkB,EAAE,kBAAkB;IAE1E;;;;;;;;;;;;;;;;;;OAkBG;IACU,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAOtE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACU,iBAAiB,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAY1E;;;;;;;;;;;;;;;;;OAiBG;IACU,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAOvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;IACU,QAAQ,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAqDjE;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACU,UAAU,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAOnE;;;;;;;;;;;;;;;;;;OAkBG;IACU,UAAU,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAUnE;;;;;;;;;;;;;;;OAeG;IACU,UAAU,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAMnE;;;;;;;;;;;;;;;;OAgBG;IACU,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAMxE;;;;;;;;;;;;;;;;;;;OAmBG;IACU,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAWlE;;;;;;;;;;;;;;;;;;OAkBG;IACU,UAAU,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAWnE;;;;;;;;;;;;;;;;;;OAkBG;IACU,UAAU,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAMnE;;;;;;;;OAQG;IACH,OAAO,CAAC,UAAU;CAOnB"}