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

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # @flink-app/flink
 
+## 2.0.0-alpha.48
+
+### Minor Changes
+
+-   AI features
+
+## 1.0.0
+
+### Minor Changes
+
+-   Align minor version, from now all packages in monorepo will have same version
+-   5c2ff97: Add schema validation bypass options to RouteProps
+
+    Handlers can now control schema validation behavior via the new `validation` property in `RouteProps`:
+
+    -   `ValidationMode.Validate` (default): Validate both request and response
+    -   `ValidationMode.SkipValidation`: Skip both request and response validation
+    -   `ValidationMode.ValidateRequest`: Validate only request, skip response validation
+    -   `ValidationMode.ValidateResponse`: Validate only response, skip request validation
+
+    This is useful for handlers that need custom validation logic or want to bypass validation for performance reasons. The feature is opt-in and defaults to existing behavior.
+
+    **Security Considerations:**
+
+    ⚠️ Use validation bypass options carefully:
+
+    -   `SkipValidation` and `ValidateRequest: false` allow unvalidated data to reach handlers, which can introduce security risks
+    -   Only skip validation when you have implemented custom validation logic or the endpoint is internal/trusted
+    -   Suitable use cases include: webhook handlers with custom signature verification, performance-critical internal endpoints, or handlers using alternative validation methods
+    -   When skipping response validation, ensure your code returns consistent data shapes to avoid breaking API contracts
+
+    Example usage:
+
+    ```typescript
+    // Skip validation for webhook with custom verification
+    export const Route: RouteProps = {
+        path: "/webhook",
+        validation: ValidationMode.SkipValidation,
+    };
+
+    // Validate request but allow flexible response during development
+    export const Route: RouteProps = {
+        path: "/api/debug",
+        validation: ValidationMode.ValidateRequest,
+    };
+    ```
+
+### Patch Changes
+
+-   ee21c29: Normalize query parameters to predictable string types
+
+    Query parameters are now automatically normalized to `string | string[]` types before reaching handlers:
+
+    -   Single values: converted to strings (e.g., `?page=1` → `{ page: "1" }`)
+    -   Repeated parameters: converted to string arrays (e.g., `?tag=a&tag=b` → `{ tag: ["a", "b"] }`)
+    -   All types (numbers, booleans, etc.) from Express parser are converted to strings
+
+    **Breaking Change (Minor):**
+
+    -   `Query` type changed from `{ [x: string]: string | string[] | undefined }` to `Record<string, string | string[]>`
+    -   `Params` type changed from `Request["params"]` to explicit `Record<string, string>`
+    -   Removed `undefined` from query/param types since normalization ensures values are never undefined
+    -   Updated OAuth and OIDC plugin query type definitions to satisfy new Query constraint
+
+    This ensures predictable query and path parameter handling regardless of Express parser configuration. Handlers can reliably parse string values as needed using `Number()`, `parseInt()`, boolean comparisons, etc.
+
 ## 0.14.3
 
 ### Patch Changes

package/cli/build.ts

@@ -40,7 +40,14 @@ module.exports = async function run(args: string[]) {
         process.exit(1);
     }
 
-    await Promise.all([compiler.parseRepos(), compiler.parseHandlers(exclude.split(",")), compiler.parseJobs(), compiler.generateStartScript()]);
+    await Promise.all([
+        compiler.parseRepos(),
+        compiler.parseHandlers(exclude.split(",")),
+        compiler.parseTools(),
+        compiler.parseAgents(),
+        compiler.parseJobs(),
+        compiler.generateStartScript(),
+    ]);
 
     console.log(`Compilation done, took ${Date.now() - startTime}ms`);
 

package/cli/run.ts

@@ -63,7 +63,14 @@ module.exports = async function run(args: string[]) {
         process.exit(1);
     }
 
-    await Promise.all([compiler.parseRepos(), compiler.parseHandlers(), compiler.parseJobs(), compiler.generateStartScript(entry)]);
+    await Promise.all([
+        compiler.parseRepos(),
+        compiler.parseHandlers(),
+        compiler.parseTools(),
+        compiler.parseAgents(),
+        compiler.parseJobs(),
+        compiler.generateStartScript(entry)
+    ]);
 
     console.log(`Compilation done, took ${Date.now() - startTime}ms`);
 

package/dist/cli/build.js

@@ -65,7 +65,14 @@ module.exports = function run(args) {
                     if (!compiler.getPreEmitDiagnostics()) {
                         process.exit(1);
                     }
-                    return [4 /*yield*/, Promise.all([compiler.parseRepos(), compiler.parseHandlers(exclude.split(",")), compiler.parseJobs(), compiler.generateStartScript()])];
+                    return [4 /*yield*/, Promise.all([
+                            compiler.parseRepos(),
+                            compiler.parseHandlers(exclude.split(",")),
+                            compiler.parseTools(),
+                            compiler.parseAgents(),
+                            compiler.parseJobs(),
+                            compiler.generateStartScript(),
+                        ])];
                 case 2:
                     _a.sent();
                     console.log("Compilation done, took ".concat(Date.now() - startTime, "ms"));

package/dist/cli/run.js

@@ -83,7 +83,14 @@ module.exports = function run(args) {
                     if (!compiler.getPreEmitDiagnostics()) {
                         process.exit(1);
                     }
-                    return [4 /*yield*/, Promise.all([compiler.parseRepos(), compiler.parseHandlers(), compiler.parseJobs(), compiler.generateStartScript(entry)])];
+                    return [4 /*yield*/, Promise.all([
+                            compiler.parseRepos(),
+                            compiler.parseHandlers(),
+                            compiler.parseTools(),
+                            compiler.parseAgents(),
+                            compiler.parseJobs(),
+                            compiler.generateStartScript(entry)
+                        ])];
                 case 2:
                     _a.sent();
                     console.log("Compilation done, took ".concat(Date.now() - startTime, "ms"));

package/dist/src/FlinkApp.d.ts

@@ -3,6 +3,9 @@ import express, { Express } from "express";
 import { JSONSchema7 } from "json-schema";
 import { Db, MongoClient } from "mongodb";
 import { ToadScheduler } from "toad-scheduler";
+import { FlinkAgentFile } from "./ai/FlinkAgent";
+import { FlinkToolFile } from "./ai/FlinkTool";
+import { LLMAdapter } from "./ai/LLMAdapter";
 import { FlinkAuthPlugin } from "./auth/FlinkAuthPlugin";
 import { FlinkContext } from "./FlinkContext";
 import { FlinkError } from "./FlinkErrors";
@@ -39,6 +42,16 @@ export declare const autoRegisteredRepos: {
  * are picked up by TypeScript compiler
  */
 export declare const autoRegisteredJobs: FlinkJobFile[];
+/**
+ * This will be populated at compile time when the apps tools
+ * are picked up by TypeScript compiler
+ */
+export declare const autoRegisteredTools: FlinkToolFile[];
+/**
+ * This will be populated at compile time when the apps agents
+ * are picked up by TypeScript compiler
+ */
+export declare const autoRegisteredAgents: FlinkAgentFile[];
 export interface FlinkOptions {
     /**
      * Name of application, will only show in logs and in HTTP header.
@@ -118,6 +131,16 @@ export interface FlinkOptions {
          */
         enabled?: boolean;
     };
+    /**
+     * AI configuration for agents and tools
+     * Register LLM adapters with custom IDs (e.g., "anthropic", "openai", "anthropic-eu", etc.)
+     * This allows multiple adapters of the same type with different configurations
+     */
+    ai?: {
+        llms?: {
+            [id: string]: LLMAdapter;
+        };
+    };
     /**
      * If true, the HTTP server will be disabled.
      * Only useful when starting a Flink app for testing purposes.
@@ -226,6 +249,9 @@ export declare class FlinkApp<C extends FlinkContext> {
     private expressServer;
     private onError?;
     private repos;
+    private llmAdapters;
+    private tools;
+    private agents;
     /**
      * Internal cache used to track registered handlers and potentially any overlapping routes
      */
@@ -253,11 +279,18 @@ export declare class FlinkApp<C extends FlinkContext> {
     private registerAutoRegisterableHandlers;
     private registerAutoRegisterableJobs;
     addRepo(instanceName: string, repoInstance: FlinkRepo<C, any>): void;
+    private registerAutoRegisterableTools;
+    private registerAutoRegisterableAgents;
     /**
      * Constructs the app context. Will inject context in all components
      * except for handlers which are handled in later stage.
      */
     private buildContext;
+    /**
+     * Initialize agents after they've been registered and context is ready
+     * Must be called after registerAutoRegisterableAgents()
+     */
+    private initializeAgents;
     /**
      * Connects to database.
      */