@weavelogic/knowledge-graph-agent 0.3.0 → 0.4.0

package/dist/workflow/handlers/webhook-handlers.d.ts

@@ -0,0 +1,397 @@
+/**
+ * Webhook Handlers
+ *
+ * Handles incoming webhooks and hooks for workflow triggers.
+ * Integrates with the existing file watcher system.
+ *
+ * @module workflow/handlers/webhook-handlers
+ */
+import type { NodeUpdateEvent, GapDetectedEvent, WorkflowCompleteEvent } from '../types.js';
+export type { NodeUpdateEvent, GapDetectedEvent, WorkflowCompleteEvent };
+/**
+ * Event types that can trigger workflows
+ */
+export type WorkflowTriggerEvent = {
+    type: 'file:created';
+    path: string;
+    timestamp: number;
+} | {
+    type: 'file:changed';
+    path: string;
+    timestamp: number;
+    changes?: string;
+} | {
+    type: 'file:deleted';
+    path: string;
+    timestamp: number;
+} | {
+    type: 'node:updated';
+    event: NodeUpdateEvent;
+} | {
+    type: 'gap:detected';
+    event: GapDetectedEvent;
+} | {
+    type: 'workflow:complete';
+    event: WorkflowCompleteEvent;
+} | {
+    type: 'timeout:inactivity';
+    lastActivity: number;
+    threshold: number;
+};
+/**
+ * Webhook handler configuration
+ */
+export interface WebhookConfig {
+    /** Secret for validating webhook signatures */
+    secret?: string;
+    /** Maximum payload size in bytes */
+    maxPayloadSize?: number;
+    /** Allowed origins for CORS */
+    allowedOrigins?: string[];
+    /** Rate limit per minute */
+    rateLimit?: number;
+}
+/**
+ * Webhook validation result
+ */
+export interface WebhookValidation {
+    /** Whether the webhook payload is valid */
+    valid: boolean;
+    /** Error message if invalid */
+    error?: string;
+    /** Parsed event if valid */
+    event?: WorkflowTriggerEvent;
+}
+/**
+ * Handler function type for processing workflow trigger events
+ * @template T - Context type passed to handlers
+ */
+export type WebhookHandler<T = unknown> = (event: WorkflowTriggerEvent, context: T) => Promise<void>;
+/**
+ * Webhook handler registry
+ *
+ * Manages registration and dispatch of webhook event handlers.
+ * Supports multiple handlers per event type and provides
+ * payload validation with optional signature verification.
+ *
+ * @example
+ * ```typescript
+ * const registry = new WebhookRegistry({ secret: 'my-secret' });
+ *
+ * // Register handler
+ * const unsubscribe = registry.on('file:changed', async (event) => {
+ *   console.log('File changed:', event.path);
+ * });
+ *
+ * // Emit event
+ * await registry.emit({
+ *   type: 'file:changed',
+ *   path: '/docs/readme.md',
+ *   timestamp: Date.now()
+ * });
+ *
+ * // Cleanup
+ * unsubscribe();
+ * ```
+ */
+export declare class WebhookRegistry {
+    private handlers;
+    private config;
+    /**
+     * Create a new webhook registry
+     * @param config - Registry configuration
+     */
+    constructor(config?: WebhookConfig);
+    /**
+     * Register a handler for an event type
+     *
+     * @param eventType - The event type to listen for
+     * @param handler - Handler function to call when event occurs
+     * @returns Unsubscribe function to remove the handler
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = registry.on('file:created', async (event) => {
+     *   if (event.type === 'file:created') {
+     *     await processNewFile(event.path);
+     *   }
+     * });
+     * ```
+     */
+    on(eventType: WorkflowTriggerEvent['type'], handler: WebhookHandler): () => void;
+    /**
+     * Remove all handlers for an event type
+     *
+     * @param eventType - The event type to clear handlers for
+     */
+    off(eventType: WorkflowTriggerEvent['type']): void;
+    /**
+     * Remove all handlers for all event types
+     */
+    clear(): void;
+    /**
+     * Get the number of handlers registered for an event type
+     *
+     * @param eventType - The event type to check
+     * @returns Number of registered handlers
+     */
+    listenerCount(eventType: WorkflowTriggerEvent['type']): number;
+    /**
+     * Emit an event to all registered handlers
+     *
+     * Handlers are called in parallel. Errors in individual handlers
+     * are caught and logged but do not prevent other handlers from running.
+     *
+     * @param event - The event to emit
+     * @param context - Optional context to pass to handlers
+     *
+     * @example
+     * ```typescript
+     * await registry.emit({
+     *   type: 'node:updated',
+     *   event: {
+     *     nodeId: 'doc-123',
+     *     userId: 'user-456',
+     *     changes: { title: 'Updated Title' },
+     *     timestamp: Date.now()
+     *   }
+     * });
+     * ```
+     */
+    emit<T>(event: WorkflowTriggerEvent, context?: T): Promise<void>;
+    /**
+     * Validate incoming webhook payload
+     *
+     * Checks that the payload is properly structured and optionally
+     * verifies the signature if a secret is configured.
+     *
+     * @param payload - Raw payload data
+     * @param signature - Optional signature for verification
+     * @returns Validation result with parsed event if valid
+     *
+     * @example
+     * ```typescript
+     * const result = registry.validatePayload(
+     *   { type: 'file:created', path: '/test.md', timestamp: Date.now() },
+     *   'sha256=abc123...'
+     * );
+     *
+     * if (result.valid && result.event) {
+     *   await registry.emit(result.event);
+     * } else {
+     *   console.error('Invalid webhook:', result.error);
+     * }
+     * ```
+     */
+    validatePayload(payload: unknown, signature?: string): WebhookValidation;
+    /**
+     * Get current configuration
+     * @returns A copy of the current configuration
+     */
+    getConfig(): Readonly<WebhookConfig>;
+    /**
+     * Verify webhook signature
+     * @param payload - The payload to verify
+     * @param signature - The signature to check against
+     * @returns Whether the signature is valid
+     */
+    private verifySignature;
+    /**
+     * Parse raw data into typed event
+     * @param data - Raw event data
+     * @returns Typed workflow trigger event
+     * @throws Error if event type is unknown or data is malformed
+     */
+    private parseEvent;
+}
+/**
+ * File watcher integration
+ *
+ * Converts file system events to workflow trigger events and
+ * manages inactivity detection for watched paths.
+ *
+ * @example
+ * ```typescript
+ * const registry = createWebhookRegistry();
+ * const watcher = createFileWatcherIntegration(registry, {
+ *   inactivityThreshold: 10 * 60 * 1000 // 10 minutes
+ * });
+ *
+ * // Register for inactivity events
+ * registry.on('timeout:inactivity', async (event) => {
+ *   console.log('No activity for:', event.threshold, 'ms');
+ * });
+ *
+ * // Start watching
+ * watcher.watch('/path/to/docs');
+ *
+ * // Simulate file events
+ * await watcher.onFileCreated('/path/to/docs/new-file.md');
+ * await watcher.onFileChanged('/path/to/docs/existing.md', 'content diff');
+ * ```
+ */
+export declare class FileWatcherIntegration {
+    private registry;
+    private watchPaths;
+    private lastActivityMap;
+    private inactivityTimers;
+    private inactivityThreshold;
+    /**
+     * Create a new file watcher integration
+     * @param registry - Webhook registry to emit events to
+     * @param options - Configuration options
+     */
+    constructor(registry: WebhookRegistry, options?: {
+        inactivityThreshold?: number;
+    });
+    /**
+     * Add a path to watch
+     *
+     * Files created, changed, or deleted under this path will
+     * trigger workflow events. Inactivity detection starts immediately.
+     *
+     * @param path - Absolute path to watch
+     *
+     * @example
+     * ```typescript
+     * watcher.watch('/path/to/docs');
+     * watcher.watch('/path/to/templates');
+     * ```
+     */
+    watch(path: string): void;
+    /**
+     * Stop watching a path
+     *
+     * Clears inactivity timer and removes path from watch list.
+     *
+     * @param path - Path to stop watching
+     */
+    unwatch(path: string): void;
+    /**
+     * Stop watching all paths and clear all timers
+     */
+    unwatchAll(): void;
+    /**
+     * Handle file created event
+     *
+     * @param path - Path to the created file
+     *
+     * @example
+     * ```typescript
+     * // Called by file system watcher
+     * fsWatcher.on('add', (path) => {
+     *   watcher.onFileCreated(path);
+     * });
+     * ```
+     */
+    onFileCreated(path: string): Promise<void>;
+    /**
+     * Handle file changed event
+     *
+     * @param path - Path to the changed file
+     * @param changes - Optional description of changes (e.g., diff)
+     *
+     * @example
+     * ```typescript
+     * // Called by file system watcher
+     * fsWatcher.on('change', (path) => {
+     *   const diff = computeDiff(path);
+     *   watcher.onFileChanged(path, diff);
+     * });
+     * ```
+     */
+    onFileChanged(path: string, changes?: string): Promise<void>;
+    /**
+     * Handle file deleted event
+     *
+     * @param path - Path to the deleted file
+     */
+    onFileDeleted(path: string): Promise<void>;
+    /**
+     * Get all watched paths
+     * @returns Array of watched paths
+     */
+    getWatchedPaths(): string[];
+    /**
+     * Get last activity timestamp for a path
+     * @param path - Path to check
+     * @returns Timestamp of last activity, or undefined if not tracked
+     */
+    getLastActivity(path: string): number | undefined;
+    /**
+     * Get the inactivity threshold
+     * @returns Inactivity threshold in milliseconds
+     */
+    getInactivityThreshold(): number;
+    /**
+     * Set the inactivity threshold
+     *
+     * Updates the threshold and resets all active timers with the new value.
+     *
+     * @param threshold - New threshold in milliseconds
+     */
+    setInactivityThreshold(threshold: number): void;
+    /**
+     * Check if path should be processed
+     * @param path - Path to check
+     * @returns Whether the path is being watched
+     */
+    private shouldProcess;
+    /**
+     * Update activity timestamp and reset inactivity timer
+     * @param path - Path where activity occurred
+     */
+    private updateActivity;
+    /**
+     * Find the watched parent path for a given path
+     * @param path - Path to find parent for
+     * @returns Watched parent path, or undefined if not found
+     */
+    private findWatchedParent;
+    /**
+     * Reset the inactivity timer for a path
+     * @param path - Path to reset timer for
+     */
+    private resetInactivityTimer;
+}
+/**
+ * Create a webhook registry instance
+ *
+ * Factory function for creating a configured webhook registry.
+ *
+ * @param config - Registry configuration
+ * @returns Configured webhook registry
+ *
+ * @example
+ * ```typescript
+ * const registry = createWebhookRegistry({
+ *   secret: process.env.WEBHOOK_SECRET,
+ *   maxPayloadSize: 2 * 1024 * 1024, // 2MB
+ *   rateLimit: 50
+ * });
+ * ```
+ */
+export declare function createWebhookRegistry(config?: WebhookConfig): WebhookRegistry;
+/**
+ * Create a file watcher integration instance
+ *
+ * Factory function for creating a configured file watcher integration.
+ *
+ * @param registry - Webhook registry to emit events to
+ * @param options - Configuration options
+ * @returns Configured file watcher integration
+ *
+ * @example
+ * ```typescript
+ * const registry = createWebhookRegistry();
+ * const watcher = createFileWatcherIntegration(registry, {
+ *   inactivityThreshold: 10 * 60 * 1000 // 10 minutes
+ * });
+ *
+ * watcher.watch('/docs');
+ * ```
+ */
+export declare function createFileWatcherIntegration(registry: WebhookRegistry, options?: {
+    inactivityThreshold?: number;
+}): FileWatcherIntegration;
+//# sourceMappingURL=webhook-handlers.d.ts.map

package/dist/workflow/handlers/webhook-handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-handlers.d.ts","sourceRoot":"","sources":["../../../src/workflow/handlers/webhook-handlers.ts"],"names":[],"mappings":"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"}