@synergenius/flow-weaver 0.2.0

package/dist/runtime/function-registry.js

@@ -0,0 +1,66 @@
+/**
+ * Function Registry for Flow Weaver
+ *
+ * Provides a global registry of functions that can be referenced by string IDs
+ * in external HTTP calls while allowing direct function passing in internal calls.
+ */
+export class FunctionRegistry {
+    functions = new Map();
+    /**
+     * Register a function with the registry
+     */
+    register(config) {
+        if (this.functions.has(config.id)) {
+            throw new Error(`Function with ID '${config.id}' is already registered`);
+        }
+        this.functions.set(config.id, config);
+    }
+    /**
+     * Get a function by ID
+     */
+    get(id) {
+        const registered = this.functions.get(id);
+        return registered?.fn;
+    }
+    /**
+     * Get function metadata without the function itself
+     */
+    getMetadata(id) {
+        const registered = this.functions.get(id);
+        if (!registered)
+            return undefined;
+        const { fn: _, ...metadata } = registered;
+        return metadata;
+    }
+    /**
+     * List all registered functions, optionally filtered by category
+     */
+    list(category) {
+        const all = Array.from(this.functions.values());
+        const filtered = category ? all.filter((f) => f.category === category) : all;
+        return filtered.map(({ fn: _, ...metadata }) => metadata);
+    }
+    /**
+     * Check if a function is registered
+     */
+    has(id) {
+        return this.functions.has(id);
+    }
+    /**
+     * Clear all registered functions (useful for testing)
+     */
+    clear() {
+        this.functions.clear();
+    }
+    /**
+     * Get the count of registered functions
+     */
+    get size() {
+        return this.functions.size;
+    }
+}
+/**
+ * Global function registry singleton
+ */
+export const functionRegistry = new FunctionRegistry();
+//# sourceMappingURL=function-registry.js.map

package/dist/runtime/index.d.ts

@@ -0,0 +1,7 @@
+export { GeneratedExecutionContext } from "./ExecutionContext.js";
+export { CancellationError } from "./CancellationError.js";
+export * from "./events.js";
+export * from "./function-registry.js";
+export * from "./parameter-resolver.js";
+export * from "./builtin-functions.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/runtime/index.js

@@ -0,0 +1,7 @@
+export { GeneratedExecutionContext } from "./ExecutionContext.js";
+export { CancellationError } from "./CancellationError.js";
+export * from "./events.js";
+export * from "./function-registry.js";
+export * from "./parameter-resolver.js";
+export * from "./builtin-functions.js";
+//# sourceMappingURL=index.js.map

package/dist/runtime/parameter-resolver.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Parameter Resolver for Flow Weaver
+ *
+ * Resolves function-like parameters to executable functions.
+ * Supports:
+ * - Direct functions (passed through)
+ * - Registry IDs (looked up in function registry)
+ * - Partial application (registry ID with pre-bound arguments)
+ */
+/**
+ * A function-like parameter that can be:
+ * - A direct function
+ * - A string registry ID
+ * - An object with registry ID and partial arguments
+ */
+export type FunctionLike<TIn, TOut> = ((input: TIn) => TOut | Promise<TOut>) | string | {
+    registryId: string;
+    partialArgs?: Partial<TIn>;
+};
+/**
+ * Result of resolving a function parameter
+ */
+export interface ResolvedFunction<TIn, TOut> {
+    fn: (input: TIn) => TOut | Promise<TOut>;
+    source: 'direct' | 'registry';
+    registryId?: string;
+}
+/**
+ * Resolve a function-like parameter to an executable function
+ *
+ * @param param - The function-like parameter to resolve
+ * @returns The resolved function with metadata
+ * @throws Error if registry ID is not found
+ *
+ * @example
+ * // Direct function
+ * const resolved = resolveFunction((x: number) => x * 2);
+ * resolved.fn(5); // 10
+ *
+ * @example
+ * // Registry ID
+ * const resolved = resolveFunction('string:uppercase');
+ * resolved.fn('hello'); // 'HELLO'
+ *
+ * @example
+ * // Partial application
+ * const resolved = resolveFunction({
+ *   registryId: 'math:clamp',
+ *   partialArgs: { min: 0, max: 100 }
+ * });
+ * resolved.fn({ value: 150 }); // 100
+ */
+export declare function resolveFunction<TIn, TOut>(param: FunctionLike<TIn, TOut>): ResolvedFunction<TIn, TOut>;
+/**
+ * Check if a value is a function-like parameter
+ */
+export declare function isFunctionLike(value: unknown): value is FunctionLike<unknown, unknown>;
+/**
+ * Try to resolve a function, returning undefined if not found
+ */
+export declare function tryResolveFunction<TIn, TOut>(param: FunctionLike<TIn, TOut>): ResolvedFunction<TIn, TOut> | undefined;
+//# sourceMappingURL=parameter-resolver.d.ts.map

package/dist/runtime/parameter-resolver.js

@@ -0,0 +1,113 @@
+/**
+ * Parameter Resolver for Flow Weaver
+ *
+ * Resolves function-like parameters to executable functions.
+ * Supports:
+ * - Direct functions (passed through)
+ * - Registry IDs (looked up in function registry)
+ * - Partial application (registry ID with pre-bound arguments)
+ */
+import { functionRegistry } from './function-registry.js';
+/**
+ * Resolve a function-like parameter to an executable function
+ *
+ * @param param - The function-like parameter to resolve
+ * @returns The resolved function with metadata
+ * @throws Error if registry ID is not found
+ *
+ * @example
+ * // Direct function
+ * const resolved = resolveFunction((x: number) => x * 2);
+ * resolved.fn(5); // 10
+ *
+ * @example
+ * // Registry ID
+ * const resolved = resolveFunction('string:uppercase');
+ * resolved.fn('hello'); // 'HELLO'
+ *
+ * @example
+ * // Partial application
+ * const resolved = resolveFunction({
+ *   registryId: 'math:clamp',
+ *   partialArgs: { min: 0, max: 100 }
+ * });
+ * resolved.fn({ value: 150 }); // 100
+ */
+export function resolveFunction(param) {
+    // Direct function - pass through
+    if (typeof param === 'function') {
+        return {
+            fn: param,
+            source: 'direct',
+        };
+    }
+    // String registry ID
+    if (typeof param === 'string') {
+        const fn = functionRegistry.get(param);
+        if (!fn) {
+            throw new Error(`Function '${param}' not found in registry`);
+        }
+        return {
+            fn,
+            source: 'registry',
+            registryId: param,
+        };
+    }
+    // Object with registry ID and optional partial args
+    if (typeof param === 'object' && param !== null && 'registryId' in param) {
+        const fn = functionRegistry.get(param.registryId);
+        if (!fn) {
+            throw new Error(`Function '${param.registryId}' not found in registry`);
+        }
+        // If partial args provided, create wrapper that merges them
+        if (param.partialArgs) {
+            const partialArgs = param.partialArgs;
+            const wrappedFn = (input) => {
+                // Merge partial args with input (input takes precedence for conflicting keys)
+                const mergedInput = typeof input === 'object' && input !== null
+                    ? { ...partialArgs, ...input }
+                    : input;
+                return fn(mergedInput);
+            };
+            return {
+                fn: wrappedFn,
+                source: 'registry',
+                registryId: param.registryId,
+            };
+        }
+        return {
+            fn,
+            source: 'registry',
+            registryId: param.registryId,
+        };
+    }
+    throw new Error(`Invalid function parameter: ${JSON.stringify(param)}`);
+}
+/**
+ * Check if a value is a function-like parameter
+ */
+export function isFunctionLike(value) {
+    if (typeof value === 'function')
+        return true;
+    if (typeof value === 'string')
+        return true;
+    if (typeof value === 'object' &&
+        value !== null &&
+        'registryId' in value &&
+        typeof value.registryId === 'string') {
+        return true;
+    }
+    return false;
+}
+/**
+ * Try to resolve a function, returning undefined if not found
+ */
+export function tryResolveFunction(param) {
+    try {
+        return resolveFunction(param);
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=parameter-resolver.js.map

package/dist/server/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Server module exports
+ */
+export { WebhookServer } from './webhook-server.js';
+export { WorkflowRegistry } from './workflow-registry.js';
+export type { WebhookServerConfig, WorkflowEndpoint, ExecutionResult, HealthResponse, WorkflowListResponse, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/server/index.js

@@ -0,0 +1,6 @@
+/**
+ * Server module exports
+ */
+export { WebhookServer } from './webhook-server.js';
+export { WorkflowRegistry } from './workflow-registry.js';
+//# sourceMappingURL=index.js.map

package/dist/server/types.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Type definitions for the webhook server
+ */
+/**
+ * Represents a workflow exposed as an HTTP endpoint
+ */
+export interface WorkflowEndpoint {
+    /** Workflow name (used in URL path) */
+    name: string;
+    /** Function name in the source file */
+    functionName: string;
+    /** Path to the source file */
+    filePath: string;
+    /** HTTP method for the endpoint */
+    method: 'POST' | 'GET';
+    /** URL path for the endpoint */
+    path: string;
+    /** JSON Schema for input parameters */
+    inputSchema?: Record<string, unknown>;
+    /** JSON Schema for output */
+    outputSchema?: Record<string, unknown>;
+    /** Workflow description */
+    description?: string;
+}
+/**
+ * Configuration for the webhook server
+ */
+export interface WebhookServerConfig {
+    /** Port to listen on */
+    port: number;
+    /** Host to bind to */
+    host: string;
+    /** Directory containing workflow files */
+    workflowDir: string;
+    /** Enable file watching for hot reload */
+    watchEnabled: boolean;
+    /** CORS origin configuration */
+    corsOrigin: string | string[];
+    /** Production mode (no trace events) */
+    production: boolean;
+    /** Precompile workflows on startup */
+    precompile: boolean;
+    /** Enable Swagger UI at /docs and OpenAPI spec at /openapi.json */
+    swaggerEnabled?: boolean;
+}
+/**
+ * Result of workflow execution via HTTP
+ */
+export interface ExecutionResult {
+    /** Whether execution succeeded */
+    success: boolean;
+    /** Name of the executed workflow */
+    workflow: string;
+    /** Execution time in milliseconds */
+    executionTime: number;
+    /** Execution result (if successful) */
+    result?: unknown;
+    /** Error details (if failed) */
+    error?: {
+        message: string;
+        stack?: string;
+    };
+    /** Execution trace events (if requested) */
+    trace?: Array<{
+        type: string;
+        timestamp: number;
+        data?: unknown;
+    }>;
+}
+/**
+ * Health check response
+ */
+export interface HealthResponse {
+    status: 'ok' | 'error';
+    timestamp: string;
+    workflows: number;
+    uptime?: number;
+}
+/**
+ * Workflow list response
+ */
+export interface WorkflowListResponse {
+    count: number;
+    workflows: Array<{
+        name: string;
+        path: string;
+        method: string;
+        description?: string;
+        inputSchema?: Record<string, unknown>;
+        outputSchema?: Record<string, unknown>;
+    }>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/server/types.js

@@ -0,0 +1,5 @@
+/**
+ * Type definitions for the webhook server
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/server/webhook-server.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Webhook server for exposing workflows as HTTP endpoints
+ */
+import type { WebhookServerConfig } from './types.js';
+/**
+ * HTTP server that exposes Flow Weaver workflows as REST endpoints
+ */
+export declare class WebhookServer {
+    private fastify;
+    private registry;
+    private config;
+    constructor(config: WebhookServerConfig);
+    /**
+     * Start the HTTP server
+     */
+    start(): Promise<void>;
+    /**
+     * Setup health check endpoint
+     */
+    private setupHealthRoute;
+    /**
+     * Setup workflow list endpoint
+     */
+    private setupListRoute;
+    /**
+     * Setup dynamic workflow execution route
+     */
+    private setupExecuteRoute;
+    /**
+     * Build OpenAPI spec from discovered workflows
+     */
+    private buildOpenApiSpec;
+    /**
+     * Setup Swagger UI and OpenAPI spec routes
+     */
+    private setupSwaggerRoutes;
+    /**
+     * Get server info for external logging
+     */
+    getServerInfo(): {
+        port: number;
+        host: string;
+        endpoints: number;
+    };
+    /**
+     * Stop the HTTP server
+     */
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=webhook-server.d.ts.map

package/dist/server/webhook-server.js

@@ -0,0 +1,269 @@
+/**
+ * Webhook server for exposing workflows as HTTP endpoints
+ */
+import { WorkflowRegistry } from './workflow-registry.js';
+import { executeWorkflowFromFile } from '../mcp/workflow-executor.js';
+/**
+ * HTTP server that exposes Flow Weaver workflows as REST endpoints
+ */
+export class WebhookServer {
+    fastify = null;
+    registry;
+    config;
+    constructor(config) {
+        this.config = config;
+        this.registry = new WorkflowRegistry(config.workflowDir, {
+            precompile: config.precompile,
+            production: config.production,
+        });
+    }
+    /**
+     * Start the HTTP server
+     */
+    async start() {
+        // Dynamic import Fastify
+        const Fastify = await import('fastify');
+        this.fastify = Fastify.default({ logger: false });
+        // Register CORS
+        try {
+            const cors = await import('@fastify/cors');
+            await this.fastify.register(cors.default, { origin: this.config.corsOrigin });
+        }
+        catch {
+            // CORS plugin not available, continue without it
+        }
+        // Initialize registry
+        await this.registry.initialize();
+        // Setup routes
+        this.setupHealthRoute();
+        this.setupListRoute();
+        this.setupExecuteRoute();
+        // Setup Swagger UI routes if enabled
+        if (this.config.swaggerEnabled) {
+            this.setupSwaggerRoutes();
+        }
+        // Start file watching
+        if (this.config.watchEnabled) {
+            await this.registry.startWatching(() => {
+                // Workflows reloaded - could emit event here if needed
+            });
+        }
+        // Start server
+        await this.fastify.listen({ port: this.config.port, host: this.config.host });
+    }
+    /**
+     * Setup health check endpoint
+     */
+    setupHealthRoute() {
+        if (!this.fastify)
+            return;
+        this.fastify.get('/health', async () => {
+            return {
+                status: 'ok',
+                timestamp: new Date().toISOString(),
+                workflows: this.registry.getAllEndpoints().length,
+                uptime: this.registry.getUptime(),
+            };
+        });
+    }
+    /**
+     * Setup workflow list endpoint
+     */
+    setupListRoute() {
+        if (!this.fastify)
+            return;
+        this.fastify.get('/workflows', async () => {
+            const endpoints = this.registry.getAllEndpoints();
+            return {
+                count: endpoints.length,
+                workflows: endpoints.map((e) => ({
+                    name: e.name,
+                    path: e.path,
+                    method: e.method,
+                    description: e.description,
+                    inputSchema: e.inputSchema,
+                    outputSchema: e.outputSchema,
+                })),
+            };
+        });
+    }
+    /**
+     * Setup dynamic workflow execution route
+     */
+    setupExecuteRoute() {
+        if (!this.fastify)
+            return;
+        // POST /workflows/:name
+        this.fastify.post('/workflows/:name', async (request, reply) => {
+            const { name } = request.params;
+            const params = request.body || {};
+            const includeTrace = request.query?.trace === 'true';
+            const endpoint = this.registry.getEndpoint(name);
+            if (!endpoint) {
+                reply.status(404);
+                return {
+                    success: false,
+                    workflow: name,
+                    executionTime: 0,
+                    error: { message: `Workflow "${name}" not found` },
+                };
+            }
+            const startTime = Date.now();
+            try {
+                const result = await executeWorkflowFromFile(endpoint.filePath, params, {
+                    workflowName: endpoint.functionName,
+                    production: this.config.production,
+                    includeTrace,
+                });
+                const response = {
+                    success: true,
+                    workflow: result.functionName,
+                    executionTime: result.executionTime,
+                    result: result.result,
+                };
+                if (includeTrace && result.trace) {
+                    response.trace = result.trace;
+                }
+                return response;
+            }
+            catch (error) {
+                reply.status(500);
+                return {
+                    success: false,
+                    workflow: endpoint.functionName,
+                    executionTime: Date.now() - startTime,
+                    error: {
+                        message: error instanceof Error ? error.message : String(error),
+                        stack: error instanceof Error ? error.stack : undefined,
+                    },
+                };
+            }
+        });
+    }
+    /**
+     * Build OpenAPI spec from discovered workflows
+     */
+    buildOpenApiSpec() {
+        const endpoints = this.registry.getAllEndpoints();
+        const paths = {};
+        for (const endpoint of endpoints) {
+            paths[endpoint.path] = {
+                post: {
+                    operationId: `execute_${endpoint.functionName}`,
+                    summary: `Execute ${endpoint.name} workflow`,
+                    description: endpoint.description || `Execute the ${endpoint.name} workflow`,
+                    tags: ['workflows'],
+                    requestBody: {
+                        description: 'Workflow input parameters',
+                        required: true,
+                        content: {
+                            'application/json': {
+                                schema: endpoint.inputSchema || { type: 'object', additionalProperties: true },
+                            },
+                        },
+                    },
+                    responses: {
+                        '200': {
+                            description: 'Successful execution',
+                            content: {
+                                'application/json': {
+                                    schema: {
+                                        type: 'object',
+                                        properties: {
+                                            success: { type: 'boolean' },
+                                            result: endpoint.outputSchema || { type: 'object' },
+                                            executionTime: { type: 'number' },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                        '500': {
+                            description: 'Execution error',
+                            content: {
+                                'application/json': {
+                                    schema: {
+                                        type: 'object',
+                                        properties: {
+                                            success: { type: 'boolean' },
+                                            error: { type: 'object', properties: { message: { type: 'string' } } },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+            };
+        }
+        return {
+            openapi: '3.0.3',
+            info: {
+                title: 'Flow Weaver API',
+                version: '1.0.0',
+                description: `Webhook server with ${endpoints.length} workflow endpoint(s)`,
+            },
+            servers: [{ url: `http://${this.config.host}:${this.config.port}`, description: 'Local server' }],
+            paths,
+            tags: [{ name: 'workflows', description: 'Workflow execution endpoints' }],
+        };
+    }
+    /**
+     * Setup Swagger UI and OpenAPI spec routes
+     */
+    setupSwaggerRoutes() {
+        if (!this.fastify)
+            return;
+        // GET /openapi.json - OpenAPI specification
+        this.fastify.get('/openapi.json', async (_req, reply) => {
+            const spec = this.buildOpenApiSpec();
+            reply.header('Content-Type', 'application/json');
+            reply.send(spec);
+        });
+        // GET /docs - Swagger UI
+        this.fastify.get('/docs', async (_req, reply) => {
+            const html = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Flow Weaver API Documentation</title>
+  <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css">
+</head>
+<body>
+  <div id="swagger-ui"></div>
+  <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
+  <script>
+    SwaggerUIBundle({
+      url: '/openapi.json',
+      dom_id: '#swagger-ui',
+      presets: [SwaggerUIBundle.presets.apis, SwaggerUIBundle.SwaggerUIStandalonePreset],
+      layout: 'BaseLayout'
+    });
+  </script>
+</body>
+</html>`;
+            reply.type('text/html').send(html);
+        });
+    }
+    /**
+     * Get server info for external logging
+     */
+    getServerInfo() {
+        return {
+            port: this.config.port,
+            host: this.config.host,
+            endpoints: this.registry.getAllEndpoints().length,
+        };
+    }
+    /**
+     * Stop the HTTP server
+     */
+    async stop() {
+        await this.registry.stopWatching();
+        if (this.fastify) {
+            await this.fastify.close();
+        }
+    }
+}
+//# sourceMappingURL=webhook-server.js.map