@valentine-efagene/qshelter-common 2.0.98 → 2.0.99

package/dist/generated/client/models/WorkflowBlocker.js

@@ -0,0 +1 @@
+export {};

package/dist/generated/client/models/index.d.ts

@@ -60,4 +60,5 @@ export * from './User';
 export * from './UserRole';
 export * from './UserSuspension';
 export * from './Wallet';
+export * from './WorkflowBlocker';
 export * from './WorkflowEvent';

package/dist/generated/client/models/index.js

@@ -60,4 +60,5 @@ export * from './User';
 export * from './UserRole';
 export * from './UserSuspension';
 export * from './Wallet';
+export * from './WorkflowBlocker';
 export * from './WorkflowEvent';

package/dist/generated/client/models.d.ts

@@ -61,4 +61,5 @@ export type * from './models/EventHandlerExecution.js';
 export type * from './models/DomainEvent.js';
 export type * from './models/PropertyTransferRequest.js';
 export type * from './models/ApprovalRequest.js';
+export type * from './models/WorkflowBlocker.js';
 export type * from './commonInputTypes.js';

package/dist/src/index.d.ts

@@ -1,4 +1,5 @@
 export * from './types/response';
+export * from './types/action-status';
 export * from './utils/errors';
 export * from './config';
 export { PrismaClient, Prisma } from '../generated/client/client';

package/dist/src/index.js

@@ -1,4 +1,5 @@
 export * from './types/response';
+export * from './types/action-status';
 export * from './utils/errors';
 export * from './config';
 export { PrismaClient, Prisma } from '../generated/client/client';

package/dist/src/middleware/auth-context.d.ts

@@ -20,11 +20,15 @@ export interface AuthContext {
     roles?: string[];
 }
 /**
- * Extracts auth context from API Gateway authorizer.
+ * Extracts auth context from API Gateway authorizer or JWT token.
  *
  * Priority:
- * 1. Production: requestContext.authorizer (set by API Gateway)
- * 2. Test/Dev: x-authorizer-* headers (set by test harness)
+ * 1. Production: requestContext.authorizer (set by API Gateway Lambda Authorizer)
+ * 2. Fallback: Decode JWT from Authorization header (LocalStack/dev/tests)
+ *
+ * In production, the Lambda Authorizer validates the JWT and injects context.
+ * In LocalStack (no authorizer), we decode the JWT directly since it contains
+ * all the same information: sub (userId), tenantId, email, roles.
  *
  * @param req Express request object
  * @returns AuthContext or null if not authenticated
@@ -54,18 +58,71 @@ export declare function requireAuth(req: Request, res: Response, next: NextFunct
  */
 export declare function getAuthContext(req: Request): AuthContext;
 /**
- * Test helper to generate authorizer headers.
- * Use this in tests to simulate API Gateway authorizer context.
+ * Test helper to generate authorization header with JWT.
+ *
+ * Since auth context is now extracted directly from the JWT,
+ * tests only need to pass the Authorization header with a valid token.
  *
  * @example
  * ```typescript
  * const response = await request(app)
  *     .post('/users')
- *     .set(authHeaders(userId, tenantId))
+ *     .set('Authorization', `Bearer ${token}`)
  *     .send({ name: 'John' });
  * ```
+ *
+ * @deprecated Use Authorization header directly with JWT token.
+ * This helper is kept for backward compatibility.
  */
 export declare function authHeaders(userId: string, tenantId: string, extras?: {
     email?: string;
     roles?: string[];
+    token?: string;
 }): Record<string, string>;
+/**
+ * Standard role names used across the platform.
+ */
+export declare const ROLES: {
+    readonly SUPER_ADMIN: "SUPER_ADMIN";
+    readonly TENANT_ADMIN: "TENANT_ADMIN";
+    readonly LOAN_OFFICER: "LOAN_OFFICER";
+    readonly CUSTOMER: "CUSTOMER";
+    readonly VIEWER: "VIEWER";
+};
+export type RoleName = (typeof ROLES)[keyof typeof ROLES];
+/**
+ * Roles that have admin privileges (can manage resources).
+ */
+export declare const ADMIN_ROLES: RoleName[];
+/**
+ * Check if user has any of the specified roles.
+ */
+export declare function hasAnyRole(userRoles: string[] | undefined, requiredRoles: string[]): boolean;
+/**
+ * Check if user has admin privileges.
+ */
+export declare function isAdmin(userRoles: string[] | undefined): boolean;
+/**
+ * Middleware factory that requires user to have specific role(s).
+ * Uses roles from API Gateway authorizer context.
+ *
+ * @example
+ * ```typescript
+ * // Require any admin role
+ * router.post('/payment-plans', requireRole(ADMIN_ROLES), createPaymentPlan);
+ *
+ * // Require specific role
+ * router.delete('/users/:id', requireRole(['SUPER_ADMIN']), deleteUser);
+ * ```
+ */
+export declare function requireRole(allowedRoles: string[]): (req: Request, res: Response, next: NextFunction) => Response<any, Record<string, any>> | undefined;
+/**
+ * Middleware that requires admin privileges.
+ * Shorthand for requireRole(ADMIN_ROLES).
+ *
+ * @example
+ * ```typescript
+ * router.post('/payment-methods', requireAdmin, createPaymentMethod);
+ * ```
+ */
+export declare function requireAdmin(req: Request, res: Response, next: NextFunction): Response<any, Record<string, any>> | undefined;

package/dist/src/middleware/auth-context.js

@@ -1,9 +1,30 @@
 /**
- * Extracts auth context from API Gateway authorizer.
+ * Safely decode JWT payload without verification.
+ * Used to extract claims like roles when authorizer context isn't available.
+ * Note: This is NOT validation - we trust the token was already validated upstream.
+ */
+function decodeJwtPayload(token) {
+    try {
+        const parts = token.split('.');
+        if (parts.length !== 3)
+            return null;
+        const payload = Buffer.from(parts[1], 'base64').toString('utf-8');
+        return JSON.parse(payload);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Extracts auth context from API Gateway authorizer or JWT token.
  *
  * Priority:
- * 1. Production: requestContext.authorizer (set by API Gateway)
- * 2. Test/Dev: x-authorizer-* headers (set by test harness)
+ * 1. Production: requestContext.authorizer (set by API Gateway Lambda Authorizer)
+ * 2. Fallback: Decode JWT from Authorization header (LocalStack/dev/tests)
+ *
+ * In production, the Lambda Authorizer validates the JWT and injects context.
+ * In LocalStack (no authorizer), we decode the JWT directly since it contains
+ * all the same information: sub (userId), tenantId, email, roles.
  *
  * @param req Express request object
  * @returns AuthContext or null if not authenticated
@@ -20,15 +41,30 @@ export function extractAuthContext(req) {
             roles: authorizer.roles ? JSON.parse(authorizer.roles) : [],
         };
     }
-    // Test/Development: Simulated authorizer headers
-    // These headers should only be set by test harness or local dev proxy
-    const userId = req.headers['x-authorizer-user-id'];
-    const tenantId = req.headers['x-authorizer-tenant-id'];
-    if (userId && tenantId) {
+    // Fallback: Decode JWT directly (LocalStack, local dev, tests)
+    // The JWT already contains: sub (userId), tenantId, email, roles
+    const authHeader = req.headers['authorization'];
+    if (authHeader?.startsWith('Bearer ')) {
+        const token = authHeader.substring(7);
+        const payload = decodeJwtPayload(token);
+        if (payload?.sub && payload?.tenantId) {
+            return {
+                userId: payload.sub,
+                tenantId: payload.tenantId,
+                email: payload.email,
+                roles: Array.isArray(payload.roles) ? payload.roles : [],
+            };
+        }
+    }
+    // Legacy fallback: Mock headers for unit tests without real JWTs
+    // These should only be used in unit tests, not E2E or production
+    const mockUserId = req.headers['x-authorizer-user-id'];
+    const mockTenantId = req.headers['x-authorizer-tenant-id'];
+    if (mockUserId && mockTenantId) {
         const rolesHeader = req.headers['x-authorizer-roles'];
         return {
-            userId,
-            tenantId,
+            userId: mockUserId,
+            tenantId: mockTenantId,
             email: req.headers['x-authorizer-email'],
             roles: rolesHeader ? JSON.parse(rolesHeader) : [],
         };
@@ -79,18 +115,29 @@ export function getAuthContext(req) {
     return auth;
 }
 /**
- * Test helper to generate authorizer headers.
- * Use this in tests to simulate API Gateway authorizer context.
+ * Test helper to generate authorization header with JWT.
+ *
+ * Since auth context is now extracted directly from the JWT,
+ * tests only need to pass the Authorization header with a valid token.
  *
  * @example
  * ```typescript
  * const response = await request(app)
  *     .post('/users')
- *     .set(authHeaders(userId, tenantId))
+ *     .set('Authorization', `Bearer ${token}`)
  *     .send({ name: 'John' });
  * ```
+ *
+ * @deprecated Use Authorization header directly with JWT token.
+ * This helper is kept for backward compatibility.
  */
 export function authHeaders(userId, tenantId, extras) {
+    // If a token is provided, just use that (preferred)
+    if (extras?.token) {
+        return { 'Authorization': `Bearer ${extras.token}` };
+    }
+    // Legacy: Build mock headers for tests without real JWT
+    // This is only for unit tests that don't have access to real tokens
     return {
         'x-authorizer-user-id': userId,
         'x-authorizer-tenant-id': tenantId,
@@ -98,3 +145,75 @@ export function authHeaders(userId, tenantId, extras) {
         ...(extras?.roles && { 'x-authorizer-roles': JSON.stringify(extras.roles) }),
     };
 }
+/**
+ * Standard role names used across the platform.
+ */
+export const ROLES = {
+    SUPER_ADMIN: 'SUPER_ADMIN',
+    TENANT_ADMIN: 'TENANT_ADMIN',
+    LOAN_OFFICER: 'LOAN_OFFICER',
+    CUSTOMER: 'CUSTOMER',
+    VIEWER: 'VIEWER',
+};
+/**
+ * Roles that have admin privileges (can manage resources).
+ */
+export const ADMIN_ROLES = [ROLES.SUPER_ADMIN, ROLES.TENANT_ADMIN, ROLES.LOAN_OFFICER];
+/**
+ * Check if user has any of the specified roles.
+ */
+export function hasAnyRole(userRoles, requiredRoles) {
+    if (!userRoles || userRoles.length === 0)
+        return false;
+    return requiredRoles.some(role => userRoles.includes(role));
+}
+/**
+ * Check if user has admin privileges.
+ */
+export function isAdmin(userRoles) {
+    return hasAnyRole(userRoles, ADMIN_ROLES);
+}
+/**
+ * Middleware factory that requires user to have specific role(s).
+ * Uses roles from API Gateway authorizer context.
+ *
+ * @example
+ * ```typescript
+ * // Require any admin role
+ * router.post('/payment-plans', requireRole(ADMIN_ROLES), createPaymentPlan);
+ *
+ * // Require specific role
+ * router.delete('/users/:id', requireRole(['SUPER_ADMIN']), deleteUser);
+ * ```
+ */
+export function requireRole(allowedRoles) {
+    return function (req, res, next) {
+        const auth = extractAuthContext(req);
+        if (!auth) {
+            return res.status(401).json({
+                success: false,
+                error: 'Unauthorized - authentication required'
+            });
+        }
+        if (!hasAnyRole(auth.roles, allowedRoles)) {
+            return res.status(403).json({
+                success: false,
+                error: 'Forbidden - insufficient permissions',
+                requiredRoles: allowedRoles,
+            });
+        }
+        next();
+    };
+}
+/**
+ * Middleware that requires admin privileges.
+ * Shorthand for requireRole(ADMIN_ROLES).
+ *
+ * @example
+ * ```typescript
+ * router.post('/payment-methods', requireAdmin, createPaymentMethod);
+ * ```
+ */
+export function requireAdmin(req, res, next) {
+    return requireRole(ADMIN_ROLES)(req, res, next);
+}

package/dist/src/types/action-status.d.ts

@@ -0,0 +1,137 @@
+/**
+ * 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 declare enum NextActor {
+    /** Customer must take action (upload, sign, pay) */
+    CUSTOMER = "CUSTOMER",
+    /** Admin must take action (review, approve, reject) */
+    ADMIN = "ADMIN",
+    /** System is processing (auto-generation, webhook, etc.) */
+    SYSTEM = "SYSTEM",
+    /** No action required - completed or waiting for external event */
+    NONE = "NONE"
+}
+/**
+ * High-level action categories for easier UI grouping
+ */
+export declare enum ActionCategory {
+    /** Document upload/reupload needed */
+    UPLOAD = "UPLOAD",
+    /** Signature required */
+    SIGNATURE = "SIGNATURE",
+    /** Review/approval needed */
+    REVIEW = "REVIEW",
+    /** Payment required */
+    PAYMENT = "PAYMENT",
+    /** Waiting for external process */
+    PROCESSING = "PROCESSING",
+    /** Phase/step/application completed */
+    COMPLETED = "COMPLETED",
+    /** Waiting for previous phase/step */
+    WAITING = "WAITING"
+}
+/**
+ * Detailed action status for a step, phase, or application
+ */
+export interface ActionStatus {
+    /** Who needs to act next */
+    nextActor: NextActor;
+    /** Category of action required */
+    actionCategory: ActionCategory;
+    /** Human-readable description of what's needed */
+    actionRequired: string;
+    /** Optional: Additional context (e.g., "2 of 3 documents uploaded") */
+    progress?: string;
+    /** Optional: When this action is due (for time-sensitive actions) */
+    dueDate?: Date | string | null;
+    /** Optional: Whether this is blocking the overall workflow */
+    isBlocking?: boolean;
+}
+/**
+ * Step-level action status with step details
+ */
+export interface StepActionStatus extends ActionStatus {
+    stepId: string;
+    stepName: string;
+    stepType: string;
+    stepOrder: number;
+}
+/**
+ * Phase-level action status with aggregated step info
+ */
+export interface PhaseActionStatus extends ActionStatus {
+    phaseId: string;
+    phaseName: string;
+    phaseType: string;
+    phaseCategory: string;
+    /** Current step requiring attention (if documentation phase) */
+    currentStep?: StepActionStatus | null;
+    /** Summary of step progress (e.g., "3 of 5 steps completed") */
+    stepsProgress?: string;
+    /** For payment phases: payment progress summary */
+    paymentProgress?: string;
+}
+/**
+ * Application-level action status with phase info
+ */
+export interface ApplicationActionStatus extends ActionStatus {
+    applicationId: string;
+    applicationNumber: string;
+    /** Current phase requiring attention */
+    currentPhase?: PhaseActionStatus | null;
+    /** Summary of phase progress */
+    phasesProgress?: string;
+}
+/**
+ * Compute action status for a documentation step
+ */
+export declare function computeStepActionStatus(step: {
+    id: string;
+    name: string;
+    stepType: string;
+    order: number;
+    status: string;
+    actionReason?: string | null;
+    dueDate?: Date | string | null;
+}, pendingDocuments?: number, totalDocuments?: number): StepActionStatus;
+/**
+ * Compute action status for a phase based on its category and current state
+ */
+export declare function computePhaseActionStatus(phase: {
+    id: string;
+    name: string;
+    phaseType: string;
+    phaseCategory: string;
+    status: string;
+    dueDate?: Date | string | null;
+    documentationPhase?: {
+        currentStep?: any | null;
+        steps?: any[];
+        completedStepsCount?: number;
+        totalStepsCount?: number;
+        approvedDocumentsCount?: number;
+        requiredDocumentsCount?: number;
+    } | null;
+    paymentPhase?: {
+        totalAmount?: number;
+        paidAmount?: number;
+        installments?: any[];
+    } | null;
+    questionnairePhase?: {
+        completedFieldsCount?: number;
+        totalFieldsCount?: number;
+    } | null;
+}): PhaseActionStatus;