@classytic/payroll 1.0.2 → 2.0.0

package/dist/plugin-D9mOr3_d.d.ts

@@ -0,0 +1,333 @@
+import { p as ObjectId, q as OperationContext, r as PayrollInstance } from './types-BSYyX2KJ.js';
+
+/**
+ * @classytic/payroll - Event System
+ *
+ * Type-safe event emitter for payroll lifecycle events
+ * Enables loose coupling and extensibility
+ */
+
+interface EmployeeHiredEventPayload {
+    employee: {
+        id: ObjectId;
+        employeeId: string;
+        position: string;
+        department?: string;
+    };
+    organizationId: ObjectId;
+    context?: OperationContext;
+}
+interface EmployeeTerminatedEventPayload {
+    employee: {
+        id: ObjectId;
+        employeeId: string;
+        name?: string;
+    };
+    terminationDate: Date;
+    reason?: string;
+    organizationId: ObjectId;
+    context?: OperationContext;
+}
+interface EmployeeRehiredEventPayload {
+    employee: {
+        id: ObjectId;
+        employeeId: string;
+        position: string;
+    };
+    previousTerminationDate?: Date;
+    organizationId: ObjectId;
+    context?: OperationContext;
+}
+interface SalaryUpdatedEventPayload {
+    employee: {
+        id: ObjectId;
+        employeeId: string;
+    };
+    previousSalary: number;
+    newSalary: number;
+    effectiveFrom: Date;
+    organizationId: ObjectId;
+    context?: OperationContext;
+}
+interface SalaryProcessedEventPayload {
+    employee: {
+        id: ObjectId;
+        employeeId: string;
+        name?: string;
+    };
+    payroll: {
+        id: ObjectId;
+        period: {
+            month: number;
+            year: number;
+        };
+        grossAmount: number;
+        netAmount: number;
+    };
+    transactionId: ObjectId;
+    organizationId: ObjectId;
+    context?: OperationContext;
+}
+interface SalaryFailedEventPayload {
+    employee: {
+        id: ObjectId;
+        employeeId: string;
+    };
+    period: {
+        month: number;
+        year: number;
+    };
+    error: string;
+    organizationId: ObjectId;
+    context?: OperationContext;
+}
+interface PayrollCompletedEventPayload {
+    organizationId: ObjectId;
+    period: {
+        month: number;
+        year: number;
+    };
+    summary: {
+        total: number;
+        successful: number;
+        failed: number;
+        totalAmount: number;
+    };
+    context?: OperationContext;
+}
+interface PayrollExportedEventPayload {
+    organizationId: ObjectId;
+    dateRange: {
+        start: Date;
+        end: Date;
+    };
+    recordCount: number;
+    format: string;
+    context?: OperationContext;
+}
+interface CompensationChangedEventPayload {
+    employee: {
+        id: ObjectId;
+        employeeId: string;
+    };
+    changeType: 'allowance_added' | 'allowance_removed' | 'deduction_added' | 'deduction_removed';
+    details: {
+        type: string;
+        amount: number;
+    };
+    organizationId: ObjectId;
+    context?: OperationContext;
+}
+interface MilestoneAchievedEventPayload {
+    employee: {
+        id: ObjectId;
+        employeeId: string;
+        name?: string;
+    };
+    milestone: {
+        type: 'tenure' | 'salary' | 'payments';
+        value: number;
+        message: string;
+    };
+    organizationId: ObjectId;
+}
+interface PayrollEventMap {
+    'employee:hired': EmployeeHiredEventPayload;
+    'employee:terminated': EmployeeTerminatedEventPayload;
+    'employee:rehired': EmployeeRehiredEventPayload;
+    'salary:updated': SalaryUpdatedEventPayload;
+    'salary:processed': SalaryProcessedEventPayload;
+    'salary:failed': SalaryFailedEventPayload;
+    'payroll:completed': PayrollCompletedEventPayload;
+    'payroll:exported': PayrollExportedEventPayload;
+    'compensation:changed': CompensationChangedEventPayload;
+    'milestone:achieved': MilestoneAchievedEventPayload;
+}
+type PayrollEventType = keyof PayrollEventMap;
+type EventHandler<T> = (payload: T) => void | Promise<void>;
+type PayrollEventHandler<K extends PayrollEventType> = EventHandler<PayrollEventMap[K]>;
+declare class EventBus {
+    private handlers;
+    /**
+     * Register an event handler
+     */
+    on<K extends PayrollEventType>(event: K, handler: PayrollEventHandler<K>): () => void;
+    /**
+     * Register a one-time event handler
+     */
+    once<K extends PayrollEventType>(event: K, handler: PayrollEventHandler<K>): () => void;
+    /**
+     * Remove an event handler
+     */
+    off<K extends PayrollEventType>(event: K, handler: PayrollEventHandler<K>): void;
+    /**
+     * Emit an event
+     */
+    emit<K extends PayrollEventType>(event: K, payload: PayrollEventMap[K]): Promise<void>;
+    /**
+     * Emit event synchronously (fire-and-forget)
+     */
+    emitSync<K extends PayrollEventType>(event: K, payload: PayrollEventMap[K]): void;
+    /**
+     * Remove all handlers for an event
+     */
+    removeAllListeners(event?: PayrollEventType): void;
+    /**
+     * Get listener count for an event
+     */
+    listenerCount(event: PayrollEventType): number;
+    /**
+     * Get all registered events
+     */
+    eventNames(): PayrollEventType[];
+}
+/**
+ * Get or create the default event bus
+ */
+declare function getEventBus(): EventBus;
+/**
+ * Create a new event bus instance
+ */
+declare function createEventBus(): EventBus;
+/**
+ * Reset the default event bus (for testing)
+ */
+declare function resetEventBus(): void;
+/**
+ * Subscribe to employee hired events
+ */
+declare function onEmployeeHired(handler: PayrollEventHandler<'employee:hired'>): () => void;
+/**
+ * Subscribe to salary processed events
+ */
+declare function onSalaryProcessed(handler: PayrollEventHandler<'salary:processed'>): () => void;
+/**
+ * Subscribe to payroll completed events
+ */
+declare function onPayrollCompleted(handler: PayrollEventHandler<'payroll:completed'>): () => void;
+/**
+ * Subscribe to milestone achieved events
+ */
+declare function onMilestoneAchieved(handler: PayrollEventHandler<'milestone:achieved'>): () => void;
+
+/**
+ * @classytic/payroll - Plugin System
+ *
+ * Extensible plugin architecture for customization
+ * Follows patterns from popular libraries like Mongoose, Fastify
+ */
+
+interface PluginContext {
+    /** Payroll instance */
+    payroll: PayrollInstance;
+    /** Event bus for subscribing to events */
+    events: EventBus;
+    /** Logger instance */
+    logger: PluginLogger;
+    /** Configuration getter */
+    getConfig: <T>(key: string) => T | undefined;
+    /** Register a hook */
+    addHook: <K extends PayrollEventType>(event: K, handler: (payload: PayrollEventMap[K]) => void | Promise<void>) => () => void;
+}
+interface PluginLogger {
+    info(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    debug(message: string, meta?: Record<string, unknown>): void;
+}
+interface PluginHooks {
+    /** Called before employee is hired */
+    beforeHire?: (params: unknown) => void | Promise<void>;
+    /** Called after employee is hired */
+    afterHire?: (employee: unknown) => void | Promise<void>;
+    /** Called before salary is processed */
+    beforeProcessSalary?: (params: unknown) => void | Promise<void>;
+    /** Called after salary is processed */
+    afterProcessSalary?: (result: unknown) => void | Promise<void>;
+    /** Called before termination */
+    beforeTerminate?: (params: unknown) => void | Promise<void>;
+    /** Called after termination */
+    afterTerminate?: (employee: unknown) => void | Promise<void>;
+    /** Called on any error */
+    onError?: (error: Error, context: string) => void | Promise<void>;
+}
+interface PayrollPluginDefinition {
+    name: string;
+    version?: string;
+    hooks?: PluginHooks;
+    init?: (context: PluginContext) => void | Promise<void>;
+    destroy?: () => void | Promise<void>;
+}
+declare class PluginManager {
+    private context;
+    private plugins;
+    private hooks;
+    constructor(context: PluginContext);
+    /**
+     * Register a plugin
+     */
+    register(plugin: PayrollPluginDefinition): Promise<void>;
+    /**
+     * Unregister a plugin
+     */
+    unregister(name: string): Promise<void>;
+    /**
+     * Add a hook handler
+     */
+    private addHook;
+    /**
+     * Execute hooks for a given event
+     */
+    executeHooks<K extends keyof PluginHooks>(hookName: K, ...args: Parameters<NonNullable<PluginHooks[K]>>): Promise<void>;
+    /**
+     * Get registered plugin names
+     */
+    getPluginNames(): string[];
+    /**
+     * Check if plugin is registered
+     */
+    hasPlugin(name: string): boolean;
+}
+/**
+ * Define a plugin with type safety
+ */
+declare function definePlugin(definition: PayrollPluginDefinition): PayrollPluginDefinition;
+/**
+ * Logging plugin - logs all payroll events
+ */
+declare const loggingPlugin: PayrollPluginDefinition;
+/**
+ * Metrics plugin - collects payroll metrics
+ */
+declare const metricsPlugin: PayrollPluginDefinition;
+/**
+ * Notification plugin - sends notifications for events
+ */
+interface NotificationPluginOptions {
+    onHired?: (employee: {
+        id: unknown;
+        name?: string;
+    }) => void | Promise<void>;
+    onTerminated?: (employee: {
+        id: unknown;
+        name?: string;
+    }) => void | Promise<void>;
+    onSalaryProcessed?: (details: {
+        employee: {
+            id: unknown;
+            name?: string;
+        };
+        amount: number;
+    }) => void | Promise<void>;
+    onMilestone?: (details: {
+        employee: {
+            id: unknown;
+            name?: string;
+        };
+        milestone: string;
+    }) => void | Promise<void>;
+}
+declare function createNotificationPlugin(options: NotificationPluginOptions): PayrollPluginDefinition;
+declare const notificationPlugin: PayrollPluginDefinition;
+
+export { type CompensationChangedEventPayload as C, EventBus as E, type MilestoneAchievedEventPayload as M, type NotificationPluginOptions as N, type PayrollPluginDefinition as P, type SalaryUpdatedEventPayload as S, type PayrollEventMap as a, PluginManager as b, createEventBus as c, type PluginContext as d, onSalaryProcessed as e, onPayrollCompleted as f, getEventBus as g, onMilestoneAchieved as h, type PayrollEventType as i, type PayrollEventHandler as j, type EmployeeHiredEventPayload as k, type EmployeeTerminatedEventPayload as l, type EmployeeRehiredEventPayload as m, type SalaryProcessedEventPayload as n, onEmployeeHired as o, type SalaryFailedEventPayload as p, type PayrollCompletedEventPayload as q, resetEventBus as r, type PayrollExportedEventPayload as s, definePlugin as t, loggingPlugin as u, metricsPlugin as v, notificationPlugin as w, createNotificationPlugin as x, type PluginLogger as y, type PluginHooks as z };