@flink-app/flink 1.0.0 → 2.0.0-alpha.101

package/dist/src/FlinkContext.d.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: {
         [x: string]: FlinkRepo<any, any>;
@@ -9,4 +11,43 @@ 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/dist/src/FlinkErrors.d.ts

@@ -6,36 +6,46 @@ 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 declare function notFound(detail?: string, code?: string): FlinkResponse<FlinkError>;
+export declare function notFound(detail?: string, code?: string, meta?: unknown): FlinkResponse<FlinkError>;
 /**
  * Returns a 409 Conflict error response.
  * Use when a request conflicts with existing data (e.g., duplicate username/email).
  *
  * @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 declare function conflict(detail?: string, code?: string): FlinkResponse<FlinkError>;
+export declare function conflict(detail?: string, code?: string, meta?: unknown): FlinkResponse<FlinkError>;
 /**
  * Returns a 400 Bad Request error response.
  * Use when the request is malformed or contains invalid data (e.g., validation errors).
  *
  * @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 declare function badRequest(detail?: string, code?: string): FlinkResponse<FlinkError>;
+export declare function badRequest(detail?: string, code?: string, meta?: unknown): FlinkResponse<FlinkError>;
 /**
  * Returns a 401 Unauthorized error response.
  * Use when authentication is required but missing or invalid (e.g., no token, expired token).
@@ -43,12 +53,13 @@ export declare function badRequest(detail?: string, code?: string): FlinkRespons
  *
  * @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 declare function unauthorized(detail?: string, code?: string): FlinkResponse<FlinkError>;
+export declare function unauthorized(detail?: string, code?: string, meta?: unknown): FlinkResponse<FlinkError>;
 /**
  * Returns a 403 Forbidden error response.
  * Use when the user is authenticated but lacks permission to access the resource.
@@ -56,21 +67,23 @@ export declare function unauthorized(detail?: string, code?: string): FlinkRespo
  *
  * @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 declare function forbidden(detail?: string, code?: string): FlinkResponse<FlinkError>;
+export declare function forbidden(detail?: string, code?: string, meta?: unknown): FlinkResponse<FlinkError>;
 /**
  * Returns a 500 Internal Server Error response.
  * Use when an unexpected error occurs on the server side.
  *
  * @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"); }
  * ```
  */
-export declare function internalServerError(detail?: string, code?: string): FlinkResponse<FlinkError>;
+export declare function internalServerError(detail?: string, code?: string, meta?: unknown): FlinkResponse<FlinkError>;

package/dist/src/FlinkErrors.js

@@ -1,4 +1,15 @@
 "use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.notFound = notFound;
 exports.conflict = conflict;
@@ -13,20 +24,17 @@ var uuid_1 = require("uuid");
  *
  * @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 });
  * ```
  */
-function notFound(detail, code) {
+function notFound(detail, code, meta) {
     return {
         status: 404,
-        error: {
-            id: (0, uuid_1.v4)(),
-            title: "Not Found",
-            detail: detail || "The requested resource does not exist",
-            code: code || "notFound"
-        },
+        error: __assign({ id: (0, uuid_1.v4)(), title: "Not Found", detail: detail || "The requested resource does not exist", code: code || "notFound" }, (meta !== undefined && { meta: meta })),
     };
 }
 /**
@@ -35,20 +43,16 @@ function notFound(detail, code) {
  *
  * @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");
  * ```
  */
-function conflict(detail, code) {
+function conflict(detail, code, meta) {
     return {
         status: 409,
-        error: {
-            id: (0, uuid_1.v4)(),
-            title: "Conflict",
-            detail: detail || "An identical entity exits",
-            code: code || "conflict"
-        },
+        error: __assign({ id: (0, uuid_1.v4)(), title: "Conflict", detail: detail || "An identical entity exits", code: code || "conflict" }, (meta !== undefined && { meta: meta })),
     };
 }
 /**
@@ -57,20 +61,22 @@ function conflict(detail, code) {
  *
  * @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",
+ * });
  * ```
  */
-function badRequest(detail, code) {
+function badRequest(detail, code, meta) {
     return {
         status: 400,
-        error: {
-            id: (0, uuid_1.v4)(),
-            title: "Bad Request",
-            detail: detail || "Invalid request",
-            code: code || "badRequest"
-        },
+        error: __assign({ id: (0, uuid_1.v4)(), title: "Bad Request", detail: detail || "Invalid request", code: code || "badRequest" }, (meta !== undefined && { meta: meta })),
     };
 }
 /**
@@ -80,20 +86,16 @@ function badRequest(detail, code) {
  *
  * @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");
  * ```
  */
-function unauthorized(detail, code) {
+function unauthorized(detail, code, meta) {
     return {
         status: 401,
-        error: {
-            id: (0, uuid_1.v4)(),
-            title: "Unauthorized",
-            detail: detail || "Authentication required",
-            code: code || "unauthorized"
-        },
+        error: __assign({ id: (0, uuid_1.v4)(), title: "Unauthorized", detail: detail || "Authentication required", code: code || "unauthorized" }, (meta !== undefined && { meta: meta })),
     };
 }
 /**
@@ -103,20 +105,16 @@ function unauthorized(detail, code) {
  *
  * @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");
  * ```
  */
-function forbidden(detail, code) {
+function forbidden(detail, code, meta) {
     return {
         status: 403,
-        error: {
-            id: (0, uuid_1.v4)(),
-            title: "Forbidden",
-            detail: detail || "You do not have permission to access this resource",
-            code: code || "forbidden"
-        },
+        error: __assign({ id: (0, uuid_1.v4)(), title: "Forbidden", detail: detail || "You do not have permission to access this resource", code: code || "forbidden" }, (meta !== undefined && { meta: meta })),
     };
 }
 /**
@@ -125,19 +123,15 @@ function forbidden(detail, code) {
  *
  * @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"); }
  * ```
  */
-function internalServerError(detail, code) {
+function internalServerError(detail, code, meta) {
     return {
         status: 500,
-        error: {
-            id: (0, uuid_1.v4)(),
-            title: "Internal Server Error",
-            detail: detail || "Something unexpected went wrong",
-            code: code || "internalServerError"
-        },
+        error: __assign({ id: (0, uuid_1.v4)(), title: "Internal Server Error", detail: detail || "Something unexpected went wrong", code: code || "internalServerError" }, (meta !== undefined && { meta: meta })),
     };
 }

package/dist/src/FlinkHttpHandler.d.ts

@@ -1,5 +1,4 @@
 import { Request } from "express";
-import { JSONSchema } from "./FlinkApp";
 import { FlinkContext } from "./FlinkContext";
 import { FlinkError } from "./FlinkErrors";
 import { FlinkResponse } from "./FlinkResponse";
@@ -57,11 +56,55 @@ type Params = Record<string, string>;
  */
 type Query = Record<string, string | string[]>;
 /**
- * Flink request extends express Request but adds reqId and user object.
+ * 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, 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;
+    userPermissions?: string[];
+    token?: any;
+    rawToken?: string;
 };
 /**
  * Route props to control routing.
@@ -93,6 +136,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[];
     /**
@@ -136,15 +200,104 @@ export interface RouteProps {
      * @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>>;
 /**
  * Http handler function specifically for GET requests as those does
@@ -163,24 +316,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 = {
     name: string;

package/dist/src/FlinkJob.d.ts

@@ -31,6 +31,16 @@ 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;
 };
 /**
  * Type for Flink job function. This function should be default exported from

package/dist/src/FlinkLog.d.ts

@@ -1,24 +1,88 @@
+type LogLevel = "trace" | "debug" | "info" | "warn" | "error";
+/**
+ * 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 declare const log: {
+    /**
+     * Trace logs (stdout)
+     * Use for extremely detailed diagnostic information (most verbose level)
+     */
+    trace: (...args: any[]) => void;
+    /**
+     * Debug logs (stdout)
+     * Use for detailed diagnostic information during development
+     */
     debug: (...args: any[]) => void;
+    /**
+     * Info logs (stdout)
+     * Use for general informational messages about application state
+     */
     info: (...args: any[]) => void;
+    /**
+     * Warning logs (stderr)
+     * Use for potentially harmful situations that aren't errors
+     * Writes to stderr following Unix/POSIX best practices
+     */
     warn: (...args: any[]) => void;
+    /**
+     * 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[]) => void;
-    json: (...args: any) => void;
-    bgColorLog: (ticket: "black" | "red" | "green" | "yellow" | "blue" | "magenta" | "cyan" | "white", text: string, setting?: {
-        reverse?: boolean | undefined;
-        bold?: boolean | undefined;
-        italic?: boolean | undefined;
-        dim?: boolean | undefined;
-        underscore?: boolean | undefined;
-        strikethrough?: boolean | undefined;
-    }) => void;
-    fontColorLog: (ticket: "black" | "red" | "green" | "yellow" | "blue" | "magenta" | "cyan" | "white", text: string, setting?: {
-        reverse?: boolean | undefined;
-        bold?: boolean | undefined;
-        italic?: boolean | undefined;
-        dim?: boolean | undefined;
-        underscore?: boolean | undefined;
-        strikethrough?: boolean | undefined;
-    }) => void;
-    setLevel: (level: "debug" | "info" | "warn" | "error") => void;
+    /**
+     * JSON output (stdout)
+     * Use for structured data output
+     */
+    json: (...args: any[]) => void;
+    /**
+     * Colored background log (stdout)
+     * Use for highlighted messages during development
+     */
+    bgColorLog: (color: string, ...args: any[]) => void;
+    /**
+     * Colored font log (stdout)
+     * Use for colored messages during development
+     */
+    fontColorLog: (color: string, ...args: any[]) => void;
+    /**
+     * Set log level for the default "app" logger
+     *
+     * @deprecated Use flink.config.js or FlinkLogFactory.setComponentLevel("app", level) instead
+     */
+    setLevel: (level: LogLevel) => void;
 };
+export {};