@platform-modules/civil-aviation-authority 2.3.280 → 2.3.282

package/src/i18n/workflow-chat-message.builder.ts

@@ -0,0 +1,578 @@
+/**
+ * CAA standard bilingual workflow/chat message builder.
+ *
+ * All services MUST use these helpers (never hardcode message strings).
+ * Templates live in workflow-chat-i18n.json; dynamic values use parallel EN/AR params.
+ */
+import catalog from './workflow-chat-i18n.json';
+
+export type BilingualText = { en: string; ar: string };
+
+export type WorkflowChatI18nCatalog = {
+  workflowTemplates: Record<string, BilingualText>;
+  chatTemplates: Record<string, BilingualText>;
+  workflowStatusLabels: Record<string, string>;
+  chatStatusLabels: Record<string, string>;
+};
+
+/** Master-data fields with English + Arabic columns (roles, departments, sections, users). */
+export type BilingualActorNames = {
+  roleName?: string | null;
+  roleArabicName?: string | null;
+  deptName?: string | null;
+  deptArabicName?: string | null;
+  sectionName?: string | null;
+  sectionArabicName?: string | null;
+  userName?: string | null;
+  userArabicName?: string | null;
+  employeeId?: string | number | null;
+};
+
+export type WorkflowMessageAction =
+  | 'request_submitted'
+  | 'notification_sent_pending'
+  | 'notification_sent_successfully'
+  | 'approval_in_progress'
+  | 'approval_pending'
+  | 'approved'
+  | 'rejected'
+  | 'returned_for_modification'
+  | 'approval_pending_update';
+
+export type ChatMessageAction =
+  | 'cancellation_submitted'
+  | 'request_received'
+  | 'approved'
+  | 'rejected'
+  | 'returned_for_modification';
+
+export type WorkflowMessageContext = BilingualActorNames & {
+  action: WorkflowMessageAction;
+  /** First human approval step → "in progress"; later steps → "pending". */
+  isFirstApprovalStep?: boolean;
+  comment?: string | null;
+};
+
+export type ChatMessageContext = BilingualActorNames & {
+  action: ChatMessageAction;
+  comment?: string | null;
+};
+
+const WORKFLOW_TEMPLATES = catalog.workflowTemplates as Record<string, BilingualText>;
+const CHAT_TEMPLATES = catalog.chatTemplates as Record<string, BilingualText>;
+const WORKFLOW_STATUS_LABELS = catalog.workflowStatusLabels as Record<string, string>;
+const CHAT_STATUS_LABELS = catalog.chatStatusLabels as Record<string, string>;
+
+export function getWorkflowChatI18nCatalog(): WorkflowChatI18nCatalog {
+  return catalog as WorkflowChatI18nCatalog;
+}
+
+function interpolate(template: string, params: Record<string, string> = {}): string {
+  return template.replace(/\{\{(\w+)\}\}/g, (_, key: string) => params[key] ?? '');
+}
+
+/** Arabic DB column preferred; English fallback so AR keeps identical structure to EN. */
+export function resolveBilingualName(
+  englishName?: string | null,
+  arabicName?: string | null,
+): string {
+  const ar = arabicName?.trim();
+  if (ar) return ar;
+  return englishName?.trim() || '';
+}
+
+export function pickLocalizedName(
+  englishName?: string | null,
+  arabicName?: string | null,
+  fallback = '',
+): string {
+  return resolveBilingualName(englishName, arabicName) || fallback;
+}
+
+/** @deprecated Use resolveBilingualName */
+export function pickArabicName(arabicName?: string | null): string {
+  return arabicName?.trim() || '';
+}
+
+function joinLabels(...parts: Array<string | null | undefined>): string {
+  return parts.map((p) => p?.trim()).filter(Boolean).join(' - ');
+}
+
+/** Build parallel EN / AR actor label from role OR dept+section. */
+export function resolveActorDisplayNames(actors: BilingualActorNames): { en: string; ar: string } {
+  if (actors.roleName?.trim()) {
+    const en = actors.roleName.trim();
+    return { en, ar: resolveBilingualName(en, actors.roleArabicName) };
+  }
+  const en = joinLabels(actors.deptName, actors.sectionName);
+  const ar = joinLabels(
+    resolveBilingualName(actors.deptName, actors.deptArabicName),
+    resolveBilingualName(actors.sectionName, actors.sectionArabicName),
+  );
+  return { en, ar };
+}
+
+/** @deprecated Use resolveActorDisplayNames */
+export function joinDeptSectionBilingualLabels(
+  deptEn?: string | null,
+  deptAr?: string | null,
+  sectEn?: string | null,
+  sectAr?: string | null,
+): { en: string; ar: string } {
+  return resolveActorDisplayNames({
+    deptName: deptEn,
+    deptArabicName: deptAr,
+    sectionName: sectEn,
+    sectionArabicName: sectAr,
+  });
+}
+
+/** @deprecated Use resolveActorDisplayNames */
+export function joinDeptSectionArabicLabels(
+  deptArabic?: string | null,
+  sectionArabic?: string | null,
+): string {
+  return joinLabels(deptArabic, sectionArabic);
+}
+
+export function formatWorkflowCommentSuffix(comment?: string | null): string {
+  const text = comment?.trim();
+  return text ? `: ${text}` : '';
+}
+
+export function formatChatCommentSuffix(comment?: string | null): string {
+  const text = comment?.trim();
+  return text ? ` - ${text}` : '';
+}
+
+/** Core renderer — always pass explicit EN and AR param objects with the same keys. */
+export function renderSynchronizedWorkflowMessage(
+  templateKey: string,
+  enParams: Record<string, string>,
+  arParams: Record<string, string>,
+): BilingualText {
+  const tpl = WORKFLOW_TEMPLATES[templateKey];
+  if (!tpl) return { en: templateKey, ar: templateKey };
+  return {
+    en: interpolate(tpl.en, enParams),
+    ar: interpolate(tpl.ar, arParams),
+  };
+}
+
+export function renderSynchronizedChatMessage(
+  templateKey: string,
+  enParams: Record<string, string>,
+  arParams: Record<string, string>,
+): BilingualText {
+  const tpl = CHAT_TEMPLATES[templateKey];
+  if (!tpl) return { en: templateKey, ar: templateKey };
+  return {
+    en: interpolate(tpl.en, enParams),
+    ar: interpolate(tpl.ar, arParams),
+  };
+}
+
+export function buildBilingualFromTemplate(
+  templateCatalog: Record<string, BilingualText>,
+  key: string,
+  params: Record<string, string> = {},
+  arParams?: Record<string, string>,
+): BilingualText {
+  const tpl = templateCatalog[key];
+  if (!tpl) return { en: key, ar: key };
+  const arabicParams = arParams ?? params;
+  return {
+    en: interpolate(tpl.en, params),
+    ar: interpolate(tpl.ar, arabicParams),
+  };
+}
+
+export function workflowTemplate(
+  key: string,
+  params: Record<string, string> = {},
+  arParams?: Record<string, string>,
+): BilingualText {
+  return buildBilingualFromTemplate(WORKFLOW_TEMPLATES, key, params, arParams);
+}
+
+export function chatTemplate(
+  key: string,
+  params: Record<string, string> = {},
+  arParams?: Record<string, string>,
+): BilingualText {
+  return buildBilingualFromTemplate(CHAT_TEMPLATES, key, params, arParams);
+}
+
+/**
+ * Standard entry point for workflow `content` + `content_ar`.
+ * Use for every workflow log insert/update across all CAA modules.
+ */
+export function buildSynchronizedWorkflowMessage(ctx: WorkflowMessageContext): BilingualText {
+  const commentWf = formatWorkflowCommentSuffix(ctx.comment);
+  const { en: actorEn, ar: actorAr } = resolveActorDisplayNames(ctx);
+
+  switch (ctx.action) {
+    case 'request_submitted':
+      return workflowTemplate('request_submitted');
+    case 'notification_sent_pending':
+      return workflowTemplate('notification_sent_pending');
+    case 'notification_sent_successfully':
+      return workflowTemplate('notification_sent_successfully');
+    case 'approval_in_progress':
+      return actorEn
+        ? renderSynchronizedWorkflowMessage(
+            'request_approval_in_progress_from',
+            { name: actorEn },
+            { name: actorAr },
+          )
+        : workflowTemplate('request_approval_in_progress');
+    case 'approval_pending':
+      return actorEn
+        ? renderSynchronizedWorkflowMessage(
+            'request_approval_pending_from',
+            { name: actorEn },
+            { name: actorAr },
+          )
+        : workflowTemplate('request_approval_pending');
+    case 'approved':
+      return actorEn
+        ? renderSynchronizedWorkflowMessage(
+            'request_approved_by',
+            { name: actorEn, comment: commentWf },
+            { name: actorAr, comment: commentWf },
+          )
+        : renderSynchronizedWorkflowMessage(
+            'request_approved',
+            { comment: commentWf },
+            { comment: commentWf },
+          );
+    case 'rejected':
+      return actorEn
+        ? renderSynchronizedWorkflowMessage(
+            'request_rejected_by',
+            { name: actorEn, comment: commentWf },
+            { name: actorAr, comment: commentWf },
+          )
+        : renderSynchronizedWorkflowMessage(
+            'request_rejected',
+            { comment: commentWf },
+            { comment: commentWf },
+          );
+    case 'returned_for_modification':
+      return actorEn
+        ? renderSynchronizedWorkflowMessage(
+            'request_returned_for_modification_by',
+            { name: actorEn, comment: commentWf },
+            { name: actorAr, comment: commentWf },
+          )
+        : renderSynchronizedWorkflowMessage(
+            'request_returned_for_modification',
+            { comment: commentWf },
+            { comment: commentWf },
+          );
+    case 'approval_pending_update':
+      return actorEn
+        ? renderSynchronizedWorkflowMessage(
+            'request_approval_pending_from',
+            { name: actorEn, comment: commentWf },
+            { name: actorAr, comment: commentWf },
+          )
+        : renderSynchronizedWorkflowMessage(
+            'request_approval_pending',
+            { comment: commentWf },
+            { comment: commentWf },
+          );
+    default:
+      return workflowTemplate('request_submitted');
+  }
+}
+
+/**
+ * Standard entry point for chat `message` + `message_ar`.
+ * Use for every chat insert/update across all CAA modules.
+ */
+export function buildSynchronizedChatMessage(ctx: ChatMessageContext): BilingualText {
+  const commentChat = formatChatCommentSuffix(ctx.comment);
+
+  switch (ctx.action) {
+    case 'cancellation_submitted': {
+      const userEn = ctx.userName?.trim() || 'Unknown User';
+      const userAr = resolveBilingualName(userEn, ctx.userArabicName);
+      const employeeId = String(ctx.employeeId ?? 'N/A');
+      return chatTemplate(
+        'cancellation_submitted_by',
+        { userName: userEn, employeeId },
+        { userName: userAr, employeeId },
+      );
+    }
+    case 'request_received':
+      return chatTemplate('request_received');
+    case 'approved':
+    case 'rejected':
+    case 'returned_for_modification': {
+      const roleEn = ctx.roleName?.trim() || 'Unknown Role';
+      const roleAr = resolveBilingualName(roleEn, ctx.roleArabicName);
+      const key =
+        ctx.action === 'approved'
+          ? 'request_approved_by_role'
+          : ctx.action === 'rejected'
+            ? 'request_rejected_by_role'
+            : 'request_returned_for_modification_by_role';
+      return renderSynchronizedChatMessage(
+        key,
+        { roleName: roleEn, comment: commentChat },
+        { roleName: roleAr, comment: commentChat },
+      );
+    }
+    default:
+      return chatTemplate('request_received');
+  }
+}
+
+// ─── Backward-compatible aliases used by Cancellation pilot ───────────────────
+
+export function buildApprovalWorkflowContent(params: {
+  status: 'Approved' | 'Rejected' | 'Returned for Modification' | 'Pending' | string;
+  roleName?: string | null;
+  roleArabicName?: string | null;
+  comment?: string | null;
+}): BilingualText {
+  const status = params.status;
+  let action: WorkflowMessageAction;
+  if (status === 'Approved') action = 'approved';
+  else if (status === 'Rejected') action = 'rejected';
+  else if (status === 'Returned for Modification') action = 'returned_for_modification';
+  else action = 'approval_pending_update';
+
+  return buildSynchronizedWorkflowMessage({
+    action,
+    roleName: params.roleName,
+    roleArabicName: params.roleArabicName,
+    comment: params.comment,
+  });
+}
+
+export function buildHumanApprovalWorkflowContent(params: {
+  isFirst: boolean;
+  roleName?: string | null;
+  roleArabicName?: string | null;
+  deptName?: string | null;
+  deptArabicName?: string | null;
+  sectionName?: string | null;
+  sectionArabicName?: string | null;
+}): BilingualText {
+  return buildSynchronizedWorkflowMessage({
+    action: params.isFirst ? 'approval_in_progress' : 'approval_pending',
+    roleName: params.roleName,
+    roleArabicName: params.roleArabicName,
+    deptName: params.deptName,
+    deptArabicName: params.deptArabicName,
+    sectionName: params.sectionName,
+    sectionArabicName: params.sectionArabicName,
+  });
+}
+
+export function buildApprovalChatMessage(params: {
+  status: 'Approved' | 'Rejected' | 'Returned for Modification' | string;
+  roleName?: string | null;
+  roleArabicName?: string | null;
+  comment?: string | null;
+}): BilingualText {
+  let action: ChatMessageAction = 'approved';
+  if (params.status === 'Rejected') action = 'rejected';
+  else if (params.status === 'Returned for Modification') action = 'returned_for_modification';
+
+  return buildSynchronizedChatMessage({
+    action,
+    roleName: params.roleName,
+    roleArabicName: params.roleArabicName,
+    comment: params.comment,
+  });
+}
+
+// ─── Status labels ───────────────────────────────────────────────────────────
+
+export function resolveWorkflowStatusAr(status: string | null | undefined): string | null {
+  if (status == null || status === '') return null;
+  return WORKFLOW_STATUS_LABELS[status] ?? status;
+}
+
+export function resolveChatStatusAr(status: string | null | undefined): string | null {
+  if (status == null || status === '') return null;
+  return CHAT_STATUS_LABELS[status] ?? status;
+}
+
+// ─── Legacy row enrichment (read API) ────────────────────────────────────────
+
+/** Pull bilingual actor fields from joined relations on workflow/chat rows. */
+export function extractBilingualActorsFromRecord(
+  record: Record<string, unknown>,
+): BilingualActorNames {
+  const role = (record.approver_role ?? record.role) as Record<string, unknown> | undefined;
+  const user = (record.approver_user ?? record.user) as Record<string, unknown> | undefined;
+  const dept = (record.approver_department ?? record.department) as Record<string, unknown> | undefined;
+  const section = (record.approver_section ?? record.section) as Record<string, unknown> | undefined;
+
+  return {
+    roleName: role?.name != null ? String(role.name) : null,
+    roleArabicName: role?.arabic_name != null ? String(role.arabic_name) : null,
+    deptName: dept?.department_name != null ? String(dept.department_name) : null,
+    deptArabicName: dept?.department_arabic_name != null ? String(dept.department_arabic_name) : null,
+    sectionName: section?.section_name != null ? String(section.section_name) : null,
+    sectionArabicName: section?.section_arabic_name != null ? String(section.section_arabic_name) : null,
+    userName: user?.employee_name != null ? String(user.employee_name) : null,
+    userArabicName: user?.employee_arabic_name != null ? String(user.employee_arabic_name) : null,
+    employeeId: user?.employee_id != null ? String(user.employee_id) : null,
+  };
+}
+
+/** Arabic actor label for workflow templates (role, dept+section, or user). */
+function resolveArabicWorkflowActorName(
+  actors: BilingualActorNames | undefined,
+  parsedEnglishName?: string,
+): string {
+  if (actors) {
+    const { ar } = resolveActorDisplayNames(actors);
+    if (ar) return ar;
+    if (actors.userName?.trim()) {
+      return resolveBilingualName(actors.userName, actors.userArabicName);
+    }
+  }
+  return parsedEnglishName?.trim() || '';
+}
+
+/** Arabic role/user label for chat templates. */
+function resolveArabicChatRoleName(
+  actors: BilingualActorNames | undefined,
+  parsedEnglishRole?: string,
+): string {
+  if (actors?.roleName?.trim()) {
+    return resolveBilingualName(actors.roleName, actors.roleArabicName);
+  }
+  if (actors?.userName?.trim()) {
+    return resolveBilingualName(actors.userName, actors.userArabicName);
+  }
+  return resolveBilingualName(parsedEnglishRole, actors?.roleArabicName);
+}
+
+export function resolveWorkflowContentAr(
+  content: string | null | undefined,
+  actors?: BilingualActorNames,
+): string | null {
+  if (content == null || content.trim() === '') return null;
+  const normalized = content.trim();
+
+  for (const tpl of Object.values(WORKFLOW_TEMPLATES)) {
+    if (tpl.en === normalized) return tpl.ar;
+  }
+
+  const commentIdx = normalized.indexOf(': ');
+  if (commentIdx > 0) {
+    const baseEn = normalized.slice(0, commentIdx).trim();
+    const commentText = normalized.slice(commentIdx + 2).trim();
+    const commentSuffix = formatWorkflowCommentSuffix(commentText);
+
+    for (const tpl of Object.values(WORKFLOW_TEMPLATES)) {
+      if (!tpl.en.includes('{{comment}}')) continue;
+      const withoutComment = tpl.en.replace('{{comment}}', '');
+      if (withoutComment.includes('{{name}}')) {
+        const staticPrefix = withoutComment.replace('{{name}}', '').trim();
+        if (baseEn.startsWith(staticPrefix)) {
+          const namePartEn = baseEn.slice(staticPrefix.length).trim();
+          const nameAr = resolveArabicWorkflowActorName(actors, namePartEn);
+          return interpolate(tpl.ar, { name: nameAr, comment: commentSuffix });
+        }
+      } else if (withoutComment.trim() === baseEn) {
+        return interpolate(tpl.ar, { comment: commentSuffix });
+      }
+    }
+  }
+
+  const inProgressPrefix = WORKFLOW_TEMPLATES.request_approval_in_progress_from?.en.split('{{name}}')[0].trim();
+  if (inProgressPrefix && normalized.startsWith(inProgressPrefix)) {
+    const namePartEn = normalized.slice(inProgressPrefix.length).trim();
+    const nameAr = resolveArabicWorkflowActorName(actors, namePartEn);
+    return interpolate(WORKFLOW_TEMPLATES.request_approval_in_progress_from.ar, { name: nameAr });
+  }
+  const pendingPrefix = WORKFLOW_TEMPLATES.request_approval_pending_from?.en.split('{{name}}')[0].trim();
+  if (pendingPrefix && normalized.startsWith(pendingPrefix)) {
+    const namePartEn = normalized.slice(pendingPrefix.length).trim();
+    const nameAr = resolveArabicWorkflowActorName(actors, namePartEn);
+    return interpolate(WORKFLOW_TEMPLATES.request_approval_pending_from.ar, { name: nameAr });
+  }
+
+  return null;
+}
+
+export function resolveChatMessageAr(
+  message: string | null | undefined,
+  actors?: BilingualActorNames,
+): string | null {
+  if (message == null || message.trim() === '') return null;
+  const normalized = message.trim();
+
+  for (const tpl of Object.values(CHAT_TEMPLATES)) {
+    if (tpl.en === normalized) return tpl.ar;
+  }
+
+  const submittedTpl = CHAT_TEMPLATES.cancellation_submitted_by;
+  if (submittedTpl) {
+    const prefix = submittedTpl.en.split('{{userName}}')[0];
+    if (normalized.startsWith(prefix)) {
+      const afterPrefix = normalized.slice(prefix.length);
+      const parenMatch = afterPrefix.match(/^(.+?) \((.+)\)$/);
+      if (parenMatch) {
+        const userEn = parenMatch[1].trim();
+        const employeeId = parenMatch[2].trim();
+        const userAr = actors?.userName?.trim()
+          ? resolveBilingualName(actors.userName, actors.userArabicName)
+          : resolveBilingualName(userEn, actors?.userArabicName);
+        return interpolate(submittedTpl.ar, { userName: userAr, employeeId });
+      }
+    }
+  }
+
+  for (const tpl of Object.values(CHAT_TEMPLATES)) {
+    if (!tpl.en.includes('{{roleName}}')) continue;
+    const prefix = tpl.en.split('{{roleName}}')[0];
+    if (!normalized.startsWith(prefix)) continue;
+    const rest = normalized.slice(prefix.length);
+    const commentIdx = rest.lastIndexOf(' - ');
+    const roleNameEn = commentIdx >= 0 ? rest.slice(0, commentIdx) : rest;
+    const commentSuffix = commentIdx >= 0 ? rest.slice(commentIdx) : '';
+    const roleNameAr = resolveArabicChatRoleName(actors, roleNameEn.trim());
+    return interpolate(tpl.ar, { roleName: roleNameAr, comment: commentSuffix });
+  }
+
+  return null;
+}
+
+/** Generic workflow log enricher — use in all module repositories. */
+export function enrichWorkflowLog(log: Record<string, unknown>): Record<string, unknown> {
+  const status = log.status != null ? String(log.status) : null;
+  const content = log.content != null ? String(log.content) : null;
+  const actors = extractBilingualActorsFromRecord(log);
+  return {
+    ...log,
+    content_ar: log.content_ar ?? resolveWorkflowContentAr(content, actors),
+    status_ar: log.status_ar ?? resolveWorkflowStatusAr(status),
+  };
+}
+
+/** Generic chat enricher — use in all module repositories. */
+export function enrichChatMessage(chat: Record<string, unknown>): Record<string, unknown> {
+  const status = chat.status != null ? String(chat.status) : null;
+  const message = chat.message != null ? String(chat.message) : null;
+  const actors = extractBilingualActorsFromRecord(chat);
+  return {
+    ...chat,
+    message_ar: chat.message_ar ?? resolveChatMessageAr(message, actors),
+    status_ar: chat.status_ar ?? resolveChatStatusAr(status),
+  };
+}
+
+/** @deprecated Use enrichWorkflowLog */
+export const enrichCancellationWorkflowLog = enrichWorkflowLog;
+
+/** @deprecated Use enrichChatMessage */
+export const enrichCancellationChatMessage = enrichChatMessage;

package/src/index.ts

@@ -504,4 +504,4 @@ export * from './models/SlaApprovalsViewModel';
 export * from './models/ServiceSlaApprovalModel';
 export * from './sla/sla-table-sync.service';
 export * from './sla/sla-approval-mirror';
-export * from './i18n/workflow-chat-i18n';
+export * from './i18n/workflow-chat-message.builder';