@autobe/agent/lib/orchestrate/interface/structures/IAutoBeInterfaceOperationApplication.d.ts

AI backend server code generator

import { AutoBeOpenApi } from "@autobe/interface";
import { tags } from "typia";
export interface IAutoBeInterfaceOperationApplication {
    /**
     * Generate detailed API operations from path/method combinations.
     *
     * This function creates complete API operations following REST principles and
     * quality standards. Each generated operation includes specification, path,
     * method, detailed multi-paragraph description, concise summary, parameters,
     * and appropriate request/response bodies.
     *
     * The function processes as many operations as possible in a single call,
     * with progress tracking to ensure iterative completion of all required
     * endpoints.
     *
     * @param props Properties containing the operations to generate.
     */
    makeOperations(props: IAutoBeInterfaceOperationApplication.IProps): void;
}
export declare namespace IAutoBeInterfaceOperationApplication {
    interface IProps {
        /**
         * Array of API operations to generate.
         *
         * Each operation in this array must include:
         *
         * - Specification: Detailed API specification with clear purpose and
         *   functionality
         * - Path: Resource-centric URL path (e.g., "/resources/{resourceId}")
         * - Method: HTTP method (get, post, put, delete, patch)
         * - Description: Extremely detailed multi-paragraph description referencing
         *   Prisma schema comments
         * - Summary: Concise one-sentence summary of the endpoint
         * - Parameters: Array of all necessary parameters with descriptions and
         *   schema definitions
         * - RequestBody: For POST/PUT/PATCH methods, with typeName referencing
         *   components.schemas
         * - ResponseBody: With typeName referencing appropriate response type
         *
         * All operations must follow strict quality standards:
         *
         * 1. Detailed descriptions referencing Prisma schema comments
         * 2. Accurate parameter definitions matching path parameters
         * 3. Appropriate request/response body type references
         * 4. Consistent patterns for CRUD operations
         *
         * For list retrievals (typically PATCH), include pagination, search, and
         * sorting. For detail retrieval (GET), return a single resource. For
         * creation (POST), use .ICreate request body. For modification (PUT), use
         * .IUpdate request body.
         */
        operations: IOperation[];
    }
    /**
     * Operation of the Restful API.
     *
     * This interface defines a single API endpoint with its HTTP {@link method},
     * {@link path}, {@link parameters path parameters},
     * {@link requestBody request body}, and {@link responseBody} structure. It
     * corresponds to an individual operation in the paths section of an OpenAPI
     * document.
     *
     * Each operation requires a detailed explanation of its purpose through the
     * reason and description fields, making it clear why the API was designed and
     * how it should be used.
     *
     * All request bodies and responses for this operation must be object types
     * and must reference named types defined in the components section. The
     * content-type is always `application/json`. For file upload/download
     * operations, use `string & tags.Format<"uri">` in the appropriate schema
     * instead of binary data formats.
     *
     * In OpenAPI, this might represent:
     *
     * ```json
     * {
     *   "/shoppings/customers/orders": {
     *     "post": {
     *       "description": "Create a new order application from shopping cart...",
     *       "parameters": [...],
     *       "requestBody": {...},
     *       "responses": {...}
     *     }
     *   }
     * }
     * ```
     */
    interface IOperation extends Omit<AutoBeOpenApi.IOperation, "authorizationRole"> {
        /**
         * Authorization roles required to access this API operation.
         *
         * This field specifies which user roles are allowed to access this
         * endpoint. Multiple roles can be specified to allow different types of
         * users to access the same endpoint.
         *
         * ## Important Guidelines
         *
         * - Set to empty array `[]` for public endpoints that require no
         *   authentication
         * - Set to array with role strings for role-restricted endpoints
         * - The role names MUST match exactly with the user type/role defined in the
         *   database
         * - This will be used by the Realize Agent to generate appropriate decorator
         *   and authorization logic in the provider functions
         * - The controller will apply the corresponding authentication decorator
         *   based on these roles
         *
         * ## Examples
         *
         * - `[]` - Public endpoint, no authentication required
         * - `["user"]` - Any authenticated user can access
         * - `["admin"]` - Only admin users can access
         * - `["admin", "moderator"]` - Both admin and moderator users can access
         * - `["seller"]` - Only seller users can access
         *
         * Note: The actual authentication/authorization implementation will be
         * handled by decorators at the controller level, and the provider function
         * will receive the authenticated user object with the appropriate type.
         */
        authorizationRoles: Array<string & tags.MinLength<1>>;
    }
}