@astralibx/call-log-engine 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,445 @@
+import { Request, Router } from 'express';
+import mongoose, { Document, Schema, Model } from 'mongoose';
+import { IPipeline, IPipelineStage, ICallLog, IContactRef, IStageChange, ITimelineEntry, ICallLogSettings, IPriorityConfig, ResolvedOptions, CallLogEngineConfig, DateRange, AgentInfo, AgentCallStats, PipelineReport, PipelineFunnel, DailyReport, DashboardStats, OverallCallReport, ExportFormat, ExportFilter, AuthResult } from '@astralibx/call-log-types';
+export { CallLogEngineConfig, DEFAULT_OPTIONS, ResolvedOptions } from '@astralibx/call-log-types';
+import { LogAdapter, AlxError } from '@astralibx/core';
+
+interface IPipelineStageDocument extends IPipelineStage, Document {
+}
+interface IPipelineDocument extends IPipeline, Document {
+}
+declare const PipelineStageSchema: Schema<IPipelineStageDocument, Model<IPipelineStageDocument, any, any, any, Document<unknown, any, IPipelineStageDocument, any, {}> & IPipelineStageDocument & Required<{
+    _id: mongoose.Types.ObjectId;
+}> & {
+    __v: number;
+}, any>, {}, {}, {}, {}, mongoose.DefaultSchemaOptions, IPipelineStageDocument, Document<unknown, {}, mongoose.FlatRecord<IPipelineStageDocument>, {}, mongoose.DefaultSchemaOptions> & mongoose.FlatRecord<IPipelineStageDocument> & Required<{
+    _id: mongoose.Types.ObjectId;
+}> & {
+    __v: number;
+}>;
+declare const PipelineSchema: Schema<IPipelineDocument, Model<IPipelineDocument, any, any, any, Document<unknown, any, IPipelineDocument, any, {}> & IPipelineDocument & Required<{
+    _id: mongoose.Types.ObjectId;
+}> & {
+    __v: number;
+}, any>, {}, {}, {}, {}, mongoose.DefaultSchemaOptions, IPipelineDocument, Document<unknown, {}, mongoose.FlatRecord<IPipelineDocument>, {}, mongoose.DefaultSchemaOptions> & mongoose.FlatRecord<IPipelineDocument> & Required<{
+    _id: mongoose.Types.ObjectId;
+}> & {
+    __v: number;
+}>;
+declare function createPipelineModel(connection: mongoose.Connection, prefix?: string): Model<IPipelineDocument>;
+
+interface ICallLogDocument extends Omit<ICallLog, 'agentId'>, Document {
+    agentId: mongoose.Types.ObjectId;
+}
+declare const ContactRefSchema: Schema<IContactRef, Model<IContactRef, any, any, any, Document<unknown, any, IContactRef, any, {}> & IContactRef & {
+    _id: mongoose.Types.ObjectId;
+} & {
+    __v: number;
+}, any>, {}, {}, {}, {}, mongoose.DefaultSchemaOptions, IContactRef, Document<unknown, {}, mongoose.FlatRecord<IContactRef>, {}, mongoose.DefaultSchemaOptions> & mongoose.FlatRecord<IContactRef> & {
+    _id: mongoose.Types.ObjectId;
+} & {
+    __v: number;
+}>;
+declare const TimelineEntrySchema: Schema<ITimelineEntry, Model<ITimelineEntry, any, any, any, Document<unknown, any, ITimelineEntry, any, {}> & ITimelineEntry & {
+    _id: mongoose.Types.ObjectId;
+} & {
+    __v: number;
+}, any>, {}, {}, {}, {}, mongoose.DefaultSchemaOptions, ITimelineEntry, Document<unknown, {}, mongoose.FlatRecord<ITimelineEntry>, {}, mongoose.DefaultSchemaOptions> & mongoose.FlatRecord<ITimelineEntry> & {
+    _id: mongoose.Types.ObjectId;
+} & {
+    __v: number;
+}>;
+declare const StageChangeSchema: Schema<IStageChange, Model<IStageChange, any, any, any, Document<unknown, any, IStageChange, any, {}> & IStageChange & {
+    _id: mongoose.Types.ObjectId;
+} & {
+    __v: number;
+}, any>, {}, {}, {}, {}, mongoose.DefaultSchemaOptions, IStageChange, Document<unknown, {}, mongoose.FlatRecord<IStageChange>, {}, mongoose.DefaultSchemaOptions> & mongoose.FlatRecord<IStageChange> & {
+    _id: mongoose.Types.ObjectId;
+} & {
+    __v: number;
+}>;
+declare const CallLogSchema: Schema<ICallLogDocument, Model<ICallLogDocument, any, any, any, Document<unknown, any, ICallLogDocument, any, {}> & ICallLogDocument & Required<{
+    _id: mongoose.Types.ObjectId;
+}> & {
+    __v: number;
+}, any>, {}, {}, {}, {}, mongoose.DefaultSchemaOptions, ICallLogDocument, Document<unknown, {}, mongoose.FlatRecord<ICallLogDocument>, {}, mongoose.DefaultSchemaOptions> & mongoose.FlatRecord<ICallLogDocument> & Required<{
+    _id: mongoose.Types.ObjectId;
+}> & {
+    __v: number;
+}>;
+declare function createCallLogModel(connection: mongoose.Connection, prefix?: string): Model<ICallLogDocument>;
+
+interface ICallLogSettingsDocument extends ICallLogSettings, Document {
+}
+declare const CallLogSettingsSchema: Schema<ICallLogSettingsDocument, Model<ICallLogSettingsDocument, any, any, any, Document<unknown, any, ICallLogSettingsDocument, any, {}> & ICallLogSettingsDocument & Required<{
+    _id: mongoose.Types.ObjectId;
+}> & {
+    __v: number;
+}, any>, {}, {}, {}, {}, mongoose.DefaultSchemaOptions, ICallLogSettingsDocument, Document<unknown, {}, mongoose.FlatRecord<ICallLogSettingsDocument>, {}, mongoose.DefaultSchemaOptions> & mongoose.FlatRecord<ICallLogSettingsDocument> & Required<{
+    _id: mongoose.Types.ObjectId;
+}> & {
+    __v: number;
+}>;
+declare function createCallLogSettingsModel(connection: mongoose.Connection, prefix?: string): Model<ICallLogSettingsDocument>;
+
+declare class SettingsService {
+    private CallLogSettings;
+    private logger;
+    private tenantId?;
+    constructor(CallLogSettings: Model<ICallLogSettingsDocument>, logger: LogAdapter, tenantId?: string | undefined);
+    private get settingsFilter();
+    private buildDefaults;
+    get(): Promise<ICallLogSettingsDocument>;
+    update(data: Partial<{
+        availableTags: string[];
+        availableCategories: string[];
+        priorityLevels: IPriorityConfig[];
+        defaultFollowUpDays: number;
+        followUpReminderEnabled: boolean;
+        defaultPipelineId: string;
+        timelinePageSize: number;
+        maxConcurrentCalls: number;
+        metadata: Record<string, unknown>;
+    }>): Promise<ICallLogSettingsDocument>;
+}
+
+interface CreatePipelineInput {
+    name: string;
+    description?: string;
+    stages: Omit<IPipelineStage, 'stageId'>[];
+    isDefault?: boolean;
+    createdBy: string;
+    tenantId?: string;
+    metadata?: Record<string, unknown>;
+}
+interface UpdatePipelineInput {
+    name?: string;
+    description?: string;
+    isActive?: boolean;
+    isDefault?: boolean;
+    metadata?: Record<string, unknown>;
+}
+declare class PipelineService {
+    private Pipeline;
+    private CallLog;
+    private logger;
+    private tenantId?;
+    constructor(Pipeline: Model<IPipelineDocument>, CallLog: Model<ICallLogDocument>, logger: LogAdapter, tenantId?: string | undefined);
+    private get tenantFilter();
+    create(data: CreatePipelineInput): Promise<IPipelineDocument>;
+    update(pipelineId: string, data: UpdatePipelineInput): Promise<IPipelineDocument>;
+    delete(pipelineId: string): Promise<void>;
+    list(filter?: {
+        isActive?: boolean;
+    }): Promise<IPipelineDocument[]>;
+    get(pipelineId: string): Promise<IPipelineDocument>;
+    addStage(pipelineId: string, stage: Omit<IPipelineStage, 'stageId'>): Promise<IPipelineDocument>;
+    removeStage(pipelineId: string, stageId: string): Promise<IPipelineDocument>;
+    updateStage(pipelineId: string, stageId: string, data: Partial<IPipelineStage>): Promise<IPipelineDocument>;
+    reorderStages(pipelineId: string, stageIds: string[]): Promise<IPipelineDocument>;
+}
+
+declare class TimelineService {
+    private CallLog;
+    private logger;
+    private options;
+    constructor(CallLog: Model<ICallLogDocument>, logger: LogAdapter, options: ResolvedOptions);
+    addNote(callLogId: string, content: string, authorId: string, authorName: string): Promise<ITimelineEntry>;
+    addSystemEntry(callLogId: string, content: string): Promise<ITimelineEntry>;
+    getTimeline(callLogId: string, pagination: {
+        page: number;
+        limit: number;
+    }): Promise<{
+        entries: ITimelineEntry[];
+        total: number;
+    }>;
+    getContactTimeline(externalId: string, pagination: {
+        page: number;
+        limit: number;
+    }): Promise<{
+        entries: (ITimelineEntry & {
+            callLogId: string;
+        })[];
+        total: number;
+    }>;
+}
+
+interface CreateCallLogInput {
+    pipelineId: string;
+    contactRef: ICallLog['contactRef'];
+    direction: ICallLog['direction'];
+    callDate?: Date | string;
+    agentId: string;
+    priority?: ICallLog['priority'];
+    tags?: string[];
+    category?: string;
+    nextFollowUpDate?: Date;
+    durationMinutes?: number;
+    tenantId?: string;
+    metadata?: Record<string, unknown>;
+}
+interface UpdateCallLogInput {
+    priority?: ICallLog['priority'];
+    tags?: string[];
+    category?: string;
+    nextFollowUpDate?: Date;
+    durationMinutes?: number;
+}
+interface ListCallLogsFilter {
+    pipelineId?: string;
+    currentStageId?: string;
+    agentId?: string;
+    tags?: string[];
+    category?: string;
+    isClosed?: boolean;
+    contactExternalId?: string;
+    contactName?: string;
+    contactPhone?: string;
+    contactEmail?: string;
+    priority?: ICallLog['priority'];
+    direction?: ICallLog['direction'];
+    dateRange?: DateRange;
+    page?: number;
+    limit?: number;
+    sort?: Record<string, 1 | -1>;
+}
+interface ListCallLogsResult {
+    callLogs: ICallLogDocument[];
+    total: number;
+    page: number;
+    limit: number;
+}
+interface BulkChangeStageResult {
+    succeeded: string[];
+    failed: {
+        callLogId: string;
+        error: string;
+    }[];
+    total: number;
+}
+type ResolvedHooks = NonNullable<CallLogEngineConfig['hooks']>;
+declare class CallLogService {
+    private CallLog;
+    private Pipeline;
+    private timeline;
+    private logger;
+    private hooks;
+    private options;
+    constructor(CallLog: Model<ICallLogDocument>, Pipeline: Model<IPipelineDocument>, timeline: TimelineService, logger: LogAdapter, hooks: ResolvedHooks, options: ResolvedOptions);
+    create(data: CreateCallLogInput): Promise<ICallLogDocument>;
+    update(callLogId: string, data: UpdateCallLogInput): Promise<ICallLogDocument>;
+    changeStage(callLogId: string, newStageId: string, agentId: string): Promise<ICallLogDocument>;
+    assign(callLogId: string, agentId: string, assignedBy: string): Promise<ICallLogDocument>;
+    list(filter?: ListCallLogsFilter): Promise<ListCallLogsResult>;
+    get(callLogId: string): Promise<ICallLogDocument>;
+    getByContact(externalId: string): Promise<ICallLogDocument[]>;
+    getFollowUpsDue(agentId?: string, dateRange?: DateRange): Promise<ICallLogDocument[]>;
+    bulkChangeStage(callLogIds: string[], newStageId: string, agentId: string): Promise<BulkChangeStageResult>;
+    close(callLogId: string, agentId: string): Promise<ICallLogDocument>;
+    reopen(callLogId: string, agentId: string): Promise<ICallLogDocument>;
+}
+
+interface WeeklySummary {
+    week: string;
+    year: number;
+    totalCalls: number;
+    closedCalls: number;
+}
+interface TeamStats {
+    teamId: string | null;
+    agentStats: AgentCallStats[];
+    totalCalls: number;
+}
+declare class AnalyticsService {
+    private CallLog;
+    private Pipeline;
+    private logger;
+    private resolveAgent?;
+    constructor(CallLog: Model<ICallLogDocument>, Pipeline: Model<IPipelineDocument>, logger: LogAdapter, resolveAgent?: ((agentId: string) => Promise<AgentInfo | null>) | undefined);
+    private getAgentName;
+    private buildDateMatch;
+    getAgentStats(agentId: string, dateRange: DateRange): Promise<AgentCallStats>;
+    getAgentLeaderboard(dateRange: DateRange): Promise<AgentCallStats[]>;
+    getPipelineStats(pipelineId: string, dateRange: DateRange): Promise<PipelineReport>;
+    getPipelineFunnel(pipelineId: string, dateRange: DateRange): Promise<PipelineFunnel>;
+    getTeamStats(teamId?: string, dateRange?: DateRange): Promise<TeamStats>;
+    getDailyReport(dateRange: DateRange): Promise<DailyReport[]>;
+    getDashboardStats(): Promise<DashboardStats>;
+    getWeeklyTrends(weeks: number): Promise<WeeklySummary[]>;
+    getOverallReport(dateRange: DateRange): Promise<OverallCallReport>;
+}
+
+declare class ExportService {
+    private CallLog;
+    private analytics;
+    private logger;
+    constructor(CallLog: Model<ICallLogDocument>, analytics: AnalyticsService, logger: LogAdapter);
+    exportCallLog(callLogId: string, format: ExportFormat): Promise<string>;
+    exportCallLogs(filter: ExportFilter, format: ExportFormat): Promise<string>;
+    exportPipelineReport(pipelineId: string, dateRange: DateRange, format: ExportFormat): Promise<string>;
+    private toCSV;
+    private escapeCSV;
+}
+
+declare const ERROR_CODE: {
+    readonly PipelineNotFound: "CALL_PIPELINE_NOT_FOUND";
+    readonly InvalidPipeline: "CALL_INVALID_PIPELINE";
+    readonly StageNotFound: "CALL_STAGE_NOT_FOUND";
+    readonly StageInUse: "CALL_STAGE_IN_USE";
+    readonly CallLogNotFound: "CALL_LOG_NOT_FOUND";
+    readonly CallLogClosed: "CALL_LOG_CLOSED";
+    readonly ContactNotFound: "CALL_CONTACT_NOT_FOUND";
+    readonly AgentCapacityFull: "CALL_AGENT_CAPACITY_FULL";
+    readonly InvalidConfig: "CALL_INVALID_CONFIG";
+    readonly AuthFailed: "CALL_AUTH_FAILED";
+};
+type ErrorCode = (typeof ERROR_CODE)[keyof typeof ERROR_CODE];
+declare const ERROR_MESSAGE: {
+    readonly PipelineNotFound: "Pipeline not found";
+    readonly PipelineNoDefaultStage: "Pipeline must have exactly one default stage";
+    readonly PipelineNoTerminalStage: "Pipeline must have at least one terminal stage";
+    readonly PipelineDuplicateStageNames: "Stage names must be unique within a pipeline";
+    readonly StageNotFound: "Stage not found in pipeline";
+    readonly StageInUse: "Cannot remove stage that has active calls";
+    readonly CallLogNotFound: "Call log not found";
+    readonly CallLogClosed: "Cannot modify a closed call log";
+    readonly ContactNotFound: "Contact not found";
+    readonly AgentCapacityFull: "Agent has reached maximum concurrent calls";
+    readonly AuthFailed: "Authentication failed";
+};
+declare const PIPELINE_DEFAULTS: {
+    readonly MaxStages: 20;
+};
+declare const CALL_LOG_DEFAULTS: {
+    readonly MaxTimelineEntries: 200;
+    readonly DefaultFollowUpDays: 3;
+    readonly TimelinePageSize: 20;
+};
+declare const AGENT_CALL_DEFAULTS: {
+    readonly MaxConcurrentCalls: 10;
+};
+declare const SYSTEM_TIMELINE: {
+    readonly CallCreated: "Call log created";
+    readonly CallClosed: "Call closed";
+    readonly CallReopened: "Call reopened";
+    readonly FollowUpCompleted: "Follow-up completed";
+};
+declare const SYSTEM_TIMELINE_FN: {
+    readonly stageChanged: (from: string, to: string) => string;
+    readonly callAssigned: (agentName: string) => string;
+    readonly callReassigned: (from: string, to: string) => string;
+    readonly followUpSet: (date: string) => string;
+};
+
+declare class AlxCallLogError extends AlxError {
+    readonly context?: Record<string, unknown> | undefined;
+    constructor(message: string, code: string, context?: Record<string, unknown> | undefined);
+}
+declare class PipelineNotFoundError extends AlxCallLogError {
+    readonly pipelineId: string;
+    constructor(pipelineId: string);
+}
+declare class InvalidPipelineError extends AlxCallLogError {
+    readonly reason: string;
+    readonly pipelineId?: string | undefined;
+    constructor(reason: string, pipelineId?: string | undefined);
+}
+declare class StageNotFoundError extends AlxCallLogError {
+    readonly pipelineId: string;
+    readonly stageId: string;
+    constructor(pipelineId: string, stageId: string);
+}
+declare class StageInUseError extends AlxCallLogError {
+    readonly pipelineId: string;
+    readonly stageId: string;
+    readonly activeCallCount: number;
+    constructor(pipelineId: string, stageId: string, activeCallCount: number);
+}
+declare class CallLogNotFoundError extends AlxCallLogError {
+    readonly callLogId: string;
+    constructor(callLogId: string);
+}
+declare class CallLogClosedError extends AlxCallLogError {
+    readonly callLogId: string;
+    readonly attemptedAction: string;
+    constructor(callLogId: string, attemptedAction: string);
+}
+declare class ContactNotFoundError extends AlxCallLogError {
+    readonly contactQuery: Record<string, unknown>;
+    constructor(contactQuery: Record<string, unknown>);
+}
+declare class AgentCapacityError extends AlxCallLogError {
+    readonly agentId: string;
+    readonly currentCalls: number;
+    readonly maxCalls: number;
+    constructor(agentId: string, currentCalls: number, maxCalls: number);
+}
+declare class InvalidConfigError extends AlxCallLogError {
+    readonly field: string;
+    readonly reason: string;
+    constructor(field: string, reason: string);
+}
+declare class AuthFailedError extends AlxCallLogError {
+    readonly reason?: string | undefined;
+    constructor(reason?: string | undefined);
+}
+
+/**
+ * Validates a pipeline's stages array against all business rules.
+ *
+ * @param stages - The array of pipeline stages to validate.
+ * @param pipelineId - Optional pipeline identifier used in error messages.
+ * @throws InvalidPipelineError when any rule is violated.
+ */
+declare function validatePipelineStages(stages: IPipelineStage[], pipelineId?: string): void;
+
+interface FollowUpWorkerDeps {
+    CallLog: Model<ICallLogDocument>;
+    hooks: {
+        onFollowUpDue?: (callLog: ICallLog) => void | Promise<void>;
+    };
+    logger: LogAdapter;
+    options: ResolvedOptions;
+}
+declare class FollowUpWorker {
+    private deps;
+    private intervalId;
+    private running;
+    constructor(deps: FollowUpWorkerDeps);
+    start(): void;
+    stop(): void;
+    private tick;
+}
+
+interface RouteServices {
+    pipelines: PipelineService;
+    callLogs: CallLogService;
+    timeline: TimelineService;
+    analytics: AnalyticsService;
+    settings: SettingsService;
+    export: ExportService;
+}
+interface RouteOptions {
+    authenticateRequest?: (req: Request) => Promise<AuthResult | null>;
+    logger: LogAdapter;
+}
+declare function createRoutes(services: RouteServices, options: RouteOptions): Router;
+
+interface CallLogEngine {
+    pipelines: PipelineService;
+    callLogs: CallLogService;
+    timeline: TimelineService;
+    analytics: AnalyticsService;
+    settings: SettingsService;
+    export: ExportService;
+    routes: Router;
+    models: {
+        Pipeline: Model<IPipelineDocument>;
+        CallLog: Model<ICallLogDocument>;
+        CallLogSettings: Model<ICallLogSettingsDocument>;
+    };
+    destroy: () => Promise<void>;
+}
+declare function createCallLogEngine(config: CallLogEngineConfig): CallLogEngine;
+
+export { AGENT_CALL_DEFAULTS, AgentCapacityError, AlxCallLogError, AnalyticsService, AuthFailedError, CALL_LOG_DEFAULTS, CallLogClosedError, type CallLogEngine, CallLogNotFoundError, CallLogSchema, CallLogService, CallLogSettingsSchema, ContactNotFoundError, ContactRefSchema, ERROR_CODE, ERROR_MESSAGE, type ErrorCode, ExportService, FollowUpWorker, type ICallLogDocument, type ICallLogSettingsDocument, type IPipelineDocument, type IPipelineStageDocument, InvalidConfigError, InvalidPipelineError, PIPELINE_DEFAULTS, PipelineNotFoundError, PipelineSchema, PipelineService, PipelineStageSchema, SYSTEM_TIMELINE, SYSTEM_TIMELINE_FN, SettingsService, StageChangeSchema, StageInUseError, StageNotFoundError, TimelineEntrySchema, TimelineService, createCallLogEngine, createCallLogModel, createCallLogSettingsModel, createPipelineModel, createRoutes, validatePipelineStages };