@valentine-efagene/qshelter-common 2.0.98 → 2.0.100

package/dist/src/types/action-status.js

@@ -0,0 +1,402 @@
+/**
+ * Action Status Types - Back-end driven UI indicators
+ *
+ * This module provides types for indicating who needs to act next
+ * at various levels of the application (application, phase, step).
+ *
+ * The frontend uses this to show:
+ * - "Awaiting your action" (CUSTOMER)
+ * - "Under review" (ADMIN)
+ * - "Processing..." (SYSTEM)
+ * - "Completed" (NONE)
+ * - "Awaiting payment" (CUSTOMER for payment phases)
+ */
+/**
+ * The actor who needs to take the next action
+ */
+export var NextActor;
+(function (NextActor) {
+    /** Customer must take action (upload, sign, pay) */
+    NextActor["CUSTOMER"] = "CUSTOMER";
+    /** Admin must take action (review, approve, reject) */
+    NextActor["ADMIN"] = "ADMIN";
+    /** System is processing (auto-generation, webhook, etc.) */
+    NextActor["SYSTEM"] = "SYSTEM";
+    /** No action required - completed or waiting for external event */
+    NextActor["NONE"] = "NONE";
+})(NextActor || (NextActor = {}));
+/**
+ * High-level action categories for easier UI grouping
+ */
+export var ActionCategory;
+(function (ActionCategory) {
+    /** Document upload/reupload needed */
+    ActionCategory["UPLOAD"] = "UPLOAD";
+    /** Signature required */
+    ActionCategory["SIGNATURE"] = "SIGNATURE";
+    /** Review/approval needed */
+    ActionCategory["REVIEW"] = "REVIEW";
+    /** Payment required */
+    ActionCategory["PAYMENT"] = "PAYMENT";
+    /** Waiting for external process */
+    ActionCategory["PROCESSING"] = "PROCESSING";
+    /** Phase/step/application completed */
+    ActionCategory["COMPLETED"] = "COMPLETED";
+    /** Waiting for previous phase/step */
+    ActionCategory["WAITING"] = "WAITING";
+})(ActionCategory || (ActionCategory = {}));
+/**
+ * Compute action status for a documentation step
+ */
+export function computeStepActionStatus(step, pendingDocuments, totalDocuments) {
+    const base = {
+        stepId: step.id,
+        stepName: step.name,
+        stepType: step.stepType,
+        stepOrder: step.order,
+        dueDate: step.dueDate ?? null,
+        isBlocking: true,
+    };
+    // Handle step status
+    switch (step.status) {
+        case 'COMPLETED':
+            return {
+                ...base,
+                nextActor: NextActor.NONE,
+                actionCategory: ActionCategory.COMPLETED,
+                actionRequired: 'Step completed',
+                isBlocking: false,
+            };
+        case 'SKIPPED':
+            return {
+                ...base,
+                nextActor: NextActor.NONE,
+                actionCategory: ActionCategory.COMPLETED,
+                actionRequired: 'Step skipped',
+                isBlocking: false,
+            };
+        case 'NEEDS_RESUBMISSION':
+            return {
+                ...base,
+                nextActor: NextActor.CUSTOMER,
+                actionCategory: ActionCategory.UPLOAD,
+                actionRequired: step.actionReason || 'Please resubmit the required document',
+                progress: 'Document was rejected - resubmission required',
+            };
+        case 'ACTION_REQUIRED':
+            return {
+                ...base,
+                nextActor: NextActor.CUSTOMER,
+                actionCategory: ActionCategory.UPLOAD,
+                actionRequired: step.actionReason || 'Your action is required',
+            };
+        case 'AWAITING_REVIEW':
+            return {
+                ...base,
+                nextActor: NextActor.ADMIN,
+                actionCategory: ActionCategory.REVIEW,
+                actionRequired: 'Document submitted - awaiting admin review',
+                progress: 'Under review',
+            };
+        case 'IN_PROGRESS':
+        case 'PENDING':
+            // Determine based on step type
+            return computeStepActionByType(step, base, pendingDocuments, totalDocuments);
+        case 'FAILED':
+            return {
+                ...base,
+                nextActor: NextActor.ADMIN,
+                actionCategory: ActionCategory.REVIEW,
+                actionRequired: 'Step failed - admin intervention required',
+            };
+        default:
+            return {
+                ...base,
+                nextActor: NextActor.NONE,
+                actionCategory: ActionCategory.WAITING,
+                actionRequired: 'Waiting',
+            };
+    }
+}
+/**
+ * Compute action status based on step type for PENDING/IN_PROGRESS steps
+ */
+function computeStepActionByType(step, base, pendingDocuments, totalDocuments) {
+    switch (step.stepType) {
+        case 'UPLOAD':
+            const progress = totalDocuments !== undefined && pendingDocuments !== undefined
+                ? `${totalDocuments - pendingDocuments} of ${totalDocuments} documents uploaded`
+                : undefined;
+            return {
+                ...base,
+                nextActor: NextActor.CUSTOMER,
+                actionCategory: ActionCategory.UPLOAD,
+                actionRequired: `Upload required: ${step.name}`,
+                progress,
+            };
+        case 'SIGNATURE':
+            return {
+                ...base,
+                nextActor: NextActor.CUSTOMER,
+                actionCategory: ActionCategory.SIGNATURE,
+                actionRequired: `Signature required: ${step.name}`,
+            };
+        case 'APPROVAL':
+        case 'REVIEW':
+            return {
+                ...base,
+                nextActor: NextActor.ADMIN,
+                actionCategory: ActionCategory.REVIEW,
+                actionRequired: `Admin review required: ${step.name}`,
+                progress: 'Awaiting admin approval',
+            };
+        case 'GENERATE_DOCUMENT':
+            return {
+                ...base,
+                nextActor: NextActor.SYSTEM,
+                actionCategory: ActionCategory.PROCESSING,
+                actionRequired: `Generating document: ${step.name}`,
+                progress: 'System is processing',
+            };
+        case 'EXTERNAL_CHECK':
+        case 'WAIT':
+            return {
+                ...base,
+                nextActor: NextActor.SYSTEM,
+                actionCategory: ActionCategory.PROCESSING,
+                actionRequired: `Waiting for external process: ${step.name}`,
+                progress: 'Awaiting external verification',
+            };
+        case 'PRE_APPROVAL':
+        case 'UNDERWRITING':
+            return {
+                ...base,
+                nextActor: NextActor.SYSTEM,
+                actionCategory: ActionCategory.PROCESSING,
+                actionRequired: `Processing: ${step.name}`,
+                progress: 'Underwriting in progress',
+            };
+        default:
+            return {
+                ...base,
+                nextActor: NextActor.CUSTOMER,
+                actionCategory: ActionCategory.UPLOAD,
+                actionRequired: step.name,
+            };
+    }
+}
+/**
+ * Compute action status for a phase based on its category and current state
+ */
+export function computePhaseActionStatus(phase) {
+    const base = {
+        phaseId: phase.id,
+        phaseName: phase.name,
+        phaseType: phase.phaseType,
+        phaseCategory: phase.phaseCategory,
+        dueDate: phase.dueDate ?? null,
+    };
+    // Handle phase status
+    switch (phase.status) {
+        case 'COMPLETED':
+            return {
+                ...base,
+                nextActor: NextActor.NONE,
+                actionCategory: ActionCategory.COMPLETED,
+                actionRequired: 'Phase completed',
+                isBlocking: false,
+            };
+        case 'SKIPPED':
+        case 'SUPERSEDED':
+            return {
+                ...base,
+                nextActor: NextActor.NONE,
+                actionCategory: ActionCategory.COMPLETED,
+                actionRequired: 'Phase skipped',
+                isBlocking: false,
+            };
+        case 'PENDING':
+            return {
+                ...base,
+                nextActor: NextActor.NONE,
+                actionCategory: ActionCategory.WAITING,
+                actionRequired: 'Waiting for previous phase to complete',
+                isBlocking: false,
+            };
+        case 'FAILED':
+            return {
+                ...base,
+                nextActor: NextActor.ADMIN,
+                actionCategory: ActionCategory.REVIEW,
+                actionRequired: 'Phase failed - admin intervention required',
+                isBlocking: true,
+            };
+    }
+    // For IN_PROGRESS/ACTIVE phases, determine based on category
+    switch (phase.phaseCategory) {
+        case 'DOCUMENTATION':
+            return computeDocumentationPhaseStatus(phase, base);
+        case 'PAYMENT':
+            return computePaymentPhaseStatus(phase, base);
+        case 'QUESTIONNAIRE':
+            return computeQuestionnairePhaseStatus(phase, base);
+        default:
+            return {
+                ...base,
+                nextActor: NextActor.CUSTOMER,
+                actionCategory: ActionCategory.UPLOAD,
+                actionRequired: 'Action required',
+                isBlocking: true,
+            };
+    }
+}
+function computeDocumentationPhaseStatus(phase, base) {
+    const docPhase = phase.documentationPhase;
+    if (!docPhase) {
+        return {
+            ...base,
+            nextActor: NextActor.CUSTOMER,
+            actionCategory: ActionCategory.UPLOAD,
+            actionRequired: 'Documentation required',
+            isBlocking: true,
+        };
+    }
+    const completedSteps = docPhase.completedStepsCount ?? 0;
+    const totalSteps = docPhase.totalStepsCount ?? docPhase.steps?.length ?? 0;
+    const stepsProgress = `${completedSteps} of ${totalSteps} steps completed`;
+    // Get current step status
+    const currentStep = docPhase.currentStep;
+    if (currentStep) {
+        const stepStatus = computeStepActionStatus(currentStep);
+        return {
+            ...base,
+            nextActor: stepStatus.nextActor,
+            actionCategory: stepStatus.actionCategory,
+            actionRequired: stepStatus.actionRequired,
+            progress: stepStatus.progress,
+            stepsProgress,
+            currentStep: stepStatus,
+            isBlocking: true,
+        };
+    }
+    // No current step - check if all steps are completed
+    const steps = docPhase.steps || [];
+    const allCompleted = steps.every((s) => s.status === 'COMPLETED');
+    if (allCompleted) {
+        return {
+            ...base,
+            nextActor: NextActor.NONE,
+            actionCategory: ActionCategory.COMPLETED,
+            actionRequired: 'All steps completed',
+            stepsProgress,
+            isBlocking: false,
+        };
+    }
+    // Find next pending step
+    const nextStep = steps.find((s) => s.status !== 'COMPLETED' && s.status !== 'SKIPPED');
+    if (nextStep) {
+        const stepStatus = computeStepActionStatus(nextStep);
+        return {
+            ...base,
+            nextActor: stepStatus.nextActor,
+            actionCategory: stepStatus.actionCategory,
+            actionRequired: stepStatus.actionRequired,
+            progress: stepStatus.progress,
+            stepsProgress,
+            currentStep: stepStatus,
+            isBlocking: true,
+        };
+    }
+    return {
+        ...base,
+        nextActor: NextActor.NONE,
+        actionCategory: ActionCategory.WAITING,
+        actionRequired: 'Waiting',
+        stepsProgress,
+        isBlocking: false,
+    };
+}
+function computePaymentPhaseStatus(phase, base) {
+    const payPhase = phase.paymentPhase;
+    if (!payPhase) {
+        return {
+            ...base,
+            nextActor: NextActor.CUSTOMER,
+            actionCategory: ActionCategory.PAYMENT,
+            actionRequired: 'Payment required',
+            isBlocking: true,
+        };
+    }
+    const totalAmount = payPhase.totalAmount ?? 0;
+    const paidAmount = payPhase.paidAmount ?? 0;
+    const remainingAmount = totalAmount - paidAmount;
+    const paymentProgress = `₦${paidAmount.toLocaleString()} of ₦${totalAmount.toLocaleString()} paid`;
+    if (remainingAmount <= 0) {
+        return {
+            ...base,
+            nextActor: NextActor.NONE,
+            actionCategory: ActionCategory.COMPLETED,
+            actionRequired: 'Payment completed',
+            paymentProgress,
+            isBlocking: false,
+        };
+    }
+    // Check for pending installments
+    const installments = payPhase.installments || [];
+    const pendingInstallment = installments.find((i) => i.status === 'PENDING' || i.status === 'OVERDUE' || i.status === 'PARTIALLY_PAID');
+    if (pendingInstallment) {
+        const isOverdue = pendingInstallment.status === 'OVERDUE';
+        return {
+            ...base,
+            nextActor: NextActor.CUSTOMER,
+            actionCategory: ActionCategory.PAYMENT,
+            actionRequired: isOverdue
+                ? `Overdue payment: ₦${pendingInstallment.amount.toLocaleString()}`
+                : `Payment due: ₦${pendingInstallment.amount.toLocaleString()}`,
+            paymentProgress,
+            dueDate: pendingInstallment.dueDate,
+            isBlocking: true,
+        };
+    }
+    return {
+        ...base,
+        nextActor: NextActor.CUSTOMER,
+        actionCategory: ActionCategory.PAYMENT,
+        actionRequired: `Remaining balance: ₦${remainingAmount.toLocaleString()}`,
+        paymentProgress,
+        isBlocking: true,
+    };
+}
+function computeQuestionnairePhaseStatus(phase, base) {
+    const qPhase = phase.questionnairePhase;
+    if (!qPhase) {
+        return {
+            ...base,
+            nextActor: NextActor.CUSTOMER,
+            actionCategory: ActionCategory.UPLOAD,
+            actionRequired: 'Complete questionnaire',
+            isBlocking: true,
+        };
+    }
+    const completedFields = qPhase.completedFieldsCount ?? 0;
+    const totalFields = qPhase.totalFieldsCount ?? 0;
+    const progress = `${completedFields} of ${totalFields} fields completed`;
+    if (completedFields >= totalFields && totalFields > 0) {
+        return {
+            ...base,
+            nextActor: NextActor.NONE,
+            actionCategory: ActionCategory.COMPLETED,
+            actionRequired: 'Questionnaire completed',
+            progress,
+            isBlocking: false,
+        };
+    }
+    return {
+        ...base,
+        nextActor: NextActor.CUSTOMER,
+        actionCategory: ActionCategory.UPLOAD,
+        actionRequired: 'Complete questionnaire fields',
+        progress,
+        isBlocking: true,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valentine-efagene/qshelter-common",
-  "version": "2.0.98",
+  "version": "2.0.100",
   "description": "Shared database schemas and utilities for QShelter services",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",

package/prisma/migrations/20260113000000_remove_workflow_analytics_summary/migration.sql

@@ -0,0 +1,5 @@
+-- RemoveWorkflowAnalyticsSummary
+-- Removes the workflow_analytics_summaries table as we compute analytics on-demand
+-- from the workflow_blockers table instead of pre-aggregating.
+
+DROP TABLE IF EXISTS `workflow_analytics_summaries`;