donobu/dist/apis/FlowsApi.d.ts

Create browser automations with an LLM agent and replay them as Playwright scripts.

import type { Request, Response } from 'express';
import type { 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;
    private static DEFAULT_CODE_OPTIONS;
    constructor(donobuFlowsManager: DonobuFlowsManager);
    /**
     * 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>;
    /**
     * Returns the log snapshot for a flow. For running flows, returns the live
     * in-memory buffer. For completed flows, returns the persisted snapshot.
     */
    getFlowLogs(req: Request, res: Response): Promise<void>;
    /**
     * 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": [ "flowId1", "flowId2", "flowId3" ],
     *   "options": {
     *     "areElementIdsVolatile": true,
     *     "disableSelectorFailover": true
     *   }
     * }
     *
     * 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>;
    /**
     * 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
     * ```
     */
    getFlowAsRerun(req: Request, res: Response): Promise<void>;
    /**
     * 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
     * - `partialName`: Filter by partial 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
     * - `sortBy`: Column to sort results by (created_at, name, run_mode, state) (default: created_at)
     * - `sortOrder`: Sort direction (asc, desc) (default: desc)
     */
    getFlows(req: Request, res: Response): Promise<void>;
    /**
     * 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",
     *   "maxToolCalls": 30
     * }
     *
     * Response: FlowMetadata object with state "UNSTARTED" or "INITIALIZING"
     * ```
     */
    createFlow(req: Request, res: Response): Promise<void>;
    /**
     * 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 is invalid.
     *
     * @example
     * ```http
     * POST /api/flows/abc123/rename
     * Content-Type: application/json
     *
     * {
     *   "name": "Updated Flow Name"
     * }
     * ```
     */
    renameFlow(req: Request, res: Response): Promise<void>;
    /**
     * 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
     * ```
     */
    getFlowMetadata(req: Request, res: Response): Promise<void>;
    /**
     * 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>;
    /**
     * 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>;
}
//# sourceMappingURL=FlowsApi.d.ts.map