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

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";
@@ -10,24 +9,102 @@ 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";
 /**
- * Flink request extends express Request but adds reqId and user object.
+ * 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.
@@ -59,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[];
     /**
@@ -82,15 +180,124 @@ 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>>;
 /**
  * Http handler function specifically for GET requests as those does
@@ -109,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/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/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