@m6d/cortex-server 1.6.0 → 1.8.0

package/src/sample/domains/servicing/endpoints/updateServiceRequest.endpoint.ts

@@ -0,0 +1,355 @@
+import { defineEndpoint } from "@m6d/cortex-server";
+import { serviceRequestConcept } from "../concepts/serviceRequest.concept";
+import { createServiceRequestRule } from "../rules/createServiceRequest.rule";
+import { passingOptionFieldsRule } from "../rules/passingOptionFields.rule";
+
+export const updateServiceRequestEndpoint = defineEndpoint({
+    name: "Update service request",
+    path: "/servicing/requests/{id}",
+    method: "PUT",
+    description:
+        "Update the data of a draft service request (before it is submitted). The body is the full updated request data JSON.",
+    mutates: [serviceRequestConcept],
+
+    governedBy: [createServiceRequestRule, passingOptionFieldsRule],
+
+    // @auto-generated-start
+    autoGenerated: {
+        params: [{ name: "id", required: true, type: "uuid" }] as const,
+        body: [] as const,
+        response: [
+            { name: "id", required: false, type: "uuid" },
+            { name: "createdTime", required: false, type: "datetime" },
+            {
+                name: "service",
+                required: false,
+                type: "object",
+                properties: [
+                    { name: "id", required: false, type: "uuid" },
+                    { name: "builtInId", required: false, type: "string" },
+                    {
+                        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: "subcategory",
+                        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: "description",
+                                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",
+                                        properties: [
+                                            { name: "ar", required: false, type: "string" },
+                                            { name: "en", required: false, type: "string" },
+                                        ],
+                                    },
+                                ],
+                            },
+                        ],
+                    },
+                    { name: "isProxyApplicationEnabled", required: false, type: "boolean" },
+                    { name: "isArchived", required: false, type: "boolean" },
+                    { name: "isSystemManaged", required: false, type: "boolean" },
+                    {
+                        name: "states",
+                        required: false,
+                        type: "object",
+                        isArray: true,
+                        properties: [
+                            { name: "value", required: false, type: "string" },
+                            {
+                                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: "actions",
+                        required: false,
+                        type: "object",
+                        isArray: true,
+                        properties: [
+                            { name: "key", required: false, type: "string" },
+                            {
+                                name: "name",
+                                required: false,
+                                type: "object",
+                                properties: [
+                                    { name: "ar", required: false, type: "string" },
+                                    { name: "en", required: false, type: "string" },
+                                ],
+                            },
+                        ],
+                    },
+                    {
+                        name: "requirements",
+                        required: false,
+                        type: "object",
+                        isArray: true,
+                        properties: [
+                            {
+                                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: "globalExtraData", required: false, type: "unknown" },
+                ],
+            },
+            {
+                name: "applyingUser",
+                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: "globalExtraData", required: false, type: "unknown" },
+                ],
+            },
+            {
+                name: "state",
+                required: false,
+                type: "object",
+                properties: [
+                    { name: "value", required: false, type: "string" },
+                    {
+                        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: "lastAction",
+                required: false,
+                type: "object",
+                properties: [
+                    { name: "key", required: false, type: "string" },
+                    {
+                        name: "name",
+                        required: false,
+                        type: "object",
+                        properties: [
+                            { name: "ar", required: false, type: "string" },
+                            { name: "en", required: false, type: "string" },
+                        ],
+                    },
+                ],
+            },
+            { name: "data", required: false, type: "object" },
+            { name: "latestTransactionCreatedTime", required: false, type: "datetime" },
+            {
+                name: "ability",
+                required: false,
+                type: "object",
+                properties: [
+                    { name: "canWrite", required: false, type: "boolean" },
+                    { name: "canDelete", required: false, type: "boolean" },
+                    { name: "canCancel", required: false, type: "boolean" },
+                ],
+            },
+            { name: "isUserSuspended", required: false, type: "boolean" },
+            { name: "globalExtraData", required: false, type: "unknown" },
+            { name: "validActions", required: false, type: "string", isArray: true },
+            {
+                name: "transactions",
+                required: false,
+                type: "object",
+                isArray: true,
+                properties: [
+                    { name: "id", required: false, type: "uuid" },
+                    { name: "createdTime", required: false, type: "datetime" },
+                    {
+                        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: "fromState",
+                        required: false,
+                        type: "object",
+                        properties: [
+                            { name: "value", required: false, type: "string" },
+                            {
+                                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: "action",
+                        required: false,
+                        type: "object",
+                        properties: [
+                            { name: "key", required: false, type: "string" },
+                            {
+                                name: "name",
+                                required: false,
+                                type: "object",
+                                properties: [
+                                    { name: "ar", required: false, type: "string" },
+                                    { name: "en", required: false, type: "string" },
+                                ],
+                            },
+                        ],
+                    },
+                    {
+                        name: "toState",
+                        required: false,
+                        type: "object",
+                        properties: [
+                            { name: "value", required: false, type: "string" },
+                            {
+                                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: "data", required: false, type: "object" },
+                ],
+            },
+        ] as const,
+        successStatus: 200,
+        errorStatuses: [401, 404],
+        responseKind: "object",
+    } as const,
+    // @auto-generated-end
+});

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

@@ -0,0 +1,44 @@
+import { defineDomain } from "@m6d/cortex-server";
+import type { DomainDef } from "@m6d/cortex-server";
+import { serviceConcept } from "./concepts/service.concept";
+import { serviceRequestConcept } from "./concepts/serviceRequest.concept";
+import { serviceRequestApprovalConcept } from "./concepts/serviceRequestApproval.concept";
+import { cancelServiceRequestEndpoint } from "./endpoints/cancelServiceRequest.endpoint";
+import { createServiceRequestEndpoint } from "./endpoints/createServiceRequest.endpoint";
+import { getServiceRequestEndpoint } from "./endpoints/getServiceRequest.endpoint";
+import { getServiceRequestFormItems } from "./endpoints/getServiceRequestFormItems.endpoint";
+import { getServiceRequestTransactionFormItemsEndpoint } from "./endpoints/getServiceRequestTransactionFormItems.endpoint";
+import { getServiceStatesEndpoint } from "./endpoints/getServiceStates.endpoint";
+import { invokeServiceRequestActionEndpoint } from "./endpoints/invokeServiceRequestAction.endpoint";
+import { listServiceRequestsEndpoint } from "./endpoints/listServiceRequests.endpoint";
+import { listServicesEndpoint } from "./endpoints/listServices.endpoint";
+import { updateServiceRequestEndpoint } from "./endpoints/updateServiceRequest.endpoint";
+import { checkValidActionsRule } from "./rules/checkValidActions.rule";
+import { createServiceRequestRule } from "./rules/createServiceRequest.rule";
+import { filterServiceRequestsByStateRule } from "./rules/filterServiceRequestsByState.rule";
+import { passingOptionFieldsRule } from "./rules/passingOptionFields.rule";
+
+export const servicingDomain: DomainDef = defineDomain({
+    name: "Servicing",
+    description:
+        "Service request workflows and servicing APIs, including service listing, request creation, state transitions, and form metadata retrieval.",
+    concepts: [serviceConcept, serviceRequestConcept, serviceRequestApprovalConcept],
+    endpoints: [
+        cancelServiceRequestEndpoint,
+        createServiceRequestEndpoint,
+        getServiceRequestEndpoint,
+        getServiceRequestFormItems,
+        getServiceRequestTransactionFormItemsEndpoint,
+        getServiceStatesEndpoint,
+        invokeServiceRequestActionEndpoint,
+        listServiceRequestsEndpoint,
+        listServicesEndpoint,
+        updateServiceRequestEndpoint,
+    ],
+    rules: [
+        createServiceRequestRule,
+        passingOptionFieldsRule,
+        filterServiceRequestsByStateRule,
+        checkValidActionsRule,
+    ],
+});

package/src/sample/domains/servicing/rules/checkValidActions.rule.ts

@@ -0,0 +1,7 @@
+import { defineRule } from "@m6d/cortex-server";
+
+export const checkValidActionsRule = defineRule({
+    name: "Check valid actions before invoking",
+    description:
+        'Before invoking an action on a service request, always fetch the request first (GET /servicing/requests/{id}) and check the "validActions" array to confirm the desired action is available. The valid actions depend on the request\'s current state and the current user\'s permissions. For newly created requests, "submit" is typically the only valid action. For submitted requests, other users may see "approve", "return", or "reject".',
+});

package/src/sample/domains/servicing/rules/createServiceRequest.rule.ts

@@ -0,0 +1,7 @@
+import { defineRule } from "@m6d/cortex-server";
+import { getServiceRequestFormItems } from "../endpoints/getServiceRequestFormItems.endpoint";
+
+export const createServiceRequestRule = defineRule({
+    name: "Ensure the correct data is passed before creating a request",
+    description: `Before you create the request, you need to pass in the correct data, which can be fetched from the ${getServiceRequestFormItems.path}`,
+});

package/src/sample/domains/servicing/rules/filterServiceRequestsByState.rule.ts

@@ -0,0 +1,7 @@
+import { defineRule } from "@m6d/cortex-server";
+
+export const filterServiceRequestsByStateRule = defineRule({
+    name: "Service request state filter requires single service",
+    description:
+        "When filtering service requests by state, exactly one serviceIds value must be provided. The valid state values are specific to each service and must be fetched from GET /servicing/services/{id}/states before using them as a filter.",
+});

package/src/sample/domains/servicing/rules/passingOptionFields.rule.ts

@@ -0,0 +1,7 @@
+import { defineRule } from "@m6d/cortex-server";
+
+export const passingOptionFieldsRule = defineRule({
+    name: "Passing option field in request/transaction forms",
+    description:
+        'When filling the data for option fields, make sure to set in the following format: `{ "id": "the actual value", "name": { "ar": "Arabic label from the form", "en": "English label from the form" } }`',
+});

package/src/sample/domains/shared/rules/pagination.rule.ts

@@ -0,0 +1,7 @@
+import { defineRule } from "@m6d/cortex-server";
+
+export const paginationRule = defineRule({
+    name: "Pagination required for large lists",
+    description:
+        'NEVER use pageSize=-1 on list endpoints that return employee-scoped records (leaves, service requests, balance transactions). These can have thousands of records and will exceed response size limits. Always use the default pageSize (usually 20) and rely on count/filteredCount from the response to tell the user the total. If the user asks for "all" records, fetch the first page and say "You have N total, here are the most recent 20. Would you like to see more?". Only use pageSize=-1 on small reference/lookup endpoints like leave types, balance types, and services list.',
+});

package/src/sample/domains/suggestions/concepts/suggestion.concept.ts

@@ -0,0 +1,19 @@
+import { defineConcept } from "@m6d/cortex-server";
+import { paginationRule } from "../../shared/rules/pagination.rule";
+
+export const suggestionConcept = defineConcept({
+    name: "Suggestion",
+    description:
+        "An employee suggestion or idea submitted by the current user, including its category, impact level, files, employees involved, and lifecycle state such as draft, submitted, returned, or completed.",
+    aliases: [
+        "suggestion",
+        "idea",
+        "my suggestions",
+        "employee suggestion",
+        "اقتراح",
+        "اقتراحاتي",
+        "فكرة",
+        "أفكاري",
+    ],
+    governedBy: [paginationRule],
+});

package/src/sample/domains/suggestions/concepts/suggestionCategory.concept.ts

@@ -0,0 +1,7 @@
+import { defineConcept } from "@m6d/cortex-server";
+
+export const suggestionCategoryConcept = defineConcept({
+    name: "Suggestion Category",
+    description: "A selectable category used when creating or updating a suggestion.",
+    aliases: ["suggestion category", "category", "تصنيف الاقتراح"],
+});

package/src/sample/domains/suggestions/concepts/suggestionImpactLevel.concept.ts

@@ -0,0 +1,7 @@
+import { defineConcept } from "@m6d/cortex-server";
+
+export const suggestionImpactLevelConcept = defineConcept({
+    name: "Suggestion Impact Level",
+    description: "A selectable impact level describing the expected impact of a suggestion.",
+    aliases: ["impact level", "suggestion impact", "مستوى التأثير"],
+});