@m6d/cortex-server 1.7.0 → 1.8.0

package/src/sample/domains/notifications/endpoints/markMyNotificationAsRead.endpoint.ts

@@ -0,0 +1,32 @@
+import { defineEndpoint } from "@m6d/cortex-server";
+import { notificationConcept } from "../concepts/notification.concept";
+import { listMyNotificationsEndpoint } from "./listMyNotifications.endpoint";
+
+export const markMyNotificationAsReadEndpoint = defineEndpoint({
+    name: "Mark current user notification as read",
+    path: "/notifications/users/{id}/read",
+    method: "PUT",
+    description: "Marks a notification belonging to the current user as read.",
+    paramDescriptions: {
+        id: "The notification identifier",
+    },
+    mutates: [notificationConcept],
+    dependsOn: [
+        {
+            endpoint: listMyNotificationsEndpoint,
+            fromField: "id",
+            paramName: "id",
+        },
+    ],
+
+    // @auto-generated-start
+    autoGenerated: {
+        params: [{ name: "id", required: true, type: "uuid" }] as const,
+        body: [] as const,
+        response: [] as const,
+        successStatus: 204,
+        errorStatuses: [404],
+        responseKind: "none",
+    } as const,
+    // @auto-generated-end
+});

package/src/sample/domains/notifications/index.ts

@@ -0,0 +1,20 @@
+import { defineDomain } from "@m6d/cortex-server";
+import type { DomainDef } from "@m6d/cortex-server";
+import { notificationConcept } from "./concepts/notification.concept";
+import { countMyNotificationsEndpoint } from "./endpoints/countMyNotifications.endpoint";
+import { getMyNotificationEndpoint } from "./endpoints/getMyNotification.endpoint";
+import { listMyNotificationsEndpoint } from "./endpoints/listMyNotifications.endpoint";
+import { markMyNotificationAsReadEndpoint } from "./endpoints/markMyNotificationAsRead.endpoint";
+
+export const notificationsDomain: DomainDef = defineDomain({
+    name: "Notifications",
+    description:
+        "Personal notifications domain covering the current user's notifications, unread counts, and read-state updates.",
+    concepts: [notificationConcept],
+    endpoints: [
+        listMyNotificationsEndpoint,
+        getMyNotificationEndpoint,
+        markMyNotificationAsReadEndpoint,
+        countMyNotificationsEndpoint,
+    ],
+});

package/src/sample/domains/payroll/concepts/payslip.concept.ts

@@ -0,0 +1,18 @@
+import { defineConcept } from "@m6d/cortex-server";
+import { paginationRule } from "../../shared/rules/pagination.rule";
+
+export const payslipConcept = defineConcept({
+    name: "Payslip",
+    description:
+        "A payroll payslip for the current user or current employee context, including totals, allowances, deductions, bonuses, banking details, and prior-period comparison.",
+    aliases: [
+        "payslip",
+        "salary slip",
+        "salary statement",
+        "my payslips",
+        "قسيمة الراتب",
+        "الراتب",
+        "كشوف الرواتب",
+    ],
+    governedBy: [paginationRule],
+});

package/src/sample/domains/payroll/concepts/salaryCertificate.concept.ts

@@ -0,0 +1,17 @@
+import { defineConcept } from "@m6d/cortex-server";
+import { paginationRule } from "../../shared/rules/pagination.rule";
+
+export const salaryCertificateConcept = defineConcept({
+    name: "Salary Certificate",
+    description:
+        "A salary or employment certificate for the current employee, including type, language, requesting entity, generated file, and related service request.",
+    aliases: [
+        "salary certificate",
+        "employment certificate",
+        "salary letter",
+        "certificate",
+        "شهادة راتب",
+        "شهادة لمن يهمه الأمر",
+    ],
+    governedBy: [paginationRule],
+});

package/src/sample/domains/payroll/concepts/salaryCertificateRequestingEntity.concept.ts

@@ -0,0 +1,8 @@
+import { defineConcept } from "@m6d/cortex-server";
+
+export const salaryCertificateRequestingEntityConcept = defineConcept({
+    name: "Salary Certificate Requesting Entity",
+    description:
+        "A selectable external entity used when previewing or requesting a salary certificate.",
+    aliases: ["certificate requesting entity", "requesting entity", "جهة طلب الشهادة"],
+});

package/src/sample/domains/payroll/endpoints/getPayslipById.endpoint.ts

@@ -0,0 +1,238 @@
+import { defineEndpoint } from "@m6d/cortex-server";
+import { payslipConcept } from "../concepts/payslip.concept";
+import { listPayslipsEndpoint } from "./listPayslips.endpoint";
+
+export const getPayslipByIdEndpoint = defineEndpoint({
+    name: "Get payslip by id",
+    path: "/payroll/payslips/{id}",
+    method: "GET",
+    description: "Returns a single payslip accessible to the current user.",
+    queries: [payslipConcept],
+    returns: [{ concept: payslipConcept }],
+    paramDescriptions: {
+        id: "The payslip identifier",
+    },
+    dependsOn: [
+        {
+            endpoint: listPayslipsEndpoint,
+            fromField: "id",
+            paramName: "id",
+        },
+    ],
+
+    // @auto-generated-start
+    autoGenerated: {
+        params: [{ name: "id", required: true, type: "uuid" }] as const,
+        body: [] as const,
+        response: [
+            { name: "id", required: false, type: "uuid" },
+            {
+                name: "salary",
+                required: false,
+                type: "object",
+                properties: [
+                    { 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: "number", required: false, type: "string" },
+                            {
+                                name: "jobClassification",
+                                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: "jobLevel",
+                                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: "jobTitle",
+                                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: "category",
+                                        required: false,
+                                        type: "object",
+                                        properties: [
+                                            { name: "id", required: false, type: "uuid" },
+                                            { name: "name", required: false, type: "object" },
+                                        ],
+                                    },
+                                ],
+                            },
+                            {
+                                name: "department",
+                                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: "user",
+                                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: "amount", required: false, type: "number" },
+                    { name: "pensionDeductionAmount", required: false, type: "number" },
+                    { name: "baseAmount", required: false, type: "number" },
+                    { name: "totalAmount", required: false, type: "number" },
+                    { name: "totalAllowanceAmount", required: false, type: "number" },
+                    { name: "totalDeductionAmount", required: false, type: "number" },
+                ],
+            },
+            {
+                name: "register",
+                required: false,
+                type: "object",
+                properties: [
+                    { name: "id", required: false, type: "uuid" },
+                    { name: "month", required: false, type: "number" },
+                    { name: "year", required: false, type: "number" },
+                ],
+            },
+            { name: "amount", required: false, type: "number" },
+            { name: "baseAmount", required: false, type: "number" },
+            { name: "totalAmount", required: false, type: "number" },
+            { name: "totalAllowanceAmount", required: false, type: "number" },
+            { name: "totalDeductionAmount", required: false, type: "number" },
+            { name: "totalBonusAmount", required: false, type: "number" },
+            { name: "totalReductionAmount", required: false, type: "number" },
+            { name: "pensionDeductionAmount", required: false, type: "number" },
+            {
+                name: "currency",
+                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: "abbreviatedName",
+                        required: false,
+                        type: "object",
+                        properties: [
+                            { name: "ar", required: false, type: "string" },
+                            { name: "en", required: false, type: "string" },
+                        ],
+                    },
+                    { name: "symbol", required: false, type: "string" },
+                ],
+            },
+            { name: "hasChanged", required: false, type: "boolean" },
+            {
+                name: "allowances",
+                required: false,
+                type: "object",
+                isArray: true,
+                properties: [
+                    { name: "id", required: false, type: "uuid" },
+                    {
+                        name: "type",
+                        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: "amount", required: false, type: "number" },
+                    { name: "from", required: false, type: "date" },
+                    { name: "to", required: false, type: "date" },
+                    { name: "notes", required: false, type: "string" },
+                ],
+            },
+        ] as const,
+        successStatus: 200,
+        errorStatuses: [404],
+        responseKind: "object",
+    } as const,
+    // @auto-generated-end
+});

package/src/sample/domains/payroll/endpoints/listPayslips.endpoint.ts

@@ -0,0 +1,216 @@
+import { defineEndpoint } from "@m6d/cortex-server";
+import { payslipConcept } from "../concepts/payslip.concept";
+import { payrollEmployeeContextRule } from "../rules/payrollEmployeeContext.rule";
+
+export const listPayslipsEndpoint = defineEndpoint({
+    name: "List payslips",
+    path: "/payroll/payslips",
+    method: "GET",
+    description:
+        "Returns paginated payslips. In self-service conversations, this should be constrained to the current employee context.",
+    queries: [payslipConcept],
+    returns: [{ concept: payslipConcept }],
+    governedBy: [payrollEmployeeContextRule],
+    paramDescriptions: {
+        employeeIds:
+            "Filter by employee identifiers. For self-service use the current employee id.",
+        registerIds: "Optional payroll register filters",
+        months: "Optional month filters",
+        years: "Optional year filters",
+        hasChanged: "Optional filter for payslips changed from the previous period",
+        page: "Pagination page number",
+        pageSize: "Pagination page size",
+    },
+
+    // @auto-generated-start
+    autoGenerated: {
+        params: [
+            { name: "registerIds", required: false, type: "uuid", isArray: true },
+            { name: "employeeIds", required: false, type: "uuid", isArray: true },
+            { name: "months", required: false, type: "number", isArray: true },
+            { name: "years", required: false, type: "number", isArray: true },
+            { name: "hasChanged", required: false, type: "boolean" },
+            {
+                name: "filterCountExclusions",
+                required: false,
+                type: "'employee_ids' | 'register_ids'",
+                isArray: true,
+            },
+            { name: "pageNumber", required: false, type: "number" },
+            { name: "pageSize", required: false, type: "number" },
+        ] as const,
+        body: [] as const,
+        response: [
+            {
+                name: "items",
+                required: false,
+                type: "object",
+                isArray: true,
+                properties: [
+                    { name: "id", required: false, type: "uuid" },
+                    {
+                        name: "salary",
+                        required: false,
+                        type: "object",
+                        properties: [
+                            { 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: "number", required: false, type: "string" },
+                                    {
+                                        name: "jobClassification",
+                                        required: false,
+                                        type: "object",
+                                        properties: [
+                                            { name: "id", required: false, type: "uuid" },
+                                            { name: "name", required: false, type: "object" },
+                                            { name: "type", required: false, type: "string" },
+                                        ],
+                                    },
+                                    {
+                                        name: "jobLevel",
+                                        required: false,
+                                        type: "object",
+                                        properties: [
+                                            { name: "id", required: false, type: "uuid" },
+                                            { name: "name", required: false, type: "object" },
+                                        ],
+                                    },
+                                    {
+                                        name: "jobTitle",
+                                        required: false,
+                                        type: "object",
+                                        properties: [
+                                            { name: "id", required: false, type: "uuid" },
+                                            { name: "name", required: false, type: "object" },
+                                            { name: "category", required: false, type: "object" },
+                                        ],
+                                    },
+                                    {
+                                        name: "department",
+                                        required: false,
+                                        type: "object",
+                                        properties: [
+                                            { name: "id", required: false, type: "uuid" },
+                                            { name: "name", required: false, type: "object" },
+                                        ],
+                                    },
+                                    {
+                                        name: "user",
+                                        required: false,
+                                        type: "object",
+                                        properties: [
+                                            { name: "id", required: false, type: "uuid" },
+                                            { name: "name", required: false, type: "object" },
+                                        ],
+                                    },
+                                ],
+                            },
+                            { name: "amount", required: false, type: "number" },
+                            { name: "pensionDeductionAmount", required: false, type: "number" },
+                            { name: "baseAmount", required: false, type: "number" },
+                            { name: "totalAmount", required: false, type: "number" },
+                            { name: "totalAllowanceAmount", required: false, type: "number" },
+                            { name: "totalDeductionAmount", required: false, type: "number" },
+                        ],
+                    },
+                    {
+                        name: "register",
+                        required: false,
+                        type: "object",
+                        properties: [
+                            { name: "id", required: false, type: "uuid" },
+                            { name: "month", required: false, type: "number" },
+                            { name: "year", required: false, type: "number" },
+                        ],
+                    },
+                    { name: "amount", required: false, type: "number" },
+                    { name: "baseAmount", required: false, type: "number" },
+                    { name: "totalAmount", required: false, type: "number" },
+                    { name: "totalAllowanceAmount", required: false, type: "number" },
+                    { name: "totalDeductionAmount", required: false, type: "number" },
+                    { name: "totalBonusAmount", required: false, type: "number" },
+                    { name: "totalReductionAmount", required: false, type: "number" },
+                    { name: "pensionDeductionAmount", required: false, type: "number" },
+                    {
+                        name: "currency",
+                        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: "abbreviatedName",
+                                required: false,
+                                type: "object",
+                                properties: [
+                                    { name: "ar", required: false, type: "string" },
+                                    { name: "en", required: false, type: "string" },
+                                ],
+                            },
+                            { name: "symbol", required: false, type: "string" },
+                        ],
+                    },
+                    { name: "hasChanged", required: false, type: "boolean" },
+                    {
+                        name: "allowances",
+                        required: false,
+                        type: "object",
+                        isArray: true,
+                        properties: [
+                            { name: "id", required: false, type: "uuid" },
+                            {
+                                name: "type",
+                                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: "amount", required: false, type: "number" },
+                            { name: "from", required: false, type: "date" },
+                            { name: "to", required: false, type: "date" },
+                            { name: "notes", required: false, type: "string" },
+                        ],
+                    },
+                ],
+            },
+            { name: "count", required: false, type: "number" },
+            { name: "filteredCount", required: false, type: "number" },
+        ] as const,
+        successStatus: 200,
+        errorStatuses: [],
+        responseKind: "object",
+    } as const,
+    // @auto-generated-end
+});

package/src/sample/domains/payroll/endpoints/listSalaryCertificateLanguages.endpoint.ts

@@ -0,0 +1,25 @@
+import { defineEndpoint } from "@m6d/cortex-server";
+import { salaryCertificateConcept } from "../concepts/salaryCertificate.concept";
+
+export const listSalaryCertificateLanguagesEndpoint = defineEndpoint({
+    name: "List salary certificate languages",
+    path: "/payroll/salaries/certificates/languages",
+    method: "GET",
+    description:
+        "Returns the available salary certificate languages used for previews and filtering.",
+    queries: [salaryCertificateConcept],
+
+    // @auto-generated-start
+    autoGenerated: {
+        params: [] as const,
+        body: [] as const,
+        response: [
+            { name: "id", required: false, type: "string" },
+            { name: "name", required: false, type: "string" },
+        ] as const,
+        successStatus: 200,
+        errorStatuses: [],
+        responseKind: "array",
+    } as const,
+    // @auto-generated-end
+});

package/src/sample/domains/payroll/endpoints/listSalaryCertificateRequestingEntities.endpoint.ts

@@ -0,0 +1,62 @@
+import { defineEndpoint } from "@m6d/cortex-server";
+import { salaryCertificateRequestingEntityConcept } from "../concepts/salaryCertificateRequestingEntity.concept";
+
+export const listSalaryCertificateRequestingEntitiesEndpoint = defineEndpoint({
+    name: "List salary certificate requesting entities",
+    path: "/payroll/salaries/certificate-requesting-entities",
+    method: "GET",
+    description:
+        "Returns the requesting entities available for salary certificate preview or request flows.",
+    queries: [salaryCertificateRequestingEntityConcept],
+    returns: [{ concept: salaryCertificateRequestingEntityConcept }],
+    paramDescriptions: {
+        keyword: "Optional keyword filter",
+        page: "Pagination page number",
+        pageSize: "Pagination page size",
+    },
+
+    // @auto-generated-start
+    autoGenerated: {
+        params: [
+            { name: "keyword", required: false, type: "string" },
+            { name: "pageNumber", required: false, type: "number" },
+            { name: "pageSize", required: false, type: "number" },
+        ] as const,
+        body: [] as const,
+        response: [
+            {
+                name: "items",
+                required: false,
+                type: "object",
+                isArray: true,
+                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: "description",
+                        required: false,
+                        type: "object",
+                        properties: [
+                            { name: "ar", required: false, type: "string" },
+                            { name: "en", required: false, type: "string" },
+                        ],
+                    },
+                ],
+            },
+            { name: "count", required: false, type: "number" },
+            { name: "filteredCount", required: false, type: "number" },
+        ] as const,
+        successStatus: 200,
+        errorStatuses: [],
+        responseKind: "object",
+    } as const,
+    // @auto-generated-end
+});