@trentapps/manager-protocol 1.1.3 → 1.2.0

package/dist/utils/shared.d.ts

@@ -0,0 +1,306 @@
+/**
+ * Enterprise Agent Supervisor - Shared Utilities
+ *
+ * Common utility functions used across the codebase.
+ * Extracted from various modules to reduce duplication and ensure consistency.
+ *
+ * Tasks: #40, #41, #42, #48
+ */
+/**
+ * Simple string hash function for generating IDs.
+ * Uses a fast, non-cryptographic hash algorithm (djb2 variant).
+ *
+ * @param str - The string to hash
+ * @param options - Optional configuration
+ * @returns Hexadecimal hash string (default) or base36 string
+ *
+ * @example
+ * ```typescript
+ * hashString('hello world'); // Returns: 'a3e45bc1'
+ * hashString('hello world', { base: 36 }); // Returns: 'x7k2m'
+ * hashString('hello world', { length: 16 }); // Returns: '00000000a3e45bc1'
+ * ```
+ */
+export declare function hashString(str: string, options?: {
+    base?: 16 | 36;
+    length?: number;
+}): string;
+/**
+ * Options for TimeWindow calculations
+ */
+export interface TimeWindowOptions {
+    /** Duration in milliseconds. Defaults to 24 hours */
+    durationMs?: number;
+    /** Reference time (defaults to Date.now()) */
+    referenceTime?: number;
+}
+/**
+ * Result of a time window check
+ */
+export interface TimeWindowResult {
+    /** Start of the window (ISO timestamp) */
+    start: string;
+    /** End of the window (ISO timestamp) */
+    end: string;
+    /** Start timestamp in milliseconds */
+    startMs: number;
+    /** End timestamp in milliseconds */
+    endMs: number;
+    /** Whether a given timestamp is within this window */
+    contains: (timestamp: string | number | Date) => boolean;
+}
+/**
+ * Common time window durations
+ */
+export declare const TimeWindows: {
+    /** 1 hour in milliseconds */
+    readonly HOUR: number;
+    /** 24 hours in milliseconds */
+    readonly DAY: number;
+    /** 7 days in milliseconds */
+    readonly WEEK: number;
+    /** 30 days in milliseconds */
+    readonly MONTH: number;
+};
+/**
+ * Create a time window for filtering data.
+ *
+ * @param options - Time window options
+ * @returns TimeWindowResult with start/end times and contains() function
+ *
+ * @example
+ * ```typescript
+ * // Last 24 hours
+ * const window = createTimeWindow();
+ *
+ * // Last hour
+ * const hourWindow = createTimeWindow({ durationMs: TimeWindows.HOUR });
+ *
+ * // Check if a timestamp is in the window
+ * if (window.contains(event.timestamp)) {
+ *   // Event is within the time window
+ * }
+ * ```
+ */
+export declare function createTimeWindow(options?: TimeWindowOptions): TimeWindowResult;
+/**
+ * Check if a window has expired based on start time and duration.
+ * Uses >= comparison for consistency (window expires AT the boundary).
+ *
+ * @param windowStart - Window start timestamp in milliseconds
+ * @param windowMs - Window duration in milliseconds
+ * @param now - Current time (defaults to Date.now())
+ * @returns true if the window has expired
+ *
+ * @example
+ * ```typescript
+ * if (isWindowExpired(bucket.windowStart, config.windowMs)) {
+ *   // Reset the window
+ *   bucket.count = 0;
+ *   bucket.windowStart = Date.now();
+ * }
+ * ```
+ */
+export declare function isWindowExpired(windowStart: number, windowMs: number, now?: number): boolean;
+/**
+ * Calculate the reset time for a window.
+ *
+ * @param windowStart - Window start timestamp in milliseconds
+ * @param windowMs - Window duration in milliseconds
+ * @returns Date object for when the window resets
+ */
+export declare function getWindowResetTime(windowStart: number, windowMs: number): Date;
+/**
+ * Options for metric calculation
+ */
+export interface MetricCalculationOptions<T> {
+    /** Field to extract for aggregation (e.g., 'tokensUsed', 'latencyMs') */
+    valueField?: keyof T;
+    /** Field containing the timestamp (defaults to 'timestamp') */
+    timestampField?: keyof T;
+    /** Field to check for errors (defaults to 'outcome') */
+    outcomeField?: keyof T;
+    /** Value that indicates failure (defaults to 'failure') */
+    failureValue?: string;
+    /** Include 24h metrics (defaults to true) */
+    include24h?: boolean;
+}
+/**
+ * Generic metrics summary structure
+ */
+export interface MetricsSummary {
+    total: number;
+    count: number;
+    average: number;
+    min: number;
+    max: number;
+    errorCount: number;
+    errorRate: number;
+    last24h?: {
+        total: number;
+        count: number;
+        errors: number;
+    };
+}
+/**
+ * Calculate aggregate metrics from an array of data items.
+ *
+ * @param items - Array of items to analyze
+ * @param valueExtractor - Function to extract numeric value from each item
+ * @param options - Configuration options
+ * @returns Aggregated metrics
+ *
+ * @example
+ * ```typescript
+ * const activities = [
+ *   { tokensUsed: 100, timestamp: '2024-01-01T00:00:00Z', outcome: 'success' },
+ *   { tokensUsed: 200, timestamp: '2024-01-01T01:00:00Z', outcome: 'failure' },
+ * ];
+ *
+ * const metrics = calculateMetrics(
+ *   activities,
+ *   item => item.tokensUsed,
+ *   {
+ *     timestampField: 'timestamp',
+ *     outcomeField: 'outcome',
+ *     failureValue: 'failure'
+ *   }
+ * );
+ * // Returns: { total: 300, count: 2, average: 150, min: 100, max: 200, ... }
+ * ```
+ */
+export declare function calculateMetrics<T>(items: T[], valueExtractor: (item: T) => number | undefined, options?: MetricCalculationOptions<T>): MetricsSummary;
+/**
+ * Calculate grouped metrics (e.g., by category, by type).
+ *
+ * @param items - Array of items to analyze
+ * @param groupExtractor - Function to extract group key from each item
+ * @returns Map of group key to count
+ *
+ * @example
+ * ```typescript
+ * const events = [
+ *   { eventType: 'action_evaluated' },
+ *   { eventType: 'action_approved' },
+ *   { eventType: 'action_evaluated' },
+ * ];
+ *
+ * const byType = calculateGroupedCounts(events, e => e.eventType);
+ * // Returns: { 'action_evaluated': 2, 'action_approved': 1 }
+ * ```
+ */
+export declare function calculateGroupedCounts<T>(items: T[], groupExtractor: (item: T) => string | undefined): Record<string, number>;
+/**
+ * Get top N items from a count record.
+ *
+ * @param counts - Record of key to count
+ * @param limit - Maximum number of items to return
+ * @returns Array of { key, count } sorted by count descending
+ */
+export declare function getTopCounts(counts: Record<string, number>, limit?: number): Array<{
+    key: string;
+    count: number;
+}>;
+/**
+ * Validation result
+ */
+export interface ValidationResult {
+    valid: boolean;
+    error?: string;
+}
+/**
+ * Collection of common input validators.
+ *
+ * Each validator returns { valid: true } or { valid: false, error: 'message' }
+ */
+export declare const validators: {
+    /**
+     * Validate email format
+     *
+     * @example
+     * ```typescript
+     * validators.email('user@example.com'); // { valid: true }
+     * validators.email('invalid'); // { valid: false, error: '...' }
+     * ```
+     */
+    email(value: string): ValidationResult;
+    /**
+     * Validate URL format
+     *
+     * @example
+     * ```typescript
+     * validators.url('https://example.com'); // { valid: true }
+     * validators.url('not-a-url'); // { valid: false, error: '...' }
+     * ```
+     */
+    url(value: string, options?: {
+        requireHttps?: boolean;
+    }): ValidationResult;
+    /**
+     * Validate file path (basic validation, no traversal attacks)
+     *
+     * @example
+     * ```typescript
+     * validators.path('/valid/path'); // { valid: true }
+     * validators.path('../traversal'); // { valid: false, error: '...' }
+     * ```
+     */
+    path(value: string, options?: {
+        allowRelative?: boolean;
+    }): ValidationResult;
+    /**
+     * Validate that a string is non-empty
+     */
+    nonEmpty(value: string, fieldName?: string): ValidationResult;
+    /**
+     * Validate string length
+     */
+    length(value: string, options?: {
+        min?: number;
+        max?: number;
+        fieldName?: string;
+    }): ValidationResult;
+    /**
+     * Validate number within range
+     */
+    numberRange(value: number, options?: {
+        min?: number;
+        max?: number;
+        fieldName?: string;
+    }): ValidationResult;
+    /**
+     * Validate port number
+     */
+    port(value: number): ValidationResult;
+    /**
+     * Validate identifier (alphanumeric with dashes/underscores)
+     */
+    identifier(value: string, fieldName?: string): ValidationResult;
+    /**
+     * Validate enum value
+     */
+    enum<T extends string>(value: string, allowedValues: readonly T[], fieldName?: string): ValidationResult;
+    /**
+     * Validate ISO date string
+     */
+    isoDate(value: string): ValidationResult;
+    /**
+     * Validate GitHub repository format (owner/repo)
+     */
+    githubRepo(value: string): ValidationResult;
+    /**
+     * Compose multiple validators (all must pass)
+     */
+    all(...validations: ValidationResult[]): ValidationResult;
+};
+/**
+ * Helper to run validation and throw on failure
+ *
+ * @example
+ * ```typescript
+ * assertValid(validators.email(userEmail), 'email');
+ * // Throws if invalid: "Validation failed for email: Invalid email format"
+ * ```
+ */
+export declare function assertValid(result: ValidationResult, context?: string): void;
+//# sourceMappingURL=shared.d.ts.map

package/dist/utils/shared.d.ts.map

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