adminforth 2.27.0-next.7 → 2.27.0-next.71

package/dist/spa/src/types/Back.ts

@@ -1,5 +1,7 @@
 import type { Express, Request, Response } from 'express';
+import type { AnySchemaObject } from 'ajv';
 import type { Writable } from 'stream';
+import type { ZodType } from 'zod';
 
 import { ActionCheckSource, AdminForthFilterOperators, AdminForthSortDirections, AllowedActionsEnum, AdminForthResourcePages,
   type AdminForthComponentDeclaration, 
@@ -13,6 +15,7 @@ import { ActionCheckSource, AdminForthFilterOperators, AdminForthSortDirections,
   type AdminForthConfigMenuItem,
   type AnnouncementBadgeResponse,
   type AdminForthResourceColumnInputCommon,
+  type ColumnMinMaxValue,
 } from './Common.js';
 
 export interface ICodeInjector {
@@ -37,6 +40,81 @@ export interface IAdminForthHttpResponse {
     blobStream: () => Writable,
 };
 
+export interface IAdminForthEndpointHandlerInput {
+  body: any;
+  adminUser: AdminUser | undefined;
+  query: {[key: string]: any};
+  headers: {[key: string]: any};
+  cookies: Array<{ key: string, value: string }>;
+  response: IAdminForthHttpResponse;
+  requestUrl: string;
+  abortSignal: AbortSignal;
+  _raw_express_req: Request;
+  _raw_express_res: Response;
+  tr: ITranslateFunction;
+}
+
+export interface IAdminForthEndpointOptions {
+  method: string,
+  noAuth?: boolean,
+  path: string,
+  description?: string,
+  request_schema?: AnySchemaObject,
+  response_schema?: AnySchemaObject,
+  responce_schema?: AnySchemaObject,
+  handler: (input: IAdminForthEndpointHandlerInput) => void | Promise<any>,
+}
+
+export type AdminForthExpressSchemaInput = AnySchemaObject | ZodType;
+
+export interface IAdminForthExpressRouteSchema {
+  /**
+   * Detailed OpenAPI operation description for a custom Express route.
+   */
+  description?: string;
+
+  /**
+   * JSON schema or Zod schema describing the request body for a custom Express route.
+   */
+  request?: AdminForthExpressSchemaInput;
+
+  /**
+   * JSON schema or Zod schema describing the JSON response body for a custom Express route.
+   */
+  response?: AdminForthExpressSchemaInput;
+}
+
+export interface IRegisteredApiSchema {
+  method: string;
+  path: string;
+  description?: string;
+  request_schema?: AnySchemaObject;
+  response_schema?: AnySchemaObject;
+}
+
+export interface IAdminForthApiValidationError {
+  instancePath: string;
+  schemaPath: string;
+  keyword: string;
+  message?: string;
+  params: {[key: string]: any};
+}
+
+export interface IAdminForthApiValidationResult {
+  valid: boolean;
+  errors?: IAdminForthApiValidationError[];
+}
+
+export interface IOpenApiRegistry {
+  registeredSchemas: IRegisteredApiSchema[];
+
+  registerApiSchema(options: IAdminForthEndpointOptions): IRegisteredApiSchema;
+  register_api_schema(options: IAdminForthEndpointOptions): IRegisteredApiSchema;
+  validateRequestSchema(route: IRegisteredApiSchema | null, payload: any): IAdminForthApiValidationResult;
+  validateResponseSchema(route: IRegisteredApiSchema | null, payload: any): IAdminForthApiValidationResult;
+  renderOpenApiDocument(): {[key: string]: any};
+}
+
 /**
  * Implement this interface to create custom HTTP server adapter for AdminForth.
  */
@@ -56,23 +134,7 @@ export interface IHttpServer {
    * 
    * @param options : Object with method, path and handler properties.
    */
-  endpoint(options: {
-    method: string,
-    noAuth?: boolean,
-    path: string,
-    handler: (
-      body: any, 
-      adminUser: any, 
-      query: {[key: string]: string}, 
-      headers: {[key: string]: string}, 
-      cookies: {[key: string]: string}, 
-      response: IAdminForthHttpResponse,
-      requestUrl: string,
-      abortSignal: AbortSignal,
-      _raw_express_req: Request,
-      _raw_express_res: Response,
-    ) => void,
-  }): void;
+  endpoint(options: IAdminForthEndpointOptions): void;
 
 }
 
@@ -106,14 +168,38 @@ export interface IExpressHttpServer extends IHttpServer {
    * ```
    * 
    */  
-  authorize(callable: Function): void;
+  authorize(callable: (...args: any[]) => any): (...args: any[]) => any;
+
+  /**
+   * Method (middleware) to inject translation helper into Express request object.
+   */
+  translatable(callable: (...args: any[]) => any): (...args: any[]) => any;
+
+  /**
+   * Registers OpenAPI schemas for a custom Express route.
+   *
+   * Wrap this around the handler passed to `app.get/post/...`.
+   * If you also need authorization, make `withSchema` the outer wrapper:
+   *
+   * ```ts
+  * import * as z from 'zod';
+  *
+   * app.get('/myApi', admin.express.withSchema({
+   *   description: 'Returns current user profile',
+  *   response: z.object({ user: z.unknown() }),
+   * }, admin.express.authorize((req, res) => {
+   *   res.json({ user: req.adminUser });
+   * })));
+   * ```
+   */
+  withSchema(schema: IAdminForthExpressRouteSchema, callable: (...args: any[]) => any): (...args: any[]) => any;
 }
 
 export interface ITranslateFunction {
   (
     msg: string,
     category: string,
-    params: any,
+    params?: any,
     pluralizationNumber?: number
   ): Promise<string>;
 }
@@ -256,7 +342,7 @@ export interface IAdminForthDataSourceConnector {
    * 
    * Internally should call {@link IAdminForthDataSourceConnector.getFieldValue} for both min and max values.
    */
-  getMinMaxForColumnsWithOriginalTypes({ resource, columns }: { resource: AdminForthResource, columns: AdminForthResourceColumn[] }): Promise<{ [key: string]: { min: any, max: any } }>;
+  getMinMaxForColumnsWithOriginalTypes({ resource, columns }: { resource: AdminForthResource, columns: AdminForthResourceColumn[] }): Promise<ColumnMinMaxValue>;
 
 
   /**
@@ -309,7 +395,7 @@ export interface IAdminForthDataSourceConnectorBase extends IAdminForthDataSourc
     newValues: any, 
   }): Promise<{ok: boolean, error?: string}>;
 
-  getMinMaxForColumns({ resource, columns }: { resource: AdminForthResource, columns: AdminForthResourceColumn[] }): Promise<{ [key: string]: { min: any, max: any } }>;
+  getMinMaxForColumns({ resource, columns }: { resource: AdminForthResource, columns: AdminForthResourceColumn[] }): Promise<ColumnMinMaxValue>;
 
   deleteMany?({resource, recordIds}:{resource: AdminForthResource, recordIds: any[]}): Promise<number>;
 }
@@ -358,7 +444,8 @@ export interface IAdminForthRestAPI {
 export interface IAdminForth {
   config: AdminForthConfig;
   codeInjector: ICodeInjector;
-  express: IHttpServer;
+  express: IExpressHttpServer;
+  openApi: IOpenApiRegistry;
 
   restApi: IAdminForthRestAPI;
   activatedPlugins: Array<IAdminForthPlugin>;
@@ -455,6 +542,8 @@ export interface IAdminForth {
    * ```
    */
   getPluginById<T>(id: string): T;
+
+  refreshMenuBadge(menuItemId: string, adminUser: AdminUser): Promise<void>;
 }
 
 
@@ -532,7 +621,7 @@ export type BeforeDataSourceRequestFunction = (params: {
     body: any,
     query: Record<string, string>,
     headers: Record<string, string>,
-    cookies: Record<string, string>,
+    cookies: { key: string, value: string }[],
     requestUrl: string,
   },
   filtersTools: any,
@@ -570,7 +659,7 @@ export interface HttpExtra {
   body: any,
   query: Record<string, string>,
   headers: Record<string, string>,
-  cookies: Record<string, string>,
+  cookies: { key: string, value: string }[],
   requestUrl: string,
   meta?: any,
   response: IAdminForthHttpResponse
@@ -1305,6 +1394,19 @@ export interface AdminForthActionInput {
     standardAllowedActions: AllowedActions;
   }) => boolean;
   url?: string;
+  bulkHandler?: (params: {
+      adminforth: IAdminForth;
+      resource: AdminForthResource;
+      recordIds: (string | number)[];
+      adminUser: AdminUser;
+      response: IAdminForthHttpResponse;
+      extra?: HttpExtra;
+      tr: ITranslateFunction;
+  }) => Promise<{
+      ok: boolean;
+      error?: string;
+      successMessage?: string;
+  }>;
   action?: (params: {
       adminforth: IAdminForth;
       resource: AdminForthResource;
@@ -1312,7 +1414,7 @@ export interface AdminForthActionInput {
       adminUser: AdminUser;
       response: IAdminForthHttpResponse;
       extra?: HttpExtra;
-      tr: Function;
+      tr: ITranslateFunction;
   }) => Promise<{
       ok: boolean;
       error?: string;
@@ -1837,6 +1939,8 @@ export interface ResourceOptionsInput extends Omit<NonNullable<AdminForthResourc
   /** 
    * Custom bulk actions list. Bulk actions available in list view when user selects multiple records by
    * using checkboxes.
+   * @deprecated Since 2.26.5. Will be removed in 3.0.0. Use `actions` instead.
+
    */
   bulkActions?: Array<AdminForthBulkAction>,
 
@@ -2003,7 +2107,7 @@ export interface AdminForthBulkAction extends AdminForthBulkActionCommon {
    * It should return Promise which will be resolved when action is done.
    */
   action: ({ resource, selectedIds, adminUser, response, tr }: { 
-    resource: AdminForthResource, selectedIds: Array<any>, adminUser: AdminUser, response: IAdminForthHttpResponse, tr: (key: string, category?: string, params?: any) => string
+    resource: AdminForthResource, selectedIds: Array<any>, adminUser: AdminUser, response: IAdminForthHttpResponse, tr: ITranslateFunction
   }) => Promise<{ ok: boolean, error?: string, successMessage?: string }>,
 
   /**
@@ -2136,4 +2240,11 @@ export interface IWebSocketBroker {
   publish: (topic: string, data: any, filterUsers?: (adminUser: AdminUser) => Promise<boolean>) => void;
 
   registerWsClient: (client: IWebSocketClient) => void;
+}
+export interface PluginsCommonOptions {
+   /**
+     * Id of the plugin. It should be unique across all plugins.
+     * It is required if you want to log custom actions, otherwise it is optional.
+    */
+    id?: string;
 }

package/dist/spa/src/types/Common.ts

@@ -303,7 +303,7 @@ export interface AdminForthComponentDeclarationFull {
     [key: string]: any,
   }
 }
-import { type AdminForthActionInput, type AdminForthResource } from './Back.js' 
+import { type IAdminForth, type AdminForthActionInput, type AdminForthResource } from './Back.js' 
 export { type AdminForthActionInput } from './Back.js'
 
 export type AdminForthComponentDeclaration = AdminForthComponentDeclarationFull | string;
@@ -314,8 +314,9 @@ export type FieldGroup = {
   noTitle?: boolean;
 };
 
-export interface AdminForthActionFront extends Omit<AdminForthActionInput, 'id'> {
+export interface AdminForthActionFront extends Omit<AdminForthActionInput, 'id' | 'bulkHandler' | 'action' | 'allowed'> {
   id: string;
+  hasBulkHandler?: boolean;
 }
 
 export interface AdminForthBulkActionFront extends Omit<AdminForthBulkActionCommon, 'id'> {
@@ -329,7 +330,7 @@ export interface AdminForthOptionsForFrontend extends Omit<AdminforthOptionsComm
   bulkActions?: AdminForthBulkActionFront[],
 }
 
-export interface AdminForthResourceFrontend extends Omit<AdminForthResourceCommon, 'options'> {
+export interface AdminForthResourceFrontend extends Omit<AdminForthResourceCommon, 'options' | 'table' | 'dataSource'> {
   options: AdminForthOptionsForFrontend;
 }
 
@@ -610,14 +611,14 @@ export type ValidationObject = {
      * ```
      * 
      */
-    regExp: string,
+    regExp?: string,
 
     /**
      * Error message shown to user if validation fails
      * 
      * Example: "Invalid email format"
      */
-    message: string,
+    message?: string,
 
     /**
      * Whether to check case sensitivity (i flag)
@@ -633,6 +634,20 @@ export type ValidationObject = {
      * Whether to check global strings (g flag)
      */
     global?: boolean
+
+    /**
+     * Custom validator function.
+     * 
+     * Example:
+     * 
+     * ```ts
+     * validator: async (value) => {
+     *   // custom validation logic
+     *   return { isValid: true, message: 'Validation passed' }; // or { isValid: false, message: 'Validation failed' }
+     * }
+     * ```
+     */
+    validator?: (value: any, record: any, adminForth: IAdminForth) => {isValid: boolean, message?: string} | Promise<{isValid: boolean, message?: string}> | boolean,
 }
 
 
@@ -1149,7 +1164,7 @@ export interface AdminForthConfigMenuItem {
    * Optional callback which will be called before rendering the menu for each item.
    * Result of callback if not null will be used as a small badge near the menu item.
    */
-  badge?: string | ((user: AdminUser) => Promise<string>),
+  badge?: string | number | ((user: AdminUser, adminForth: IAdminForth) => Promise<string | number> | string | number),
 
   /**
    * Tooltip shown on hover for badge
@@ -1242,4 +1257,8 @@ export interface GetBaseConfigResponse {
   config: AdminForthConfigForFrontend,
   adminUser: AdminUser,
   version: string,
+}
+
+export interface ColumnMinMaxValue { 
+  [key: string]: { min: any, max: any } 
 }

package/dist/spa/src/types/adapters/CompletionAdapter.ts

@@ -1,3 +1,18 @@
+import type { JSONSchemaType } from "ajv";
+
+export type CompletionStreamEvent = {
+  type: "output" | "reasoning";
+  delta: string;
+  text: string;
+  source?: "summary" | "text";
+};
+
+export type CompletionTool<Input = Record<string, any>, Output = any> = {
+  name: string;
+  input_schema: JSONSchemaType<Input>;
+  description?: string;
+  handler: (input: Input) => Promise<Output> | Output;
+};
 export interface CompletionAdapter {
 
   /**
@@ -7,17 +22,24 @@ export interface CompletionAdapter {
   validate(): void;
 
   /**
-   * This method should return a text completion based on the provided content and stop sequence.
+   * This method should return a text completion based on the provided content.
    * @param content - The input text to complete
-   * @param stop - An array of stop sequences to indicate where to stop the completion
    * @param maxTokens - The maximum number of tokens to generate
+   * @param outputSchema - Optional structured output schema for the response
+   * @param reasoningEffort - Optional parameter to indicate the level of reasoning effort for the completion
+   * @param onChunk - Optional callback invoked for each streamed chunk or reasoning event
    * @returns A promise that resolves to an object containing the completed text and other metadata
    */
   complete(
     content: string,
-    stop: string[],
     maxTokens: number,
-    outputSchema?: any
+    outputSchema?: any,
+    reasoningEffort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh',
+    tools?: CompletionTool[],
+    onChunk?: (
+      chunk: string,
+      event?: CompletionStreamEvent,
+    ) => void | Promise<void>,
   ): Promise<{
     content?: string;
     finishReason?: string;
@@ -30,4 +52,4 @@ export interface CompletionAdapter {
    * @returns The number of tokens in the input content
    */
   measureTokensCount(content: string): Promise<number> | number;
-}
+}

package/dist/spa/src/types/adapters/index.ts

@@ -1,8 +1,8 @@
 export type { EmailAdapter } from './EmailAdapter.js';
-export type { CompletionAdapter } from './CompletionAdapter.js';
+export type { CompletionAdapter, CompletionStreamEvent, CompletionTool } from './CompletionAdapter.js';
 export type { ImageGenerationAdapter } from './ImageGenerationAdapter.js';
 export type { KeyValueAdapter } from './KeyValueAdapter.js';
 export type { ImageVisionAdapter } from './ImageVisionAdapter.js';
 export type { OAuth2Adapter } from './OAuth2Adapter.js';
 export type { StorageAdapter } from './StorageAdapter.js';
-export type { CaptchaAdapter } from './CaptchaAdapter.js';
+export type { CaptchaAdapter } from './CaptchaAdapter.js';

package/dist/spa/src/utils/createEditUtils.ts

@@ -0,0 +1,65 @@
+import type { AdminForthResourceColumn } from '@/types/Back';
+import { useAdminforth } from '@/adminforth';
+import { type Ref, nextTick } from 'vue';
+
+export function scrollToInvalidField(resourceFormRef: any, t: (key: string) => string) {
+  const { alert } = useAdminforth();
+  let columnsWithErrors: {column: AdminForthResourceColumn, error: string}[] = [];
+  for (const column of resourceFormRef.value?.editableColumns || []) {
+    if (resourceFormRef.value?.columnsWithErrors[column.name]) {
+      columnsWithErrors.push({
+        column,
+        error: resourceFormRef.value?.columnsWithErrors[column.name]
+      });
+    }
+  }
+  const errorMessage = t('Failed to save. Please fix errors for the following fields:') + '<ul class="mt-2 list-disc list-inside">' + columnsWithErrors.map(c => `<li><strong>${c.column.label || c.column.name}</strong>: ${c.error}</li>`).join('') + '</ul>';
+  alert({
+    messageHtml: errorMessage,
+    variant: 'danger'
+  });
+  const firstInvalidElement = document.querySelector('.af-invalid-field-message');
+  if (firstInvalidElement) {
+    firstInvalidElement.scrollIntoView({ behavior: 'smooth', block: 'center' });
+  }
+}
+
+export async function saveRecordPreparations(
+  viewMode: 'create' | 'edit',
+  validatingMode: Ref<boolean>, 
+  resourceFormRef: Ref<any>, 
+  isValid: Ref<boolean>, 
+  t: (key: string) => string, 
+  saving: Ref<boolean>, 
+  runSaveInterceptors: any, 
+  record: Ref<Record<string, any>>, 
+  coreStore: any, 
+  route: any
+) {
+  validatingMode.value = true;
+  await nextTick();
+  //wait for response for the user validation function if it exists
+  while (1) {
+    if (resourceFormRef.value?.isValidating) {
+      await new Promise(resolve => setTimeout(resolve, 100));
+    } else {
+      break;
+    }
+  }
+  if (!isValid.value) {
+    await nextTick();
+    scrollToInvalidField(resourceFormRef, t);
+    return;
+  } else {
+    validatingMode.value = false;
+  }
+
+  saving.value = true;
+  const interceptorsResult = await runSaveInterceptors({
+    action: viewMode,
+    values: record.value,
+    resource: coreStore.resource,
+    resourceId: route.params.resourceId as string,
+  });
+  return interceptorsResult;
+}

package/dist/spa/src/utils/index.ts

@@ -1,2 +1,3 @@
 export * from './utils';
-export * from './listUtils';
+export * from './listUtils';
+export * from './createEditUtils';

package/dist/spa/src/utils/listUtils.ts

@@ -1,11 +1,11 @@
 import { nextTick, onMounted, ref, resolveComponent } from 'vue';
 import { callAdminForthApi } from '@/utils';
-import { type AdminForthResourceCommon } from '../types/Common';
+import { type AdminForthResourceFrontend } from '../types/Common';
 import { useAdminforth } from '@/adminforth';
 import { showErrorTost } from '@/composables/useFrontendApi'
 
 let getResourceDataLastAbortController: AbortController | null = null;
-export async function getList(resource: AdminForthResourceCommon, isPageLoaded: boolean, page: number | null , pageSize: number, sort: any, checkboxes:{ value: any[] }, filters: any = [] ) {
+export async function getList(resource: AdminForthResourceFrontend, isPageLoaded: boolean, page: number | null , pageSize: number, sort: any, checkboxes:{ value: any[] }, filters: any = [] ) {
   let rows: any[] = [];
   let totalRows: number | null = null;
   if (!isPageLoaded) {
@@ -53,7 +53,7 @@ export async function getList(resource: AdminForthResourceCommon, isPageLoaded:
 
 
 
-export async function startBulkAction(actionId: string, resource: AdminForthResourceCommon, checkboxes: { value: any[] }, 
+export async function startBulkAction(actionId: string, resource: AdminForthResourceFrontend, checkboxes: { value: any[] }, 
   bulkActionLoadingStates: {value: Record<string, boolean>}, getListInner: () => Promise<any>) {
   const action = resource?.options?.bulkActions?.find(a => a.id === actionId);
   const { confirm, alert } = useAdminforth();

package/dist/spa/src/utils/utils.ts

@@ -8,7 +8,7 @@ import { Dropdown } from 'flowbite';
 import adminforth, { useAdminforth } from '../adminforth';
 import sanitizeHtml  from 'sanitize-html'
 import debounce from 'debounce';
-import type { AdminForthResourceColumnInputCommon, Predicate } from '@/types/Common';
+import type { AdminForthActionFront, AdminForthResourceColumnInputCommon, AdminForthResourceFrontend, Predicate } from '@/types/Common';
 import { i18nInstance } from '../i18n'
 import { useI18n } from 'vue-i18n';
 import { onBeforeRouteLeave } from 'vue-router';
@@ -101,11 +101,13 @@ export async function callAdminForthApi(
   }
 }
 
-export function formatComponent(component: AdminForthComponentDeclaration): AdminForthComponentDeclarationFull {
+export function formatComponent(component: AdminForthComponentDeclaration | undefined): AdminForthComponentDeclarationFull {
   if (typeof component === 'string') {
     return { file: component, meta: {} };
-  } else {
+  } else if (typeof component === 'object') {
     return { file: component.file, meta: component.meta };
+  } else {
+    return { file: '', meta: {} };
   }
 }
 
@@ -191,7 +193,8 @@ export function applyRegexValidation(value: any, validation: ValidationObject[]
   if ( validation?.length ) {
     const validationArray = validation;
     for (let i = 0; i < validationArray.length; i++) {
-      if (validationArray[i].regExp) {
+      const regExpPattern = validationArray[i].regExp;
+      if (regExpPattern) {
         let flags = '';
         if (validationArray[i].caseSensitive) {
           flags += 'i';
@@ -203,7 +206,7 @@ export function applyRegexValidation(value: any, validation: ValidationObject[]
           flags += 'g';
         }
 
-        const regExp = new RegExp(validationArray[i].regExp, flags);
+        const regExp = new RegExp(regExpPattern, flags);
         if (value === undefined || value === null) {
           value = '';
         }
@@ -766,6 +769,7 @@ export async function executeCustomBulkAction({
   onError,
   setLoadingState,
   confirmMessage,
+  resource,
 }: {
   actionId: string | number | undefined,
   resourceId: string,
@@ -775,6 +779,7 @@ export async function executeCustomBulkAction({
   onError?: (error: string) => void,
   setLoadingState?: (loading: boolean) => void,
   confirmMessage?: string,
+  resource?: AdminForthResourceFrontend,
 }): Promise<any> {
   if (!recordIds || recordIds.length === 0) {
     if (onError) {
@@ -796,7 +801,38 @@ export async function executeCustomBulkAction({
   setLoadingState?.(true);
 
   try {
-    // Execute action for all records in parallel using Promise.all
+    const action = resource?.options?.actions?.find((a: any) => a.id === actionId) as AdminForthActionFront | undefined;
+
+    if (action?.hasBulkHandler && action?.showIn?.bulkButton) {
+      const result = await callAdminForthApi({
+        path: '/start_custom_bulk_action',
+        method: 'POST',
+        body: {
+          resourceId,
+          actionId,
+          recordIds,
+          extra: extra || {},
+        }
+      });
+
+      if (result?.ok) {
+        if (onSuccess) {
+          await onSuccess([result]);
+        }
+        return { ok: true, results: [result] };
+      }
+
+      if (result?.error) {
+        if (onError) {
+          onError(result.error);
+        }
+        return { error: result.error };
+      }
+
+      return result;
+    }
+
+    // Per-record parallel calls (legacy path)
     const results = await Promise.all(
       recordIds.map(recordId =>
         callAdminForthApi({
@@ -811,7 +847,6 @@ export async function executeCustomBulkAction({
         })
       )
     );
-
     const lastResult = results[results.length - 1];
     if (lastResult?.redirectUrl) {
       if (lastResult.redirectUrl.includes('target=_blank')) {

package/dist/spa/src/utils.ts

@@ -1,2 +1,3 @@
 export * from './utils/utils';
-export * from './utils/listUtils';
+export * from './utils/listUtils';
+export * from './utils/createEditUtils';