@flink-app/flink 0.14.3 → 2.0.0-alpha.48

package/dist/src/FlinkHttpHandler.d.ts

@@ -10,24 +10,95 @@ export declare enum HttpMethod {
     delete = "delete",
     patch = "patch"
 }
-type Params = Request["params"];
+/**
+ * Validation mode for handler request and response schemas.
+ *
+ * Controls whether request and/or response data is validated against JSON schemas.
+ *
+ * **Security Note:** Skipping validation can introduce security risks. Only use
+ * SkipValidation or ValidateResponse when you have implemented custom validation
+ * or the endpoint is internal/trusted.
+ *
+ * - Validate: Validate both request and response (default behavior)
+ * - SkipValidation: Skip both request and response validation
+ * - ValidateRequest: Validate only request, skip response validation
+ * - ValidateResponse: Validate only response, skip request validation
+ *
+ * @example
+ * ```typescript
+ * // Skip validation for webhook with custom signature verification
+ * export const Route: RouteProps = {
+ *   path: "/webhook",
+ *   validation: ValidationMode.SkipValidation
+ * };
+ *
+ * // Validate request but allow flexible response during development
+ * export const Route: RouteProps = {
+ *   path: "/api/data",
+ *   validation: ValidationMode.ValidateRequest
+ * };
+ * ```
+ */
+export declare enum ValidationMode {
+    Validate = "Validate",
+    SkipValidation = "SkipValidation",
+    ValidateRequest = "ValidateRequest",
+    ValidateResponse = "ValidateResponse"
+}
+type Params = Record<string, string>;
 /**
  * Query type for request query parameters.
- * Does currently not allow nested objects, although
- * underlying express Request does allow it.
  *
- * Uses index signature to allow both Record types and interface types
- * to be assignable to Query without requiring explicit index signatures.
+ * All query parameter values are normalized to strings or string arrays:
+ * - Single values: string (e.g., ?name=John becomes { name: "John" })
+ * - Multiple values: string[] (e.g., ?tag=a&tag=b becomes { tag: ["a", "b"] })
+ *
+ * Does not allow nested objects, although underlying Express Request does allow it.
  */
-type Query = {
-    [x: string]: string | string[] | undefined;
-};
+type Query = Record<string, string | string[]>;
+/**
+ * Stream format for streaming handlers.
+ * - sse: Server-Sent Events (text/event-stream)
+ * - ndjson: Newline-Delimited JSON (application/x-ndjson)
+ */
+export type StreamFormat = "sse" | "ndjson";
+/**
+ * Stream writer interface for SSE/NDJSON streaming.
+ *
+ * Provides methods to write data chunks, handle errors, and manage the stream lifecycle.
+ * Only available in handlers where streamFormat is specified in RouteProps.
+ */
+export interface StreamWriter<T = any> {
+    /**
+     * Write data to the stream.
+     * Data is automatically JSON-stringified and formatted according to streamFormat.
+     */
+    write(data: T): void;
+    /**
+     * Send error to client and close the stream.
+     */
+    error(error: Error | string): void;
+    /**
+     * Close the stream gracefully.
+     */
+    end(): void;
+    /**
+     * Check if stream is still open (client connected).
+     * Returns false if client has disconnected.
+     */
+    isOpen(): boolean;
+}
 /**
- * Flink request extends express Request but adds reqId and user object.
+ * Flink request extends express Request but adds reqId, user object, and userPermissions.
+ *
+ * userPermissions is populated by auth plugins during authentication and contains
+ * the resolved permissions array based on the plugin's configuration (roles, dynamic
+ * roles, custom permissions, etc.)
  */
 export type FlinkRequest<T = any, P = Params, Q = Query> = Request<P, any, T, Q> & {
     reqId: string;
     user?: any;
+    userPermissions?: string[];
 };
 /**
  * Route props to control routing.
@@ -59,6 +130,27 @@ export interface RouteProps {
     mockApi?: boolean;
     /**
      * Set permissions needed to access route if route requires authentication.
+     *
+     * When an array is provided, the user must have **ALL** permissions in the array (AND logic).
+     * To require any one of multiple permissions (OR logic), implement custom permission
+     * checking in the handler using the `user.permissions` array.
+     *
+     * @example
+     * ```typescript
+     * // Single permission
+     * permissions: "car:create"
+     *
+     * // Multiple permissions (user must have ALL)
+     * permissions: ["car:create", "car:premium"]
+     *
+     * // OR logic requires custom implementation
+     * const handler = async ({ ctx, user }) => {
+     *   if (!user.permissions.includes("car:admin") && !user.permissions.includes("car:moderator")) {
+     *     throw forbidden("Need admin or moderator permission");
+     *   }
+     *   // ... handler logic
+     * };
+     * ```
      */
     permissions?: string | string[];
     /**
@@ -82,15 +174,66 @@ export interface RouteProps {
      * to avoid conflicts you can set a negative order.
      */
     order?: number;
+    /**
+     * Validation mode for request and response schemas.
+     *
+     * Controls schema validation behavior for this handler. Use with caution as
+     * skipping validation can introduce security vulnerabilities.
+     *
+     * **Options:**
+     * - Validate: Validate both request and response (default)
+     * - SkipValidation: Skip both request and response validation
+     * - ValidateRequest: Validate only request, skip response validation
+     * - ValidateResponse: Validate only response, skip request validation
+     *
+     * **When to skip validation:**
+     * - Webhook handlers with custom signature verification
+     * - Performance-critical internal endpoints
+     * - Handlers using alternative validation methods (e.g., Zod, Joi)
+     *
+     * @default ValidationMode.Validate
+     */
+    validation?: ValidationMode;
+    /**
+     * Stream format for streaming handlers (SSE or NDJSON).
+     *
+     * When specified, the handler becomes a streaming handler and receives a `stream`
+     * parameter for writing data chunks. Response validation is automatically skipped
+     * for streaming handlers (chunks are progressive, not a final JSON response).
+     *
+     * **Formats:**
+     * - sse: Server-Sent Events (text/event-stream) - ideal for browser EventSource API
+     * - ndjson: Newline-Delimited JSON (application/x-ndjson) - ideal for LLM text streaming
+     *
+     * **Example:**
+     * ```typescript
+     * export const Route: RouteProps = {
+     *   path: "/ai/stream",
+     *   streamFormat: "sse"
+     * };
+     *
+     * const handler: GetHandler<{}, void> = async ({ ctx, stream }) => {
+     *   if (!stream) throw new Error("Stream not available");
+     *   stream.write({ message: "Hello" });
+     *   stream.end();
+     * };
+     * ```
+     */
+    streamFormat?: StreamFormat;
 }
 /**
  * Http handler function that handlers implements in order to
  * handle HTTP requests and return a JSON response.
+ *
+ * For streaming handlers (when streamFormat is specified in RouteProps),
+ * the stream parameter is available. Streaming handlers should still return
+ * a FlinkResponse (can be empty), but it will be ignored by the framework.
  */
 export type Handler<Ctx extends FlinkContext, ReqSchema = any, ResSchema = any, P extends Params = Params, Q extends Query = Query> = (props: {
     req: FlinkRequest<ReqSchema, P, Q>;
     ctx: Ctx;
     origin?: string;
+    stream?: StreamWriter;
 }) => Promise<FlinkResponse<ResSchema | FlinkError>>;
 /**
  * Http handler function specifically for GET requests as those does

package/dist/src/FlinkHttpHandler.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HttpMethod = void 0;
+exports.ValidationMode = exports.HttpMethod = void 0;
 var HttpMethod;
 (function (HttpMethod) {
     HttpMethod["get"] = "get";
@@ -9,3 +9,39 @@ var HttpMethod;
     HttpMethod["delete"] = "delete";
     HttpMethod["patch"] = "patch";
 })(HttpMethod || (exports.HttpMethod = HttpMethod = {}));
+/**
+ * Validation mode for handler request and response schemas.
+ *
+ * Controls whether request and/or response data is validated against JSON schemas.
+ *
+ * **Security Note:** Skipping validation can introduce security risks. Only use
+ * SkipValidation or ValidateResponse when you have implemented custom validation
+ * or the endpoint is internal/trusted.
+ *
+ * - Validate: Validate both request and response (default behavior)
+ * - SkipValidation: Skip both request and response validation
+ * - ValidateRequest: Validate only request, skip response validation
+ * - ValidateResponse: Validate only response, skip request validation
+ *
+ * @example
+ * ```typescript
+ * // Skip validation for webhook with custom signature verification
+ * export const Route: RouteProps = {
+ *   path: "/webhook",
+ *   validation: ValidationMode.SkipValidation
+ * };
+ *
+ * // Validate request but allow flexible response during development
+ * export const Route: RouteProps = {
+ *   path: "/api/data",
+ *   validation: ValidationMode.ValidateRequest
+ * };
+ * ```
+ */
+var ValidationMode;
+(function (ValidationMode) {
+    ValidationMode["Validate"] = "Validate";
+    ValidationMode["SkipValidation"] = "SkipValidation";
+    ValidationMode["ValidateRequest"] = "ValidateRequest";
+    ValidationMode["ValidateResponse"] = "ValidateResponse";
+})(ValidationMode || (exports.ValidationMode = ValidationMode = {}));

package/dist/src/TypeScriptCompiler.d.ts

@@ -18,6 +18,28 @@ declare class TypeScriptCompiler {
      */
     private tsSchemasSymbolsToImports;
     constructor(cwd: string);
+    /**
+     * Loads additional source paths from tsconfig.json's flink configuration.
+     * Allows projects to specify extra directories to include in compilation.
+     *
+     * Example tsconfig.json:
+     * {
+     *   "flink": {
+     *     "sourcePaths": ["src/custom-types/**\/*.ts", "src/utils/**\/*.ts"]
+     *   }
+     * }
+     */
+    private getFlinkSourcePaths;
+    /**
+     * Recursively resolves and adds imported files to the project.
+     * This ensures that files imported by handlers, schemas, etc. are available for type resolution.
+     *
+     * Handles three types of imports:
+     * 1. Relative imports (./foo, ../bar) - always resolved
+     * 2. Workspace package imports (@mycompany/shared) - resolved if symlinked outside node_modules
+     * 3. External packages (lodash, express) - skipped to avoid loading entire dependency trees
+     */
+    private resolveImportedFiles;
     /**
      * Detects if the project is using ESM (ECMAScript Modules)
      * by checking type in package.json.
@@ -41,6 +63,15 @@ declare class TypeScriptCompiler {
      * exists. Warnings will be passed thru but logged.
      */
     getPreEmitDiagnostics(): boolean;
+    /**
+     * Finds a variable declaration by its TypeScript type name.
+     * This allows finding variables based on their type annotation rather than variable name.
+     *
+     * @param sf Source file to search in
+     * @param typeName Name of the type to search for (e.g., "FlinkToolProps", "FlinkAgentProps")
+     * @returns The first matching variable declaration, or undefined if not found
+     */
+    private findVariableDeclarationByType;
     /**
      * Scans project for handlers and add those to Flink
      * "singleton" property `autoRegisteredHandlers` so they can
@@ -55,6 +86,17 @@ declare class TypeScriptCompiler {
      */
     private parseHandlerDir;
     parseRepos(): Promise<SourceFile>;
+    /**
+     * Scans project for tools and adds those to Flink
+     * "singleton" property `autoRegisteredTools` so they can
+     * be registered during start.
+     */
+    parseTools(): Promise<SourceFile>;
+    /**
+     * Scans project for agents and validates tool references.
+     * Agents are declarative (no default function).
+     */
+    parseAgents(): Promise<SourceFile>;
     /**
      * Generates a start script that will import references to handlers, repos and the
      * actual Flink app to start.