donobu/dist/esm/managers/AdminApiController.d.ts

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

import type { EnvPick } from 'env-struct';
import type { env } from '../envVars';
import type { ControlPanelFactory } from '../models/ControlPanel';
import type { DonobuDeploymentEnvironment } from '../models/DonobuDeploymentEnvironment';
/**
 * Central API controller responsible for setting up and managing the complete Donobu HTTP API server.
 *
 * The AdminApiController serves as the main orchestrator for the Donobu REST API, handling
 * the initialization of the Express.js framework, middleware configuration, route registration,
 * and dependency injection of all API controllers. It provides a unified entry point for
 * starting the HTTP server and manages the complete request/response lifecycle.
 *
 * **Architecture Overview:**
 * - **Dependency Management**: Initializes and wires together all API controllers and managers
 * - **Middleware Pipeline**: Configures JSON parsing, authentication, caching, logging, and error handling
 * - **Route Registration**: Sets up all REST endpoints with proper HTTP methods and handlers
 * - **Environment Adaptation**: Adjusts available endpoints based on deployment environment
 * - **Error Handling**: Provides comprehensive error processing with proper HTTP status codes
 *
 * **Deployment Environment Support:**
 * - **LOCAL**: Full API access including flow control, tool call proposals, and auth management
 * - **DONOBU_HOSTED_SINGLE_TENANT**: Standard API with restricted administrative operations
 * - **DONOBU_HOSTED_MULTI_TENANT**: Standard API with restricted administrative operations
 *
 * **Security Features:**
 * - Environment-specific endpoint restrictions for security isolation
 * - Request context management with authentication token handling
 *
 * **Request Processing Pipeline:**
 * 1. **JSON Body Parsing**: 1MB limit with malformed JSON detection
 * 2. **Authentication Middleware**: Token extraction and context establishment
 * 3. **Cache Control**: Prevents API response caching
 * 4. **Access Logging**: Request/response tracking for monitoring
 * 5. **Route Handling**: Endpoint-specific business logic execution
 * 6. **Error Processing**: Standardized error responses with appropriate status codes
 *
 * **Error Handling Strategy:**
 * - **Zod Validation Errors**: 400 Bad Request with detailed field-level errors
 * - **Donobu Business Exceptions**: Mapped to appropriate HTTP status codes with user-friendly messages
 * - **Unexpected Errors**: 500 Internal Server Error with sanitized error information
 * - **Development vs Production**: Enhanced error details in development environments
 */
export declare class AdminApiController {
    private readonly app;
    private server?;
    /**
     * Creates a new instance.
     *
     * @param donobuDeploymentEnvironment The environment in which this application is running in.
     * @param controlPanelFactory A factory for creating control panel for flows. This is injected
     *   because if this SDK is being run inside an Electron application, it needs to be able to
     *   inject code that controls Electron windows, and we do not want to have Electron as a
     *   compile-time or runtime dependency for this SDK.
     *
     * This has material consequences! If this is set to a value of LOCAL then...
     * - additional API endpoints are registered, of which allow operations that would
     *   otherwise be considered unsafe.
     * - operations around active flows are considered fair game.
     * - no checking for flow ownership is performed, as all flows are considered owned by the
     *   local environment.
     */
    static create(donobuDeploymentEnvironment: DonobuDeploymentEnvironment, controlPanelFactory: ControlPanelFactory, environ: EnvPick<typeof env, 'ANTHROPIC_API_KEY' | 'ANTHROPIC_MODEL_NAME' | 'AWS_ACCESS_KEY_ID' | 'AWS_BEDROCK_MODEL_NAME' | 'AWS_SECRET_ACCESS_KEY' | 'BASE64_GPT_CONFIG' | 'BROWSERBASE_API_KEY' | 'BROWSERBASE_PROJECT_ID' | 'DONOBU_API_BASE_URL' | 'DONOBU_API_KEY' | 'DONOBU_PERSISTENCE_API_KEY' | 'GOOGLE_GENERATIVE_AI_API_KEY' | 'GOOGLE_GENERATIVE_AI_MODEL_NAME' | 'OLLAMA_API_URL' | 'OLLAMA_MODEL_NAME' | 'OPENAI_API_KEY' | 'OPENAI_API_MODEL_NAME' | 'PERSISTENCE_PRIORITY'>): Promise<AdminApiController>;
    private constructor();
    /**
     * Binds the API/web-asset server to `port` and resolves once the socket is
     * listening. If the given port is 0, a random port is assigned. Rejects on
     * bind errors (e.g. EADDRINUSE) so callers — particularly those doing a
     * stop/start bounce — can recover instead of crashing on an uncaught
     * 'error' event.
     */
    start(port: number): Promise<void>;
    /**
     * Stops accepting new connections and forcibly tears down any in-flight
     * ones, then resolves. Forceful close keeps bounces predictable — a slow
     * or stuck client request can't hold the port open. Callers that want to
     * let in-flight work drain should do so before invoking stop().
     */
    stop(): Promise<void>;
    private static setupExpressFramework;
    /**
     * Sets up URL error handler middleware to catch URL parsing/decoding errors.
     * Converts server errors from malformed URLs (like '%') to proper client errors.
     * @returns Express middleware for handling URL parsing errors
     */
    private static setupUrlErrorHandler;
    /**
     * Sets up JSON body parser middleware with validation.
     * @returns Express middleware for parsing JSON with 1MB limit and validation
     */
    private static setupJsonBodyParser;
    private static setupCacheDisabler;
    private static setupAccessLogger;
    private static setupErrorHandler;
    /**
     * Initializes all API handlers.
     */
    private static initializeApis;
    /**
     * Registers environment-specific routes.
     */
    private static registerEnvironmentRoutes;
    /**
     * Registers routes specific to LOCAL environment.
     */
    private static registerLocalRoutes;
    /**
     * Registers common routes available in all environments.
     */
    private static registerCommonRoutes;
    /**
     * Registers flow-related routes.
     */
    private static registerFlowRoutes;
    /**
     * Registers test-related routes.
     */
    private static registerTestRoutes;
    /**
     * Registers suite-related routes.
     */
    private static registerSuiteRoutes;
    /**
     * Registers utility routes (version, ping).
     */
    private static registerUtilityRoutes;
    private static asyncHandler;
}
//# sourceMappingURL=AdminApiController.d.ts.map