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

package/src/FlinkContext.ts

@@ -1,5 +1,7 @@
 import { FlinkAuthPlugin } from "./auth/FlinkAuthPlugin";
 import { FlinkRepo } from "./FlinkRepo";
+import { FlinkAgent } from "./ai/FlinkAgent";
+import { FlinkService } from "./FlinkService";
 
 export interface FlinkContext<P = any> {
     repos: {
@@ -12,4 +14,45 @@ export interface FlinkContext<P = any> {
      * Type of authentication, if any.
      */
     auth?: FlinkAuthPlugin;
+
+    /**
+     * AI namespace containing agents
+     *
+     * Define agents directly in your context interface:
+     *
+     * @example
+     * interface AppCtx extends FlinkContext<PluginCtx> {
+     *     auth: JwtAuthPlugin;
+     *     repos: {
+     *         carRepo: CarRepo;
+     *     };
+     *     agents: {
+     *         carAgent: CarAgent;
+     *         userAgent: UserAgent;
+     *     };
+     * }
+     */
+    agents?: {
+        [x: string]: FlinkAgent<any>;
+    };
+
+    /**
+     * Optional services namespace for shared business logic.
+     *
+     * Define services directly in your context interface:
+     *
+     * @example
+     * interface AppCtx extends FlinkContext<PluginCtx> {
+     *     repos: {
+     *         carRepo: CarRepo;
+     *     };
+     *     services: {
+     *         carService: CarService;
+     *         orderService: OrderService;
+     *     };
+     * }
+     */
+    services?: {
+        [x: string]: FlinkService<any>;
+    };
 }

package/src/FlinkErrors.ts

@@ -10,19 +10,22 @@ export type FlinkError = undefined;
  *
  * @param detail - Optional custom error message
  * @param code - Optional custom error code
+ * @param meta - Optional structured payload (must be JSON-serializable)
  * @example
  * ```ts
  * if (!user) return notFound("User not found");
+ * if (!user) return notFound("User not found", "userNotFound", { userId });
  * ```
  */
-export function notFound(detail?: string, code?: string ): FlinkResponse<FlinkError> {
+export function notFound(detail?: string, code?: string, meta?: unknown): FlinkResponse<FlinkError> {
   return {
     status: 404,
     error: {
       id: v4(),
       title: "Not Found",
       detail: detail || "The requested resource does not exist",
-      code : code || "notFound"
+      code : code || "notFound",
+      ...(meta !== undefined && { meta }),
     },
   };
 }
@@ -33,19 +36,21 @@ export function notFound(detail?: string, code?: string ): FlinkResponse<FlinkEr
  *
  * @param detail - Optional custom error message
  * @param code - Optional custom error code
+ * @param meta - Optional structured payload (must be JSON-serializable)
  * @example
  * ```ts
  * if (existingUser) return conflict("Email already registered");
  * ```
  */
-export function conflict(detail?: string, code?: string ): FlinkResponse<FlinkError> {
+export function conflict(detail?: string, code?: string, meta?: unknown): FlinkResponse<FlinkError> {
   return {
     status: 409,
     error: {
       id: v4(),
       title: "Conflict",
       detail: detail || "An identical entity exits",
-      code : code || "conflict"
+      code : code || "conflict",
+      ...(meta !== undefined && { meta }),
     },
   };
 }
@@ -58,19 +63,27 @@ export function conflict(detail?: string, code?: string ): FlinkResponse<FlinkEr
  *
  * @param detail - Optional custom error message
  * @param code - Optional custom error code
+ * @param meta - Optional structured payload (must be JSON-serializable).
+ *   Useful for domain-specific context like payment decline codes,
+ *   retry hints, or structured field errors.
  * @example
  * ```ts
  * if (!email || !password) return badRequest("Email and password are required");
+ * return badRequest("Payment declined", "paymentDeclined", {
+ *   gatewayCode: "insufficient_funds",
+ *   attemptId: "att_123",
+ * });
  * ```
  */
-export function badRequest(detail?: string, code?: string): FlinkResponse<FlinkError> {
+export function badRequest(detail?: string, code?: string, meta?: unknown): FlinkResponse<FlinkError> {
   return {
     status: 400,
     error: {
       id: v4(),
       title: "Bad Request",
       detail: detail || "Invalid request",
-      code : code || "badRequest"
+      code : code || "badRequest",
+      ...(meta !== undefined && { meta }),
     },
   };
 }
@@ -82,12 +95,13 @@ export function badRequest(detail?: string, code?: string): FlinkResponse<FlinkE
  *
  * @param detail - Optional custom error message
  * @param code - Optional custom error code
+ * @param meta - Optional structured payload (must be JSON-serializable)
  * @example
  * ```ts
  * if (!ctx.auth?.user) return unauthorized("Authentication required");
  * ```
  */
-export function unauthorized(detail?: string, code?: string): FlinkResponse<FlinkError> {
+export function unauthorized(detail?: string, code?: string, meta?: unknown): FlinkResponse<FlinkError> {
   return {
     status: 401,
     error: {
@@ -95,7 +109,8 @@ export function unauthorized(detail?: string, code?: string): FlinkResponse<Flin
       title: "Unauthorized",
       detail:
         detail || "Authentication required",
-      code : code || "unauthorized"
+      code : code || "unauthorized",
+      ...(meta !== undefined && { meta }),
     },
   };
 }
@@ -107,19 +122,21 @@ export function unauthorized(detail?: string, code?: string): FlinkResponse<Flin
  *
  * @param detail - Optional custom error message
  * @param code - Optional custom error code
+ * @param meta - Optional structured payload (must be JSON-serializable)
  * @example
  * ```ts
  * if (ctx.auth?.user?.role !== "admin") return forbidden("Admin access required");
  * ```
  */
-export function forbidden(detail?: string, code?: string): FlinkResponse<FlinkError> {
+export function forbidden(detail?: string, code?: string, meta?: unknown): FlinkResponse<FlinkError> {
   return {
     status: 403,
     error: {
       id: v4(),
       title: "Forbidden",
       detail: detail || "You do not have permission to access this resource",
-      code : code || "forbidden"
+      code : code || "forbidden",
+      ...(meta !== undefined && { meta }),
     },
   };
 }
@@ -130,6 +147,7 @@ export function forbidden(detail?: string, code?: string): FlinkResponse<FlinkEr
  *
  * @param detail - Optional custom error message
  * @param code - Optional custom error code
+ * @param meta - Optional structured payload (must be JSON-serializable)
  * @example
  * ```ts
  * try { ... } catch (error) { return internalServerError("Failed to process request"); }
@@ -137,7 +155,8 @@ export function forbidden(detail?: string, code?: string): FlinkResponse<FlinkEr
  */
 export function internalServerError(
   detail?: string,
-  code?: string
+  code?: string,
+  meta?: unknown
 ): FlinkResponse<FlinkError> {
   return {
     status: 500,
@@ -145,7 +164,8 @@ export function internalServerError(
       id: v4(),
       title: "Internal Server Error",
       detail: detail || "Something unexpected went wrong",
-      code : code || "internalServerError"
+      code : code || "internalServerError",
+      ...(meta !== undefined && { meta }),
     },
   };
 }

package/src/FlinkHttpHandler.ts

@@ -12,24 +12,111 @@ export enum HttpMethod {
     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 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.)
+ *
+ * token / rawToken are populated by auth plugins that have a token concept (e.g. JWT).
+ * `token` is the decoded, signature-verified payload; `rawToken` is the original token
+ * string that authenticated the request (Bearer header or custom tokenExtractor output).
+ * Both are optional and only set once authentication succeeds.
  */
-export type FlinkRequest<T = any, P = Params, Q = Query> = Request<P, any, T, Q> & { reqId: string; user?: any };
+export type FlinkRequest<T = any, P = Params, Q = Query> = Request<P, any, T, Q> & {
+    reqId: string;
+    user?: any;
+    userPermissions?: string[]; // Resolved permissions from auth plugin
+    token?: any; // Decoded, verified token payload (set by auth plugin)
+    rawToken?: string; // Raw token string that authenticated the request
+};
 
 /**
  * Route props to control routing.
@@ -64,6 +151,27 @@ export interface RouteProps {
 
     /**
      * 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[];
 
@@ -91,16 +199,142 @@ 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;
+
+    /**
+     * When set, the handler's `data` field is sent as a raw response with the
+     * given content type instead of the standard JSON envelope. Response schema
+     * validation is automatically skipped.
+     *
+     * Accepts Express shorthand names (`"html"`, `"csv"`, `"text"`, `"xml"`)
+     * or any full MIME type string (`"application/pdf"`, etc.).
+     *
+     * @example
+     * ```typescript
+     * export const Route: RouteProps = {
+     *   path: "/dashboard",
+     *   responseType: "html",
+     * };
+     *
+     * const handler: GetHandler<AppContext, void> = async ({ ctx }) => {
+     *   return { data: `<h1>Hello</h1>` };
+     * };
+     * ```
+     *
+     * @example
+     * ```typescript
+     * export const Route: RouteProps = {
+     *   path: "/export",
+     *   responseType: "csv",
+     * };
+     *
+     * const handler: GetHandler<AppContext, void> = async ({ ctx }) => {
+     *   return { data: `id,name\n1,Alice` };
+     * };
+     * ```
+     *
+     * @example
+     * ```typescript
+     * export const Route: RouteProps = {
+     *   path: "/logo",
+     *   responseType: "image/png",
+     * };
+     *
+     * const handler: GetHandler<AppContext, Buffer> = async ({ ctx }) => {
+     *   const imageBuffer = await fs.promises.readFile("./logo.png");
+     *   return { data: imageBuffer };
+     * };
+     * ```
+     */
+    responseType?:
+        | "html"
+        | "csv"
+        | "text"
+        | "xml"
+        | "image/png"
+        | "image/jpeg"
+        | "image/gif"
+        | "image/svg+xml"
+        | "image/webp"
+        | "application/pdf"
+        | "application/octet-stream"
+        | (string & {});
+
+    /**
+     * Direct JSON Schema for request body validation.
+     * When set, bypasses manifest lookup for request schema.
+     * Useful for plugin handlers that have their own compiled schemas.
+     */
+    reqSchema?: object;
+
+    /**
+     * Direct JSON Schema for response body validation.
+     * When set, bypasses manifest lookup for response schema.
+     * Useful for plugin handlers that have their own compiled schemas.
+     */
+    resSchema?: object;
 }
 
 /**
  * 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>>;
 
 /**
@@ -121,26 +355,10 @@ export type HandlerFile = {
     default: Handler<any, any, any, any, any>;
     Route?: RouteProps;
     /**
-     * Name of schemas, is set at compile time by Flink compiler.
-     */
-    __schemas?: {
-        reqSchema?: JSONSchema;
-        resSchema?: JSONSchema;
-    };
-    /**
-     * Typescript source file name, is set at compile time by Flink compiler.
+     * Typescript source file path (relative to project root), set at compile time by Flink compiler.
+     * Used to look up handler metadata from schema-manifest.json at runtime.
      */
     __file?: string;
-
-    /**
-     * Description of query params, is set at compile time by Flink compiler.
-     */
-    __query?: QueryParamMetadata[];
-
-    /**
-     * Description of path params, is set at compile time by Flink compiler.
-     */
-    __params?: QueryParamMetadata[];
 };
 
 export type QueryParamMetadata = {

package/src/FlinkJob.ts

@@ -37,6 +37,17 @@ export type FlinkJobProps = {
      * retried after the next interval.
      */
     singleton?: boolean;
+
+    /**
+     * If true, this job will run on all instances regardless of leader election.
+     *
+     * By default, when leader election is enabled, jobs only run on the leader instance.
+     * Set this to true for jobs that should run on every instance, such as
+     * local cache cleanup or instance-specific health checks.
+     *
+     * Has no effect when leader election is not enabled.
+     */
+    runOnAllInstances?: boolean;
 };
 
 /**

package/src/FlinkLog.ts

@@ -1,16 +1,123 @@
-import Logger from "node-color-log";
+import { FlinkLogFactory } from "./FlinkLogFactory";
 
+type LogLevel = "trace" | "debug" | "info" | "warn" | "error";
+
+/**
+ * Lazy-loaded application logger using FlinkLogFactory
+ *
+ * This logger uses the component name "app" and respects all
+ * logging configuration from flink.config.js and environment variables.
+ *
+ * Configured via:
+ * - flink.config.js: components["app"] = "debug"
+ * - Environment: LOG_LEVEL=debug
+ * - Programmatic: FlinkLogFactory.setComponentLevel("app", "debug")
+ */
+let appLogger: ReturnType<typeof FlinkLogFactory.createLogger> | null = null;
+
+/**
+ * Get or create the app logger (lazy initialization)
+ */
+function getAppLogger() {
+    if (!appLogger) {
+        appLogger = FlinkLogFactory.createLogger("app");
+    }
+    return appLogger;
+}
+
+/**
+ * Simple logging utility with proper stdout/stderr separation
+ *
+ * Following Unix/POSIX best practices:
+ * - trace, debug, info → stdout (normal output)
+ * - warn, error → stderr (diagnostic output)
+ *
+ * Benefits:
+ * - Respects flink.config.js logging configuration
+ * - Container orchestration can capture streams separately
+ * - Shell redirection works correctly (command > out.log 2> err.log)
+ * - Log aggregation tools can route differently
+ * - Monitoring systems can alert on stderr only
+ *
+ * @example
+ * ```typescript
+ * import { log } from "@flink-app/flink";
+ *
+ * log.trace("Detailed trace info");
+ * log.debug("Debug information");
+ * log.info("General information");
+ * log.warn("Warning message");
+ * log.error("Error message");
+ * ```
+ *
+ * @example Configure via flink.config.js
+ * ```javascript
+ * module.exports = {
+ *   logging: {
+ *     components: {
+ *       "app": "debug"  // Enable debug for default log
+ *     }
+ *   }
+ * };
+ * ```
+ */
 export const log = {
-    debug: Logger.debug.bind(Logger),
-    info: Logger.info.bind(Logger),
-    warn: Logger.warn.bind(Logger),
-    error: Logger.error.bind(Logger),
-    json: (...args: any) => {
-        for (const o of args) {
-            console.log(JSON.stringify(o, null, 2));
-        }
+    /**
+     * Trace logs (stdout)
+     * Use for extremely detailed diagnostic information (most verbose level)
+     */
+    trace: (...args: any[]) => getAppLogger().trace(...args),
+
+    /**
+     * Debug logs (stdout)
+     * Use for detailed diagnostic information during development
+     */
+    debug: (...args: any[]) => getAppLogger().debug(...args),
+
+    /**
+     * Info logs (stdout)
+     * Use for general informational messages about application state
+     */
+    info: (...args: any[]) => getAppLogger().info(...args),
+
+    /**
+     * Warning logs (stderr)
+     * Use for potentially harmful situations that aren't errors
+     * Writes to stderr following Unix/POSIX best practices
+     */
+    warn: (...args: any[]) => getAppLogger().warn(...args),
+
+    /**
+     * Error logs (stderr)
+     * Use for error events that might still allow the app to continue
+     * Writes to stderr following Unix/POSIX best practices
+     */
+    error: (...args: any[]) => getAppLogger().error(...args),
+
+    /**
+     * JSON output (stdout)
+     * Use for structured data output
+     */
+    json: (...args: any[]) => getAppLogger().json(...args),
+
+    /**
+     * Colored background log (stdout)
+     * Use for highlighted messages during development
+     */
+    bgColorLog: (color: string, ...args: any[]) => getAppLogger().bgColorLog(color, ...args),
+
+    /**
+     * Colored font log (stdout)
+     * Use for colored messages during development
+     */
+    fontColorLog: (color: string, ...args: any[]) => getAppLogger().fontColorLog(color, ...args),
+
+    /**
+     * Set log level for the default "app" logger
+     *
+     * @deprecated Use flink.config.js or FlinkLogFactory.setComponentLevel("app", level) instead
+     */
+    setLevel: (level: LogLevel) => {
+        getAppLogger().setLevel(level);
     },
-    bgColorLog: Logger.bgColorLog.bind(Logger),
-    fontColorLog: Logger.fontColorLog.bind(Logger),
-    setLevel: (level: "debug" | "info" | "warn" | "error") => Logger.setLevel.bind(Logger)(level),
 };