@m6d/cortex-server 1.6.0 → 1.8.0

package/src/sample/domains/employees/services/employees.service.ts

@@ -0,0 +1,181 @@
+import { defineService } from "@m6d/cortex-server";
+import type { ConceptDef } from "@m6d/cortex-server";
+import { employeeConcept } from "../concepts/employee.concept";
+
+function employeeService(config: {
+    name: string;
+    builtInId: string;
+    belongsTo: ConceptDef;
+    description: string;
+    intakeMode: "conversational" | "form";
+}) {
+    return defineService({
+        name: config.name,
+        builtInId: config.builtInId,
+        belongsTo: config.belongsTo,
+        description: config.description,
+        metadata: {
+            intakeMode: config.intakeMode,
+        },
+    });
+}
+
+export const detailsUpdateService = employeeService({
+    name: "Details update request",
+    builtInId: "services:details_update",
+    belongsTo: employeeConcept,
+    description:
+        "Request to update personal details such as name change, ID renewal, passport renewal, acquiring qualification, spouse employment or resignation, phone number, or home address.",
+    intakeMode: "form",
+});
+
+export const changeJobTitleService = employeeService({
+    name: "Change job title request",
+    builtInId: "services:change_job_title",
+    belongsTo: employeeConcept,
+    description:
+        "Request to change job title. Requires selecting the new job title and providing a reason.",
+    intakeMode: "conversational",
+});
+
+export const changeNationalityService = employeeService({
+    name: "Change nationality request",
+    builtInId: "services:change_nationality",
+    belongsTo: employeeConcept,
+    description: "Request to change nationality on employee record.",
+    intakeMode: "form",
+});
+
+export const changeMaritalStatusService = employeeService({
+    name: "Change marital status request",
+    builtInId: "services:change_marital_status",
+    belongsTo: employeeConcept,
+    description: "Request to change marital status due to marriage, divorce, or death of spouse.",
+    intakeMode: "form",
+});
+
+export const medalService = employeeService({
+    name: "Decoration, medal, badge, or insignia request",
+    builtInId: "services:medal",
+    belongsTo: employeeConcept,
+    description: "Request for a decoration, medal, badge, or insignia award.",
+    intakeMode: "conversational",
+});
+
+export const grievanceService = employeeService({
+    name: "Grievance request",
+    builtInId: "services:grievance",
+    belongsTo: employeeConcept,
+    description: "Submit a grievance or complaint.",
+    intakeMode: "conversational",
+});
+
+export const serviceInclusionService = employeeService({
+    name: "Service inclusion request",
+    builtInId: "services:service_inclusion",
+    belongsTo: employeeConcept,
+    description:
+        "Request to include previous work service. Requires previous work entity name, employment title, and start date.",
+    intakeMode: "conversational",
+});
+
+export const socialAllowanceAdditionService = employeeService({
+    name: "Social allowance addition request",
+    builtInId: "services:social_allowance_addition",
+    belongsTo: employeeConcept,
+    description: "Request to add a social allowance.",
+    intakeMode: "conversational",
+});
+
+export const socialAllowanceWithholdingService = employeeService({
+    name: "Social allowance withholding request",
+    builtInId: "services:social_allowance_withholding",
+    belongsTo: employeeConcept,
+    description: "Request to withhold a social allowance.",
+    intakeMode: "conversational",
+});
+
+export const supervisorMeetingService = employeeService({
+    name: "Supervisor meeting request",
+    builtInId: "services:supervisor_meeting",
+    belongsTo: employeeConcept,
+    description: "Request a meeting with a supervisor.",
+    intakeMode: "conversational",
+});
+
+export const additionOrWithholdingAllowanceService = employeeService({
+    name: "Addition or withholding allowance request",
+    builtInId: "services:addition_or_withholding_allowance",
+    belongsTo: employeeConcept,
+    description: "Request to add or withhold an allowance.",
+    intakeMode: "conversational",
+});
+
+export const medicalExemptionService = employeeService({
+    name: "Medical exemption request",
+    builtInId: "services:medical_exemption",
+    belongsTo: employeeConcept,
+    description: "Request a medical exemption.",
+    intakeMode: "conversational",
+});
+
+export const pursueOfHigherEducationService = employeeService({
+    name: "Pursue of higher education request",
+    builtInId: "services:pursue_of_higher_education",
+    belongsTo: employeeConcept,
+    description: "Request to pursue higher education.",
+    intakeMode: "conversational",
+});
+
+export const renewOrReplaceMilitaryCardService = employeeService({
+    name: "Renew or replace military card request",
+    builtInId: "services:renew_or_replace_military_card",
+    belongsTo: employeeConcept,
+    description: "Request to renew or replace a military card.",
+    intakeMode: "conversational",
+});
+
+export const internalTransferService = employeeService({
+    name: "Internal transfer request",
+    builtInId: "services:internal_transfer",
+    belongsTo: employeeConcept,
+    description: "Request an internal transfer to a different department.",
+    intakeMode: "conversational",
+});
+
+export const externalEntityAffiliationService = employeeService({
+    name: "External entity affiliation request",
+    builtInId: "services:external_entity_affiliation",
+    belongsTo: employeeConcept,
+    description: "Request for affiliation with an external entity.",
+    intakeMode: "conversational",
+});
+
+export const employeeTerminationService = employeeService({
+    name: "End of service request",
+    builtInId: "services:employee_termination",
+    belongsTo: employeeConcept,
+    description:
+        "Request for end of service (termination). Covers various termination types including resignation, retirement, and other end-of-service scenarios.",
+    intakeMode: "form",
+});
+
+export const employeeServices = [
+    detailsUpdateService,
+    changeJobTitleService,
+    changeNationalityService,
+    changeMaritalStatusService,
+    medalService,
+    grievanceService,
+    serviceInclusionService,
+    socialAllowanceAdditionService,
+    socialAllowanceWithholdingService,
+    supervisorMeetingService,
+    additionOrWithholdingAllowanceService,
+    medicalExemptionService,
+    pursueOfHigherEducationService,
+    renewOrReplaceMilitaryCardService,
+    internalTransferService,
+    externalEntityAffiliationService,
+    employeeTerminationService,
+];

package/src/sample/domains/index.ts

@@ -0,0 +1,10 @@
+export * from "./employees";
+export * from "./leaves";
+export * from "./servicing";
+export * from "./attendance";
+export * from "./appraisals";
+export * from "./account";
+export * from "./notifications";
+export * from "./suggestions";
+export * from "./surveys";
+export * from "./payroll";

package/src/sample/domains/leaves/concepts/leave.concept.ts

@@ -0,0 +1,21 @@
+import { defineConcept } from "@m6d/cortex-server";
+import { paginationRule } from "../../shared/rules/pagination.rule";
+
+export const leaveConcept = defineConcept({
+    name: "Leave",
+    description:
+        "Applying for or submitting a new leave request. Used when an employee wants to take time off work. Includes start date, end date and leave type.",
+    aliases: [
+        "leave",
+        "leave application",
+        "time off request",
+        "leave",
+        "my leaves",
+        "طلب إجازة",
+        "إجازاتي",
+        "طلبات الإجازة",
+        "أريد إجازة",
+        "أبي أطلب إجازة",
+    ],
+    governedBy: [paginationRule],
+});

package/src/sample/domains/leaves/concepts/leaveBalance.concept.ts

@@ -0,0 +1,17 @@
+import { defineConcept } from "@m6d/cortex-server";
+
+export const leaveBalanceConcept = defineConcept({
+    name: "LeaveBalance",
+    description:
+        "Employee leave balance — the number of available/remaining leave days an employee has for each leave type. Tracks accrued, used, and remaining days. رصيد الإجازات",
+    aliases: [
+        "leave balance",
+        "remaining leaves",
+        "available leave days",
+        "رصيد الإجازات",
+        "رصيد إجازاتي",
+        "كم باقي لي إجازة",
+        "كم يوم إجازة عندي",
+        "أيام الإجازة المتبقية",
+    ],
+});

package/src/sample/domains/leaves/concepts/leaveBalanceTransaction.concept.ts

@@ -0,0 +1,16 @@
+import { defineConcept } from "@m6d/cortex-server";
+import { paginationRule } from "../../shared/rules/pagination.rule";
+
+export const leaveBalanceTransactionConcept = defineConcept({
+    name: "LeaveBalanceTransaction",
+    description:
+        "A transaction record showing additions to or deductions from an employee's leave balance. Tracks the history of balance changes. حركات رصيد الإجازات",
+    aliases: [
+        "balance transaction",
+        "leave balance history",
+        "balance change",
+        "حركات الرصيد",
+        "سجل رصيد الإجازات",
+    ],
+    governedBy: [paginationRule],
+});

package/src/sample/domains/leaves/concepts/leaveType.concept.ts

@@ -0,0 +1,13 @@
+import { defineConcept } from "@m6d/cortex-server";
+
+export const leaveTypeConcept = defineConcept({
+    name: "LeaveType",
+    description: "The category or type of leave being requested or referenced.",
+    aliases: [
+        "leave type",
+        "types of leave",
+        "أنواع الإجازات",
+        "ما هي أنواع الإجازات",
+        "leave categories",
+    ],
+});

package/src/sample/domains/leaves/concepts/leaveTypes.concept.ts

@@ -0,0 +1,205 @@
+import { defineConcept } from "@m6d/cortex-server";
+import { leaveBalanceConcept } from "./leaveBalance.concept";
+import { leaveConcept } from "./leave.concept";
+
+export const annualLeaveConcept = defineConcept({
+    name: "AnnualLeave",
+    description:
+        "Annual leave — regular vacation days that accumulate yearly. The most commonly used leave type. Requires balance check. Cannot apply in the past.",
+    aliases: [
+        "annual leave",
+        "vacation",
+        "yearly leave",
+        "إجازة سنوية",
+        "إجازتي السنوية",
+        "أبي أطلب إجازة سنوية",
+    ],
+    parentConcept: leaveConcept,
+});
+
+export const sickLeaveConcept = defineConcept({
+    name: "SickLeave",
+    description:
+        "Sick leave — leave taken due to illness or medical condition. Less than 5 days needs basic approval; 5+ days requires medical committee approval and medical certificate.",
+    aliases: [
+        "sick leave",
+        "medical leave",
+        "illness leave",
+        "إجازة مرضية",
+        "مريض",
+        "أبي إجازة مرضية",
+    ],
+    parentConcept: leaveConcept,
+});
+
+export const casualLeaveConcept = defineConcept({
+    name: "CasualLeave",
+    description:
+        "Casual leave — short-notice leave for urgent personal matters. Must be taken today (not in past or future). Cannot have adjacent leaves. Requires balance. Not available for all job classifications.",
+    aliases: ["casual leave", "urgent personal leave", "إجازة اضطرارية", "إجازة طارئة"],
+    parentConcept: leaveConcept,
+});
+
+export const maternityLeaveConcept = defineConcept({
+    name: "MaternityLeave",
+    description:
+        "Maternity leave — 90 days fixed balance for female employees after childbirth. Requires date of birth and medical report. Only female employees.",
+    aliases: ["maternity leave", "إجازة أمومة", "إجازة وضع"],
+    parentConcept: leaveConcept,
+});
+
+export const pilgrimageLeaveConcept = defineConcept({
+    name: "PilgrimageLeave",
+    description: "Pilgrimage leave (Hajj leave) — 30 days fixed balance for Hajj pilgrimage.",
+    aliases: ["pilgrimage leave", "hajj leave", "إجازة حج"],
+    parentConcept: leaveConcept,
+});
+
+export const encashLeaveDaysConcept = defineConcept({
+    name: "EncashLeaveDays",
+    description:
+        "Leave encashment — converting unused leave days into cash payment. Requires specifying the number of days and leave type.",
+    aliases: [
+        "encash leave",
+        "leave encashment",
+        "cash out leave",
+        "بدل إجازة",
+        "صرف إجازة",
+        "تعويض إجازة",
+    ],
+    parentConcept: leaveConcept,
+});
+
+export const returnFromLeaveConcept = defineConcept({
+    name: "ReturnFromLeave",
+    description:
+        "Return from leave — a service request to officially register returning from an ongoing leave, possibly earlier than the planned end date.",
+    aliases: [
+        "return from leave",
+        "early return",
+        "مباشرة بعد إجازة",
+        "عودة من إجازة",
+        "رجعت من الإجازة",
+    ],
+    parentConcept: leaveConcept,
+});
+
+export const timeInLieuLeaveConcept = defineConcept({
+    name: "TimeInLieuLeave",
+    description:
+        "Time in lieu leave — leave taken in exchange for overtime hours worked. Uses time-in-lieu balance.",
+    aliases: ["time in lieu", "TOIL", "overtime leave", "comp time", "إجازة بديلة"],
+    parentConcept: leaveConcept,
+});
+
+export const paternalLeaveConcept = defineConcept({
+    name: "PaternalLeave",
+    description: "Paternal leave — leave for new fathers after childbirth.",
+    aliases: ["paternal leave", "paternity leave", "إجازة أبوة"],
+    parentConcept: leaveConcept,
+});
+
+export const examLeaveConcept = defineConcept({
+    name: "ExamLeave",
+    description: "Exam leave — leave to sit for academic examinations.",
+    aliases: ["exam leave", "study leave", "إجازة امتحانات"],
+    parentConcept: leaveConcept,
+});
+
+export const unpaidLeaveConcept = defineConcept({
+    name: "UnpaidLeave",
+    description: "Unpaid leave — leave without pay for personal reasons.",
+    aliases: ["unpaid leave", "leave without pay", "إجازة بدون راتب"],
+    parentConcept: leaveConcept,
+});
+
+export const guardianLeaveConcept = defineConcept({
+    name: "GuardianLeave",
+    description: "Guardian leave — leave to accompany a sick family member for treatment.",
+    aliases: ["guardian leave", "accompanying leave", "إجازة مرافقة", "إجازة مرافقة مريض"],
+    parentConcept: leaveConcept,
+});
+
+export const sabbaticalLeaveConcept = defineConcept({
+    name: "SabbaticalLeave",
+    description: "Sabbatical leave — extended leave for personal or professional development.",
+    aliases: ["sabbatical leave", "sabbatical", "إجازة تفرغ"],
+    parentConcept: leaveConcept,
+});
+
+export const mourningLeaveConcept = defineConcept({
+    name: "MourningLeave",
+    description: "Mourning leave (bereavement leave) — leave due to the death of a close relative.",
+    aliases: ["mourning leave", "bereavement leave", "إجازة عزاء", "إجازة وفاة"],
+    parentConcept: leaveConcept,
+});
+
+export const iddaLeaveConcept = defineConcept({
+    name: "IddaLeave",
+    description:
+        "Idda leave — leave for the Islamic waiting period (عدة) after death of spouse or divorce. Women only.",
+    aliases: ["idda leave", "إجازة عدة"],
+    parentConcept: leaveConcept,
+});
+
+export const officialDutyLeaveConcept = defineConcept({
+    name: "OfficialDutyLeave",
+    description:
+        "Official duty leave — leave for work-related travel, conferences, or official assignments.",
+    aliases: ["official duty leave", "duty leave", "إجازة مهمة رسمية"],
+    parentConcept: leaveConcept,
+});
+
+export const careLeaveConcept = defineConcept({
+    name: "CareLeave",
+    description: "Care leave — leave to care for a sick child or family member.",
+    aliases: ["care leave", "إجازة رعاية"],
+    parentConcept: leaveConcept,
+});
+
+export const contactWithInfectedPatientLeaveConcept = defineConcept({
+    name: "ContactWithInfectedPatientLeave",
+    description:
+        "Contact with infected patient leave — quarantine leave due to exposure to an infectious disease.",
+    aliases: ["quarantine leave", "infected patient leave", "إجازة مخالطة", "إجازة حجر صحي"],
+    parentConcept: leaveConcept,
+});
+
+export const urgentLeaveConcept = defineConcept({
+    name: "UrgentLeave",
+    description: "Urgent leave — leave for emergencies that cannot wait.",
+    aliases: ["urgent leave", "emergency leave", "إجازة طارئة", "إجازة اضطرارية"],
+    parentConcept: leaveConcept,
+});
+
+export const timeInLieuBalanceCreditGrantConcept = defineConcept({
+    name: "TimeInLieuBalanceCreditGrant",
+    description:
+        "Time in lieu balance credit grant — manager action to add overtime compensation days to an employee time-in-lieu balance.",
+    aliases: ["grant time in lieu", "time in lieu credit", "منح رصيد إجازة تعويضية"],
+    parentConcept: leaveBalanceConcept,
+});
+
+/** All specific leave type concepts as an array. */
+export const leaveTypeConcepts = [
+    annualLeaveConcept,
+    sickLeaveConcept,
+    casualLeaveConcept,
+    maternityLeaveConcept,
+    pilgrimageLeaveConcept,
+    encashLeaveDaysConcept,
+    returnFromLeaveConcept,
+    timeInLieuLeaveConcept,
+    paternalLeaveConcept,
+    examLeaveConcept,
+    unpaidLeaveConcept,
+    guardianLeaveConcept,
+    sabbaticalLeaveConcept,
+    mourningLeaveConcept,
+    iddaLeaveConcept,
+    officialDutyLeaveConcept,
+    careLeaveConcept,
+    contactWithInfectedPatientLeaveConcept,
+    urgentLeaveConcept,
+    timeInLieuBalanceCreditGrantConcept,
+];

package/src/sample/domains/leaves/endpoints/getBalance.endpoint.ts

@@ -0,0 +1,53 @@
+import { defineEndpoint } from "@m6d/cortex-server";
+import { leaveBalanceConcept } from "../concepts/leaveBalance.concept";
+import { annualLeaveConcept } from "../concepts/leaveTypes.concept";
+import { listLeaveTypesEndpoint } from "./listLeaveTypes.endpoint";
+
+export const getBalanceEndpoint = defineEndpoint({
+    name: "Get employee leave balance",
+    path: "/leaves/balances/employees/{employeeId}/{type}",
+    method: "GET",
+    description: "Get a specific employee's leave balance for a given type",
+    queries: [leaveBalanceConcept, annualLeaveConcept],
+    returns: [{ concept: leaveBalanceConcept }],
+    dependsOn: [
+        {
+            endpoint: listLeaveTypesEndpoint,
+            paramName: "type",
+            fromField: "id",
+        },
+    ],
+
+    // @auto-generated-start
+    autoGenerated: {
+        params: [
+            { name: "employeeId", required: true, type: "uuid" },
+            { name: "type", required: true, type: "string" },
+        ] as const,
+        body: [] as const,
+        response: [
+            {
+                name: "employee",
+                required: false,
+                type: "object",
+                properties: [
+                    { name: "id", required: false, type: "uuid" },
+                    {
+                        name: "name",
+                        required: false,
+                        type: "object",
+                        properties: [
+                            { name: "ar", required: false, type: "string" },
+                            { name: "en", required: false, type: "string" },
+                        ],
+                    },
+                ],
+            },
+            { name: "balance", required: false, type: "number" },
+        ] as const,
+        successStatus: 200,
+        errorStatuses: [404],
+        responseKind: "object",
+    } as const,
+    // @auto-generated-end
+});

package/src/sample/domains/leaves/endpoints/getLeaveById.endpoint.ts

@@ -0,0 +1,53 @@
+import { defineEndpoint } from "@m6d/cortex-server";
+import { leaveConcept } from "../concepts/leave.concept";
+
+export const getLeaveByIdEndpoint = defineEndpoint({
+    name: "Get leave by ID",
+    path: "/leaves/{id}",
+    method: "GET",
+    description: "Get a single leave record by its ID",
+    queries: [leaveConcept],
+    returns: [{ concept: leaveConcept }],
+
+    // @auto-generated-start
+    autoGenerated: {
+        params: [{ name: "id", required: true, type: "uuid" }] as const,
+        body: [] as const,
+        response: [
+            { name: "id", required: false, type: "uuid" },
+            {
+                name: "employee",
+                required: false,
+                type: "object",
+                properties: [
+                    { name: "id", required: false, type: "uuid" },
+                    {
+                        name: "name",
+                        required: false,
+                        type: "object",
+                        properties: [
+                            { name: "ar", required: false, type: "string" },
+                            { name: "en", required: false, type: "string" },
+                        ],
+                    },
+                ],
+            },
+            { name: "type", required: false, type: "string" },
+            { name: "from", required: false, type: "datetime" },
+            { name: "to", required: false, type: "datetime" },
+            { name: "dayCount", required: false, type: "number" },
+            { name: "daysBalanceBeforeLeave", required: false, type: "number" },
+            { name: "deductibleFromBalance", required: false, type: "boolean" },
+            {
+                name: "serviceRequest",
+                required: false,
+                type: "object",
+                properties: [{ name: "id", required: false, type: "uuid" }],
+            },
+        ] as const,
+        successStatus: 200,
+        errorStatuses: [404],
+        responseKind: "object",
+    } as const,
+    // @auto-generated-end
+});