adminforth 2.34.0 → 2.35.0

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,465 @@ 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 = {
+    title: 'AdminForthErrorResponse',
+    description: 'Standard error response returned by AdminForth endpoints.',
+    type: 'object',
+    required: ['error'],
+    properties: {
+        error: { type: 'string' },
+    },
+    additionalProperties: true,
+};
+const recordIdentifierSchema = {
+    title: 'AdminForthRecordIdentifier',
+    description: 'Record identifier accepted by AdminForth. Depending on the resource it can be a string or a number.',
+    anyOf: [
+        { type: 'string' },
+        { type: 'number' },
+    ],
+};
+const actionIdentifierSchema = {
+    title: 'AdminForthActionIdentifier',
+    description: 'Action identifier accepted by AdminForth. Depending on configuration it can be a string or a number.',
+    anyOf: [
+        { type: 'string' },
+        { type: 'number' },
+    ],
+};
+const namedColumnSchema = {
+    title: 'AdminForthNamedColumn',
+    type: 'object',
+    required: ['name'],
+    properties: {
+        name: { type: 'string' },
+    },
+    additionalProperties: true,
+};
+const validationResultSchema = {
+    title: 'AdminForthValidationResult',
+    type: 'object',
+    required: ['isValid'],
+    properties: {
+        isValid: { type: 'boolean' },
+        message: { type: 'string' },
+    },
+    additionalProperties: true,
+};
+const filterConditionExample = {
+    field: 'status',
+    operator: AdminForthFilterOperators.EQ,
+    value: 'active',
+};
+const filterGroupExample = {
+    operator: AdminForthFilterOperators.AND,
+    subFilters: [filterConditionExample],
+};
+const sortItemExample = {
+    field: 'createdAt',
+    direction: AdminForthSortDirections.desc,
+};
+const filterConditionSchema = {
+    title: 'AdminForthFilterCondition',
+    description: 'Single field comparison used in AdminForth filtering.',
+    type: 'object',
+    properties: {
+        field: { type: 'string' },
+        operator: { type: 'string', enum: SIMPLE_FILTER_OPERATORS },
+        value: {},
+        rightField: { type: 'string' },
+        insecureRawSQL: { type: 'string' },
+        insecureRawNoSQL: {},
+    },
+    additionalProperties: true,
+    examples: [filterConditionExample],
+};
+const filterGroupSchema = {
+    title: 'AdminForthFilterGroup',
+    description: 'Nested boolean filter group. Use this for AND or OR combinations of filter nodes.',
+    type: 'object',
+    required: ['operator', 'subFilters'],
+    properties: {
+        operator: {
+            type: 'string',
+            enum: [AdminForthFilterOperators.AND, AdminForthFilterOperators.OR],
+        },
+        subFilters: {
+            type: 'array',
+            items: { $ref: '#/$defs/filterNode' },
+            description: 'Nested filters evaluated with the selected operator.',
+        },
+    },
+    additionalProperties: true,
+    examples: [filterGroupExample],
+};
+const sortItemSchema = {
+    title: 'AdminForthSortItem',
+    description: 'Single sort instruction applied in order with the rest of the list.',
+    type: 'object',
+    required: ['field', 'direction'],
+    properties: {
+        field: { type: 'string' },
+        direction: { type: 'string', enum: Object.values(AdminForthSortDirections) },
+    },
+    additionalProperties: true,
+    examples: [sortItemExample],
+};
+const commonFilterSchemaDefs = {
+    singleFilter: filterConditionSchema,
+    filterGroup: filterGroupSchema,
+    filterNode: {
+        title: 'AdminForthFilterNode',
+        description: 'Either a single filter condition or a nested filter group.',
+        anyOf: [
+            { $ref: '#/$defs/singleFilter' },
+            { $ref: '#/$defs/filterGroup' },
+        ],
+        examples: [filterConditionExample, filterGroupExample],
+    },
+    sortItem: sortItemSchema,
+};
+const commonSortSchema = {
+    title: 'AdminForthSortList',
+    description: 'Ordered list of sort instructions.',
+    type: 'array',
+    items: { $ref: '#/$defs/sortItem' },
+    examples: [[sortItemExample]],
+};
+const commonFiltersSchema = {
+    title: 'AdminForthFilterInput',
+    description: 'Runtime accepts either a single filter node or an array of filter nodes. The OpenAPI document normalizes this to the array form for readability.',
+    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'],
+            description: 'Target UI context. Show and edit requests should use direct field filters that identify a single record.',
+        },
+        limit: {
+            type: 'integer',
+            description: 'Maximum number of rows to return for the current page.',
+        },
+        offset: {
+            type: 'integer',
+            description: 'Zero-based row offset used for pagination.',
+        },
+        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',
+            description: 'Maximum number of dropdown options to return.',
+        },
+        offset: {
+            type: 'integer',
+            description: 'Zero-based offset used to fetch the next option page.',
+        },
+        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 +641,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 +681,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 +844,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 +882,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 +972,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 +990,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 +1260,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 +1423,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 +1455,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 +1587,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 +1708,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 +1771,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 +1808,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 +1846,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);