adminforth 2.27.0-next.49 → 2.27.0-next.50

package/dist/modules/restApi.js

@@ -3,7 +3,7 @@ import { cascadeChildrenDelete } from './utils.js';
 import { afLogger } from "./logger.js";
 import { ADMINFORTH_VERSION, listify, getLoginPromptHTML, hookResponseError } from './utils.js';
 import AdminForthAuth from "../auth.js";
-import { ActionCheckSource, AdminForthDataTypes, AdminForthFilterOperators, AdminForthResourcePages, AllowedActionsEnum } from "../types/Common.js";
+import { ActionCheckSource, AdminForthDataTypes, AdminForthFilterOperators, AdminForthResourcePages, AdminForthSortDirections, AllowedActionsEnum } from "../types/Common.js";
 import { filtersTools } from "../modules/filtersTools.js";
 async function resolveBoolOrFn(val, ctx) {
     if (typeof val === 'function') {
@@ -26,6 +26,406 @@ async function isFilledOnCreate(col) {
     const fillOnCreate = !!col.fillOnCreate;
     return fillOnCreate;
 }
+const SIMPLE_FILTER_OPERATORS = Object.values(AdminForthFilterOperators).filter((operator) => {
+    return operator !== AdminForthFilterOperators.AND && operator !== AdminForthFilterOperators.OR;
+});
+const genericObjectSchema = {
+    type: 'object',
+    additionalProperties: true,
+};
+const errorResponseSchema = {
+    type: 'object',
+    required: ['error'],
+    properties: {
+        error: { type: 'string' },
+    },
+    additionalProperties: true,
+};
+const recordIdentifierSchema = {
+    anyOf: [
+        { type: 'string' },
+        { type: 'number' },
+    ],
+};
+const actionIdentifierSchema = {
+    anyOf: [
+        { type: 'string' },
+        { type: 'number' },
+    ],
+};
+const namedColumnSchema = {
+    type: 'object',
+    required: ['name'],
+    properties: {
+        name: { type: 'string' },
+    },
+    additionalProperties: true,
+};
+const validationResultSchema = {
+    type: 'object',
+    required: ['isValid'],
+    properties: {
+        isValid: { type: 'boolean' },
+        message: { type: 'string' },
+    },
+    additionalProperties: true,
+};
+const commonFilterSchemaDefs = {
+    singleFilter: {
+        type: 'object',
+        properties: {
+            field: { type: 'string' },
+            operator: { type: 'string', enum: SIMPLE_FILTER_OPERATORS },
+            value: {},
+            rightField: { type: 'string' },
+            insecureRawSQL: { type: 'string' },
+            insecureRawNoSQL: {},
+        },
+        additionalProperties: true,
+    },
+    filterNode: {
+        anyOf: [
+            { $ref: '#/$defs/singleFilter' },
+            {
+                type: 'object',
+                required: ['operator', 'subFilters'],
+                properties: {
+                    operator: {
+                        type: 'string',
+                        enum: [AdminForthFilterOperators.AND, AdminForthFilterOperators.OR],
+                    },
+                    subFilters: {
+                        type: 'array',
+                        items: { $ref: '#/$defs/filterNode' },
+                    },
+                },
+                additionalProperties: true,
+            },
+        ],
+    },
+    sortItem: {
+        type: 'object',
+        required: ['field', 'direction'],
+        properties: {
+            field: { type: 'string' },
+            direction: { type: 'string', enum: Object.values(AdminForthSortDirections) },
+        },
+        additionalProperties: true,
+    },
+};
+const commonSortSchema = {
+    type: 'array',
+    items: { $ref: '#/$defs/sortItem' },
+};
+const commonFiltersSchema = {
+    oneOf: [
+        {
+            type: 'array',
+            items: { $ref: '#/$defs/filterNode' },
+        },
+        { $ref: '#/$defs/filterNode' },
+    ],
+};
+function createErrorOrSuccessSchema(successSchema) {
+    return {
+        anyOf: [
+            errorResponseSchema,
+            successSchema,
+        ],
+    };
+}
+const getResourceDataRequestSchema = {
+    type: 'object',
+    $defs: commonFilterSchemaDefs,
+    required: ['resourceId', 'source', 'limit', 'offset', 'filters', 'sort'],
+    properties: {
+        resourceId: { type: 'string' },
+        source: { type: 'string', enum: ['show', 'list', 'edit'] },
+        limit: { type: 'integer' },
+        offset: { type: 'integer' },
+        sort: commonSortSchema,
+        filters: commonFiltersSchema,
+    },
+    additionalProperties: true,
+    allOf: [
+        {
+            if: {
+                properties: {
+                    source: { enum: ['show', 'edit'] },
+                },
+                required: ['source'],
+            },
+            then: {
+                properties: {
+                    filters: {
+                        type: 'array',
+                        items: {
+                            allOf: [
+                                { $ref: '#/$defs/singleFilter' },
+                                {
+                                    type: 'object',
+                                    required: ['field'],
+                                },
+                            ],
+                        },
+                    },
+                },
+            },
+        },
+    ],
+};
+const getResourceDataResponseSchema = createErrorOrSuccessSchema({
+    type: 'object',
+    required: ['data'],
+    properties: {
+        data: {
+            type: 'array',
+            items: genericObjectSchema,
+        },
+        total: { type: 'number' },
+        options: genericObjectSchema,
+    },
+    additionalProperties: true,
+});
+const getMenuBadgesResponseSchema = {
+    type: 'object',
+    additionalProperties: {
+        anyOf: [
+            { type: 'string' },
+            { type: 'number' },
+        ],
+    },
+};
+const getResourceRequestSchema = {
+    type: 'object',
+    required: ['resourceId'],
+    properties: {
+        resourceId: { type: 'string' },
+    },
+    additionalProperties: true,
+};
+const getResourceResponseSchema = createErrorOrSuccessSchema({
+    type: 'object',
+    required: ['resource'],
+    properties: {
+        resource: genericObjectSchema,
+    },
+    additionalProperties: true,
+});
+const getResourceForeignDataRequestSchema = {
+    type: 'object',
+    $defs: commonFilterSchemaDefs,
+    required: ['resourceId', 'column', 'limit', 'offset'],
+    properties: {
+        resourceId: { type: 'string' },
+        column: { type: 'string' },
+        limit: { type: 'integer' },
+        offset: { type: 'integer' },
+        search: { type: 'string' },
+        filters: commonFiltersSchema,
+        sort: commonSortSchema,
+    },
+    additionalProperties: true,
+};
+const getResourceForeignDataResponseSchema = createErrorOrSuccessSchema({
+    type: 'object',
+    required: ['items'],
+    properties: {
+        items: {
+            type: 'array',
+            items: {
+                type: 'object',
+                required: ['value', 'label'],
+                properties: {
+                    value: {},
+                    label: { type: 'string' },
+                },
+                additionalProperties: true,
+            },
+        },
+    },
+    additionalProperties: true,
+});
+const getMinMaxForColumnsRequestSchema = {
+    type: 'object',
+    required: ['resourceId'],
+    properties: {
+        resourceId: { type: 'string' },
+    },
+    additionalProperties: true,
+};
+const getMinMaxForColumnsResponseSchema = createErrorOrSuccessSchema({
+    type: 'object',
+    additionalProperties: {
+        type: 'object',
+        required: ['min', 'max'],
+        properties: {
+            min: {},
+            max: {},
+        },
+        additionalProperties: true,
+    },
+});
+const createRecordRequestSchema = {
+    type: 'object',
+    required: ['resourceId', 'record', 'requiredColumnsToSkip'],
+    properties: {
+        resourceId: { type: 'string' },
+        record: genericObjectSchema,
+        requiredColumnsToSkip: {
+            type: 'array',
+            items: namedColumnSchema,
+        },
+        meta: genericObjectSchema,
+    },
+    additionalProperties: true,
+};
+const createRecordResponseSchema = createErrorOrSuccessSchema({
+    type: 'object',
+    required: ['ok', 'newRecordId', 'redirectToRecordId'],
+    properties: {
+        ok: { const: true },
+        newRecordId: recordIdentifierSchema,
+        redirectToRecordId: recordIdentifierSchema,
+    },
+    additionalProperties: true,
+});
+const updateRecordRequestSchema = {
+    type: 'object',
+    required: ['resourceId', 'recordId', 'record'],
+    properties: {
+        resourceId: { type: 'string' },
+        recordId: recordIdentifierSchema,
+        record: genericObjectSchema,
+        meta: genericObjectSchema,
+    },
+    additionalProperties: true,
+};
+const updateRecordResponseSchema = createErrorOrSuccessSchema({
+    type: 'object',
+    required: ['ok'],
+    properties: {
+        ok: { const: true },
+        recordId: recordIdentifierSchema,
+    },
+    additionalProperties: true,
+});
+const deleteRecordRequestSchema = {
+    type: 'object',
+    required: ['resourceId', 'primaryKey'],
+    properties: {
+        resourceId: { type: 'string' },
+        primaryKey: recordIdentifierSchema,
+    },
+    additionalProperties: true,
+};
+const deleteRecordResponseSchema = createErrorOrSuccessSchema({
+    type: 'object',
+    required: ['ok', 'recordId'],
+    properties: {
+        ok: { const: true },
+        recordId: recordIdentifierSchema,
+    },
+    additionalProperties: true,
+});
+const startCustomActionRequestSchema = {
+    type: 'object',
+    required: ['resourceId', 'actionId', 'recordId'],
+    properties: {
+        resourceId: { type: 'string' },
+        actionId: actionIdentifierSchema,
+        recordId: recordIdentifierSchema,
+        extra: genericObjectSchema,
+    },
+    additionalProperties: true,
+};
+const startCustomActionResponseSchema = {
+    anyOf: [
+        errorResponseSchema,
+        {
+            type: 'object',
+            required: ['actionId', 'resourceId', 'recordId', 'redirectUrl'],
+            properties: {
+                actionId: actionIdentifierSchema,
+                resourceId: { type: 'string' },
+                recordId: recordIdentifierSchema,
+                redirectUrl: { type: 'string' },
+            },
+            additionalProperties: true,
+        },
+        {
+            type: 'object',
+            required: ['actionId', 'resourceId', 'recordId', 'ok'],
+            properties: {
+                actionId: actionIdentifierSchema,
+                resourceId: { type: 'string' },
+                recordId: recordIdentifierSchema,
+                ok: { const: true },
+            },
+            additionalProperties: true,
+        },
+    ],
+};
+const startCustomBulkActionRequestSchema = {
+    type: 'object',
+    required: ['resourceId', 'actionId', 'recordIds'],
+    properties: {
+        resourceId: { type: 'string' },
+        actionId: actionIdentifierSchema,
+        recordIds: {
+            type: 'array',
+            items: recordIdentifierSchema,
+        },
+        extra: genericObjectSchema,
+    },
+    additionalProperties: true,
+};
+const startCustomBulkActionResponseSchema = createErrorOrSuccessSchema({
+    type: 'object',
+    required: ['actionId', 'resourceId', 'recordIds', 'ok'],
+    properties: {
+        actionId: actionIdentifierSchema,
+        resourceId: { type: 'string' },
+        recordIds: {
+            type: 'array',
+            items: recordIdentifierSchema,
+        },
+        ok: { const: true },
+    },
+    additionalProperties: true,
+});
+const validateColumnsRequestSchema = {
+    type: 'object',
+    required: ['resourceId', 'editableColumns', 'record'],
+    properties: {
+        resourceId: { type: 'string' },
+        editableColumns: {
+            type: 'array',
+            items: {
+                type: 'object',
+                required: ['name'],
+                properties: {
+                    name: { type: 'string' },
+                    value: {},
+                },
+                additionalProperties: true,
+            },
+        },
+        record: genericObjectSchema,
+    },
+    additionalProperties: true,
+};
+const validateColumnsResponseSchema = createErrorOrSuccessSchema({
+    type: 'object',
+    required: ['validationResults'],
+    properties: {
+        validationResults: {
+            type: 'object',
+            additionalProperties: validationResultSchema,
+        },
+    },
+    additionalProperties: true,
+});
 export async function interpretResource(adminUser, resource, meta, source, adminforth) {
     afLogger.trace(`🪲Interpreting resource, ${resource.resourceId}, ${source}, 'adminUser', ${adminUser}`);
     const allowedActions = {};
@@ -182,7 +582,7 @@ export default class AdminForthRestAPI {
             handler: async ({ tr }) => {
                 const loginPromptHTML = await getLoginPromptHTML(this.adminforth.config.auth.loginPromptHTML);
                 return {
-                    loginPromptHTML: await tr(loginPromptHTML, 'system.loginPromptHTML'),
+                    loginPromptHTML: loginPromptHTML ? await tr(loginPromptHTML, 'system.loginPromptHTML') : null,
                 };
             }
         });
@@ -222,7 +622,7 @@ export default class AdminForthRestAPI {
         server.endpoint({
             method: 'GET',
             path: '/get_base_config',
-            handler: async ({ input, adminUser, cookies, tr, response }) => {
+            handler: async ({ adminUser, cookies, tr, response }) => {
                 var _a, _b, _c, _d, _e;
                 let username = '';
                 let userFullName = '';
@@ -385,6 +785,8 @@ export default class AdminForthRestAPI {
         server.endpoint({
             method: 'GET',
             path: '/get_menu_badges',
+            description: 'Computes the current menu badge values for the authenticated admin user. Static badges are returned directly, and dynamic badge callbacks are resolved for all configured menu items, including nested items.',
+            response_schema: getMenuBadgesResponseSchema,
             handler: async ({ adminUser }) => {
                 const badges = {};
                 const badgeFunctions = [];
@@ -421,6 +823,9 @@ export default class AdminForthRestAPI {
         server.endpoint({
             method: 'POST',
             path: '/get_resource',
+            description: 'Returns the definition of a single resource. The response includes translated labels, column metadata, allowed actions, visible bulk actions, frontend action metadata, and resource options after permission checks and removal of backend-only internals.',
+            request_schema: getResourceRequestSchema,
+            response_schema: getResourceResponseSchema,
             handler: async ({ body, adminUser, tr }) => {
                 var _a, _b;
                 const { resourceId } = body;
@@ -508,7 +913,7 @@ export default class AdminForthRestAPI {
                             col.foreignResource.unsetLabel = await tr(col.foreignResource.unsetLabel, `resource.${resource.resourceId}.foreignResource.unsetLabel`);
                         }
                         if (inCol.suggestOnCreate && typeof inCol.suggestOnCreate === 'function') {
-                            col.suggestOnCreate = await inCol.suggestOnCreate(adminUser);
+                            col.suggestOnCreate = await inCol.suggestOnCreate({ adminUser });
                         }
                         return Object.assign(Object.assign({}, col), { showIn,
                             validation, label: translated[`resCol${i}`], enum: enumItems });
@@ -526,6 +931,9 @@ export default class AdminForthRestAPI {
         server.endpoint({
             method: 'POST',
             path: '/get_resource_data',
+            description: 'Loads resource rows for list, show, or edit views. The endpoint validates access, applies request hooks, filters, sorting, pagination, record labels, and row click URLs, then returns the final dataset with resource options.',
+            request_schema: getResourceDataRequestSchema,
+            response_schema: getResourceDataResponseSchema,
             handler: async ({ body, adminUser, headers, query, cookies, requestUrl, abortSignal }) => {
                 var _a, _b, _c, _d, _e, _f;
                 const { resourceId, source } = body;
@@ -793,6 +1201,9 @@ export default class AdminForthRestAPI {
         server.endpoint({
             method: 'POST',
             path: '/get_resource_foreign_data',
+            description: 'Loads dropdown options for a foreign-key column. It resolves the referenced resource or polymorphic resources, applies optional search text, hook-injected filters, pagination, and per-record labels, then returns sanitized option items.',
+            request_schema: getResourceForeignDataRequestSchema,
+            response_schema: getResourceForeignDataResponseSchema,
             handler: async ({ body, adminUser, headers, query, cookies, requestUrl }) => {
                 const { resourceId, column, search } = body;
                 if (!this.adminforth.statuses.dbDiscover) {
@@ -953,6 +1364,9 @@ export default class AdminForthRestAPI {
         server.endpoint({
             method: 'POST',
             path: '/get_min_max_for_columns',
+            description: 'Returns min and max values for resource columns that explicitly opt in to min/max queries. This is used to build range-based filter controls without exposing columns that do not allow the query.',
+            request_schema: getMinMaxForColumnsRequestSchema,
+            response_schema: getMinMaxForColumnsResponseSchema,
             handler: async ({ body }) => {
                 const { resourceId } = body;
                 if (!this.adminforth.statuses.dbDiscover) {
@@ -982,6 +1396,9 @@ export default class AdminForthRestAPI {
         server.endpoint({
             method: 'POST',
             path: '/create_record',
+            description: 'Creates a new record in the specified resource. The endpoint validates create permissions, required fields, hidden or backend-only field rules, polymorphic foreign keys, and resource hooks before persisting and returning the created primary key.',
+            request_schema: createRecordRequestSchema,
+            response_schema: createRecordResponseSchema,
             handler: async ({ body, adminUser, query, headers, cookies, requestUrl, response }) => {
                 var _a, _b, _c, _d;
                 const resource = this.adminforth.config.resources.find((res) => res.resourceId == body['resourceId']);
@@ -1111,6 +1528,9 @@ export default class AdminForthRestAPI {
         server.endpoint({
             method: 'POST',
             path: '/update_record',
+            description: 'Updates an existing record by primary key. The endpoint validates edit permissions, current record existence, hidden, backend-only, and read-only field rules, polymorphic foreign keys, and resource hooks before saving changes.',
+            request_schema: updateRecordRequestSchema,
+            response_schema: updateRecordResponseSchema,
             handler: async ({ body, adminUser, query, headers, cookies, requestUrl, response }) => {
                 var _a, _b;
                 const resource = this.adminforth.config.resources.find((res) => res.resourceId == body['resourceId']);
@@ -1229,6 +1649,9 @@ export default class AdminForthRestAPI {
         server.endpoint({
             method: 'POST',
             path: '/delete_record',
+            description: 'Deletes an existing record by primary key. The endpoint validates delete permissions, loads the current record, executes configured cascade child deletion, and then removes the record.',
+            request_schema: deleteRecordRequestSchema,
+            response_schema: deleteRecordResponseSchema,
             handler: async ({ body, adminUser, query, headers, cookies, requestUrl, response }) => {
                 const resource = this.adminforth.config.resources.find((res) => res.resourceId == body['resourceId']);
                 if (!resource) {
@@ -1289,6 +1712,9 @@ export default class AdminForthRestAPI {
         server.endpoint({
             method: 'POST',
             path: '/start_custom_action',
+            description: 'Executes a custom resource action for a single record. The endpoint validates the resource, action existence, and action permissions, then either returns a redirect URL or executes the action handler and returns its result together with action context.',
+            request_schema: startCustomActionRequestSchema,
+            response_schema: startCustomActionResponseSchema,
             handler: async ({ body, adminUser, tr, cookies, response, headers }) => {
                 const { resourceId, actionId, recordId, extra } = body;
                 const resource = this.adminforth.config.resources.find((res) => res.resourceId == resourceId);
@@ -1323,6 +1749,9 @@ export default class AdminForthRestAPI {
         server.endpoint({
             method: 'POST',
             path: '/start_custom_bulk_action',
+            description: 'Executes a custom resource action in bulk mode for multiple records. The endpoint validates the resource, action existence, bulk handler availability, and permissions, then runs the bulk handler and returns its result together with action context.',
+            request_schema: startCustomBulkActionRequestSchema,
+            response_schema: startCustomBulkActionResponseSchema,
             handler: async ({ body, adminUser, tr, response, cookies, headers }) => {
                 const { resourceId, actionId, recordIds, extra } = body;
                 const resource = this.adminforth.config.resources.find((res) => res.resourceId == resourceId);
@@ -1358,6 +1787,9 @@ export default class AdminForthRestAPI {
         server.endpoint({
             method: 'POST',
             path: '/validate_columns',
+            description: 'Runs server-side custom validators for editable columns in a resource form. Only validators defined on submitted columns are executed, and the response maps each invalid column to its validation result.',
+            request_schema: validateColumnsRequestSchema,
+            response_schema: validateColumnsResponseSchema,
             handler: async ({ body, adminUser, query, headers, cookies, requestUrl, response }) => {
                 const { resourceId, editableColumns, record } = body;
                 const resource = this.adminforth.config.resources.find((res) => res.resourceId == resourceId);