@valentine-efagene/qshelter-common 2.0.98 → 2.0.100

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/prisma/tenant.js

@@ -1,30 +1,17 @@
 /**
- * INVERTED APPROACH: All models are tenant-scoped by default.
- * Only list models that are explicitly GLOBAL (no tenant scoping).
- *
- * This reduces the risk of accidentally omitting a new model from tenant scoping.
+ * INVERTED APPROACH: List models that DON'T have a tenantId field.
+ * All other models are assumed to be tenant-scoped.
+ * This is easier to manage since most models ARE tenant-scoped.
  */
 /**
- * Models that are intentionally GLOBAL and should NOT be tenant-scoped.
- * These models either:
- * - Don't have a tenantId field (system tables)
- * - Have optional tenantId but are designed to work across tenants (User)
- * - Are cross-tenant lookup/join tables (TenantMembership)
+ * Models that are truly global and have NO tenantId field at all.
+ * These are excluded from tenant filtering/injection.
  */
 const GLOBAL_MODELS = [
-    // User can exist across tenants or without a tenant (federated)
+    // System-level entities with no tenant ownership
+    "tenant",
     "user",
-    // TenantMembership is the user-tenant join table (queries by userId or tenantId)
     "tenantMembership",
-    // System/infrastructure tables without tenantId
-    "tenant",
-    // Legacy role assignment (global, not tenant-scoped)
-    "userRole",
-    "rolePermission",
-    "refreshToken",
-    "passwordReset",
-    "wallet",
-    "domainEvent",
 ];
 /**
  * Models that have OPTIONAL tenant scoping (nullable tenantId).
@@ -45,9 +32,16 @@ function isOptionalTenantModel(model) {
     return OPTIONAL_TENANT_MODELS.includes(model);
 }
 /**
- * A model is tenant-scoped by default unless explicitly listed as global.
+ * Check if model is tenant-scoped (required tenantId)
+ * A model is tenant-scoped if it's NOT global and NOT optional-tenant
  */
 function isTenantScopedModel(model) {
+    return !isGlobalModel(model) && !isOptionalTenantModel(model);
+}
+/**
+ * Check if model has any tenant scoping (required or optional)
+ */
+function hasTenantField(model) {
     return !isGlobalModel(model);
 }
 /**
@@ -68,7 +62,7 @@ export function createTenantPrisma(prisma, context) {
         query: {
             $allModels: {
                 async findMany({ model, args, query }) {
-                    if (isTenantScopedModel(model)) {
+                    if (hasTenantField(model)) {
                         const tenantFilter = isOptionalTenantModel(model)
                             ? { OR: [{ tenantId }, { tenantId: null }] }
                             : { tenantId };
@@ -80,7 +74,7 @@ export function createTenantPrisma(prisma, context) {
                     return query(args);
                 },
                 async findFirst({ model, args, query }) {
-                    if (isTenantScopedModel(model)) {
+                    if (hasTenantField(model)) {
                         const tenantFilter = isOptionalTenantModel(model)
                             ? { OR: [{ tenantId }, { tenantId: null }] }
                             : { tenantId };
@@ -94,7 +88,7 @@ export function createTenantPrisma(prisma, context) {
                 async findUnique({ model, args, query }) {
                     // findUnique can only filter by unique fields, so we verify after fetch
                     const result = await query(args);
-                    if (result && isTenantScopedModel(model)) {
+                    if (result && hasTenantField(model)) {
                         const record = result;
                         if (isOptionalTenantModel(model)) {
                             // Allow null tenantId (global) or matching tenantId
@@ -111,7 +105,7 @@ export function createTenantPrisma(prisma, context) {
                     return result;
                 },
                 async create({ model, args, query }) {
-                    if (isTenantScopedModel(model) && !isOptionalTenantModel(model)) {
+                    if (isTenantScopedModel(model)) {
                         // Inject tenantId for required tenant models
                         args.data.tenantId = tenantId;
                     }
@@ -124,10 +118,10 @@ export function createTenantPrisma(prisma, context) {
                     return query(args);
                 },
                 async createMany({ model, args, query }) {
-                    if (isTenantScopedModel(model)) {
+                    if (hasTenantField(model)) {
                         const data = Array.isArray(args.data) ? args.data : [args.data];
                         args.data = data.map((item) => {
-                            if (!isOptionalTenantModel(model)) {
+                            if (isTenantScopedModel(model)) {
                                 return { ...item, tenantId };
                             }
                             // For optional models, inject if not explicitly set
@@ -140,7 +134,7 @@ export function createTenantPrisma(prisma, context) {
                     return query(args);
                 },
                 async update({ model, args, query }) {
-                    if (isTenantScopedModel(model)) {
+                    if (hasTenantField(model)) {
                         // Verify tenant ownership before update
                         const tenantFilter = isOptionalTenantModel(model)
                             ? { OR: [{ tenantId }, { tenantId: null }] }
@@ -153,7 +147,7 @@ export function createTenantPrisma(prisma, context) {
                     return query(args);
                 },
                 async updateMany({ model, args, query }) {
-                    if (isTenantScopedModel(model)) {
+                    if (hasTenantField(model)) {
                         const tenantFilter = isOptionalTenantModel(model)
                             ? { OR: [{ tenantId }, { tenantId: null }] }
                             : { tenantId };
@@ -165,7 +159,7 @@ export function createTenantPrisma(prisma, context) {
                     return query(args);
                 },
                 async delete({ model, args, query }) {
-                    if (isTenantScopedModel(model)) {
+                    if (hasTenantField(model)) {
                         const tenantFilter = isOptionalTenantModel(model)
                             ? { OR: [{ tenantId }, { tenantId: null }] }
                             : { tenantId };
@@ -177,7 +171,7 @@ export function createTenantPrisma(prisma, context) {
                     return query(args);
                 },
                 async deleteMany({ model, args, query }) {
-                    if (isTenantScopedModel(model)) {
+                    if (hasTenantField(model)) {
                         const tenantFilter = isOptionalTenantModel(model)
                             ? { OR: [{ tenantId }, { tenantId: null }] }
                             : { tenantId };
@@ -189,7 +183,7 @@ export function createTenantPrisma(prisma, context) {
                     return query(args);
                 },
                 async count({ model, args, query }) {
-                    if (isTenantScopedModel(model)) {
+                    if (hasTenantField(model)) {
                         const tenantFilter = isOptionalTenantModel(model)
                             ? { OR: [{ tenantId }, { tenantId: null }] }
                             : { tenantId };

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;