# Agent-first open-source admin panel framework

> Build robust and powerful agentic back-office panels for your projects while maintaining full control over the code.

This file contains all documentation content in a single document following the llmstxt.org standard.

## Getting Started


This page provides a step-by-step guide to quickly get started with AdminForth using the `adminforth` CLI.
You will learn how to set up a new project using the `adminforth create-app` command and explore AdminForth’s fundamentals.

> 👆 For setup example without CLI check out [Hello World without CLI](./01-helloWorld.md)

## Prerequisites

AdminForth requires **Node v20** or higher. If you’re on a different version, you can switch or install using:

```bash
nvm install 20
nvm alias default 20
nvm use 20
```

## Creating an AdminForth Project

The recommended way to get started with AdminForth is via the **`create-app`** CLI, which scaffolds a basic fully functional back-office application. Apart from boilerplate, it creates one resource for user management.

There are two common setup paths:

### Path 1: Existing Database

Use this path when you already have a database and your own schema or migrations. Pass your database URL with `--db`, or enter it when the CLI asks `Please specify the database URL to use`:

```bash
npx adminforth create-app --app-name myadmin --db "postgresql://user:password@localhost:5432/dbname"
```

When you provide your own database URL, the CLI treats this as your own database. It does not create Prisma schema or Prisma migration scripts for that database. Instead, the generated project README contains the SQL or schema notes for adding the required `adminuser` table with your own migration tool.

After the project is created, navigate into it and generate resources from your existing tables:

```bash
cd myadmin
npx adminforth resource
```

Resource files are needed for AdminForth to know about your tables and define how to work with them. Use `npx adminforth resource` again when you add new tables or change their schema.

### Path 2: New Database

Use this path when you want AdminForth to scaffold a standalone app with a new local SQLite database. Omit `--db`, or accept the default `sqlite://.db.sqlite` value in the interactive prompt:

```bash
npx adminforth create-app --app-name myadmin
```

Or omit all options to be prompted interactively:

```bash
npx adminforth create-app
```

Once the project is created, navigate into its directory:

```bash
cd myadmin # or any other name you provided
```

For the new database path, the CLI can scaffold Prisma files and migration scripts for the default SQLite database.

CLI options:

* **`--app-name`** - name for your project. Used in `package.json`, `index.ts` branding, etc. Default value: **`adminforth-app`**.
* **`--db`** - database connection string. Currently PostgreSQL, MongoDB, SQLite, MySQL, Clickhouse and Qdrant (read only) are supported. Default value: **`sqlite://.db.sqlite`**

> ☝️ Database Connection String format:
>
> Format is `<scheme>://<username>:<password>@<host>:<port>/<database>`. Examples:
>
> - SQLite — `sqlite://.db.sqlite`. If database not yet exists it will be created
> - PostgreSQL — `postgresql://user:password@localhost:5432/dbname`
> - MongoDB — `mongodb://localhost:27017/dbname`
> - Clickhouse — `clickhouse://localhost:8123/dbname`
> - MySQL — `mysql://user:password@localhost:3306/dbname`
> - Qdrant - `qdrant://localhost:6333`

### Understand the generated Project Structure

The CLI will create boilerplate files and folders in your current directory and install dependencies. A typical layout looks like this:

```text
myadmin/
├── custom
│   ├── assets/           # Static assets like images, fonts, etc.
│   ├── package.json      # For any custom npm packages you will use in Vue files
│   └── tsconfig.json     # Tsconfig for Vue project (adds completion for AdminForth core components)
├── resources
│   └── adminuser.ts      # Example resource file for users management
├── schema.prisma         # Prisma schema file, generated only for the new database path
├── index.ts              # Main entry point: configures AdminForth & starts the server
├── package.json          # Project dependencies
├── pnpm-workspace.yaml
├── tsconfig.json         # TypeScript configuration
├── .env                  # Env vars like tokens, secrets that should not be in version control
├── .env.local            # General local environment variables
└── .gitignore

```

### Initial Migration & Future Migrations

For the new database path, the CLI creates Prisma files for managing migrations. Prisma is not required by AdminForth itself, but it is a convenient migration tool for standalone projects that do not have database management yet.

CLI will suggest you a command to initialize the database with Prisma:

```bash
pnpm makemigration --name init && pnpm migrate:local
```

This will create a migration file and apply it to the database.

In future, when you need to add new resources, you need to modify `schema.prisma` (add models, change fields, etc.). After doing any modification you need to create a new migration using next command:

```bash
pnpm makemigration --name init ; pnpm migrate:local
```

Other developers need to pull migration and run `pnpm migrate:local` to apply any unapplied migrations.

For the existing database path, use your own migration tool instead. The generated project README shows how to add the required `adminuser` table to your database.

## Run the Server

Now you can run your app:

```bash
pnpm start
```

Open http://localhost:3500 in your browser and (default credentials are `adminforth`/`adminforth` if you haven’t changed them).

![alt text](localhost_3500_login.png)

## AdminForth Basic Philosophy

AdminForth connects to existing databases and provides a back-office for managing data including CRUD operations, filtering, sorting, and more.

Database can be already created by using any database management tool, ORM or migrator.

AdminForth itself never modifies database schema, does not add columns or new tables. However for those who have no own migration managment AdminForth CLI suggests using Prisma. This allows to provide simple and reliable schema management for standalone projects which have no DB yet.

If you already have a database, you pass a connection string to AdminForth and define resources(tables) and describe columns you would like to see in back-office. For most DBs AdminForth can "discover" column types and constraints (e.g. max-length) by connecting to DB. However you can redefine them in AdminForth configuration. Type and constraints definition in AdminForth resource are take precedence over DB schema.

Also in AdminForth you can define in "Vue" way:

* how each field will be rendered
* create own pages e.g. Dashboard using AdminForth Components Library (AFCL) or any other Vue componetns.
* insert injections into standard pages (e.g. add diagram to list view)

## Adding an `apartments` Model

So far, our freshly generated AdminForth project includes a default `adminuser` model and a corresponding `adminuser` resource.

Let’s expand our app to suport managment of **`apartments`** model. Adding new resource will involve next steps:

1. **Add a new Prisma model** to your `schema.prisma`.
2. **Run a Prisma migration** to update your database schema.
3. **Create a corresponding resource** in the `resources/` folder.
4. **Register the new resource** in `index.ts` and see it in your AdminForth back-office.

Please note that steps 1 and 2 are compleatly independent from 3 and 4, so you can make them with any other way then Prisma.

### Step 1. Define the `apartments` Model in `schema.prisma`

Open `schema.prisma` in your project root and add a new model for `apartments`:

```prisma title="./schema.prisma"
...
//diff-add
model apartments {
//diff-add
  id                String     @id
//diff-add
  created_at        DateTime?
//diff-add
  title             String
//diff-add
  square_meter      Float?
//diff-add
  price             Decimal
//diff-add
  number_of_rooms   Int?
//diff-add
  description       String?
//diff-add
  country           String?
//diff-add
  listed            Boolean
//diff-add
  realtor_id        String?
//diff-add
}

```

### Step 2. Create and Apply the Migration

Run the following command to create a new migration:

```bash
pnpm makemigration --name add-apartments ; pnpm migrate:local
```

### Step3. Create the `apartments` resource

Use command to create a new file `apartments.ts` in the `resources/` folder

```bash
npx adminforth resource
```

After the resource file is generated, extend it with display and validation settings.

- Use recordLabel to control how each record is represented in lists and relations.
- Apply fillOnCreate to automatically populate fields during creation (e.g., generated IDs or timestamps).
- Add minLength and maxLength to string fields to enforce input constraints.
- Use enum to limit fields to predefined values and render them as dropdowns in the UI.
- Configure allowedActions to control which operations are available for the resource (editing, deleting, viewing, and filtering).

To properly apply these changes, refer to the example below and adjust the configuration according to your settings

```ts title="./resources/apartments.ts"
import { AdminForthResourceInput, AdminForthDataTypes } from 'adminforth';

export default {
  dataSource: 'maindb',
  table: 'apartments',
  //diff-remove
  resourceId: 'apartments'
  //diff-add
  resourceId: 'aparts', // resourceId is defaulted to table name but you can redefine it like this e.g. 
  //diff-add
  // in case of same table names from different data sources
  label: 'Apartments',   // label is defaulted to table name but you can change it
  //diff-add
  recordLabel: (r) => `🏡 ${r.title}`,
  columns: [
    {
      name: 'id',
      //diff-add
      type: AdminForthDataTypes.STRING,
      //diff-add
      label: 'Identifier',  // if you wish you can redefine label, defaulted to uppercased name
      showIn: { // show column in filter and in show page
        //diff-remove
        all:true,
        //diff-add
        list: false,
        //diff-add
        edit: false,
        //diff-add
        create: false,
      },
      //diff-add
      primaryKey: true,
      //diff-add
      fillOnCreate: ({ initialRecord, adminUser }) => Math.random().toString(36).substring(7),  // called during creation to generate content of field, initialRecord is values user entered, adminUser object of user who creates record
    },
    {
      name: "title",
      //diff-add
      required: true,
      showIn: {
        all:true, // all available options
      },
      //diff-add
      type: AdminForthDataTypes.STRING,
      //diff-add
      maxLength: 255,  // you can set max length for string fields
      //diff-add
      minLength: 3,  // you can set min length for string fields
    },
    {
      name: 'created_at',
      //diff-add
      type: AdminForthDataTypes.DATETIME,
      //diff-add
      allowMinMaxQuery: true,
      showIn: {
        //diff-remove
        all:true,
        //diff-add
        create: false,
      },
      //diff-add
      fillOnCreate: ({ initialRecord, adminUser }) => (new Date()).toISOString(),
    },
    {
      name: 'price',
      showIn: {
        all:true,
      },
      //diff-add
      inputSuffix: 'USD', // you can add a suffix to an input field that will be displayed when creating or editing records
      //diff-add
      allowMinMaxQuery: true,  // use better experience for filtering e.g. date range, set it only if you have index on this column or if you sure there will be low number of rows
      //diff-add
      editingNote: 'Price is in USD',  // you can put a note near field on editing or creating page
    },
    {
      name: 'square_meter',
      //diff-add
      label: 'Square',
      //diff-add
      allowMinMaxQuery: true,
      showIn: {
        all:true,
      },
      //diff-add
      minValue: 1,  // you can set min /max value for number columns so users will not be able to enter more/less
      //diff-add
      maxValue: 1000,
    },
    {
      name: 'number_of_rooms',
      //diff-add
      allowMinMaxQuery: true,
      showIn: {
        all:true,
      },
      //diff-add
      enum: [
        //diff-add
        { value: 1, label: '1 room' },
        //diff-add
        { value: 2, label: '2 rooms' },
        //diff-add
        { value: 3, label: '3 rooms' },
        //diff-add
        { value: 4, label: '4 rooms' },
        //diff-add
        { value: 5, label: '5 rooms' },
        //diff-add
      ],
    },
    {
      name: 'description',
      //diff-add
      sortable: false,
      showIn: {
        //diff-remove
        all:true,
        //diff-add
        list: false,
      }
    },
    {
      name: 'country',
      showIn: {
        all:true,
      },
      //diff-add
      enum: [{
        //diff-add
        value: 'US',
        //diff-add
        label: 'United States'
        //diff-add
      }, {
        //diff-add
        value: 'DE',
        //diff-add
        label: 'Germany'
        //diff-add
      }, {
        //diff-add
        value: 'FR',
        //diff-add
        label: 'France'
        //diff-add
      }, {
        //diff-add
        value: 'GB',
        //diff-add
        label: 'United Kingdom'
        //diff-add
      }, {
        //diff-add
        value: 'NL',
        //diff-add
        label: 'Netherlands'
        //diff-add
      }, {
        //diff-add
        value: 'IT',
        //diff-add
        label: 'Italy'
        //diff-add
      }, {
        //diff-add
        value: 'ES',
        //diff-add
        label: 'Spain'
        //diff-add
      }, {
        //diff-add
        value: 'DK',
        //diff-add
        label: 'Denmark'
        //diff-add
      }, {
        //diff-add
        value: 'PL',
        //diff-add
        label: 'Poland'
        //diff-add
      }, {
        //diff-add
        value: 'UA',
        //diff-add
        label: 'Ukraine'
        //diff-add
      }, {
        //diff-add
        value: null,
        //diff-add
        label: 'Not defined'
        //diff-add
      }],
    },
    {
      name: 'listed',
      //diff-add
      required: true,  // will be required on create/edit
      showIn: {
        all:true,
      }
    },
    {
      name: 'realtor_id',
      //diff-add
      foreignResource: {
        //diff-add
        resourceId: 'adminuser',
        //diff-add
        searchableFields: ["id", "email"], // fields available for search in filter
        //diff-add
      },
      showIn: {
        all:true,
      }
    }
  ],
  options: {
    listPageSize: 10,
    //diff-add
    allowedActions: {
      //diff-add
      edit: true,
      //diff-add
      delete: true,
      //diff-add
      show: true,
      //diff-add
      filter: true,
      //diff-add
    },
  },
} as AdminForthResourceInput;
```

### Step 4. Register the `apartments` Resource

Open `index.ts` in your project root and import the new resource:

```ts title="./index.ts"
...
//diff-add
import apartmentsResource from "./resources/apartments.js";

...
export const admin = new AdminForth({
  ...
  menu: [
//diff-add
    {
//diff-add
      label: 'Core',
//diff-add
      icon: 'flowbite:brain-solid',
//diff-add
      open: true,
//diff-add
      children: [
//diff-add
        {
//diff-add
          homepage: true,
//diff-add
          label: 'Apartments',
//diff-add
          icon: 'flowbite:home-solid',
//diff-add
          resourceId: 'aparts',
//diff-add
        },
//diff-add
      ]
//diff-add
    },
//diff-add
    { type: 'gap' },
//diff-add
    { type: 'divider' },
    {
      type: 'heading',
      label: 'SYSTEM'
    },
    {
      label: 'Users',
      icon: 'flowbite:user-solid',
      resourceId: 'adminuser'
    },
    {
      label: "Apartments",
      icon: "flowbite:user-solid",
      //diff-remove
      resourceId: "apartments",
      //diff-add
      resourceId: "aparts",
    },
  ],
  ...
});

```

## Generating fake appartments

```ts title="./index.ts"
//diff-add
async function seedDatabase() {
//diff-add
  if (await admin.resource('aparts').count() > 0) {
//diff-add
    return
//diff-add
  }
//diff-add
  for (let i = 0; i < 100; i++) {
//diff-add
    await admin.resource('aparts').create({
//diff-add
      id: `${i}`,
//diff-add
      title: `Apartment ${i}`,
//diff-add
      square_meter: Number((Math.random() * 100).toFixed(1)),
//diff-add
      price: (Math.random() * 10000).toFixed(2),
//diff-add
      number_of_rooms: Math.floor(Math.random() * 4) + 1,
//diff-add
      description: 'Next gen apartments',
//diff-add
      created_at: (new Date(Date.now() - Math.random() * 60 * 60 * 24 * 14 * 1000)).toISOString(),
//diff-add
      listed: i % 2 == 0,
//diff-add
      country: `${['US', 'DE', 'FR', 'GB', 'NL', 'IT', 'ES', 'DK', 'PL', 'UA'][Math.floor(Math.random() * 10)]}`
//diff-add
    });
//diff-add
  };
//diff-add
};

if (fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) {

  ...

  admin.discoverDatabases().then(async () => {
    if (!await admin.resource('adminuser').get([Filters.EQ('email', 'adminforth')])) {
      await admin.resource('adminuser').create({
        email: 'adminforth',
        password_hash: await AdminForth.Utils.generatePasswordHash('adminforth'),
        role: 'superadmin',
      });
    }
//diff-add
    await seedDatabase();
  });

```

This will create records during first launch. Now you should see:
![alt text](localhost_3500_resource_aparts.png)

Feel free to play with the data, add more fields, and customize the UI to your liking.

---

## Hello world app without CLI


While AdminForth CLI is the fastest way to create a new project, you can also create a new project manually.

This might help you better understand how AdminForth project is structured and how to customize it.

Here we create database with users and posts tables and admin panel for it.

Users table will be used to store a credentials for login into admin panel itself.

When back-office user creates a new post it will be automatically assigned using `authorId` to the user who created it.

## Prerequisites

We will use Node v20 for this demo. If you have other Node versions, we recommend using [NVM](https://github.com/nvm-sh/nvm?tab=readme-ov-file#install--update-script) to switch them easily:

```bash
nvm install 20
nvm alias default 20
nvm use 20
```

## Installation

```bash
mkdir af-hello
cd af-hello
pnpm init
pnpm add adminforth express@^4 @dotenvx/dotenvx @types/express typescript tsx @types/node prisma @prisma/client -D
npx --yes tsc --init --module NodeNext --target ESNext
```

## Environment variables

Create two files in your project's root directory:

- `.env.local` — Place your non-sensitive environment variables here (e.g., local database paths, default configurations). This file can be safely committed to your repository as a demo or template configuration.
- `.env` — Store sensitive tokens and secrets here (for example, `ADMINFORTH_SECRET` and other private keys). Ensure that `.env` is added to your `.gitignore` to prevent accidentally committing sensitive data.

Put the following content to the `.env.local` file:

```bash title="./.env.local"
ADMINFORTH_SECRET=123
NODE_ENV=development
DATABASE_URL=sqlite://.db.sqlite
PRISMA_DATABASE_URL=file:.db.sqlite
```

> ☝️ Production best practices:
>
> 1) Most likely you not need `.env` file at all, instead you should use environment variables (from Docker, Kubernetes, Operating System, etc.)
> 2) Set `NODE_ENV` to `production` in your deployment environment to optimize performance and disable development features like hot reloading.
> 3) You should generate very unique value `ADMINFORTH_SECRET` and store it in Vault or other secure place.

## Setting up the scripts

Open `package.json` and add the following scripts:

```json title="./package.json"
{
  ...
//diff-add
  "type": "module",
  "scripts": {
    ...
//diff-add
    "dev": "pnpm _env:dev tsx watch index.ts",
//diff-add
    "prod": "pnpm _env:prod tsx index.ts",
//diff-add
    "start": "pnpm dev",
//diff-add
    "makemigration": "pnpm _env:dev npx --yes prisma migrate dev --create-only",
//diff-add
    "migrate:local": "pnpm _env:dev npx --yes prisma migrate deploy",
//diff-add
    "migrate:prod": "pnpm _env:prod npx --yes prisma migrate deploy",
//diff-add
    "_env:dev": "dotenvx run -f .env -f .env.local --",
//diff-add
    "_env:prod": "dotenvx run -f .env.prod --"
  },
//diff-add
  "engines": {
    //diff-add
    "author": "",
    //diff-add
    "node": ">=20"
    //diff-add
  },
}
```

Create `./pnpm-workspace.yaml` and put next content there:

```json title="./pnpm-workspace.yaml"
onlyBuiltDependencies:
  - better-sqlite3
```

Run installation command to apply all dependencies
```bash
pnpm install
```

## Setting up AdminForth

Create `index.ts` file in root directory with following content:

```ts title="./index.ts"
import express from 'express';
import AdminForth from 'adminforth';
import usersResource from "./resources/adminuser.js";
import { fileURLToPath } from 'url';
import path from 'path';
import { Filters } from 'adminforth';
import { initApi } from './api.js';
import { logger } from 'adminforth';

const ADMIN_BASE_URL = '';

export const admin = new AdminForth({
  baseUrl: ADMIN_BASE_URL,
  auth: {
    usersResourceId: 'adminuser',
    usernameField: 'email',
    passwordHashField: 'password_hash',
    rememberMeDuration: '30d', 
    loginBackgroundImage: 'https://images.unsplash.com/photo-1534239697798-120952b76f2b?q=80&w=3389&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D',
    loginBackgroundPosition: '1/2',
    loginPromptHTML: async () => { 
      const adminforthUserExists = await admin.resource("adminuser").count(Filters.EQ('email', 'adminforth')) > 0;
      if (adminforthUserExists) {
        return "Please use adminforth as username and adminforth as password"
      }
    },
  },
  customization: {
    brandName: "myadmin",
    title: "myadmin",

    datesFormat: 'DD MMM',
    timeFormat: 'HH:mm a',
  showBrandNameInSidebar: true,
  showBrandLogoInSidebar: true,
    emptyFieldPlaceholder: '-',
    styles: {
      colors: {
        light: {
          primary: '#1a56db',
          sidebar: { main: '#f9fafb', text: '#213045' },
        },
        dark: {
          primary: '#82ACFF',
          sidebar: { main: '#1f2937', text: '#9ca3af' },
        }
      }
    },
  },
  dataSources: [
    {
      id: 'maindb',
      url: `${process.env.DATABASE_URL}`
    },
  ],
  resources: [
    usersResource
  ],
  menu: [
    { type: 'heading', label: 'SYSTEM' },
    {
      label: 'Users',
      icon: 'flowbite:user-solid',
      resourceId: 'adminuser'
    }
  ],
});

if (fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) {
  const app = express();
  app.use(express.json());

  initApi(app, admin);

  const port = 3500;
  
  admin.bundleNow({ hotReload: process.env.NODE_ENV === 'development' }).then(() => {
    logger.info('Bundling AdminForth SPA done.');
  });

  admin.express.serve(app);

  admin.discoverDatabases().then(async () => {
    if (await admin.resource('adminuser').count() === 0) {
      await admin.resource('adminuser').create({
        email: 'adminforth',
        password_hash: await AdminForth.Utils.generatePasswordHash('adminforth'),
        role: 'superadmin',
      });
    }
  });

  admin.express.listen(port, () => {
    logger.info(`\x1b[38;5;249m ⚡ AdminForth is available at\x1b[1m\x1b[38;5;46m http://localhost:${port}${ADMIN_BASE_URL}\x1b[0m\n`);
  });
}

```

> ☝️ For simplicity we defined whole configuration in one file. Normally once configuration grows you should
> move each resource configuration to separate file and organize them to folder and import them in `index.ts`.

Create `api.ts` file in root directory with following content:

```ts title="./api.ts"
import { Express, Response } from "express";
import { IAdminForth, IAdminUserExpressRequest } from "adminforth";
import * as z from "zod";

export function initApi(app: Express, admin: IAdminForth) {
  app.get(`${admin.config.baseUrl}/api/hello/`,

    admin.express.withSchema(
      {
        description: "Returns example data from a custom Express API together with the current authenticated AdminForth user.",
        response: z.object({
          message: z.string(),
          users: z.array(z.record(z.string(), z.unknown())),
          adminUser: z.record(z.string(), z.unknown()),
        }),
      },

      // you can use data API to work with your database https://adminforth.dev/docs/tutorial/Customization/dataApi/
      // and admin.express.authorize to inject req.adminUser
      admin.express.authorize(
        async (req: IAdminUserExpressRequest, res: Response) => {
          const allUsers = await admin.resource("adminuser").list([]);
          res.json({
            message: "Hello from AdminForth API!",
            users: allUsers,
            adminUser: req.adminUser,
          });
        }
      )
    )
  );
}
```

>Install and import Zod before using this pattern: `pnpm add zod` or `npm install zod`, then `import * as z from 'zod';`. `admin.express.withSchema(...)` will convert the Zod schema to OpenAPI for you.

Update `tsconfig.json` file in root directory with following content: 
```ts title="./tsconfig.json"
{
  "compilerOptions": {
    "target": "esnext",
    "module": "nodenext",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true
  },
  "exclude": ["node_modules", "dist"]
}
```

Create new directory `./resources/adminuser.ts` with following content:

```ts title="./resources/adminuser.ts"
import AdminForth, { AdminForthDataTypes } from 'adminforth';
import type { AdminForthResourceInput, AdminForthResource, AdminUser } from 'adminforth';
import { randomUUID } from 'crypto';
import { logger } from 'adminforth';

async function allowedForSuperAdmin({ adminUser }: { adminUser: AdminUser }): Promise<boolean> {
  return adminUser.dbUser.role === 'superadmin';
}

export default {
  dataSource: 'maindb',
  table: 'adminuser',
  resourceId: 'adminuser',
  label: 'Admin Users',
  recordLabel: (r) => `👤 ${r.email}`,
  options: {
    allowedActions: {
      edit: allowedForSuperAdmin,
      delete: allowedForSuperAdmin,
    },
  },
  columns: [
    {
      name: 'id',
      primaryKey: true,
      type: AdminForthDataTypes.STRING,
      fillOnCreate: ({ initialRecord, adminUser }) => randomUUID(),
      showIn: {
        edit: false,
        create: false,
      },
    },
    {
      name: 'email',
      required: true,
      isUnique: true,
      type: AdminForthDataTypes.STRING,
      validation: [
        // you can also use AdminForth.Utils.EMAIL_VALIDATOR which is alias to this object
        {
          regExp: '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$',
          message: 'Email is not valid, must be in format example@test.com'
        },
      ]
    },
    {
      name: 'created_at',
      type: AdminForthDataTypes.DATETIME,
      showIn: {
        edit: false,
        create: false,
      },
      fillOnCreate: ({ initialRecord, adminUser }) => (new Date()).toISOString(),
    },
    {
      name: 'role',
      type: AdminForthDataTypes.STRING,
      enum: [
        { value: 'superadmin', label: 'Super Admin' },
        { value: 'user', label: 'User' },
      ]
    },
    {
      name: 'password',
      virtual: true,  // field will not be persisted into db
      required: { create: true }, // make required only on create page
      editingNote: { edit: 'Leave empty to keep password unchanged' },
      type: AdminForthDataTypes.STRING,
      showIn: { // to show field only on create and edit pages
        show: false,
        list: false,
        filter: false,
      },
      masked: true, // to show stars in input field

      minLength: 8,
      validation: [
        // request to have at least 1 digit, 1 upper case, 1 lower case
        AdminForth.Utils.PASSWORD_VALIDATORS.UP_LOW_NUM,
      ],
    },
    {
      name: 'password_hash',
      type: AdminForthDataTypes.STRING,
      backendOnly: true,
      showIn: { all: false }
    }
  ],
  hooks: {
    create: {
      beforeSave: async ({ record, adminUser, resource }: { record: any, adminUser: AdminUser, resource: AdminForthResource }) => {
        record.password_hash = await AdminForth.Utils.generatePasswordHash(record.password);
        return { ok: true };
      }
    },
    edit: {
      beforeSave: async ({ oldRecord, updates, adminUser, resource }: { oldRecord: any, updates: any, adminUser: AdminUser, resource: AdminForthResource }) => {
        logger.info(`Updating user, ${updates}`);
        if (oldRecord.id === adminUser.dbUser.id && updates.role) {
          return { ok: false, error: 'You cannot change your own role' };
        }
        if (updates.password) {
          updates.password_hash = await AdminForth.Utils.generatePasswordHash(updates.password);
        }
        return { ok: true }
      },
    },
  },
} as AdminForthResourceInput;
```

Create new directory `./custom/tsconfig.json` with following content:
```ts title="./custom/tsconfig.json"
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["../node_modules/adminforth/dist/spa/src/*"],
      "@@/*": ["./*"]
    }
  }
}
```

## Database creation

> ☝️ For demo purposes we will create a database using Prisma and SQLite.
> You can also create it using any other favorite tool or ORM and skip this step.

Create `./schema.prisma` and put next content there:

```text title="./schema.prisma"
generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "sqlite"
}

model adminuser {
  id            String     @id
  email         String     @unique
  password_hash String
  role          String
  created_at    DateTime
}
```

Create `./prisma.config.ts` and put next content there:

```ts title="./prisma.config.ts"
import 'dotenv/config'
import { defineConfig, env } from 'prisma/config'

export default defineConfig({
  datasource: {
    url: env('PRISMA_DATABASE_URL'),
  },
})
```

Create database using `prisma migrate`:

```bash
pnpm run makemigration --name init ; pnpm run migrate:local
```

Now you can run your app:

```bash
pnpm start
```

Open http://localhost:3500 in your browser and login with credentials `adminforth` / `adminforth`.

![alt text](localhost_3500_login.png)

## Initializing custom directory

If you are not using CLI, you can create `custom` directory and initialize it with `npm`:

```bash
cd ./custom
npm init -y
```

We will use this directory for all custom components. If you want to call your dir with other name then `custom`, just set [customComponentsDir option](/docs/api/Back/interfaces/AdminForthConfigCustomization/#customcomponentsdir)

Also, for better development experience we recommend to create file `custom/tsconfig.json` with the following content:

```json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": [
        "../node_modules/adminforth/dist/spa/src/*"
      ],
      "*": [
        "../node_modules/adminforth/dist/spa/node_modules/*"
      ],
      "@@/*": [
        "."
      ]
    }
  }
}
```

## Possible configuration options

Check [AdminForthConfig](/docs/api/Back/interfaces/AdminForthConfig.md) for all possible options.

---

## Glossary


## dataSource

A DataSource is a connection to one database. Datasources have id for references from resources and URL which follows the standard URI format. For example `mysql://user:password@localhost:3306/database`.
It used to:

* Discover the columns in the database
* Make queries to get the list and show records
* Make queries to modify data

There might be several datasources in the system for various databases e.g. One datasource to Mongo DBs and one to Postgres DB. 

### connectionRecovery

For PostgreSQL datasources AdminForth keeps a connection pool. The optional `connectionRecovery` flag controls how the connector reacts when that connection drops (DB restart, failover, network blip, etc.):

```ts
dataSources: [
  {
    id: 'maindb',
    url: `${process.env.DATABASE_URL}`,
    connectionRecovery: true, // default
  },
],
```

- `true` (default, recommended) — **self-heal mode.** The pool recovers automatically: a dead idle connection is dropped and a fresh one is transparently opened on the next query, so the app keeps working without a manual restart. Queries that were in-flight at the moment of the outage will fail, but subsequent queries succeed once the database is back.
- `false` — **legacy mode.** On a connection error the pool is destroyed and recreated after 1 second. If the outage outlasts that retry, the app can be left with a permanently dead pool and require a manual restart. Kept only for backward compatibility.

This flag is currently honored by the PostgreSQL connector; other connectors rely on their driver's built-in recovery.

## resource

A [Resource](/docs/api/Back/interfaces/AdminForthResource.md) is a AdminForth representation of a table or collection in database. One resource is one table in the database. Resource has `table` property which should be equal to the name of the table in the database.
It has a datasource id to point to database, a  definition of list of columns and various customization options. 

## column

A [Column](/docs/api/Back/interfaces/AdminForthResourceColumn.md) is a representation of a column in a table. It has a `name` which should be equal to name in database and various configuration options.

## record

A record is a row in a relational database table. Or Document in document database table.

## action

Action is one of operations which can be performed on the resource or it's records. 

There are next [actions](/docs/api/Common/enumerations/AllowedActionsEnum.md):

* create
* edit
* delete
* list
* show
* filter

## adminUser

[Object](/docs/api/Common/interfaces/AdminUser) which represents a user who logged in to the AdminForth. 

## hook

Hook is a optional async function which allows to inject in backend logic before executing the datasource query or after it. 
Hooks exist for all database queries including data read queries like list, show, and data write queries like create, edit, delete.
All AdminForth hooks are executed on the backend side only.

## allowedAction

Static boolean value or async function which returns boolean and defines whether the action is allowed for the user.
allowedAction checked before any hooks or datasource queries: this means that if your allowed action function
returned false you can be sure that user attempt to perform the action or get the data will be strictly prohibited on backend side.

## component

Component is a Vue frontend component which is used to add or modify UI elements in AdminForth. It can be used as a full custom page with a link in menu or as a part of the existing AdminForth page

## field

Same to column, but considered in context of record.

## Plugin

Plugin is a class defined to extend AdminForth functionality. Plugin philosophy is to simply modify AdminForth config after it is defined by user. In other words, everything that could be done in config, can be done in plugin and vice versa.

In same way, like config does it, plugins set own Frontend components and backend hooks to modify AdminForth behavior.

The main difference is that plugin allows to simplify routine repeating tasks and reduce the amount of code in the config file and code of cusomtom components.

---

## Branding and Theming


The first things you would probably like to change are the logo, favicon and the name of the admin application. 

You can place your logo and favicon files into the `custom` directory e.g. replacing existing default `logo.svg` and `favicon.png` files.

Then you can change the branding of the application in the configuration:

```ts title='./index.ts'

const admin = new AdminForth({
  ...
  customization: {
//diff-remove
    brandName: "myadmin",
//diff-add
    brandName: 'My App',  // used in login page and sidebar
//diff-remove
    title: "myadmin",
//diff-add
    title: 'My App Admin',  // used to set HTML title tag
    brandLogo: '@@/assets/logo.svg', // replace with your images in custom/assets  directory
    favicon: '@@/assets/favicon.png',
  },
  ...
});
```

Please note that `@@/` is a special prefix which tells AdminForth to look for the file in the `custom` directory. 
You can use `@@/` prefix for all paths in the configuration and also import images like this in your custom components e.g.:

```ts
<template>
  
</template>
```

## Removing brand name from sidebar

If you are using logo image which has branded title inside, you might
want completely remove default text brand name from sidebar:

```ts title='./index.ts'
brandName: 'My App',
//diff-add
showBrandNameInSidebar: false,
```

`brandName` will still be used in the other places e.g. login form.

## Removing brand logo from sidebar

If you want to hide the logo image in the sidebar while keeping the brand name text (or vice versa), disable the logo with:

```ts title='./index.ts'
brandName: 'My App',
//diff-add
showBrandLogoInSidebar: false,
```

By default, the logo is shown when available. This flag controls the sidebar logo only and does not affect the login page.

## Theming

AdminForth uses TailwindCSS for styling. You are able to customize the look of the application by changing the TailwindCSS configuration.

Use [styles.ts](https://github.com/devforth/adminforth/blob/main/adminforth/modules/styles.ts) file to see which variables are available for change.

Let's say your brand has a primary purple color and you wish to make side bar purple with white text.

In `index.ts` file set the `styles` property in the configuration:

```ts title='./index.ts'

const admin = new AdminForth({
  ...
  customization: {
    styles: {
      colors: {
        light: {
//diff-add
          // color for links, icons etc.
//diff-remove
          primary: '#1a56db',
//diff-add
          primary: '#b400b8',
//diff-add
          // color for sidebar and text
//diff-remove
          sidebar: { main: '#f9fafb', text: '#213045' },
//diff-add
          sidebar: { main:'#571e58', text: 'white'},
        },
      }
    } 
  },
  ...
});
```
Here is how it looks:
![AdminForth Themes](image-10.png)

## Single theme

If you want to enforce a consistent theme and disable the theme switcher, you can configure AdminForth to use only one theme variant. 

```ts title='./index.ts'

const admin = new AdminForth({
  ...
  customization: {
  //diff-add
    singleTheme: "light",
    styles: {
      ...
      }
    } 
  },
  ...
});
```

## Icon only sidebar 

AdminForth supports a collapsible sidebar that can be toggled between a full-width view (showing labels) and an icon-only view (showing only icons).

```ts title='./index.ts'

const admin = new AdminForth({
  ...
  customization: {
  //diff-add
    iconOnlySidebar: {
  //diff-add
      enabled: true,  // Optional: Enable the collapsible icon-only sidebar feature
  //diff-add
      logo: '@@/logo.svg',  // Optional: Custom logo to display in icon-only mode
  //diff-add
      expandedSidebarWidth: '18.5rem', // Optional: sets the expanded sidebar width, defaults to 16.5rem
  //diff-add
    }, 
  },
  ...
});
```

## Square vs rounded buttons?

Not an issue, just change:

```ts title='./index.ts'
styles: {
//diff-add
  borderRadius: {
//diff-add
    "default": "0px"
//diff-add
  }
}
```

## Login background

To make login interface less boring background image matters.

For example you might want to get [free sweet background](https://unsplash.com/s/photos/secure?license=free) from Unsplash like
[Nate Watson's apartments view](https://images.unsplash.com/photo-1516501312919-d0cb0b7b60b8?q=80&w=3404&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D).

Download it to `custom` directory, and just set it in the configuration:

```ts title='./index.ts'
const admin = new AdminForth({
  ...
  auth: {
    ...
//diff-add
    loginBackgroundImage: '@@/photo-1516501312919-d0cb0b7b60b8.jpeg',
  },
  ...
});
```
Here is how it looks:
![AdminForth Login Background](demo_adminforth_login.png)

You can also set background position and size:

```ts title='./index.ts'

auth: {
  ...
  loginBackgroundImage: '@@/photo-1516501312919-d0cb0b7b60b8.jpeg',
//diff-add
  loginBackgroundPosition: 'over',
}
```

`loginBackgroundPosition` accepts values:

- `over` - image will be over the whole login page with cover mode
- `1/2`(default), `3/4`, `2/5`, `3/5` etc. - image will be in the left side of the login page with cover mode

### Disabling background blend mode

When using `loginBackgroundPosition: 'over'`, AdminForth applies a background blend mode by default to ensure text readability over the background image. If you want to disable this blend mode and display the background image without any overlay effects, you can add:

```ts title='./index.ts'
auth: {
  ...
  loginBackgroundImage: '@@/photo-1516501312919-d0cb0b7b60b8.jpeg',
  loginBackgroundPosition: 'over',
//diff-add
  removeBackgroundBlendMode: true,
}

```

## Custom items in html head

If you want to add custom elements to the HTML head, you can define them in the configuration:

```ts title='./index.ts'
customization: {
  customHeadItems: [
    {
      tagName: 'link',
      attributes: {
        rel: 'stylesheet',
        href: 'https://example.com/custom.css'
      }
    },
    {
      tagName: 'script',
      attributes: {
        src: 'https://example.com/custom.js',
        defer: true
      }
    },
    {
      tagName: 'meta',
      attributes: {
        name: 'theme-color',
        content: ' #000000'
      }
    }
  ]
}

```

---

## Custom record field rendering


## Customizing how AdminForth renders the cells with record values

Let's change how AdminForth renders the number of rooms in the 'list' and 'show' views.
We will render '🟨' for each room and then we will print `square_meter` at the same cells.

Create directory `custom`. Create a file `RoomsCell.vue` in it:

```html title='./custom/RoomsCell.vue'
<template>
  
    
      🟨
    
      
    {{ record.square_meter }} m²
  
</template>

<script setup lang="ts">
import type { AdminForthResourceColumnCommon, AdminForthResourceCommon, AdminUser } from '@/types/Common';

const props = defineProps<{
    column: AdminForthResourceColumnCommon;
    record: any;
    meta: any;
    resource: AdminForthResourceCommon;
    adminUser: AdminUser
}>();
</script>
```

Now you can use this component in the configuration of the resource:

```ts title='./resources/apartments.ts'
{
  ...
  resourceId: 'aparts',
  columns: [
    ...
    {
      ...
      name: 'number_of_rooms',
//diff-add
      components: {
//diff-add
        show: '@@/RoomsCell.vue',
//diff-add
        list: '@@/RoomsCell.vue',
//diff-add
      }
    },
    ...
  ],
  ...
}
```
Here is how it looks:
![alt text](<Custom record field rendering.png>)

In very similar way you can render how cell is rendered in `'edit'` and `'create'` view. 
You can use it for creating custom editors for the fields. Check [component specs](/docs/api/Common/interfaces/AdminForthFieldComponents#create) to understand which props are passed to the component

## Parametrize the custom components

Sometimes you need to render same component with different parameters.
You can use [full component declaration](/docs/api/Common/interfaces/AdminForthComponentDeclarationFull)

```ts title='./resources/apartments.ts'

{
  ...
  resourceId: 'aparts',
  columns: [
    ...
    {
      ...
      name: 'number_of_rooms',
      components: {
//diff-remove
       show: '@@/RoomsCell.vue',
//diff-add
       show: {
//diff-add
         file: '@@/RoomsCell.vue',
//diff-add
         meta: {
//diff-add
           filler: '🟨',
//diff-add
         },
//diff-add
       },
//diff-remove
       list: '@@/RoomsCell.vue',
//diff-add
       list: {
//diff-add
         file: '@@/RoomsCell.vue',
//diff-add
         meta: {
//diff-add
           filler: '🟦',
//diff-add
          },
//diff-add
        }
      }
    },
    ...
  ],
  ...
}
```

Now our component can read `filler` from `meta` prop:

```ts title='./custom/RoomsCell.vue'
<template>
  
    
//diff-remove
     🟨
//diff-add
    {{ meta.filler }}
    
    {{ room.square_meter }} m²
  
</template>

<script setup lang="ts">
import type { AdminForthResourceColumnCommon, AdminForthResourceCommon, AdminUser } from '@/types/Common';

const props = defineProps<{
    column: AdminForthResourceColumnCommon;
    record: any;
    meta: any;
    resource: AdminForthResourceCommon;
    adminUser: AdminUser
}>();
</script>
```

## Using 3rd-party npm packages in the Vue components

To install 3rd-party npm packages you should create npm package in the `custom` directory:

```bash
cd custom
```

And simply do `pnpm install` for the package you need:

```bash
pnpm i <some package> -D
```

## Editing values component

In same way as we define `show` and list component, we can create component for edit/create page. 
Let's create custom dropdown for `country` field which will show emoji flags of the countries.

```html title='./custom/CountryDropdown.vue'
<template>
  <Select
      class="w-full"
      :options="column.enum"
      :model-value="record[column.name]"
      @update:model-value="emit('update:value', $event)"
  >
    <template #item="{option}">
      {{ getCountryFlag(option.value) }} {{ option.label }}
    </template>

    <template #selected-item="{option}">
      {{ getCountryFlag(option.value) }} {{ option.label }}
    </template>
  </Select>
</template>

<script setup lang="ts">
import Select from "@/afcl/Select.vue";
import type {
  AdminForthResourceColumnCommon,
  AdminForthResourceCommon,
  AdminUser,
} from "@/types/Common";

const props = defineProps<{
  column: AdminForthResourceColumnCommon;
  record: any;
  meta: any;
  resource: AdminForthResourceCommon;
  adminUser: AdminUser;
  readonly: boolean;
}>();

const emit = defineEmits(["update:value"]);

function getCountryFlag(countryCode: string) {
  return countryCode?.toUpperCase()
    .replace(/./g, (char) => String.fromCodePoint(char.charCodeAt(0) + 127397));
}

</script>
```

Now you can use this component in the configuration of the resource:

```ts title='./resources/apartments.ts'
{
  ...
  resourceId: 'aparts',
  columns: [
    ...
    {
      name: 'country',
//diff-add
      components: {
//diff-add
        edit: '@@/CountryDropdown.vue',
//diff-add
        create: '@@/CountryDropdown.vue',
//diff-add
      },
      ...
    },
    ...
  ],
  ...
}
```

### Custom record editing (updating other fields)

Sometimes a custom editor needs to update not only its own field, but also other fields of the record (for example, generate a slug from a title).

For this, custom `edit`/`create` components can emit an `update:recordFieldValue` event with the payload `{ fieldName, fieldValue }`. AdminForth will update the corresponding field in the record.

> If you emit `update:recordFieldValue` to modify a field which is hidden by `showIn.create: false` / `showIn.edit: false`, the backend will reject the request by default.
> To allow this, set the target column config to `allowModifyWhenNotShowInCreate: true` and/or `allowModifyWhenNotShowInEdit: true`.

```html title='./custom/TitleWithSlugEditor.vue'
<template>
  
    <Input
      :model-value="record[column.name]"
      :placeholder="$t('Title')"
      @update:model-value="onTitleChange"
    />
    <Input
      :model-value="record.slug"
      :placeholder="$t('Slug')"
      readonly
    />
  
</template>

<script setup lang="ts">
import Input from "@/afcl/Input.vue";
import type {
  AdminForthResourceColumnCommon,
  AdminForthResourceCommon,
  AdminUser,
} from "@/types/Common";

const props = defineProps<{
  column: AdminForthResourceColumnCommon;
  record: any;
  meta: any;
  resource: AdminForthResourceCommon;
  adminUser: AdminUser;
  readonly: boolean;
}>();

const emit = defineEmits([
  "update:value", // update current column value
  "update:recordFieldValue", // update any other field in the record
]);

function slugify(value: string) {
  return value
    ?.toLowerCase()
    .trim()
    .replace(/[^a-z0-9]+/g, "-")
    .replace(/(^-|-$)+/g, "");
}

function onTitleChange(newTitle: string) {
  // update current column value
  emit("update:value", newTitle);

  // update another field in the record (e.g. slug)
  emit("update:recordFieldValue", {
    fieldName: "slug",
    fieldValue: slugify(newTitle),
  });
}
</script>
```

And use it in the resource configuration for both `edit` and `create` views:

```ts title='./resources/apartments.ts'
{
  ...
  resourceId: 'aparts',
  columns: [
    ...
    {
      name: 'title',
      components: {
        edit: '@@/TitleWithSlugEditor.vue',
        create: '@@/TitleWithSlugEditor.vue',
      },
    },
    {
      name: 'slug',
      // standard input; value will be kept in sync
      ...
    },
    ...
  ],
  ...
}
```

### Custom inValidity inside of the custom create/edit components

Custom componets can emit `update:inValidity` event to parent to say that the field is invalid.

You can define this emit as:

```ts title='./custom/<AnyYourComponent>.vue'
const emit = defineEmits([
  "update:value", 
//diff-add  
  "update:inValidity"
]);
```

Every time when state in your component becomes invalid, you can emit this event with error message which will be shown in the UI to the user.

```ts
emit('update:inValidity', "The field has wrong value");
```

Every time when state in your component becomes valid, you can emit this event with `false`

```ts
emit('update:inValidity', false);
```

If component never emits `update:inValidity` event (includign case when you don't use it at all), the field is considered valid.

### Custom emptiness inside of the custom create/edit components

Custom componets can emit `update:emptiness` event to parent to say that the field is empty.

Emptiness is used to prevent user from saving form when `column.required` is true and field is empty.

When `column.required` is false emptiness is not checked.

You can define this emit as:

```ts
const emit = defineEmits([
  "update:value", 
//diff-add
  "update:emptiness"
]);
```

Every time when state in your component becomes empty, you can emit this event with `true`

```ts
emit('update:emptiness', true);
```

Every time when state in your component becomes not empty, you can emit this event with `false`

```ts
emit('update:emptiness', false);
```

Emptiness emit has a higher priority than natural emptiness of the field. For example when actual value under column in record is empty but component emitted `false` for `update:emptiness` (in other words child component said it non-empty), the field is considered as Non-empty. 
For another example, if companent is naturally updated some value in record but emited `true` (said that it is empty) the field is considered as empty and error in form will be shown to user.

## Pre-made renderers

Though creating custom renderers is super-easy, we have couple of pre-made renderers for you to use.

### CompactUUID

If you have a UUID column which you want display in table in more compact manner, you can use `CompactUUID` renderer.

```ts title='./resources/apartments.ts'
//diff-add
import { randomUUID } from 'crypto';

  ...
  columns: [
    { 
      name: 'id', 
      primaryKey: true,
      showIn: {
//diff-remove
        list: false,
        edit: false,
        create: false,
      },
//diff-remove
      fillOnCreate: ({ initialRecord, adminUser }) => Math.random().toString(36).substring(7),
//diff-add
      fillOnCreate: ({initialRecord}: any) => randomUUID(),
//diff-add
      components: {
//diff-add
        list: '@/renderers/CompactUUID.vue'
//diff-add
      }
    }
  ...
```

![alt text](<Group 8.jpg>)

### Country Flag

Renders string fields containing ISO-3166-1 alpha-2 country codes as flags (e.g. 'US', 'DE', 'FR', etc.)

```ts title='./resources/apartments.ts'
  columns: [
    ...
    {
      name: 'country',
  //diff-add
      components: {
  //diff-add
        list: '@/renderers/CountryFlag.vue'
  //diff-add
      },
      ...
    }
```

![alt text](<Group 13.png>)

You can also show country name after the flag:

```ts title='./resources/apartments.ts'
  columns: [
    ...
    {
      name: 'country',
  //diff-add
      components: {
  //diff-add
        list: {
  //diff-add
          file: '@/renderers/CountryFlag.vue',
  //diff-add
          meta: {
  //diff-add
            showCountryName: true
  //diff-add
          }
  //diff-add
        }
  //diff-add
      },
      ...
    }
```

![alt text](<Group 12 (1).jpg>)

### Human Number

It formats large numbers into a human-readable format (e.g., 10k, 1.5M) and supports localization for different number formats.

```ts title='./resources/apartments.ts'
  columns: [
    ...
    { 
      name: 'square_meter', 
      label: 'Square', 
      minValue: 1,  // you can set min /max value for number fields
      maxValue: 100000000,
      //diff-add
      components: {
      //diff-add
        list: {
      //diff-add
          file: '@/renderers/HumanNumber.vue',
      //diff-add
        }
      //diff-add
      }
    },
    {
    ...
```

![alt text](<HumanNumber.png>)

### URL

If your field has absolute URLs as text strings you can use `URLs` renderer to render them as clickable links.

```ts title='./resources/anyResource.ts'
  columns: [
    ...
    {
      name: 'url',
  //diff-add
      components: {
  //diff-add
        list: '@/renderers/URL.vue'
  //diff-add
      },
    ...
```

### Relative Time

To format your date fields to display the elapsed time, you can utilize the RelativeTime renderer.
 
```ts title='./resources/anyResource.ts'
  columns: [
    ...
    {
      name: 'created_at',
  //diff-add
      components: {
  //diff-add
        list: '@/renderers/RelativeTime.vue'
  //diff-add
      },
    ...
```

### Rich text and Zero-style Rich text

If you have some field which holds HTML content you can use `RichText` renderer to render it as HTML.

```ts title='./resources/anyResource.ts'
  columns: [
    ...
    {
      name: 'content',
  //diff-add
      components: {
  //diff-add
        list: '@/renderers/RichText.vue'
  //diff-add
      },
      ...
    }
  ] 
```

The renderer will render the HTML content and protect against XSS attacks. 
If HTML in field has some tags or classes which covered by adminforth internal styles (including Tailwind classes), they will be styled (text/p styles etc). If this is an issue for your task and you need full raw preview of the HTML, you can use `ZeroStyleRichText` renderer:

```ts title='./resources/anyResource.ts'
//diff-remove
list: '@/renderers/RichText.vue',
//diff-add
list: '@/renderers/ZeroStylesRichText.vue',
//diff-add
```

`ZeroStyleRichText` fits well for tasks like email templates preview fields.

### Sensitive data blur

For fields containing sensitive data (like passwords, API keys, tokens, or other confidential values), use the `SensitiveBlurCell` renderer. It blurs the value by default and reveals it on click.

```ts title='./resources/anyResource.ts'
  columns: [
    ...
    {
      name: 'api_key',
  //diff-add
      components: {
  //diff-add
        show: '@/renderers/SensitiveBlurCell.vue',
  //diff-add
        list: '@/renderers/SensitiveBlurCell.vue',
  //diff-add
      },
    ...
```

The renderer wraps the standard value output and adds a click-to-reveal blur effect. Clicking again hides the value.

For long values (like API keys) you can enable compact mode by passing `compact: true` via `meta`. When set, the value is shortened the same way as the `CompactUUID` renderer (first 4 + `...` + last 4 characters). You can additionally pass `copy: true` to render a copy-to-clipboard button next to the value, and `eyeButton: true` to render an eye icon that also toggles the blur. `compact`, `copy` and `eyeButton` are independent of each other and can be combined in any way:

```ts title='./resources/anyResource.ts'
  columns: [
    ...
    {
      name: 'api_key',
      components: {
        show: {
  //diff-add
          file: '@/renderers/SensitiveBlurCell.vue',
  //diff-add
          meta: { compact: true, copy: true, eyeButton: true },
        },
        list: {
  //diff-add
          file: '@/renderers/SensitiveBlurCell.vue',
  //diff-add
          meta: { compact: true, copy: true, eyeButton: true },
        },
      },
    ...
```

### Custom filter component for square meters

Sometimes standard filters are not enough, and you want to make a convenient UI for selecting a range of apartment areas. For example, buttons with options for “Small (&lt;25 m²)”, “Medium (25–90 m²)” and “Large (&gt;90 m²)”.

```ts title='./custom/SquareMetersFilter.vue'
<template>
  
    {{ $t('Square meters filter') }}
    
      <button
        v-for="option in options"
        :key="option.value"
        type="button"
        class="flex gap-1 items-center py-1 px-3 text-sm font-medium rounded-default border focus:outline-none focus:z-10 focus:ring-4"
        :class="{
          'text-white bg-blue-500 border-blue-500 hover:bg-blue-600 focus:ring-blue-200 dark:focus:ring-blue-800': selected === option.value,
          'text-gray-900 bg-white border-gray-300 hover:bg-gray-100 hover:text-blue-500 focus:ring-gray-100 dark:focus:ring-gray-700 dark:bg-gray-800 dark:text-gray-400 dark:border-gray-600 dark:hover:text-white dark:hover:bg-gray-700': selected !== option.value
        }"
        @click="select(option.value)"
      >
        {{ $t(option.label) }}
      </button>
    
  
</template>

<script setup lang="ts">
import { ref, watch, onMounted } from 'vue';

const emit = defineEmits(['update:modelValue']);

const props = defineProps<{
  modelValue: Array<{ operator: string; value: number }> | null;
}>();

const selected = ref<string | null>(null);

const options = [
  { value: 'small', label: 'Small' },
  { value: 'medium', label: 'Medium' },
  { value: 'large', label: 'Large' }
];

onMounted(() => {
  const val = props.modelValue;
  if (!val || val.length === 0) {
    selected.value = null;
    return;
  }

  const ops = val.map((v) => `${v.operator}:${v.value}`);

  if (ops.includes('lt:25')) selected.value = 'small';
  else if (ops.includes('gte:25') && ops.includes('lte:90')) selected.value = 'medium';
  else if (ops.includes('gt:90')) selected.value = 'large';
  else selected.value = null;
});

watch(selected, (size) => {
  if (!size) {
    emit('update:modelValue', []);
    return;
  }

  const filters = {
    small: [{ operator: 'lt', value: 25 }],
    medium: [
      { operator: 'gte', value: 25 },
      { operator: 'lte', value: 90 }
    ],
    large: [{ operator: 'gt', value: 90 }]
  };

  emit('update:modelValue', filters[size]);
});

function select(size: string) {
  selected.value = size;

  switch (size) {
    case 'small':
      emit('update:modelValue', [{ operator: 'lt', value: 25 }]);
      break;
    case 'medium':
      emit('update:modelValue', [
        { operator: 'gte', value: 25 },
        { operator: 'lte', value: 90 }
      ]);
      break;
    case 'large':
      emit('update:modelValue', [{ operator: 'gt', value: 90 }]);
      break;
  }
}
</script>
```

```ts title='./resources/apartments.ts'
  columns: [
    ...
    {
      name: 'square_meter', 
      label: 'Square',
      //diff-add
      components: {
      //diff-add
        filter: '@@/SquareMetersFilter.vue'
      //diff-add
      }
    },
    ...
]

---

## Virtual columns


## Virtual column for show and list

Sometimes you need to visualize custom columns which do not exist in database. 
For doing this you can use `virtual` columns.

```ts title='./resources/apartments.ts'

//diff-add
import { AdminForthResourcePages } from 'adminforth';

...
resourceId: 'aparts',
columns: [
  ...
//diff-add
  {
//diff-add
    name: 'Country Flag',
//diff-add
    label: 'Country Flag',
//diff-add
    type: AdminForthDataTypes.STRING,
//diff-add
    virtual: true,
//diff-add
    showIn: {
//diff-add
      [AdminForthResourcePages.edit]: false,
//diff-add
      [AdminForthResourcePages.create]: false,
//diff-add
      [AdminForthResourcePages.filter]: false,
//diff-add
    },
//diff-add
    components: {
//diff-add
      show: '@@/CountryFlag.vue',
//diff-add
      list: '@@/CountryFlag.vue',
//diff-add
    },
//diff-add
  }
  ...
]
```
 
 This field will be displayed in show and list views with custom component `CountryFlag.vue`.

:::tip Enriching a virtual column from a hook
If you fill a virtual column from a hook (e.g. [`afterDatasourceResponse`](./04-hooks.md#modify-record-after-it-is-returned-from-database)) instead of a custom component, write the enriched value into a field with **the same name as the virtual column**. This keeps the value addressable by column name everywhere — most importantly, the [Agent plugin](/docs/tutorial/Plugins/agent/) selects records by column name, so a mismatched field name makes it select the (empty) virtual column and miss your enriched data.
:::
 Create file `CountryFlag.vue` in `custom` folder of your project:
 
 ```html title="./custom/CountryFlag.vue"
 <template>
    {{ getFlagEmojiFromIso(record.country) }}
</template>
   
<script setup lang="ts">
  import type { AdminForthResourceColumnCommon, AdminForthResourceCommon, AdminUser } from '@/types/Common';

  const props = defineProps<{
      column: AdminForthResourceColumnCommon;
      record: any;
      meta: any;
      resource: AdminForthResourceCommon;
      adminUser: AdminUser
  }>();
    
   function getFlagEmojiFromIso(iso) {
      return iso?.toUpperCase()?.replace(/./g, (char) => String.fromCodePoint(char.charCodeAt(0) + 127397));
   }
</script>
```

Here is how it looks:

![alt text](<Virtual columns.png>)

## Virtual columns for filtering.

Virtual column can also be used as a shorthand for a complex filtering.
Lets say we want to divide apartments into two types: "base" ones and "luxury" and then allow admins to filter apartments by this category. Condition for being a "luxury" apartment is either having more then 80 sq.m area or costing more then 100k.
One way to do it is to actually add a real column to a table and then fill it every time new apartment is added. A more simple way is to add a virtual column and then use `list.beforeDatasourceRequest` hook to replace filtering on this column with desired one.
For this purpose following changes will be required for apartments config:

```ts title='./resources/apartments.ts'
import { Filters } from "adminforth";
...
resourceId: 'aparts',
...
hooks: {
...
  list: {
    beforeDatasourceRequest: async ({ query }: { query: any }) => {
      query.filters = query.filters.map((filter: any) => {
        // replace apartment_type filter with complex one
        if (filter.field === 'apartment_type') {
          if (filter.value === 'luxury') {
            return Filters.OR(Filters.GTE('square_meter', 80), Filters.GTE('price', 100000));
          }

          // filter for "base" apartment as default
          return Filters.AND(Filters.LT('square_meter', 80), Filters.LT('price', 100000));
        }

        return filter;
      });
      return { ok: true, error: "" };
    },
    ...
  },
...
},
...
columns: [
  ...
  {
    name: "apartment_type",
    virtual: true,
    showIn: { all: false, filter: true }, // hide it from display everywhere, except filter page
    enum: [
      {
        value: 'base',
        label: 'Base',
      },
      {
        value: 'luxury',
        label: 'Luxury'
      },
    ],
    filterOptions: {
      multiselect: false, // allow to only select one category when filtering
    },
  },
  ...
]
```

This way, when admin selects, for example, "Luxury" option for "Apartment Type" filter, it will be replace with a more complex "or" filter.

### Custom SQL queries with `insecureRawSQL`

Rarely the set of Filters supported by AdminForth is not enough for your needs.
In this case you can use `insecureRawSQL` to write your own part of where clause.

However the vital concern that the SQL passed to DB as is, so if you substitute any user inputs it will not be escaped and can lead to SQL injection. To mitigate the issue we recommend using `sqlstring` package which will escape the inputs for you.

```bash
pnpm i sqlstring
```

Then you can use it like this:

```ts title='./resources/apartments.ts'
import sqlstring from 'sqlstring';
...

  beforeDatasourceRequest: async ({ query }: { query: any }) => {
    query.filters = query.filters.map((filter: any) => {
      // replace apartment_type filter with complex one
      if (filter.field === 'some_json_b_field') {
        return {
          // check if some_json_b_field->'$.some_field' is equal to filter.value
          insecureRawSQL: `some_json_b_field->>'$.some_field' = ${sqlstring.escape(filter.value)}`,
        }
      }

      return filter;
    });
    return { ok: true, error: "" };
  }
```

This example will allow to search for some nested field in JSONB column, however you can use any SQL query here.

### Custom Mongo queries with `insecureRawNoSQL`

For MongoDB data sources, you can inject a raw Mongo filter object via `insecureRawNoSQL`. This is useful when the built-in filters are not enough or you need dot-notation and operators not covered by AdminForth helpers.

Important: The object you provide is sent directly to MongoDB. Validate and sanitize any user inputs to prevent abuse of operators like `$where`, `$regex`, etc.

Example — filter by nested field using dot-notation:

```ts title='./resources/apartments.ts'
...
hooks: {
  list: {
    beforeDatasourceRequest: async ({ query, body }: { query: any, body: any }) => {
      // Add raw Mongo filter: meta.is_active must equal body.is_active
      query.filters.push({
        insecureRawNoSQL: { 'meta.is_active': body.is_active },
      });
      return { ok: true, error: '' };
    },
  },
},
```

You can combine it with other AdminForth filters using AND/OR:

```ts
import { Filters } from 'adminforth';

query.filters = [
  Filters.AND(
    { insecureRawNoSQL: { 'meta.is_active': true } },
    Filters.EQ('status', 'active'),
  )
];
```

Notes:
- `insecureRawNoSQL` is Mongo-only. For SQL databases, use `insecureRawSQL`.
- If both `field`/`operator`/`value` and `insecureRawNoSQL` are present in one filter object, validation will fail.
- `insecureRawSQL` is ignored by the Mongo connector.

## Virtual columns for editing.

Another usecase of `virtual` columns is to add new fields in edit and create view. In the [Getting started](/docs/tutorial/001-gettingStarted.md) we used this feature to add `password` field to the `adminuser` resource. 
Thing is that password itself can't be stored in the database, but instead their hash is stored. 
So we need to add `password` field to the `adminuser` resource and make it `virtual` so it will not be stored in the database.

```ts title="./resources/adminuser.ts"
...
resourceId: 'adminuser',
...
columns: [
  ...
  {
    name: 'password',
    virtual: true,  // field will not be persisted into db
    required: { create: true }, // make required only on create page
    editingNote: { edit: 'Leave empty to keep password unchanged' },
    minLength: 8,
    type: AdminForthDataTypes.STRING,
    showIn: { // to show field only on create and edit pages
      show: false,
      list: false,
      filter: false,
    },
    masked: true, // to show stars in input field
  }
  ...
]
 ```

Now to handle virtual `password` field we use hooks:
 

```ts title="./resources/adminuser.ts"
  hooks: {
    create: {
      beforeSave: async ({ record, adminUser, resource }: { record: any, adminUser: AdminUser, resource: AdminForthResource }) => {
        record.password_hash = await AdminForth.Utils.generatePasswordHash(record.password);
        return { ok: true };
      }
    },
    edit: {
      beforeSave: async ({ updates, adminUser, resource }: { updates: any, adminUser: AdminUser, resource: AdminForthResource }) => {
        if (updates.password) {
          updates.password_hash = await AdminForth.Utils.generatePasswordHash(updates.password);
        }
        return { ok: true }
      },
    },
  },
```

Hook still has access to the virtual field `updates.password`, and we use built-in AdminForth hasher to hash password and write it into
`password_hash` field which exists in database.

After hook is executed, `updates.password` will be removed from the record since it is virtual, so password itself will not be saved to the database.

---

## Hooks


Hooks are used to:

- modify the data before it is saved to the database on create or update
- execute something after data were saved or deleted
- change the query before fetching items from the database
- modify the fetched data before it is displayed in the list and show
- prevent the request to db depending on some condition (Better use [allowedActions](./05-limitingAccess.md) for this)

Every hook is executed when AdminForth frontend (Vue SPA) makes some internal API HTTP request to the backend. Every hook function is always executed only on backend side (Node.js) from the HTTP request handler and allows you to perform some actions before or after the actual request to datasource (database) is made. This is most flexible way to control flow and extend it with custom logic.

Every hook must return one of two objects:
1) If everything is fine and request flow should be continued hook should return `{ ok: true }`
2) If for some reason you need to interrupt request flow in hook you should return `{ ok: false, error: 'some error message for user' }`. This is
handy for access-related tasks, though most of such tasks should be solved with [allowedActions](./05-limitingAccess.md) and not hooks.

Every hook is array of async functions, so you can have multiple hooks for one event. 
For simplicity of course you can specify hook as scalar async function and not as array, but internally it will be anyway converted to array with single element just after app start. Plugins can push new own hooks in front of yours (using `unshift`) or after yours (using `push`). For example audit log plugin adds hooks for registration of all changes in the database.

Here we will consider possible flows one by one

### Performance notice

Every hook function is async, so you can use `await` inside it to perform some async operations like fetching data from another service or database, but please remember that while hook will not finish its execution, the request flow will be waiting for it. So every delay awaited in hook will delay the whole request. That is why we encourage you to use parallel async operations in hooks (like Promise.all) to make them faster. 

If multiple hooks are defined (e.g. plugin might add own hook to `list.beforeDatasourceRequest` after you will already add one in your config), then hooks will be executed one by one, and can't be parallelized. This ensures that different hooks will not interfere with each other, but also means that if you have bootleneck in one hook, all other hooks will wait for it and whole request will be slower. 

## Initial data for edit page flow

When user opens edit page, AdminForth makes a request to the backend to get the initial data for the form.

![Initial data for edit page flow](get_resource_data.png)

Practically you can use `show.afterDatasourceResponse` to modify or add some data before it is displayed on the edit page. In other words, at this stage you can enrich the data with some additional metadata which might be handy on edit page for custom Vue fields.

For example [upload plugin](/docs/tutorial/Plugins/upload/) uses this hook to generate signed preview URL so user can see existing uploaded file preview in form, and at the same time database stores only original file path which might be not accessible without presigned URL.

## Saving data on edit page

When user clicks the "Save" button on edit page, AdminForth makes a request to the backend to save the data.

![Saving data on edit page](image-27.png)

Practically you can use `hooks.edit.beforeSave` hook to modify the data or populate new fields before it is saved to the database.

> 👆 Note: according to diagram you should understand that interrupting flow from `hooks.edit.afterSave` does not prevent data modification in DB

## Saving data on create page

When user clicks the "Save" button from create page, AdminForth makes a request to the backend to create new record.

![Saving data on create page](image-26.png)

### Example: modify the created object before it is saved to the database

Let's add reference to `adminUser` when user creates a new apartment:

```ts title='./resources/apartments.ts'
// diff-add
import type { AdminUser } from  'adminforth';

{
  ...
  resourceId: 'aparts',
  columns: [
    ...
    {
      name: 'realtor_id',
      ...
//diff-add
      showIn: { // don't even show this field in create
//diff-add
        create: false,
//diff-add
        filter: false,
//diff-add
      },
      ...
    },
    ...
  ],
  ...
//diff-add
  hooks: {
//diff-add
    create: {
//diff-add
      beforeSave: async ({ adminUser, record }: { adminUser: AdminUser, record: any }) => {
//diff-add
        record.realtor_id = adminUser.dbUser.id;
//diff-add
        return { ok: true };
//diff-add
      }
//diff-add
    }
//diff-add
  }
}
```

In this way user who creates the apartment will be assigned as a realtor. Also user can't set other realtor then himself, even if he will make request using curl/devtools because hook will override the value.

## List page flow

When user opens the list page, AdminForth makes a request to the backend to get the list of items.

![List page flow](image-31.png)

### Example: limit access in list to user-related records

For example we can prevent the user to see Apartments created by other users. Superadmin user still can see all:

```ts title='./resources/apartments.ts'
{
  ...
  hooks: {
    list: {
      beforeDatasourceRequest: async ({
        query, adminUser, resource,
      }: {
        query: any; adminUser: AdminUser; resource: AdminForthResource;
      }) => {
        if (adminUser.dbUser.role === "superadmin") {
          return { ok: true };
        }

        // this function will skip existing realtor_id filter if it supplied already from UI or previous hook, and will add new one for realtor_id
        query.filterTools.replaceOrAddTopFilter(Filters.EQ('realtor_id', adminUser.dbUser.id))
       
        return { ok: true };
      },
    },
  },
}
```

This hook will prevent the user to see Apartments created by other users in list, however if user will be able to discover
the apartment id, he will be able to use show page to see the apartment details, that is why separate limiting for show page is required as well. Below we will discover how to limit access to show page.

### Modify record after it is returned from database

You can also change resource data after it was loaded.

For example, you can change the way columns value is displayed by changing the value itself:

```ts title='./resources/apartments.ts'
{
  ...
  hooks: {
    list: {
//diff-add
      afterDatasourceResponse: async ({ response }: { response: any }) => {
//diff-add
        response.forEach((r: any) => {
//diff-add
          r.price = `$${r.price}`;
//diff-add
        });
//diff-add
        return { ok: true, error: "" };
//diff-add
      },
    },
  },
}
```

Also you can use this hook to enrich the returned records list with some additional data fields which might be handy for custom Vue components defined in `components.list` or `components.show` for this resource. For example you can use [key-value adapter](/docs/tutorial/Adapters/key-value-adapters/) to get some global configuration values and add them to each record in the list:

```ts title='./resources/apartments.ts'

{
  ...
  hooks: {
    list: {
//diff-add
      afterDatasourceResponse: async ({ response }: { response: any }) => {
//diff-add
        response.forEach((r: any) => {  
          const taxRate = await kvAdapter.getValue('taxRate');
          r.priceWithTax = r.price * (1 + taxRate);
        });
        return { ok: true, error: "" };
      },
    },
  },
}
```

:::tip Name enriched fields after the virtual column
When you enrich records with extra fields for display, declare a matching [virtual column](./03-virtualColumns.md) and use **the same name** for the field you add in the hook (e.g. add a `priceWithTax` virtual column and write `r.priceWithTax` in the hook). 

Reusing the same name keeps the enriched value tied to a column the rest of AdminForth knows about. In particular, the [Agent plugin](/docs/tutorial/Plugins/agent/) selects records by column name when answering questions — if the hook writes to a different field than the virtual column, the agent selects the (empty) virtual column and never sees your enriched value.
:::

### Dropdown list of foreignResource

By default if there is `foreignResource` like we use for demo on `realtor_id` column, the filter will suggest a
select dropdown with list of all Realtors. 

This might bring us a leak where explorer will get id's of other users in the system which might be not desired 

Let's limit it:

```ts title='./resources/apartments.ts'
{
  ...

  foreignResource: { 
    
    ...

    hooks: {
      dropdownList: {
        beforeDatasourceRequest: async ({ adminUser, query }: { adminUser: AdminUser, query: any }) => {
          if (adminUser.dbUser.role !== "superadmin") {
            query.filtersTools.replaceOrAddTopFilter(Filters.EQ("id", adminUser.dbUser.id));
          };
          return {
            "ok": true,
          };
        }
      },
    },
  }
}
```

> ☝️☝️☝️ This hooks should be written only inside column. If you'll add it in resource hooks - it won't work

In our case we limit the dropdown list to show only the current user, however you can use same sample to list only objects who are related to the current user in case if you will have relation configurations which require to show related objects which belongs to the current user.

Flow diagram for dropdown list:

![Flow diagram for dropdown list](image-30.png)

## Show page flow

When user opens the show page, AdminForth makes a request to the backend to get the item. This request ia absolutely the same as one for edit initial data, because naturally for most of cases data for show page are the same as initial data for edit page.

However if you still need to distinguish between these two cases you can use `query.source` parameter in hook (we do not mentioned it in diagram for simplicity and rare demand).

Here is show request flow:

![Here is show request](image-29.png)

### Example show limiting:

```ts title='./resources/apartments.ts'
{
  ...
  hooks: {
    show: {
      afterDatasourceResponse: async ({
        adminUser, response,
      }: {
        adminUser: AdminUser; response: any;
      }) => {
        if (adminUser.dbUser.role === "superadmin") {
          return { ok: true, response };
        }
        if (response[0].realtor_id.pk !== adminUser.dbUser.id) {
          return { ok: false, error: "You are not allowed to see this record" };
        }
        return { ok: true, response };
      }
    }
  }
}
```

> 👆 Please note that we use `response[0].realtor_id.pk` because this field has `foreignResource` in column option is set
> Otherwise you would use  just `response[0].realtor_id`

Important notice: Using hook to filter out list of items for list page or list of items for dropdown makes a lot of sense because gives ability to change filter of database request. However using hook for show page is not reasonable:

First of all it semantically better aligns with using `allowedActions` interface. For this particular case you must use [allowedActions.show](./05-limitingAccess.md#disable-showing-the-resource-based-on-owner)

Secondly limiting access from this hook will not prevent executing other hooks (e.g. `beforeDatasourceRequest`), when allowedActions check
always performed before any hooks and any database requests. 

## All hooks

Check all hooks in the [API reference](/docs/api/Back/interfaces/AdminForthResource).

---

## Limiting actions access


As you might have noticed in diagrams from [adminforth hooks](./04-hooks.md) section of this tutorial, AdminForth checks `options.allowedActions` before executing any action. In this section we will show real-code examples of how to limit access to actions based on user role or record values.

Before we start it is worth to mention that callbacks or scalars defined in `allowedActions` are called/parsed not only before actual request but also before displaying buttons in the UI. So first time, when frontend loads any page of resource, it "calls" `allowedActions` to understand whether user has access to each function, and e.g. if it says that user can't delete record, AdminForth will not show delete icon in the UI:

![Resource any page request](image-21.png)

As you can see allowedAction callbacks are called in parallel in async manner. However it is important to keep them fast and not to make any slow operations in them, to keep UI responsive.

## Statically disable some action on resource

You can use `options.allowedActions` on resource to limit access to the resource actions (list, show, create, edit, delete).

If you want to disable deletion of the resource records for all users:

```ts title="./resources/adminuser.ts"
{
  ...
  resourceId: 'adminuser',
  ...
//diff-add
  options: {
//diff-add
    allowedActions: {
//diff-add
      delete: false
//diff-add
    }
//diff-add
  }
}
```

## Disable full access to resource based on logged in user record or role

If you want to disable all actions to the resource for all users except users with role `superadmin`:

```ts title="./resources/adminuser.ts"
{
  ...
  resourceId: 'adminuser',
  ...
//diff-add
  options: {
//diff-add
    allowedActions: {
//diff-add
      all: async ({ adminUser }: { adminUser: AdminUser }): Promise<boolean> => {
//diff-add
        return adminUser.dbUser.role === 'superadmin';
//diff-add
      }
//diff-add
    }
//diff-add
  }
}
```

> ☝️ This will not hide link to the resource in the menu, you should separately use [menuItem.visible](/docs/tutorial/Customization/menuConfiguration/#visibility-of-menu-items) to hide it.

> ☝️ instead of reading role from user you can check permission using complex ACL/RBAC models with permissions stored in the database.
> However we recommend you to keep in mind that allowedActions callback is called on every request related to resource, so it should be fast.
> So try to minimize requests to database as much as possible.

## Disable only some action based on logged in user record or role

If you want to disable deletion of apartments for all users apart from users with role `superadmin`:

```ts title='./resources/apartments.ts'
//diff-add
import type { AdminUser } from  'adminforth';

{
  ...
  resourceId: 'aparts',
  ...
  options: {
//diff-add
    allowedActions: {
//diff-add
      delete: async ({ adminUser }: { adminUser: AdminUser }): Promise<boolean> => {
//diff-add
        return adminUser.dbUser.role === 'superadmin';
//diff-add
      }
//diff-add
    }
    ...
  }
}
```

### Reuse the same callback for multiple actions

Let's disable creating and editing of new users for all users apart from users with role `superadmin`, and at the same time disable deletion for all users:

```ts title="./resources/adminuser.ts"
//diff-add
import type { AdminUser } from  'adminforth';

//diff-add
async function allowedForSuperAdmin({ adminUser }: { adminUser: AdminUser }): Promise<boolean> {
//diff-add
  return adminUser.dbUser.role === 'superadmin';
//diff-add
}

...

{
  ...
  resourceId: 'adminuser',
  ...
  options: {
    allowedActions: {
//diff-add
      create: allowedForSuperAdmin,
//diff-add
      edit: allowedForSuperAdmin,
      delete: false
    }
    ...
  }
}
```

## Customizing the access control based on resource values

In more advanced cases you might need to check access based on record value. 
Generally it happens in multi-tenant applications where you need to check if user has access to the record based on some field value.

### Disable editing of the resource based on owner

For example, allow to edit apartments only if user is a realtor of the apartment (defined as realtor_id), otherwise return error
"You are not assigned to this apartment and can't edit it":

```ts title="./resources/apartments.ts"
import type { AdminUser } from  'adminforth';
import { ActionCheckSource } from  'adminforth';

async function canModifyApart({ adminUser, source, meta }: { adminUser: AdminUser, meta: any, source: ActionCheckSource }): Promise<boolean | string> {
  if (source === ActionCheckSource.DisplayButtons) {
    // if check is done for displaying button - we show button to everyone
    return true; 
  }
  const { oldRecord, newRecord } = meta;
  if (oldRecord.realtor_id !== adminUser.dbUser.id) {
    return "You are not assigned to this apartment and can't edit it";
  }
  if (newRecord.realtor_id !== oldRecord.realtor_id) {
    return "You can't change the owner of the apartment";
  }
  return true;
}

{
  ...
  resourceId: 'aparts',
  ...
  options: {
    allowedActions: {
      edit: canModifyApart,
    }
    ...
  }
}
```

### Disable deletion of the resource based on owner

If we need to allow only owner to delete the apartment:

```ts title="./resources/apartments.ts"
import type { AdminUser } from  'adminforth';

async function canDeleteApart({ adminUser, meta }: { adminUser: AdminUser, meta: any }): Promise<boolean | string> {
  const { record } = meta;
  if (record.realtor_id !== adminUser.dbUser.id) {
    return "You are not assigned to this apartment and can't delete it";
  }
  return true;
}

{
  ...
  resourceId: 'aparts',
  ...
  options: {
    allowedActions: {
      delete: canDeleteApart,
    }
    ...
  }
}
```

### Disable showing the resource based on owner

This one might sound pretty tricky. If Update and Delete callbacks in allowedActions were called with `meta` object which already had a records values,
here we need to fetch the record from the database to check if user is the owner of the record.
This is done because of architecture of AdminForth: `show` callback is called before action `list` or `show` hooks and requests.

```ts title="./resources/apartments.ts"
 allowedActions: {
    ...
    show: async ({adminUser, meta, source, adminforth}: any) => {
      if (source === 'showRequest' || source === 'editLoadRequest') {
        const record = await adminforth.resource('aparts').get(Filters.EQ('id', meta.pk));
        return record.realtor_id === adminUser.dbUser.id;
      }
      return true;
    },
 }
```

Please note that show callback is called not only when user visits show page (source will be `'showRequest'` during this check) but also
when user visits edit page (source will be `'editLoadRequest'`).

---

## Custom pages


Most Admin Panels should have some Dashboards or custom pages. 

In AdminForth creation of custom page is very simple.

Create a Vue component in the `custom` directory of your project, e.g. `Dashboard.vue`:

```html title="./custom/Dashboard.vue"
<template>
  
  
    
      
        
          {{ data.totalAparts }}
          {{  $t('Apartment last 7 days | Apartments last 7 days', data.totalAparts) }}
        
        <BarChart
          :data="apartsCountsByDaysChart"
          :series="[{
            name: $t('Added apartments'),
            fieldName: 'count',
            color: COLORS[0],
          }]"
          :options="{
            chart: {
              height: 180,
            },
            yaxis: {
              stepSize: 1,
              labels: { show: false },
            },
            grid: {
              show: false,
            }
          }"
        />
      

      
        
          {{ $t('Top countries') }}
        

        
        <PieChart
          :data="topCountries"
          :options="{
            chart: { type: 'pie', height: 300 },
            legend: {
              show: false,
            },
            dataLabels: {
              enabled: true,
              formatter: function (value, o) {
                const countryISO = o.w.config.labels[o.seriesIndex];
                return countryISO;
              }
            },
          }"
        />
      
      

      
        
          <dl>
            <dt class="text-base font-normal text-gray-500 dark:text-gray-400 pb-1">
              {{ $t('Listed price') }}
            </dt>
            <dd class="leading-none text-xl font-bold" :style="{color:COLORS[0]}">
              {{
              new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD', maximumFractionDigits: 0, }).format(
                data.totalListedPrice,
              ) }}
            </dd>
          </dl>
          <dl>
            <dt class="text-base font-normal text-gray-500 dark:text-gray-400 pb-1">
              {{ $t('Unlisted price') }}</dt>
            <dd class="leading-none text-xl font-bold" :style="{color:COLORS[1]}">
            {{
              new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD', maximumFractionDigits: 0, }).format(
                data.totalUnlistedPrice,
              ) }}
            </dd>
          </dl>
        

        <BarChart
          :data="listedVsUnlistedCountByDays"
          :series="[{
            name: $t('Listed Count'),
            fieldName: 'listed',
            color: COLORS[0],
          },
          {
            name: $t('Unlisted Count'),
            fieldName: 'unlisted',
            color: COLORS[1],
          }]"
          :options="{
            chart: {
              height: 600,
            },
            xaxis: {
              labels: { show: true },
              stepSize: 1,  // since count is integer, otherwise axis will be float
            },
            yaxis: {
              labels: { show: true }
            },
            grid: {
              show: true,
            },
            plotOptions: {
              bar: { 
                horizontal: true, // by default bars are vertical
              }
            },
          }"
        />

      

      
        {{ $t('Apartment by rooms') }}
        
        <PieChart
          :data="apartsCountsByRooms"
          :options="{
            chart: { type: 'donut', height: 300 },
            plotOptions: {
              pie: {
                donut: {
                  labels: {
                    total: {
                      show: true,
                      label: $t('Total square'),
                      formatter: () => `${data.totalSquareMeters.toFixed(0)} m²`,
                    },
                  },
                },
              },
            },
          }"
        />
      
      

      
        {{ $t('Unlisted vs Listed price' ) }}

        <AreaChart 
          :data="listedVsUnlistedPriceByDays"
          :series="[{
            name: $t('Listed'),
            fieldName: 'listedPrice',
            color: COLORS[0],
          },
          {
            name: $t('Unlisted'),
            fieldName: 'unlistedPrice',
            color: COLORS[1],
          }]"
          :options="{
            chart: {
              height: 320,
            },
            yaxis: {
              labels: {
                formatter: function (value) {
                  return '$' + value;
                }
              }
            },
          }"
        />
      

    
  
</template>

<script setup lang="ts">
import { ref, type Ref, onMounted, computed } from 'vue';
import dayjs from 'dayjs';
import { callApi } from '@/utils';
import { useI18n } from 'vue-i18n';
import { useAdminforth } from '@/adminforth';
import { AreaChart, BarChart, PieChart } from '@/afcl';

const data: Ref<{listedVsUnlistedPriceByDays: any, listedVsUnlistedByDays: any, 
  apartsByDays: any, apartsCountsByRooms: any, topCountries: any, totalAparts: any} | null> = ref(null);

const { t } = useI18n();

const { alert } = useAdminforth();

const COLORS = ["#4E79A7", "#F28E2B", "#E15759", "#76B7B2", "#59A14F"]

const apartsCountsByDaysChart = computed(() => {
  return data.value.apartsByDays?.reverse().map(
    (item) => ({
      x: dayjs(item.day).format('DD MMM'),
      count: item.count
    })
  );
});

const listedVsUnlistedPriceByDays = computed(() => {
  return data.value.listedVsUnlistedPriceByDays?.map(
    (item) => ({
      x: dayjs(item.day).format('DD MMM'),
      listedPrice: item.listedPrice.toFixed(2),
      unlistedPrice: item.unlistedPrice.toFixed(2),
    })
  );
});

const listedVsUnlistedCountByDays = computed(() => {
  return data.value.listedVsUnlistedByDays?.map(
    (item) => ({
      x: dayjs(item.day).format('DD MMM'),
      listed: item.listed,
      unlisted: item.unlisted,
    })
  );
});

const apartsCountsByRooms = computed(() => {
  return data.value.apartsCountsByRooms?.map(
    (item, i) => ({
      label: t(`{number_of_rooms} rooms`, { number_of_rooms: item.number_of_rooms }),
      amount: item.count,
      color: COLORS[i],
    })
  );
});

const topCountries = computed(() => {
  return data.value.topCountries?.map(
    (item, i) => ({
      label: item.country,
      amount: item.count,
      color: COLORS[i],
    })
  );
});

onMounted(async () => {
  // Fetch data from the API
  try {
    data.value = await callApi({path: '/api/dashboard/', method: 'GET'});
  } catch (error) {
    alert({
      message: t(`Error fetching data: {message}`, { message: error.message }),
      variant: 'danger',
    });
  }
})
</script>
```

> ☝️ use https://flowbite.com/ to get pre-designed tailwind design blocks for your pages

Now let's add this page to the AdminForth menu and make it homepage instead of Apartments page:

```ts title="/index.ts"
menu: [
//diff-add
    {
//diff-add
      label: 'Dashboard',
//diff-add
      path: '/overview',
//diff-add
      homepage: true,
//diff-add
      icon: 'flowbite:chart-pie-solid',
//diff-add
      component: '@@/Dashboard.vue',
//diff-add
    },
    {
      label: 'Core',
      icon: 'flowbite:brain-solid',
      open: true,
      children: [
        {
//diff-remove
          homepage: true,  
          label: 'Apartments',
          icon: 'flowbite:home-solid',
          resourceId: 'aparts',
        },
      ]
    },
```

> ☝️ To find icon go to https://icon-sets.iconify.design/flowbite/?query=chart, click on icon you like and copy name:
![Iconify icon select](image-icon-select.png)

You might notice that in mounted hook page fetches custom endpoint '/api/dashboard-stats'. 
Now we have to define this endpoint in the backend to make our page work:

## Defining custom API for own page and components

Open `api.ts` file and add the following code *BEFORE* `admin.express.authorize` !

```ts title="/api.ts"

import type { IAdminUserExpressRequest } from 'adminforth';
import express from 'express';
import * as z from 'zod';

....

app.get(`${ADMIN_BASE_URL}/api/dashboard/`,
  admin.express.withSchema(
    {
      description: 'Returns aggregated apartment metrics for the custom dashboard page.',
      response: z.object({
        apartsByDays: z.array(z.record(z.string(), z.unknown())),
        totalAparts: z.number(),
      }).catchall(z.unknown()),
    },
    admin.express.authorize(
      async (req:IAdminUserExpressRequest, res: express.Response) => {
      const days = req.body.days || 7;
      const apartsByDays = admin.resource('aparts').dataConnector.client.prepare(
        `SELECT 
          strftime('%Y-%m-%d', created_at) as day, 
          COUNT(*) as count 
        FROM apartments 
        GROUP BY day 
        ORDER BY day DESC
        LIMIT ?;
        `
      ).all(days);

      const totalAparts = apartsByDays.reduce((acc: number, { count }: { count:number }) => acc + count, 0);

      // add listed, unlisted, listedPrice, unlistedPrice
      const listedVsUnlistedByDays = admin.resource('aparts').dataConnector.client.prepare(
        `SELECT 
          strftime('%Y-%m-%d', created_at) as day, 
          SUM(listed) as listed, 
          COUNT(*) - SUM(listed) as unlisted,
          SUM(listed * price) as listedPrice,
          SUM((1 - listed) * price) as unlistedPrice
        FROM apartments
        GROUP BY day
        ORDER BY day DESC
        LIMIT ?;
        `
      ).all(days);

      const apartsCountsByRooms = await admin.resource('aparts').dataConnector.client.prepare(
        `SELECT 
          number_of_rooms, 
          COUNT(*) as count 
        FROM apartments 
        GROUP BY number_of_rooms 
        ORDER BY number_of_rooms;
        `
      ).all();

      const topCountries = await admin.resource('aparts').dataConnector.client.prepare(
        `SELECT 
          country, 
          COUNT(*) as count 
        FROM apartments 
        GROUP BY country 
        ORDER BY count DESC
        LIMIT 4;
        `
      ).all();

      const totalSquare = admin.resource('aparts').dataConnector.client.prepare(
        `SELECT 
          SUM(square_meter) as totalSquare 
        FROM apartments;
        `
      ).get();

      const listedVsUnlistedPriceByDays = admin.resource('aparts').dataConnector.client.prepare(
        `SELECT 
          strftime('%Y-%m-%d', created_at) as day, 
          SUM(listed * price) as listedPrice,
          SUM((1 - listed) * price) as unlistedPrice
        FROM apartments
        GROUP BY day
        ORDER BY day DESC
        LIMIT ?;
        `
      ).all(days);
        
      const totalListedPrice = Math.round(listedVsUnlistedByDays.reduce((
        acc: number, { listedPrice }: { listedPrice:number }
      ) => acc + listedPrice, 0));
      const totalUnlistedPrice = Math.round(listedVsUnlistedByDays.reduce((
        acc: number, { unlistedPrice }: { unlistedPrice:number } 
      ) => acc + unlistedPrice, 0));

      res.json({ 
        apartsByDays,
        totalAparts,
        listedVsUnlistedByDays,
        apartsCountsByRooms,
        topCountries,
        totalSquareMeters: totalSquare.totalSquare,
        totalListedPrice,
        totalUnlistedPrice,
        listedVsUnlistedPriceByDays,
      });
      }
    )
  )
);
```

Install and import Zod before using this pattern: `pnpm add zod` or `npm install zod`, then `import * as z from 'zod';`. `admin.express.withSchema(...)` will convert the Zod schema to OpenAPI for you.

If you created the app with the CLI defaults, start it and open `http://localhost:3500/api-docs` in your browser to see this custom method in the generated API docs.

> ☝️ Please note that we are using `admin.express.authorize` middleware to check if the user is logged in. If you want to make this endpoint public, you can remove this middleware. If user is not logged in, the request will return 401 Unauthorized status code, and protect our statistics from leak.

> ☝️ Moreover if you wrap your endpoint with `admin.express.authorize` middleware, you can access `req.adminUser` object in your endpoint to get the current user information.

> ☝️ Using `admin.express.withSchema(...)` is the recommended approach because it adds your route to `/api/v1/openapi.json` and `/api-docs` (Solar), performs early runtime validation for API calls, and gives agent plugins a machine-readable API contract they can use in skills. It is still optional though, and you can register plain Express routes without `withSchema(...)` if you prefer.

> ☝️ If you do not want to use Zod, you can pass a plain JSON Schema (or convert it from e.g. typebox) object instead of a Zod schema. For example, this Zod response schema:
>
> ```ts
> response: z.object({
>   apartsByDays: z.array(z.record(z.string(), z.unknown())),
>   totalAparts: z.number(),
> }).catchall(z.unknown()),
> ```
>
> can be written as pure JSON Schema:
>
> ```ts
> response: {
>   type: 'object',
>   properties: {
>     apartsByDays: {
>       type: 'array',
>       items: {
>         type: 'object',
>         additionalProperties: true,
>       },
>     },
>     totalAparts: {
>       type: 'number',
>     },
>   },
>   required: ['apartsByDays', 'totalAparts'],
>   additionalProperties: true,
> },
> ```

> ☝️ AdminForth does provide own data access facility called [DATA API](./11-dataApi.md) to access data in database. But it is very basic and mostly covers only simple CRUD operations. For complex queries like in this example, it is better to use your own data access code with any ORM. You are free to use any ORM like Prisma, TypeORM, Sequelize, mongoose, or just use raw SQL queries against your tables.

Demo:

![alt text](dashDemo.gif)

## Custom pages without menu item

Sometimes you might need to add custom page but don't want to add it to the menu.

In this case you can add custom page using `customization.customPages` option:

```ts title="/index.ts"
new AdminForth({
  // ...
  customization: {
    customPages: [
      {
        path: '/setup2fa', // route path
        component: { 
          file: '@@/pages/TwoFactorsSetup.vue',
          meta: { 
            title: 'Setup 2FA',  // meta title for this page
              //diff-add
            sidebarAndHeader: 'none'  // Layout options: 'none' (no sidebar/header), 'default' (full layout), 'preferIconOnly' (collapsed sidebar)
          }
        }
      }
    ]
  }
})
```

> 💡 **Layout Options Explained:**
> - `'none'`: Renders the page without AdminForth's default sidebar and header layout - perfect for standalone pages like setup wizards, or public (logged-out) pages (Terms-of-Service/PP/Contact form etc)
> - `'default'`: Uses the full AdminForth layout with sidebar and header - ideal for pages that should feel integrated with the admin panel
> - `'preferIconOnly'`: Uses the default layout but starts with a collapsed sidebar (even if icon-only sidebar is disabled in your configuration) - great for pages that need more screen space or already have some navigation

This will register custom page with path `/setup2fa` and will not include it in the menu. 

You can navigate user to this page using any router link, e.g.:

```html
<template>
  <Link to="/setup2fa">Setup 2FA</Link>
</template>
```

Add to your `<script setup>` section:

```ts
import { Link } from '@/afcl';
```

If you set `sidebarAndHeader: 'none'` in the `meta` object, it will not include default layout like sidebar and header, so you can create your own layout for this page. 

### Disable redirects to login page (Public pages)

Any route which has sidebar and header (e.g. default CRUD pages or menu item with `component`) uses internal AdminForth REST API to fetch menu items and user information, so it passes authentication check and if authentication cookie is not provided or has expired JWT user gets redirected to the login page.

In case if you set `sidebarAndHeader: 'none'`, it will not call these APIs so user will not be automatically redirected to the login page in case of expired or not-provided authentication cookie. That feature allows you to implement public pages without authentication, e.g. Terms of Service, Privacy Policy and many others. In case if you need to check if user is logged in just call any custom API which has `admin.express.authorize` middleware. Obviously for public pages if they use any APIs you should create API endpoint WITHOUT `admin.express.authorize` middleware.

> Please note that AdminForth uses classic SPA Vue app, so even public pages will be rendered by JavaScript in the browser and not on the server side. If your public page should be indexed by search engines, you should use some SSR framework like Nuxt.js to create such pages. At the same time public pages can still be usefull if you don't focus on old-fashioned search engines (modern search engines can index SPA pages as well) or if indexing is not important for such pages at all (e.g. Terms of Service, Privacy Policy, Contact Us and many others).

### Passing meta attributes to the page

You can add custom meta attributes to the page by passing `meta` object to the page:

```ts title="/index.ts"

    customPages: [
      {
        path: '/setup2fa', // route path
        component: { 
          file: '@@/pages/TwoFactorsSetup.vue',
          meta: { 
            title: 'Setup 2FA',  // meta title for this page
            sidebarAndHeader: 'none',   // don't include default layout like menu/header
    //diff-add
            myAttribute: 'a1'
          }
        }
      }
    ]
```

To access passed meta attributes in your page, you can use `useRoute` hook:

```ts
import { useRoute } from 'vue-router';

const route = useRoute();

console.log(route.meta.myAttribute);  // a1
```

## Settings View 

If you want to add a Settings section to your project:

```ts title='./index.ts' 
export const admin = new AdminForth({
  baseUrl : ADMIN_BASE_URL,
  auth: {
    //diff-add
    userMenuSettingsPages: [
      //diff-add
      {
        //diff-add
        pageLabel: 'Profile settings',
        //diff-add
        component: '@@/ProfileSettings.vue',
        //diff-add
        // Specify a slug if you want a custom URL path.
        //diff-add
        // For example, without a slug, the URL will be:
        //diff-add
        //   example.com/settings/profile-settings
        //diff-add
        // With a custom slug, you could have:
        //diff-add
        //   example.com/settings/users-settings
        //diff-add
        slug: "users-settings",
        //diff-add
        icon:"flowbite:user-solid"
        //diff-add
      },
      //diff-add
      {
        //diff-add
        pageLabel: 'Security',
        //diff-add
        component: "@@/MySecrets.vue",
        //diff-add
        icon: "flowbite:lock-solid"
        //diff-add
      }
      //diff-add
    ],
  }
});
```

After this, you will have a custom Settings section in the users menu:

![alt text](SettingsView-1.png)

## Explicit register of components

There might be rare cases, when you need to register component explicitly and then re-use it somewhere else:

```ts title='./index.ts'
  ...

  customization: {
      brandName: "dev-demo",
      title: "dev-demo",
      favicon: '@@/assets/favicon.png',
      brandLogo: '@@/assets/logo.svg',

  ...

  },
  //diff-add
  componentsToExplicitRegister: [
    //diff-add
    { 
      //diff-add
      file: '@@/JobCustomComponent.vue',
      //diff-add
      meta: {
        //diff-add
        label: 'Job Custom Component',
        //diff-add
      }
      //diff-add
    }
    //diff-add
  ],

```

and then you can re-use this component like:

```html title='CustomVueComponent.vue'
  //diff-add
  import { getCustomComponent } from '@/utils';

  ...
    //diff-add
    <component 
    //diff-add
      :is="getCustomComponent('@@/JobCustomComponent.vue')" 
      //diff-add
    />

```

---

## Alerts and confirmations


When you are writing custom components or pages you might need to show alerts or confirmations to the user.

For example if fetch to the API fails you might want to show an error message to the user.

AdminForth has very simple [frontend API](/docs/api/FrontendAPI/interfaces/FrontendAPIInterface) for this.

## Alerts

To show an alert use `adminforth.alert` method:

```ts
import { useAdminforth } from '@/adminforth';

const { alert } = useAdminforth();

alert({message: 'Hello world', variant: 'success'})
```

Next variants are supported:

* `success`
* `danger`
* `warning`
* `info`

### Making alert responsive
You can pass buttons in the alert method and receive a response like:

```ts
adminforth.alert({
    message: 'Do you want to receive news?', 
    variant: 'info', 
    buttons: [
        { value: "yes", label: "Yes" }, 
        { value: "no", label: "No" }
    ],
    timeout: 'unlimited'
}).then((value) => {
    switch (value) {
        case "yes":
            console.log('User selected "Yes"');
            break;
        case "no":
            console.log('User selected "No"');
            break;
        default:
            console.log("User closed alert");
            break;
    }
});

```

Here's how the alert looks now:

![alt text](<Alerts and confirmations3.png>)

## Confirmations

To show a confirmation dialog use `adminforth.confirm` method:

```ts
import { useAdminforth } from '@/adminforth';

const { confirm } = useAdminforth();

const isConfirmed = await confirm({message: 'Are you sure?', yes: 'Yes', no: 'No'})
```

## Usage example

Create a Vue component in the custom directory of your project, e.g. `Alerts.vue`:

```html title="./custom/Alerts.vue"
<template>
    
        <Button @click="successAlert($t('Example success alert'))" class="bg-green-700 hover:bg-green-800 focus:ring-green-300 dark:bg-green-600 dark:hover:bg-green-700 dark:focus:ring-green-800" >
            {{$t('Call success alert')}}
        </Button>

        <Button @click="warningAlert($t('Example danger alert'))" class="bg-orange-500 hover:bg-orange-400 focus:ring-orange-100 dark:bg-orange-600 dark:hover:bg-orange-700 dark:focus:ring-orange-900" >
            {{$t('Call warning alert')}}
        </Button>

        <Button @click="doConfirm" class="bg-red-700 hover:bg-red-800 focus:ring-red-300 dark:bg-red-600 dark:hover:bg-red-700 dark:focus:ring-red-900" >
            {{$t('Call confirm dialog')}}
        </Button>
    
</template>
<script setup>
import { useAdminforth } from '@/adminforth';
import { Button } from '@/afcl'
import { useI18n } from 'vue-i18n';

const { t } = useI18n();

const { alert, confirm } = useAdminforth();

function successAlert(message) {
    alert({message, variant: 'success'})
};

function warningAlert(message) {
    alert({message, variant: 'warning'})
};

async function doConfirm() {
    const isConfirmed = await confirm({message: t('Are you sure?'), yes: t('Yes'), no: t('No')})
    if (isConfirmed){
        alert({message: t('Confirmed'), variant: 'success'})
    } else {
        alert({message: t('Not confirmed'), variant: 'warning'})
    }
}
</script>
```

Now let's add this page to the AdminForth menu:

```html title="/index.ts"
menu: [
//diff-add
{
//diff-add
    label: 'Alerts',
//diff-add
    icon: 'flowbite:bell-active-alt-solid',
//diff-add
    component: '@@/Alerts.vue',
//diff-add
    path: '/alerts'
//diff-add
}
```

Here is how alert looks:
![alt text](image-12.png)

And here is how confirmation looks:
![alt text](<Alerts and confirmations2.png>)

## Announcement

You can notify users of important information by displaying an announcement badge in side bar:

```ts title="/index.ts"

  customization: {
//diff-add
    announcementBadge: (adminUser: AdminUser) => {
//diff-add
      return { 
//diff-add
        html: '⭐ Star us on GitHub to support a project!',
//diff-add
        closable: true,
//diff-add
        title: 'Support us for free',
//diff-add
      }
//diff-add
    }
  },
```

Here's what the announcement will look like:
![alt text](image-11.png)

## Disable "There are unsaved changed" popup for resource

By default, when you want to leave create/edit pages with usaved changes, there will be shown an confirmation popup. If you don't like this behaviour, you can disable it for resource:

```ts title='./resources/cusom_resource.ts'
    ...

    options: {
      listPageSize: 12,
      //diff-add
      dontShowWarningAboutUnsavedChanges: true,
        ...
    }
    ...

```

---

## Page Injections


In addition to ability to create custom pages and overwrite how fields are rendered, you can also inject custom components in standard AdminForth page. 

For example let's add a custom pie chart to the `list` page of the `aparts` resource. Pie chart will show the distribution of the rooms count and more over will allow to filter the list by the rooms count.

```ts title="./resources/apartments.ts"
{
  resourceId: 'aparts',
  ...
//diff-add
  options: {
//diff-add
    pageInjections: {
//diff-add
      list: {
//diff-add
        afterBreadcrumbs: '@@/ApartsPie.vue',
//diff-add
      }
//diff-add
    }   
//diff-add
  }
}
```

Now create file `ApartsPie.vue` in the `custom` folder of your project:

```html title="./custom/ApartsPie.vue"
<template>
    
      <PieChart
        v-if="data.length"
        :data="rooms" 
        :options="{
          chart: {
            height: 250,
            events: {
              dataPointSelection: function (event, chartContext, config) {
                if (config.selectedDataPoints[0].length) {
                  const selectedRoomsCount = data[config.dataPointIndex].rooms;
                  adminforth.list.updateFilter({field: 'number_of_rooms', operator: 'eq', value: selectedRoomsCount});
                } else {
                  // clear filter
                  adminforth.list.updateFilter({field: 'number_of_rooms', value: undefined});
                }
              }
            }
          },
          dataLabels: {
            enabled: true,
          },
          plotOptions: {
            pie: {
              dataLabels: {
                offset: -10,
                minAngleToShowLabel: 10,
              },
              expandOnClick: true,
            },
          },
        }"
      />
      Loading...
    
  </template>
  
  
  <script setup lang="ts">
  import { onMounted, ref, Ref, computed } from 'vue';
  import { PieChart } from '@/afcl';
  import { callApi } from '@/utils';
  import { useAdminforth } from '@/adminforth';
  
  
  const data: Ref<any[]> = ref([]);

  const { alert } = useAdminforth(); 

  const COLORS = ["#4E79A7", "#F28E2B", "#E15759", "#76B7B2", "#59A14F"]
  const rooms = computed(() => {
    return data.value?.map(
      (item, i) => ({
        label: item.rooms + ' rooms',
        amount: item.percentage,
        color: COLORS[i],
      })
    );
  });

  onMounted(async () => {
    try {
    data.value = await callApi({ path: '/api/aparts-by-room-percentages', method: 'GET' });
    } catch (error) {
      alert({
        message: `Error fetching data: ${error.message}`,
        variant: 'danger',
        timeout: 'unlimited'
      });
      return;
    }
  })
  
  </script>
```

Also we have to add an Api to get percentages:

```ts title="/api.ts"
import type { IAdminUserExpressRequest } from 'adminforth';
import express from 'express';
import * as z from 'zod';

....

  app.get(`${ADMIN_BASE_URL}/api/aparts-by-room-percentages/`,
    admin.express.withSchema(
      {
        description: 'Returns apartment room-count percentages for the page injection chart.',
        response: z.array(z.object({
          rooms: z.number(),
          percentage: z.number(),
        })),
      },
      admin.express.authorize(
        async (req: IAdminUserExpressRequest, res: express.Response) => {
        const roomPercentages = await admin.resource('aparts').dataConnector.client.prepare(
          `SELECT 
            number_of_rooms, 
            COUNT(*) as count 
          FROM apartments 
          GROUP BY number_of_rooms
          ORDER BY number_of_rooms;
          `
        ).all()
        

        const totalAparts = roomPercentages.reduce((acc, { count }) => acc + count, 0);

        res.json(
          roomPercentages.map(
            ({ number_of_rooms, count }) => ({
              rooms: number_of_rooms,
              percentage: Math.round(count / totalAparts * 100),
            })
          )
        );
        }
      )
    )
  );
```

Install and import Zod before using this pattern: `pnpm add zod` or `npm install zod`, then `import * as z from 'zod';`. `admin.express.withSchema(...)` will convert the Zod schema to OpenAPI for you.

> ☝️ Please note that we are using [Frontend API](/docs/api/FrontendAPI/interfaces/FrontendAPIInterface/) `adminforth.list.updateFilter({field: 'number_of_rooms', operator: 'eq', value: selectedRoomsCount});` to set filter when we are located on apartments list page

> ☝️ The outer `admin.express.withSchema(...)` wrapper makes this custom Express route appear in `/api/v1/openapi.json` and `/api-docs`.

Here is how it looks:
![alt text](<Page Injections.png>)

## Login page customization

You can also inject custom components to the login page. 

`loginPageInjections.underInputs` and `loginPageInjections.panelHeader` allows to add one or more panels under or over the login form inputs:

![login Page Injections underInputs](<loginPageInjection.png>)

For example:

```ts title="/index.ts"

new AdminForth({
  ...
  customization: {
    loginPageInjections: {
      underInputs: '@@/CustomLoginFooter.vue',
    }
    ...
  }

  ...
})
```

Now create file `CustomLoginFooter.vue` in the `custom` folder of your project:

```html title="./custom/CustomLoginFooter.vue"
<template>
  
    {{$t('By logging in, you agree to our')}} {{$t('Terms of Service')}} {{$t('and')}} {{$t('Privacy Policy')}}
  
</template>
```

Also you can add `panelHeader`

```ts title="/index.ts"

new AdminForth({
  ...
  customization: {
    loginPageInjections: {
      underInputs: '@@/CustomLoginFooter.vue',
//diff-add
      panelHeader: '@@/CustomLoginHeader.vue',
    }
    ...
  }

  ...
})
```

Now create file `CustomLoginHeader.vue` in the `custom` folder of your project:

```html title="./custom/CustomLoginHeader.vue"
<template>
    
        
          AdminForth
        
    
</template>
```

## List view page injections shrinking: thin enough to shrink?

When none of `bottom`, `beforeBreadcrumbs`, `beforeActionButtons`, `afterBreadcrumbs` injections are set in list table, the table tries to shrink into viewport for better UX. In other words, in this default mode it moves scroll from body to the table itself:

![alt text](<Group 15.png>)

However if one of the above injections is set, the table will not try to shrink it's height into viewport and will have a fixed height. We apply this behavior because generally page injection might take a lot of height and table risks to be too small to be usable. So vertical scroll is moved to the body (horizontal scroll is still on the table):

![alt text](<Group 17.png>)

However, if you intend to use injection as a small panel, you can set `meta.thinEnoughToShrinkTable` to `true` in the injection instantiation:

```ts title="/apartments.ts"
{
  resourceId: 'aparts',
  ...
  options: {
    pageInjections: {
      list: {
        bottom: {
          file: '@@/<ComponentForBottomPanel>.vue',
          meta: {
            thinEnoughToShrinkTable: true,
          }
        }
      }
    }
  }
}
```

![alt text](<Group 19.png>)

If at least one injection will not set or will not define `meta.thinEnoughToShrinkTable` as `true`, the table will not try to shrink into viewport.

## Three dots menu customization

You can also inject custom components to the three dots menu on the top right corner of the page.

![alt text](<Group 4.png>)

```ts title="/apartments.ts"
{
  resourceId: 'aparts',
  ...
  options: {
    pageInjections: {
      show: {
          threeDotsDropdownItems: [
            '@@/CheckReadingTime.vue',
          ]
      }
    }
  }
}
```

Now create file `CheckReadingTime.vue` in the `custom` folder of your project:

```html title="./custom/CheckReadingTime.vue"
<template>
  
    
      Check reading time
    
  
</template>

<script setup>
import { getReadingTime} from "text-analyzer";
import { useAdminforth } from '@/adminforth';

defineExpose({
  click,
});

const { alert, list } = useAdminforth();

function checkReadingTime() {
  const text = document.querySelector('[data-af-column="description"]')?.innerText;
  if (text) {
    const readingTime = getReadingTime(text);
    alert({
      message: `Reading time: ${readingTime.minutes} minutes`,
      variant: 'success',
    });
  }
  list.closeThreeDotsDropdown();
}

function click() {
  checkReadingTime();
}

</script>
```

For this demo we will use text-analyzer package:

```bash 
cd custom
pnpm i text-analyzer
```

> ☝️ Please note that we are using AdminForth [Frontend API](/docs/api/FrontendAPI/interfaces/FrontendAPIInterface/) `list.closeThreeDotsDropdown();` to close the dropdown after the item is clicked.

>☝️ Please note that the injected component might have an exposed click function as well as a defined click function, which executes the click on component logic.

## List table custom action icons

`customActionIcons` allows to add custom actions to the list page

![alt text](<Group 3.png>)

```ts title="/apartments.ts"
{
  resourceId: 'aparts',
  ...
  options: {
    pageInjections: {
      list: {
          customActionIcons: [
            '@@/SearchForApartmentInGoogle.vue',
          ]
      }
    }
  }
}
```

Now create file `SearchForApartmentInGoogle.vue` in the `custom` folder of your project:

```html title="./custom/SearchForApartmentInGoogle.vue"
<template>
    <Tooltip>
        
            <IconCardSearch class="w-5 h-5 me-2"/>
        

        <template #tooltip>
            {{$t('Search for competitive apartments in Google')}}
        </template>
    </Tooltip>
</template>

<script setup lang="ts">
import { IconCardSearch } from '@iconify-prerendered/vue-mdi';
import Tooltip from '@/afcl/Tooltip.vue';
import type { AdminForthResourceColumnCommon, AdminForthResourceCommon, AdminUser } from '@/types/Common';

const props = defineProps<{
  column: AdminForthResourceColumnCommon;
  record: any;
  meta: any;
  resource: AdminForthResourceCommon;
  adminUser: AdminUser
}>();
</script>
```

Install used icon:

```sh
cd custom
pnpm i @iconify-prerendered/vue-mdi
```

## List table row replace injection

`tableRowReplace` lets you fully control how each list table row is rendered. Instead of the default table `…` markup, AdminForth will mount your Vue component per record and use its returned DOM to display the row. Use this when you need custom row layouts, extra controls, or conditional styling that goes beyond column-level customization.

Supported forms:
- Single component: `pageInjections.list.tableRowReplace = '@@/MyRowRenderer.vue'`
- Object form with meta: `pageInjections.list.tableRowReplace = { file: '@@/MyRowRenderer.vue', meta: { /* optional */ } }`
- If an array is provided, the first element is used.

Example configuration:

```ts title="/resources/apartments.ts"
{
  resourceId: 'aparts',
  ...
  options: {
    pageInjections: {
      list: {
        tableRowReplace: {
          file: '@@/ApartRowRenderer.vue',
          meta: {
            // You can pass any meta your component may read
          }
        }
      }
    }
  }
}
```

Minimal component example (decorate default row with a border):

```vue title="/custom/ApartRowRenderer.vue"
<template>
  
    <slot />
  
  
</template>

<script setup lang="ts">
import { computed } from 'vue';
const props = defineProps<{
  record: any
  resource: any
  meta: any
  adminUser: any
}>();
</script>
```

Component contract:
- Inputs
  - `record`: the current record object
  - `resource`: the resource config object
  - `meta`: the meta object passed in the injection config
- Slots
  - Default slot: the table’s standard row content (cells) will be projected here. Your component can wrap or style it.
- Output
  - Render a full `…` fragment. For example, to replace the standard set of cells with a single full‑width cell, render:

```vue

  
    <slot />
  

```

Notes and tips:
- Requirements:
  - Required `` structure around `<slot />`

## List table three dots menu injection

`customActionIconsThreeDotsMenuItems` allows to inject component inside three dots menu for each recod in list table.

```ts
  options: {
    pageInjections: {
      list: {
        customActionIconsThreeDotsMenuItems: {
          file: '@@/ApartRowRenderer.vue',
          meta: {
            // You can pass any meta your component may read
          }
        }
      }
    }
  }
```

## List table beforeActionButtons

`beforeActionButtons` allows injecting one or more compact components into the header bar of the list page, directly to the left of the default action buttons (`Create`, `Filter`, bulk actions, three‑dots menu). Use it for small inputs (quick search, toggle, status chip) rather than large panels.

![alt text](<Group 5.png>)

```ts title="/apartments.ts"
{
  resourceId: 'aparts',
  ...
  options: {
    pageInjections: {
      list: {
        beforeActionButtons: {
          file: '@@/UniversalQuickSearch.vue',
          meta: {
            thinEnoughToShrinkTable: true
          }
        }
      }
    }
  }
}
```

Multiple components:

```ts
beforeActionButtons: [
  {
    file: '@@/UniversalQuickSearch.vue',
    meta: { thinEnoughToShrinkTable: true }
  },
  {
    file: '@@/RecordsSummary.vue',
    meta: { thinEnoughToShrinkTable: true }
  }
]
```

> ☝️ Keep these components visually light; wide or tall content should use `afterBreadcrumbs` or `bottom` instead.

## List table custom

## Global Injections

You have opportunity to inject custom components to the global layout. For example, you can add a custom items into user menu

* `config.customization.globalInjections.userMenu`:

![alt text](<Group 6.png>)

use `closeUserMenuDropdown();` to close the dropdown after the item is clicked.

```ts title="/index.ts"
{
  ...
  customization: {
    globalInjections: {
      userMenu: [
        '@@/CustomUserMenuItem.vue',
      ]
    }
  }
  ...
}
```

Now create file `CustomUserMenuItem.vue` in the `custom` folder of your project:

```html title="./custom/CustomUserMenuItem.vue"
<template>
  
    Custom Page
  
</template>

<script setup>
import { useAdminforth } from '@/adminforth';

const { alert, closeUserMenuDropdown } = useAdminforth()

function openCustomPage() {
  alert({
    message: 'Custom page is opened',
    variant: 'success',
  });
  closeUserMenuDropdown();
}
</script>
```

Also there are:

* `config.customization.globalInjections.header`
* `config.customization.globalInjections.sidebar`
* `config.customization.globalInjections.sidebarTop` — renders inline at the very top of the sidebar, on the same row with the logo/brand name. If the logo is hidden via `showBrandLogoInSidebar: false`, this area expands to the whole row width.
* `config.customization.globalInjections.everyPageBottom`

Unlike `userMenu`, `header` and `sidebar` injections, `everyPageBottom` will be added to the bottom of every page even when user is not logged in.
You can use it to execute some piece of code when any page is loaded. For example, you can add welcoming pop up when user visits a page.

```ts title="/index.ts"
{
  ...
  customization: {
    globalInjections: {
      userMenu: [
        '@@/CustomUserMenuItem.vue',
//diff-remove
      ]
//diff-add
      ],
//diff-add
      everyPageBottom: [
//diff-add
        '@@/AnyPageWelcome.vue',
//diff-add
      ]
    }
  }
  ...
}
```

Now create file `AnyPageWelcome.vue` in the `custom` folder of your project:

```html title="./custom/AnyPageWelcome.vue"
<template></template>

<script setup>
import { onMounted } from 'vue';
import { useAdminforth } from '@/adminforth';

const { alert } = useAdminforth();

onMounted(() => {
  alert({
    message: 'Welcome!',
    variant: 'success',
  });
});
</script>
```

## Sidebar Top Injection

You can place compact controls on the very top line of the sidebar, next to the logo/brand name:

```ts title="/index.ts"
new AdminForth({
  ...
  customization: {
    globalInjections: {
      sidebarTop: [
        '@@/QuickSwitch.vue',
      ],
    }
  }
})
```

If you hide the logo with `showBrandLogoInSidebar: false`, components injected via `sidebarTop` will take the whole line width.

## Injection order

Most of injections accept an array of components. By defult the order of components is the same as in the array. You can use standard array methods e.g. `push`, `unshift`, `splice` to put item in desired place.

However, if you want to control the order of injections dynamically, which is very handly for plugins, you can use `meta.afOrder` property in the injection instantiation. The higher the number, the earlier the component will be rendered. For example

```ts title="/index.ts"
{
  ...
  customization: {
    globalInjections: {
      userMenu: [
        {
          file: '@@/CustomUserMenuItem.vue',
          meta: { afOrder: 10 }
        },
        {
          file: '@@/AnotherCustomUserMenuItem.vue',
          meta: { afOrder: 20 }
        },
        {
          file: '@@/LastCustomUserMenuItem.vue',
          meta: { afOrder: 5 }
        },
      ]
    }
  }
  ...
}
```

## Order of components inserted by plugins

For plugins, the plugin developers encouraged to use `meta.afOrder` to control the order of injections and allow to pass it from plugin options.

For example "OAuth2 plugin", when registers a login button component for login page injection, uses `meta.afOrder` and sets it equal to 'YYY' passed in plugin options:

```ts title="/index.ts"
// plugin CODE
adminforth.config.customization.loginPageInjections.underLoginButton.push({
    file: '@@/..vue',
    meta: {
      afOrder: this.pluginOptions.YYY || 0
    }
 })
```

So you can just pass `YYY` option to the plugin to control the order of the injection.

## Custom scripts in head

If you want to inject tags in your html head:

```ts title='./index.ts'

customization: {
  ...
  customHeadItems: [
    {
      tagName: 'script',
      attributes: { async: 'true', defer: 'true' },
      innerCode: "console.log('Hello from HTML head')"
    }
  ],
...
}

```

---

## Actions


## Single record actions

You might need to give admin users a feature to perform some action on a single record. Actions can be displayed as buttons in the list view and/or in the three-dots menu.

Here's how to add a custom action:

```ts title="./resources/apartments.ts"
{
  resourceId: 'aparts',
  options: {
    actions: [
      {
        name: 'Auto submit',  // Display name of the action
        icon: 'flowbite:play-solid',  // Icon to display (using Flowbite icons)
        
        // Control who can see/use this action
        allowed: ({ adminUser, standardAllowedActions }) => {
          return true;  // Allow everyone
        },
        
        // Handler function when action is triggered
        action: async ({ recordId, adminUser }) => {
          logger.info("auto submit", recordId, adminUser);
          return { 
            ok: true, 
            successMessage: "Auto submitted" 
          };
        },

        // Configure where the action appears
        showIn: {
          list: false,             // Show in list view
          listThreeDotsMenu: true, // Show in three dots menu in list view
          showButton: true,        // Show as a button
          showThreeDotsMenu: true, // Show in three-dots menu
        }
      }
    ]
  }
}
```

### Action Configuration Options

- `name`: Display name of the action
- `icon`: Icon to show (using Flowbite icon set)
- `allowed`: Function to control access to the action
- `action`: Handler function that executes when action is triggered for a **single** record
- `bulkHandler`: Handler function that executes when the action is triggered for **multiple** records at once (see [Dedicated bulk handler](#dedicated-bulk-handler))
- `showIn`: Controls where the action appears
  - `list`: whether to show as an icon button per row in the list view
  - `listThreeDotsMenu`: whether to show in the three-dots menu per row in the list view
  - `showButton`: whether to show as a button on the show view
  - `showThreeDotsMenu`: whether to show in the three-dots menu of the show view
  - `bulkButton`: whether to show as a bulk action button when rows are selected

### Bulk button with `action`

When `showIn.bulkButton` is `true` and only `action` (not `bulkHandler`) is defined, AdminForth automatically calls your `action` function **once per selected record** using `Promise.all`. This is convenient for simple cases but means N separate handler invocations run in parallel:

```ts title="./resources/apartments.ts"
{
  name: 'Auto submit',
  action: async ({ recordId }) => {
    // Called once per selected record when used as a bulk button
    await doSomething(recordId);
    return { ok: true, successMessage: 'Done' };
  },
  showIn: {
    bulkButton: true,   // triggers Promise.all over selected records
    showButton: true,
  }
}
```

### Dedicated bulk handler

If your operation can be expressed more efficiently as a single batched query (e.g., a single `UPDATE … WHERE id IN (…)`), define `bulkHandler` instead. AdminForth will call it **once** with all selected record IDs:

```ts title="./resources/apartments.ts"
{
  name: 'Auto submit',
  // bulkHandler receives all recordIds in one call – use it for batched operations
  bulkHandler: async ({ recordIds, adminforth, resource }) => {
    await doSomethingBatch(recordIds);
    return { ok: true, successMessage: `Processed ${recordIds.length} records` };
  },
  // You can still keep `action` for the single-record show/edit buttons
  action: async ({ recordId }) => {
    await doSomething(recordId);
    return { ok: true, successMessage: 'Done' };
  },
  showIn: {
    bulkButton: true,
    showButton: true,
  }
}
```

> ☝️ When both `action` and `bulkHandler` are defined, AdminForth uses `bulkHandler` for bulk operations and `action` for single-record operations. When only `action` is defined and `bulkButton` is enabled, AdminForth falls back to `Promise.all` over individual `action` calls.

### Bulk-specific options

| Option | Type | Description |
|---|---|---|
| `showIn.bulkButton` | `boolean` | Show as a bulk action button in the list toolbar. |
| `bulkHandler` | `async ({ recordIds, adminUser, adminforth, resource, response, tr }) => { ok, error?, message? }` | Called with all selected IDs at once. Falls back to calling `action` per record in parallel if omitted. |
| `bulkConfirmationMessage` | `string` | Confirmation dialog text shown before the bulk action executes. |
| `bulkSuccessMessage` | `string` | Success message shown after the bulk operation. Defaults to `"N out of M items processed successfully"`. |

## Standalone Bulk Actions

For operations that only apply to multiple selected records, use `options.bulkActions`. The built-in **Delete checked** action is a good reference.

```ts title="./resources/apartments.ts"
{
  resourceId: 'aparts',
  options: {
    bulkActions: [
      {
        label: 'Send Invitation',
        icon: 'flowbite:envelope-solid',
        confirm: 'Are you sure you want to send invitation emails?',
        allowed: async ({ adminUser }) => adminUser.dbUser.role === 'superadmin',
        action: async ({ selectedIds }) => {
          await sendBulkInvitations(selectedIds);
          return { ok: true, successMessage: `Sent to ${selectedIds.length} users` };
        },
      },
    ],
  },
}
```

### Confirmation dialog

Pass `confirm` to show a dialog before the action runs.

**String** — shown as the dialog title, no secondary message:

```ts
confirm: 'Are you sure you want to send invitation emails?',
```

**Object** — full control over the dialog. `{count}` in `message` is replaced with the number of selected records; `|` separates singular and plural forms:

```ts
confirm: {
  title: 'Are you sure you want to archive the selected items?',
  message: 'Archiving {count} item. This process is irreversible. | Archiving {count} items. This process is irreversible.',
  yes: 'Archive',
  no: 'Cancel',
},
```

Omit `confirm` entirely to skip the dialog and run the action immediately.

### Access Control

You can control who can use an action through the `allowed` function. This function receives:

```ts title="./resources/apartments.ts"
{
  options: {
    actions: [
      {
        name: 'Auto submit',
        allowed: async ({ adminUser, standardAllowedActions }) => {
          if (adminUser.dbUser.role !== 'superadmin') {
            return false;
          }
          return true;
        },
        // ... other configuration
      }
    ]
  }
}
```

The `allowed` function receives:
- `adminUser`: The current admin user object
- `standardAllowedActions`: Standard permissions for the current user

Return:
- `true` to allow access
- `false` to deny access
- A string with an error message to explain why access was denied — e.g. `return 'Only superadmins can perform this action'`

Here is how it looks:
![alt text](<Single record actions.png>)

### Action URL

Instead of defining an `action` handler, you can specify a `url` that the user will be redirected to when clicking the action button:

```ts title="./resources/apartments.ts"
{
  name: 'View details',
  icon: 'flowbite:eye-solid',
  url: '/resource/aparts',  // URL to redirect to
  showIn: {
    list: true,
    listThreeDotsMenu: false,
    showButton: true,
    showThreeDotsMenu: true,
  } 
}
```

> ☝️ Note: You cannot specify both `action` and `url` for the same action - only one should be used.

The URL can be:
- A relative path within your admin panel (starting with '/')
- An absolute URL (starting with 'http://' or 'https://')
- function which creates URL based on record fields

To open the URL in a new tab, append `target=_blank` as a query parameter. If the URL already has query parameters, use `&target=_blank`; otherwise use `?target=_blank`:

```ts
{
  name: 'View on Google',
  icon: 'flowbite:external-link-solid',
  url: 'https://google.com/search?q=apartment&target=_blank',
  showIn: {
    list: true,
    showButton: true
  }
}
```

Example to generate dynamic URL:

```ts
{
  name: 'View on Google',
  icon: 'flowbite:external-link-solid',
  url: async ({record, recordId, adminUser, resource }) => `https://google.com/search?q=Apartment ${record.title}`,
  showIn: {
    list: true,
    showButton: true
  }
}
```

> ☝️ Note: Though url function might be async we recommend to omit long awaits, or ideally don't use them at all, cause slow execution of this hook might be a subject of bottleneck for resource pages rendering. For built actions the async functions would be called in parallel to optimize loading speed.

### Deep-level redirects.

Using `url` prop described above is recommended way to implementing URL navigation from actions (internal or external), because URLs are rendered into direct anchour tag and support all anchour features (like Open in new tab). 

However, rearely you might also like to decide whether to redirect only after performing some logic (conditionally). This way is not recommended for most of cases, because it is not compatible with action native features (we can't know URL before executing action body):

```ts
{
  name: 'View on Google',
  icon: 'flowbite:external-link-solid',
  action: async ({ recordId }) => {
    if (await testSomething(recordId)) {
        return { ok: true, redirectUrl: 'https://google.com/search?q=apartment' };
    };
    return { ok: true, successMessage: 'Done' };
  },
  showIn: {
    list: true,
    showButton: true
  }
}
```

## Custom Component

If you want to style an action's button/icon without changing its behavior, attach a custom UI wrapper via `customComponent`. 
The file points to your SFC in the custom folder (alias `@@/`), and `meta` lets you pass lightweight styling options (e.g., border color, radius).

Below we wrap a "Mark as listed" action.

```ts title="./resources/apartments.ts"
{
  resourceId: 'aparts',
  options: {
    actions: [
      {
        name: 'Mark as listed',
        icon: 'flowbite:eye-solid',
        // UI wrapper for the built-in action button
        //diff-add
        customComponent: {
          //diff-add
          file: '@@/ActionBorder.vue',        // SFC path in your custom folder
          //diff-add
          meta: { color: '#94a3b8', radius: 10 }
          //diff-add
        },
        showIn: { list: false, listThreeDotsMenu: true, showButton: true, showThreeDotsMenu: true },
        action: async ({ recordId }) => {
          await admin.resource('aparts').update(recordId, { listed: 1 });
          return { ok: true, successMessage: 'Marked as listed' };
        }
      },
    ]
  }
}
```

Use this minimal wrapper component to add a border/rounding around the default action UI while keeping the action logic intact. 
Keep the `<slot />` (that's where AdminForth renders the default button) and emit `callAction` (optionally with a payload) to trigger the handler when the wrapper is clicked.

```ts title="./custom/ActionBorder.vue"
<template>
  <!-- Keep the slot: AdminForth renders the default action button/icon here -->
  <!-- Emit `callAction` (optionally with a payload) to trigger the action when the wrapper is clicked -->
  <!-- Example: provide `meta.extra` to send custom data. In list views we merge with `row` so recordId context is kept. -->
  
    <slot />
  
</template>

<script setup lang="ts">
import { computed } from 'vue';

const props = defineProps<{
  // meta can style the wrapper and optionally carry extra payload for the action
  meta?: { color?: string; radius?: number; padding?: number; extra?: any };
  // When used in list view, the table passes current row
  row?: any;
  // When used in show/edit views, the page passes current record
  record?: any;
}>();
const emit = defineEmits<{ (e: 'callAction', payload?: any): void }>();

const styleObj = computed(() => ({
  display: 'inline-block',
  border: `1px solid ${props.meta?.color ?? '#e5e7eb'}`,
  borderRadius: (props.meta?.radius ?? 8) + 'px',
  padding: (props.meta?.padding ?? 2) + 'px',
}));

function click(payload: any) {
  emit('callAction', { ...props.row, ...(props.meta?.extra ?? {}) })
}
//we need to define this expose, because padding is added by adminforth wrapper and to trigger click on this padding we use this expose
defineExpose({
  click
});
</script>
```

### Pass dynamic values to the action

You can pass arbitrary data from your custom UI wrapper to the backend action by emitting `callAction` with a payload. That payload will be available on the server under the `extra` argument of your action handler.

Frontend examples:

```vue title="./custom/ActionToggleListed.vue"
<template>
  <!-- Two buttons that pass different flags to the action -->
  <button @click="emit('callAction', { asListed: true })" class="mr-2">Mark as listed</button>
  <button @click="emit('callAction', { asListed: false })">Mark as unlisted</button>

  <!-- Or keep the default slot button and wrap it: -->
  
    <slot />
  
</template>

<script setup lang="ts">
const emit = defineEmits<{ (e: 'callAction', payload?: any): void }>();
</script>
```

Backend handler: read the payload via `extra`.

```ts title="./resources/apartments.ts"
{
  resourceId: 'aparts',
  options: {
    actions: [
      {
        name: 'Toggle listed',
        icon: 'flowbite:eye-solid',
        showIn: { list: false, listThreeDotsMenu: false, showButton: true, showThreeDotsMenu: true },
        // The payload from emit('callAction', { asListed: true|false }) arrives here as `extra`
        customComponent: {
          file: '@@/ActionToggleListed.vue'
        },
        action: async ({ recordId, extra }) => {
          const asListed = extra?.asListed === true;
          // Example update (use your own data layer):
          await admin.resource('aparts').update(recordId, { listed: asListed });
          return { ok: true, successMessage: `Set listed=${asListed}` };
        }
      }
    ]
  }
}
```

Notes:
- If you don’t emit a payload, the default behavior is used by the UI (e.g., in lists the current row context is used). When you do provide a payload, it will be forwarded to the backend as `extra` for your action handler.
- You can combine default context with your own payload by merging before emitting, for example: `emit('callAction', { ...row, asListed: true })` if your component has access to the row object.

## Start actions programmatically
You can execute resource actions manually using adminforth.runAction(). This is useful inside hooks, plugins, cron jobs, custom endpoints, or any backend automation.

```ts title="./resources/apartments.ts"
actions: [
  {
  //diff-add
  id: 'testToggle listedAction',
  name: 'Toggle listed',
  icon: 'flowbite:eye-solid',
  ...  
  }
]
```
Then execute it from a hook for example:

```ts title="./resources/apartments.ts"
hooks: {
      ...
      afterSave: async ({ record, adminUser, resource, adminforth }: { record: any, adminUser: AdminUser, resource: AdminForthResource, adminforth: any }) => {

        await adminforth.runAction({
          actionId: 'Toggle listed',
          resourceId: resource.resourceId,
          recordId: record.id,
          adminUser,
        });

        return { ok: true };
      },
    },
```

runAction() automatically:
- finds the resource
- finds the action
- checks permissions via allowed
- executes the action handler
- passes full action context (recordId, adminUser, extra, etc.)

> ☝️ runAction() is not limited to hooks — you can call it anywhere you have access to the AdminForth instance.

---

## Menu & Header


## Icons

Adminforth uses [Iconify](https://iconify.design/) icons everywhere, including the menu. 

You can set an icon for each menu item using the `icon` field.

You can use any icon from the [Iconify Gallery](https://icon-sets.iconify.design/) in the format `<setname>:<icon>`. For example, `flowbite:brain-solid`.

![Icons for AdminForth](image-14.png)

> 👋 With deep respect to Alex Kozack who created great [iconify-prerendered](https://github.com/cawa-93/iconify-prerendered) MIT package used by AdminForth. It uses a scheduled job to prerender all icons from Iconify to icons font and then publish them to npm

## Grouping 

You can created a group of menu items with open or close:

E.g. create group "Blog" with Items who link to resource "posts" and "categories":
  
```ts title='./index.ts'
  {
    ...
    menu: [
      {
        label: 'Blog',
        icon: 'flowbite:brain-solid',
        open: true,
        children: [
          {
            label: 'Posts',
            icon: 'flowbite:book-open-outline',
            resourceId: 'posts',
          },
          {
            label: 'Categories',
            icon: 'flowbite:folder-duplicate-outline',
            resourceId: 'categories',
          },
        ],
      },
      {
        label: 'Users',
        icon: 'flowbite:folder-duplicate-outline',
        resourceId: 'adminuser',
      },
    ],
    ...
  }
```

If it is rare Group you can make it `open: false` so it would not take extra space in menu, but admin users will be able to open it by clicking on the group name.

## Adding menu items from plugins

Plugins can add top-level menu items without mutating the user-defined `config.menu`. This keeps the application menu owned by the app configuration, while plugins can contribute their own entries.

Use `registerMenuContribution` from a plugin's `modifyResourceConfig`:

```ts title='./plugins/adminforth-dashboard/index.ts'
async modifyResourceConfig(adminforth, resourceConfig) {
  super.modifyResourceConfig(adminforth, resourceConfig);

  adminforth.registerMenuContribution({
    item: {
      itemId: 'dashboard',
      type: 'page',
      label: 'Dashboard',
      icon: 'flowbite:chart-pie-solid',
      path: '/dashboard',
      component: this.componentPath('Dashboard.vue'),
    },
    placement: { before: { resourceId: 'adminuser' } },
  });
}
```

Supported placements:

```ts
adminforth.registerMenuContribution({
  item: {
    itemId: 'dashboard',
    type: 'page',
    label: 'Dashboard',
    path: '/dashboard',
    component: this.componentPath('Dashboard.vue'),
  },
  placement: { position: 'first' },
});

adminforth.registerMenuContribution({
  item: {
    itemId: 'reports',
    type: 'page',
    label: 'Reports',
    path: '/reports',
    component: this.componentPath('Reports.vue'),
  },
  placement: { after: { resourceId: 'orders' } },
});
```

`placement` can be:

- `{ position: 'first' }`
- `{ position: 'last' }`
- `{ before: 'usersMenuItemId' }`
- `{ after: 'usersMenuItemId' }`
- `{ before: { itemId: 'usersMenuItemId' } }`
- `{ after: { resourceId: 'adminuser' } }`
- `{ before: { path: '/reports' } }`

If placement is omitted, or if the target item is not found, AdminForth appends the contributed item to the end of the top-level menu.

Plugin menu contributions are additive only:

- user-defined `config.menu` is not changed
- plugins cannot remove or edit existing menu items through this API
- contributed `itemId` must not duplicate an existing top-level menu item
- this first version inserts only top-level menu items

### Dynamic menu items from plugin state

If a plugin needs to add menu items at runtime, for example after a user clicks a button and creates a new dashboard, register a menu contribution provider. AdminForth calls providers every time it fetches the menu.

```ts title='./plugins/adminforth-dashboard/index.ts'
async modifyResourceConfig(adminforth, resourceConfig) {
  super.modifyResourceConfig(adminforth, resourceConfig);

  adminforth.registerMenuContributionProvider(async ({ adminUser, adminforth }) => {
    const dashboards = await adminforth.resource('dashboards').list();

    return [
      {
        item: {
          itemId: 'dashboardsMenu',
          type: 'group',
          label: 'Dashboards',
          icon: 'flowbite:chart-pie-solid',
          children: dashboards.map((dashboard) => ({
            itemId: `dashboard-${dashboard.id}`,
            type: 'page',
            label: dashboard.name,
            path: `/dashboards/${dashboard.id}`,
          })),
        },
        placement: { position: 'first' },
      },
    ];
  });
}
```

After the plugin changes the state used by the provider, call `refreshMenu` on the backend:

```ts
await adminforth.resource('dashboards').create({
  name: 'Sales',
});

await adminforth.refreshMenu(adminUser);
```

AdminForth sends a websocket event to the current user, and the frontend refetches the menu without a page reload.

Frontend components can also refresh the menu directly:

```ts
import { useAdminforth } from '@/adminforth';

const { menu } = useAdminforth();

await menu.refresh();
```

Dynamic menu items should point to routes that are already available in the SPA. If a provider returns a brand-new custom `component` path that was not known during AdminForth build, the menu item can appear, but the route will not be registered until the app is rebuilt.

## Visibility of menu items

You might want to hide some menu items from the menu for some users. 

To do it use `visible` field in the menu item configuration:

```ts title='./index.ts'
{
  ...
  menu: [
    {
      label: 'Categories',
      icon: 'flowbite:folder-duplicate-outline',
      resourceId: 'categories',
//diff-add
      visible: adminUser => adminUser.dbUser.role === 'admin'
    },
  ],
  ...
}
```

> 👆 Please note that this will just hide menu item for non `admin` users, but resource pages will still be available by direct
> URLs. To limit access, you should also use [allowedActions](/docs/tutorial/Customization/limitingAccess/#disable-full-access-to-resource-based-on-logged-in-user-record-or-role) field in the resource configuration in addition to this.

## Gap

You can put one or several gaps between menu items:

```ts title='./index.ts'
{
  ...
  menu: [
    {
      label: 'Posts',
      icon: 'flowbite:book-open-outline',
      resourceId: 'posts',
    },
    {
      type: 'gap',
    },
    {
      type: 'gap',
    },
    {
      label: 'Categories',
      icon: 'flowbite:folder-duplicate-outline',
      resourceId: 'categories',
    },
  ],
  ...
}
```

## Divider

To split menu items with a line you can use a divider:

```ts title='./index.ts'
{
  ...
  menu: [
    {
      label: 'Posts',
      icon: 'flowbite:book-open-outline',
      resourceId: 'posts',
    },
    {
      type: 'divider',
    },
    {
      label: 'Categories',
      icon: 'flowbite:folder-duplicate-outline',
      resourceId: 'categories',
    },
  ]
  ...
}
```

## Heading

You can add a heading to the menu:

```ts title='./index.ts'
{
  ...
  menu: [
    {
      type: 'heading',
      label: 'Editings',
    },
    {
      label: 'Posts',
      icon: 'flowbite:book-open-outline',
      resourceId: 'posts',
    },
    {
      label: 'Categories',
      icon: 'flowbite:folder-duplicate-outline',
      resourceId: 'categories',
    },
  ],
  ...
}
```

## Badge

You can add a badge near the menu item title (e.g. to get count of unread messages). To do this, you need to add a `badge` field to the menu item configuration:

```ts title='./index.ts'
{
  ...
  menu: [
    {
      label: 'Posts',
      icon: 'flowbite:book-open-outline',
      resourceId: 'posts',
      badge: async (adminUser: AdminUser) => {
        return 10
      },
      badgeTooltip: 'New posts',  // explain user what this badge means
      ...
    },
  ],
  ...
}
```

Badge function is async, but all badges are loaded in "lazy" to not block the menu rendering.

### Refreshing the badges

Most times you need to refresh the badge from some backend API or hook. To do this you can do next:

1) Add `itemId` to menu item to identify it:

```ts title='./index.ts'
{
  ...
  menu: [
    {
      label: 'Posts',
      icon: 'flowbite:book-open-outline',
      resourceId: 'posts',
//diff-add
      itemId: 'postsMenuItem',
      //diff-add
      badge: async (adminUser: AdminUser, adminForth: IAdminForth) => {
        //diff-add
        const newCount = await adminforth.resource('posts').count(Filters.EQ('verified', false));
        //diff-add
        return newCount;
      },
      badgeTooltip: 'Unverified posts',  // explain user what this badge means
      ...
    },
  ],
  ...
}
```

2) On backend point where you need to refresh the badge, you can publish a message to the websocket topic:

```ts title='./index.ts'
{
  resourceId: 'posts',
  table: 'posts',
  hooks: {
    edit: {
      //diff-add
      afterSave: async ({ record, adminUser, resource, adminforth }) => {
        //diff-add
        adminforth.refreshMenuBadge('postsMenuItem', adminUser);
        //diff-add
        return { ok: true }
        //diff-add
      }
    }
  }
}
```

> 👆 Please note that any `/opentopic/` publish can be listened by anyone without authorization. If count published in this channel might be
> a subject of security or privacy concerns, you should add [publish authorization](/docs/tutorial/Customization/websocket/#publish-authorization) to the topic.

More rare case when you need to refresh menu item from the frontend component. You can achieve this by calling the next method:

```typescript
import { useAdminforth } from '@/adminforth';

const { menu } = useAdminforth();

menu.refreshMenuBadges()
```

## Avatars

If you want your user to have custom avatar you can use avatarUrl:

```ts title='./index.ts'

auth: {

  ...

  avatarUrl: async (adminUser)=> { 
    return `https://${process.env.STORAGE_PROVIDER_PATH}/${adminUser.dbUser.avatar_path}`
  },

  ...

}

```

This syntax can be use to get unique avatar for each user of hardcode avatar, but it makes more sense to use it with [upload plugin](https://adminforth.dev/docs/tutorial/Plugins/upload/#using-plugin-for-uploading-avatar)

## Custom URL
You can use the url property to override default navigation. This is useful for linking to pre-filtered lists or external sites.

```ts title='./index.ts'

menu: [
    {
      label: 'Posts',
      icon: 'flowbite:book-open-outline',
      resourceId: 'posts',
      //diff-add
      url: '/resource/aparts?filter__country__in=["DE"]',  
      //diff-add
      isOpenInNewTab: true // You can also add isOpenInNewTab: true to open the link in a new browser tab
    },
  ],

```
> 👆 Please note start internal URLs with a leading / to ensure correct routing.

## Adding menu items from plugins

Plugins can add top-level menu items without mutating the user-defined `config.menu`. This keeps the application menu owned by the app configuration, while plugins can contribute their own entries.

Use `registerMenuContribution` from a plugin's `modifyResourceConfig`:

```ts title='./plugins/adminforth-dashboard/index.ts'
async modifyResourceConfig(adminforth, resourceConfig) {
  super.modifyResourceConfig(adminforth, resourceConfig);

  adminforth.registerMenuContribution({
    item: {
      itemId: 'dashboard',
      type: 'page',
      label: 'Dashboard',
      icon: 'flowbite:chart-pie-solid',
      path: '/dashboard',
      component: this.componentPath('Dashboard.vue'),
    },
    placement: { before: { resourceId: 'adminuser' } },
  });
}
```

Supported placements:

```ts
adminforth.registerMenuContribution({
  item: {
    itemId: 'dashboard',
    type: 'page',
    label: 'Dashboard',
    path: '/dashboard',
    component: this.componentPath('Dashboard.vue'),
  },
  placement: { position: 'first' },
});

adminforth.registerMenuContribution({
  item: {
    itemId: 'reports',
    type: 'page',
    label: 'Reports',
    path: '/reports',
    component: this.componentPath('Reports.vue'),
  },
  placement: { after: { resourceId: 'orders' } },
});
```

`placement` can be:

- `{ position: 'first' }`
- `{ position: 'last' }`
- `{ before: 'usersMenuItemId' }`
- `{ after: 'usersMenuItemId' }`
- `{ before: { itemId: 'usersMenuItemId' } }`
- `{ after: { resourceId: 'adminuser' } }`
- `{ before: { path: '/reports' } }`

If placement is omitted, or if the target item is not found, AdminForth appends the contributed item to the end of the top-level menu.

Plugin menu contributions are additive only:

- user-defined `config.menu` is not changed
- plugins cannot remove or edit existing menu items through this API
- contributed `itemId` must not duplicate an existing top-level menu item
- this first version inserts only top-level menu items

### Dynamic menu items from plugin state

If a plugin needs to add menu items at runtime, for example after a user clicks a button and creates a new dashboard, register a menu contribution provider. AdminForth calls providers every time it fetches the menu.

```ts title='./plugins/adminforth-dashboard/index.ts'
async modifyResourceConfig(adminforth, resourceConfig) {
  super.modifyResourceConfig(adminforth, resourceConfig);

  adminforth.registerMenuContributionProvider(async ({ adminUser, adminforth }) => {
    const dashboards = await adminforth.resource('dashboards').list();

    return [
      {
        item: {
          itemId: 'dashboardsMenu',
          type: 'group',
          label: 'Dashboards',
          icon: 'flowbite:chart-pie-solid',
          children: dashboards.map((dashboard) => ({
            itemId: `dashboard-${dashboard.id}`,
            type: 'page',
            label: dashboard.name,
            path: `/dashboards/${dashboard.id}`,
          })),
        },
        placement: { position: 'first' },
      },
    ];
  });
}
```

After the plugin changes the state used by the provider, call `refreshMenu` on the backend:

```ts
await adminforth.resource('dashboards').create({
  name: 'Sales',
});

await adminforth.refreshMenu(adminUser);
```

AdminForth sends a websocket event to the current user, and the frontend refetches the menu without a page reload.

Frontend components can also refresh the menu directly:

```ts
import { useAdminforth } from '@/adminforth';

const { menu } = useAdminforth();

await menu.refresh();
```

Dynamic menu items should point to routes that are already available in the SPA. If a provider returns a brand-new custom `component` path that was not known during AdminForth build, the menu item can appear, but the route will not be registered until the app is rebuilt.

---

## Data API


AdminForth Data API is a minimal set of methods to manipulate the data in the database. 
With Data API you can make very basic operations like `get`, `list`, `create`, `update`, `delete`, `count` on the resources.

## Motivation

Since AdminForth has internal DataSource Connectors with unified & secure interface to work with different databases, we decided
why not to expose this interface to you. 

This allows you to make basic operations on the data with AdminForth without using 3rd party ORMs or writing manual SQL queries.

> ☝️ For advanced operations like generating aggregations, joins and other complex queries you should use your own ORM or query builder.

## Usage

Basically you just import `Filters`, `Sorts` from the `adminforth` package and call the awaitable methods on the `admin.resource('adminuser')`.

```ts
import { Filters, Sorts } from 'adminforth';
...

const admin = new AdminForth({
  ...
});

// get the resource object
await admin.resource('adminuser').get(Filters.EQ('id', '1234'));
```

Here we will show you how to use the Data API with simple examples.

## Get one item from database

Signature:

```ts
.get(
  filters: <AdminForthFilterObject>,
): Promise<any>
```

Get item by ID:

```ts
const user = await admin.resource('adminuser').get(
  [Filters.EQ('id', '1234')]
);
```

Check School with name 'Hawkins Elementary' exits in DB

```ts
const schoolExists = !!(await admin.resource('schools').get(
  [Filters.EQ('name', 'Hawkins Elementary')]
));
```

Get user with name 'John' and role not 'SuperAdmin'

```ts
const user = await admin.resource('adminuser').get(
  Filters.EQ('name', 'John'), 
  Filters.NEQ('role', 'SuperAdmin')
);
```

## Get list of items from database

Signature:

```ts
.list(
  filters: <AdminForthFilterObject>,
  limit: number | null
  offset: number | null
  sort: []
): Promise<any[]>
```

Get 15 latest users which role is not Admin:

```ts
const users = await admin.resource('adminuser').list(
  [Filters.NEQ('role', 'Admin')], 15, 0, Sorts.DESC('createdAt')
);
```

Get 10 oldest users (with highest age):

```ts
const users = await admin.resource('adminuser').list([], 10, 0, Sorts.ASC('age'));
```

Get next page of oldest users:

```ts
const users = await admin.resource('adminuser').list([], 10, 10, Sorts.ASC('age'));
```

Get 10 schools, sort by rating first, then oldest by founded year:

```ts
const schools = await admin.resource('schools').list(
  [], 10, 0, [Sorts.DESC('rating'), Sorts.ASC('foundedYear')]
);
```

Get all users that have gmail address AND the ones created not in 2024

```ts
const users = await admin.resource('adminuser').list(
  Filters.AND(
    Filters.LIKE('email', '@gmail.com'),
    Filters.OR(
      Filters.LT('createdAt', '2024-01-01T00:00:00.000Z'),
      Filters.GTE('createdAt', '2025-01-01T00:00:00.000Z'),
    ),
  )
);
```

## Using a raw SQL in queries.

Rarely you might want to add condition for some exotic SQL but still want to keep the rest of API.
Technically it happened that AdminForth allows you to do this also

```js
const minUgcAge = 18;
const usersWithNoUgcAccess = await admin.resource('adminuser').list(
  [
    Filters.NEQ('role', 'Admin'), 
    {
       insecureRawSQL: `(user_meta->>'age') < ${sqlstring.escape(minUgcAge)}`
    }

  ], 15, 0, Sorts.DESC('createdAt')
);
```
This will produce next SQL query:

```
SELECT *
FROM "adminuser"
WHERE "role" != 'Admin'
  AND (user_meta->>'age') < 18
ORDER BY "createdAt" DESC
LIMIT 15 OFFSET 0;
```

Finds users with age less then 18 from meta field which should be a JSONB field in Postgress.

## Create a new item in database

Signature:

```ts
.create({
  <resource fields>
}): Promise<any>
```

Returns value representing created item with all fields, including fields which were populated with `fillOnCreate`.

Create a new school:

```ts
await admin.resource('schools').create({
  name: 'Hawkins Elementary',
  rating: 5,
  foundedYear: 1950,
});
```

## Count items in database

Signature:

```ts
.count(
  filters: <AdminForthFilterObject>,
): Promise<any>
```

Returns number of items in database which match the filters.

Count number of schools with rating above 4:

```ts
const schoolsCount = await admin.resource('schools').count(Filters.GT('rating', 4));
```

Create data for daily report with number of users signed up daily for last 7 days:

Note: while this is not the most efficient way to do this, it's a good example of how you can use `count` method to get the data for the report.
Plus it still should be fast enough while you have index on `createdAt` field.

```ts
const dailyReports = await Promise.all(
  Array.from({ length: 7 }, (_, i) => {
    const dateStart = new Date();
    dateStart.setDate(dateStart.getDate() - i);
    dateStart.setHours(0, 0, 0, 0);
    const dateEnd = new Date(dateStart);
    dateEnd.setDate(dateEnd.getDate() + 1);

    return admin.resource('adminuser').count(
      [Filters.GTE('createdAt', dateStart.toISOString()), Filters.LT('createdAt', dateEnd.toISOString())]
    );
  })
);
```

## Update item in database

Signature:

```ts
.update(
  primaryKey: string, // value of field marked as primaryKey in resource configuration
  {
    <resource fields which you want to update>
  }
): Promise<any>
```

Update school rating to 4.8

```ts
await admin.resource('schools').update('1234', { rating: 4.8 });
```

## Delete item from database

Signature:

```ts
.delete(
  primaryKey: string, // value of field marked as primaryKey in resource configuration
): Promise<boolean>
```

Delete school with ID '1234'

```ts
await admin.resource('schools').delete('1234');
```

## Performance considerations

Remember that AdminForth never creates an indexes on the database, so it is your responsibility to create them whether you need to speed up
the queries created from this Data API or to make AdminForth UI faster.

On low data volumes you will not notice the difference in performance with or without indexes, but on high data volumes it might be very and  very crucial.

Golden rule: create one index per query you are going to use often or where you see the performance issues.

For example if you have two queries:

```ts
const users = await admin.resource('adminuser').list(
  [Filters.NEQ('role', 'Admin')], 15, 0, Sorts.DESC('createdAt')
);
const users = await admin.resource('adminuser').list(
  [Filters.EQ('name', 'John'), Filters.NEQ('role', 'SuperAdmin')]
);
```
You have to create two different indexes:

```sql
CREATE INDEX idx_users_role ON users(role, createdAt);
CREATE INDEX idx_users_name_role ON users(name, role);
```

Create INDEX is just for example, you have to use your migrator / ORM to create indexes in your database.

First one covers performance for the first query, second one for the second query. 
If you did not understand how indexes are created: **get sorted tuple of all fields in filters + all fields in sort,
in order they appear in filters and sort**.

## Get aggregated data from database
The aggregate method allows you to compute statistical summaries over database records instead of returning raw rows. It is useful for building analytics, dashboards, charts, and reporting endpoints.

You can combine:
- filters (to narrow down dataset)
- aggregates (to compute metrics like count, average, sum, median)
- grouping (to split results by field or time periods)
This lets you answer questions like:
- How many apartments are listed per day?
- What is the average price per country?
- What is the total revenue per category?

### Available aggregates
- Aggregates.count()
- Aggregates.countDistinct(field)
- Aggregates.avg(field)
- Aggregates.sum(field)
- Aggregates.min(field)
- Aggregates.max(field)
- Aggregates.median(field)

### Available grouping
- GroupBy.Field(field, as?)
- GroupBy.DateTrunc(field, unit, timezone?, as?)

You can pass either one grouping rule or an array of grouping rules.
When you use a single grouping rule, the grouping value is returned in `group`.
When you use several grouping rules, the values are returned in `group1`, `group2`, etc.

To use explicit response keys that differ from source field names, pass the optional `as` argument to the grouping constructor.
For example, if you want the country group to be returned as `country_name` instead of `country`, pass it as the second `Field` argument.
For `DateTrunc`, pass the explicit response key as the fourth argument:

```ts
GroupBy.Field('country', 'country_name')
GroupBy.DateTrunc('created_at', 'month', 'Europe/Kyiv', 'month_name')
```

Example:
```ts
GroupBy.DateTrunc('created_at', 'month', 'Europe/Kyiv')
```

### Response format
Without grouping, each row contains only requested aggregate aliases:

```ts
[
  {
    count: number | string,
    avgPrice?: number | null,
    sum?: number | null,
    medianPrice?: number | null,
  }
]
```

With one grouping rule:

```ts
[
  {
    group: string,
    count?: number | string,
    avgPrice?: number | null,
    sum?: number | null,
    medianPrice?: number | null,
  }
]
```

With several grouping rules:

```ts
[
  {
    group1: string,
    group2: string,
    count: number | string,
    avgPrice?: number | null,
  }
]
```

With explicit grouping aliases:

```ts
[
  {
    country_name: string,
    month_name: string,
    count: number | string,
    uniqueOwners?: number | string,
    minPrice?: number | null,
    maxPrice?: number | null,
    avgPrice?: number | null,
  }
]
```

### Get daily apartment stats (count, avg, sum, median) for listed apartments
```ts
const rows = await admin.resource('apartments').aggregate(
  Filters.EQ('listed', true),
  {
    count: Aggregates.count(),
    avgPrice: Aggregates.avg('price'),
    sum: Aggregates.sum('price'),
    medianPrice: Aggregates.median('price'),
  },
  GroupBy.DateTrunc('created_at', 'day', 'Europe/Kyiv'),
);
```

What’s happening here:
- Filters.EQ('listed', true)
→ only apartments that are listed (listed = true)
- aggregates:
count() → number of records in each group
avg('price') → average price
sum('price') → total price
median('price') → median price
- GroupBy.DateTrunc('created_at', 'day', 'Europe/Kyiv')
→ groups data by day (with timezone applied)

### Get apartment stats grouped by country
```ts
const rows = await admin.resource('apartments').aggregate(
  [],
  {
    count: Aggregates.count(),
    avgPrice: Aggregates.avg('price'),
    sum: Aggregates.sum('price'),
    medianPrice: Aggregates.median('price'),
  },
  GroupBy.Field('country'),
);
```

What is happening here:
- [] → no filters (all records)
- GroupBy.Field('country')
→ grouping by country
- same aggregates (count, avg, sum, median)

### Get apartment stats grouped by country and month
```ts
const rows = await admin.resource('apartments').aggregate(
  [],
  {
    count: Aggregates.count(),
    uniqueOwners: Aggregates.countDistinct('owner_id'),
    minPrice: Aggregates.min('price'),
    maxPrice: Aggregates.max('price'),
    avgPrice: Aggregates.avg('price'),
  },
  [
    GroupBy.Field('country', 'country_name'),
    GroupBy.DateTrunc('created_at', 'month', 'Europe/Kyiv', 'month_name'),
  ],
);
```

What is happening here:
- [] → no filters (all records)
- GroupBy.Field('country', 'country_name')
→ groups by the `country` field and returns the value in the `country_name` key
- GroupBy.DateTrunc('created_at', 'month', 'Europe/Kyiv', 'month_name')
→ groups by month and returns the value in the `month_name` key
- countDistinct('owner_id') → number of unique owners in each group
- min('price') and max('price') → price range in each group
- the result has one row per country and month combination

---

## Security


Security and privacy if adminforth users is one of the most important aspects of AdminForth.

## How long does user login last?

By default after authentication user session lasts for 24 hours. After that user is redirected to login page.
You can tweak login cookie expiration time by setting environment `ADMINFORTH_AUTH_EXPIRESIN`. For example to set it to 1 hour:

```bash
ADMINFORTH_AUTH_EXPIRESIN=1h
```

Also you can set `auth.rememberMeDuration` in the config to set how long "remember me" logins will last.
For example to set it to 7 days:

```ts ./index.ts
new AdminForth({
  ...
  auth: {
    rememberMeDuration: '7d' // '7d' for 7 days, '24h' for 24 hours, '30m' for 30 minutes, etc.
  }
}
```

In this case users who will check "Remember me" checkbox will be logged in for 7 days instead of 24 hours.

## Login rate limits

AdminForth rate-limits login attempts by client IP using `auth.rateLimit`. Password login, OAuth login, and passkey login use the same configured limits, but each login method has its own independent rate-limit bucket.

By default AdminForth uses:

```ts
['500/5m', '5000/1h', '10000/1d']
```

You can override it in the app config:

```ts ./index.ts
new AdminForth({
  ...
  auth: {
    rateLimit: ['10/5m', '100/1h', '500/1d']
  }
})
```

The format is `requests/period`, where period can use `s`, `m`, `h`, or `d`.
Because rate limits are keyed by client IP, configure `auth.clientIpHeader` when AdminForth runs behind a trusted CDN or reverse proxy. See [Trusting client IP addresses](#trusting-client-ip-addresses).
> It is important to provide '`auth.clientIpHeader`, because otherwise adminforth will automatically detect client IP in headers and if you don't use proxy, hacker can change IP like `x-forwarded-for: 1.1.1.1` in request headers and skip rate limit 

## Password strength

AdminForth allows to set validation RegExp based rules for any field. This can be reused for password strength validation.
[Getting started](../001-gettingStarted.md) guide suggests you to set next parameters for password field:

```ts ./index.ts
  minLength: 8,
  validation: [
    AdminForth.Utils.PASSWORD_VALIDATORS.UP_LOW_NUM,
  ],
```

So when admin user will create another user, password will be validated against next rules:
- At least 8 characters
- At least one uppercase letter
- At least one lowercase letter
- At least one number

For improving requirement you might also request special character:

```ts ./index.ts
  minLength: 8,
  validation: [
    AdminForth.Utils.PASSWORD_VALIDATORS.UP_LOW_NUM_SPECIAL
  ],
```

Also you can add custom rules. For example to prevent popular words:

```ts ./index.ts
  minLength: 8,
  validation: [
    {
      regExp: '^(?!.*(?:qwerty|password|user|login|qwerty|123456)).*$',
      message: 'Password cannot contain easily guessed words'
    },
    AdminForth.Utils.PASSWORD_VALIDATORS.UP_LOW_NUM_SPECIAL,
  ],
```

All rules defined in password column will be also delivered to [password reset plugin](../09-Plugins/07-email-password-reset.md) if you are using it to ensure that password reset will also respect same rules.

## Trusting client IP addresses

Adminforth provides `admin.auth.getClientIp(headers)` function to get client IP address. 

This function is used for:
- Rate limiting in some standard plugins like those who are using OpenAI to protect against abuse
- Securely logging user actions e.g. in Audit Log plugin
- Can be used by your own code e.g. hooks to write first login/last login IP address to db

By default it reads `X-Forwarded-For` header from request headers to determine client IP address. 
AdminForth does not understand whether this header can be trusted or no. In some cases it might be spoofed by client like this:

```
curl -H "X-Forwarded-For: <made-out IP>" http://your-server/api...
```

So you should take additional care to make sure that this header is not spoofed (see below for examples and  best practices depending on your setup).

### Using proxing CDNs

If you are using proxying CDN like Cloudflare in front of your app, which is probably best approach for security and performance, you should do 3 things:

1) Make sure you see "orange cloud icon" in Cloudflare on domain serving app to proxy all traffic through Cloudflare.

2) Set config auth.clientIpHeader to the header that CDN uses to pass client IP address. 
For Cloudflare it is `CF-Connecting-IP`: 

```ts ./index.ts
new AdminForth({
  ...
  auth: {
    clientIpHeader: 'CF-Connecting-IP'
  }
}
```

3) Adittionally ensure that your server is only accepting requests from CDN IP addresses (& ranges) and block all other IPs. For Cloudflare this info is here: https://www.cloudflare.com/ips/ . You can set it in firewall e.g. in AWS security group, or in software firewall like UFW. There is even a script which you can use in cron https://github.com/Paul-Reed/cloudflare-ufw (just in case if list of IPs will change in future).

### Using reverse proxy

If first client-facing point is reverse proxy like Nginx or Traefik and there is no more proxies like CDN behind it, you should take care of reliably setting `X-Forwarded-For` header to the client IP address. 
Main trick here is to make sure that proxy strips any `X-Forwarded-For` headers that are already present in the requeqst and hardly overwrites it with client IP address coming from TCP connection (so it can't be spoofed by client).

In Traefik to set `X-Forwarded-For` header you should set `forwardedHeaders` in traefik config:

```yaml

 adminforth:
    build: ./app
    environment:
      - NODE_ENV=production
      ...
    labels:
//diff-add
    - "traefik.http.middlewares.sanitize-headers.headers.customRequestHeaders.X-Forwarded-For=$remote_addr"
//diff-add
    # enable middleware
//diff-add
    - "traefik.http.routers.adminforth.middlewares=sanitize-headers"
```

For nginx you should set `proxy_set_header X-Forwarded-For $remote_addr;` in your nginx config:

```nginx
server {
    ...
    location / {
        proxy_pass http://localhost:3000;
//diff-add
        proxy_set_header X-Forwarded-For $remote_addr;
    }
}
```

### Backend-only fields

Some fields should never be accessed on frontend. For example, `hashed_password` field which is always created using CLI initial app, should never be passed to frontend due to security reasons.
If any user of system can read `hashed_password` of another user, it can lead to account compromise.

To eliminate it we have 2 options:

1) Do not list `password_hash` in the `columns` array of the resource. Basic mantra: If AdminForth knows nothing about field it will never pass this field to frontend and will never "touch" it in any way.
2) Define `password_hash` in columns way but set `backendOnly`. This allows adminforth to provide full support for this field in backend but will never pass it to frontend.

The second option is more explicit and should be preferred. This option is used by default in CLI-bootstrapped projects:

```ts
{
  name: 'password_hash',
  type: AdminForthDataTypes.STRING,
  showIn: { all: false },
  backendOnly: true,  // will never go to frontend
}
```

#### Dynamically hide fields depending on user ACL / role

You can use `column.showIn` to show or hide column for user depending on his role.

However even if `showIn` value (or value returned by showIn function) is `false`, record value will still go to frontend and will be visible in the Network tab, so advanced user can still access field value. We did it in this way to provide AdminForth developers with ability to quickly use any record field in custom components.

However if you need securely hide only certain fields depending on role, you should use `column.backendOnly` and pass function there.

Let's consider example:

```ts
{
  name: 'email',
  type: AdminForthDataTypes.STRING,
  showIn: { 
//diff-add
    all: false, 
//diff-add
    list: ({ adminUser }: { adminUser: AdminUser }) => adminUser.dbUser.role === 'superadmin',
  },
}
```

So if you will configure the email column in user resource like this, only superadmin will be able to see emails, and only in the list view.
However, the email will still be present in the record and can be accessed by advanced users through the Network tab.

So to completely hide the email field from all users apart superadmins, you should use `column.backendOnly` and pass a function there.

```ts
{
  name: 'email',
  type: AdminForthDataTypes.STRING,
//diff-add
  backendOnly: ({ adminUser }: { adminUser: AdminUser }) => adminUser.dbUser.role === 'superadmin',
  showIn: { 
    all: false, 
    list: ({ adminUser }: { adminUser: AdminUser }) => adminUser.dbUser.role === 'superadmin',
  },
}
```

So if you will configure the email column in user resource like this, only superadmin will be able to see emails, and only in the list view.

## Custom user authorization hook

Default user authorization checks that cookie with JWT token is valid, signed and not expired. 
You can use custom hook to decide whether to allow exections of all default and cusotm API endpoints (wraped by authorize middleware) based on user fields.

```ts title="./index.ts"
export const admin = new AdminForth({

  ...

  auth: {
    adminUserAuthorize: [
      async ({adminUser, adminforth, extra}) => {
        if (adminUser.dbUser.status === 'banned') {
          return { allowed: false, error: "User is banned" };
        }
        return { allowed: true };
      }
    ]
  }

  ...

})

```

Now, if a user’s field `status` is changed to "banned", they won’t be able to perform any actions and moreover  will be automatically logged out upon accessing the page.

## RateLimiter for API

### Import
```ts 
import { RateLimiter } from "adminforth";
```

### Usage
```ts 
import { RateLimiter } from "adminforth";

const UserRateLimiter = new RateLimiter("20/1d");

app.post(
  `${ADMIN_BASE_URL}/api/some-api/`,
  admin.express.authorize(async (req: any, res: any) => {

    const allowed = await UserRateLimiter.consume(req.user.id);

    if (!allowed) {
      res.status(429).json({
        error: "Rate limit exceeded"
      });
      return;
    }

    // your API logic here
  })
);
```

### Limit format
"20/1d"
This means that a user is allowed to make up to 20 requests within one day, and once this limit is reached, any further requests will be blocked until the 24-hour period resets.

### Supported time units
- s → seconds (10s)
- m → minutes (5m)
- h → hours (1h)
- d → days (1d)

> ☝ Сonsume(key) is used to check whether a specific key such as a userId, IP address, or any other identifier has exceeded its allowed request limit. If the limit has not been reached, it returns true, meaning the request is allowed to proceed.

---

## Standard pages tuning


## Fields Grouping
 

In some cases, you may want to organize data fields into specific groups for better structure and clarity. For example, you could create a "Main Info" group to include columns like title, description, country, and apartment_image. Another group, "Characteristics," could hold attributes such as price, square_meter, number_of_rooms, and listed. Any values without a specified group will be categorized under "Other.

```typescript title="./resources/apartments.ts"
export default {
      ...
      options: {
        ...
          //diff-add
        fieldGroups: [
          //diff-add
          {
          //diff-add
            groupName: 'Main info',
          //diff-add
            columns: ['id','title', 'description', 'country']
          //diff-add
          },
          //diff-add
          {
          //diff-add
            groupName: 'Characteristics',
          //diff-add
            columns: ['price', 'square_meter', 'number_of_rooms', "listed"]
          //diff-add
          }
          //diff-add
        ],
      }
    }
```

Here is how it looks:
![alt text](<createEditGroups.png>)

You can hide the group title by setting `noTitle` to `true`.

```typescript title="./resources/apartments.ts"
export default {
      ...
      options: {
        ...
        fieldGroups: [
          {
            groupName: 'Main info',
            columns: ['id','title', 'description', 'country']
          //diff-add
            noTitle: true,
          },
          {
            groupName: 'Characteristics',
            columns: ['price', 'square_meter', 'number_of_rooms', "listed"]
          }
        ],
      }
    }
```

You can also specify on which page you want to create groups.

```typescript title="./resources/apartments.ts"
export default {
      ...
      options: {
        //diff-add
        createFieldGroups: [
          //diff-add
          {
          //diff-add
            groupName: 'Main info',
          //diff-add
            columns: ['id','title']
          //diff-add
          },
          //diff-add
          {
          //diff-add
            groupName: 'Characteristics',
          //diff-add
            columns: ['description', 'country', 'price', 'square_meter', 'number_of_rooms', "listed"]
          //diff-add
          }
          //diff-add
        ],
      }
    }
```
## List

### Default Sorting

```typescript title="./resources/apartments.ts"
import { AdminForthSortDirections } from 'adminforth';

...
export default {
  resourceId: 'aparts',
  options: {
//diff-add
    defaultSort: {
//diff-add
      columnName: 'created_at',
//diff-add
      direction: AdminForthSortDirections.asc, 
//diff-add
    }
  }
}
```

### Sticky column

You can make a column sticky in the list view by setting `listSticky` to `true`. This keeps the column visible when horizontally scrolling through the table, which is particularly useful for important columns like titles or IDs that should always remain in view.

```typescript title="./resources/apartments.ts"
export default {
  resourceId: 'aparts',
  ...
  columns: [
  {
    name: "title",
//diff-add
    listSticky: true,
    ...
  },
  ...
  ]
}
```

>⚠️ Please note that sticky columns can only be applied to one column per resource.

### Custom list column class

You can add a custom CSS class to any list column with `listCssClass`. AdminForth applies it to both the header cell and the data cells for that column.
Static Tailwind utility classes used here are collected into the generated Tailwind safelist during bundling, so you can use normal utility strings in the resource config.

```typescript title="./resources/apartments.ts"
export default {
  resourceId: 'aparts',
  ...
  columns: [
    {
      name: "price",
      listCssClass: "text-right font-semibold min-w-10",
    },
    ...
  ]
}
```

### Conditional display
You can conditionally display columns in forms and views based on the values of other fields in the current record using the `showIf` property. This enables dynamic layouts that automatically adapt to user input, creating more intuitive and context-aware interfaces.

```typescript title="./resources/apartments.ts"
export default {
  resourceId: 'aparts',
  columns: [
    {
      name: 'apartment_type',
      enum: [
        { value: 'studio', label: 'Studio' },
        { value: 'apartment', label: 'Apartment' },
        { value: 'penthouse', label: 'Penthouse' }
      ]
    },
    {
      name: 'number_of_rooms',
      type: AdminForthDataTypes.INTEGER,
//diff-add
      showIf: { apartment_type: { $not: 'studio' } }
    },
    {
      name: 'has_balcony',
      type: AdminForthDataTypes.BOOLEAN,
//diff-add
      showIf: { apartment_type: 'penthouse' }
    }
  ]
}
```

#### Logical Operators

Use `$and` and `$or` operators to create complex conditional logic:

```typescript title="./resources/apartments.ts"
export default {
  columns: [
    {
      name: 'premium_features',
      type: AdminForthDataTypes.JSON,
//diff-add
      showIf: {
//diff-add
        $and: [
//diff-add
          { price: { $gte: 500000 } },
//diff-add
          { apartment_type: { $in: ['penthouse', 'apartment'] } }
//diff-add
        ]
//diff-add
      }
    },
    {
      name: 'discount_reason',
      type: AdminForthDataTypes.STRING,
//diff-add
      showIf: {
//diff-add
        $or: [
//diff-add
          { price: { $lt: 100000 } },
//diff-add
          { listed: false }
//diff-add
        ]
//diff-add
      }
    }
  ]
}
```

#### Comparison Operators

Use various comparison operators for numeric and string fields:

```typescript title="./resources/apartments.ts"
export default {
  columns: [
    {
      name: 'luxury_amenities',
//diff-add
      showIf: { square_meter: { $gt: 100 } }
    },
    {
      name: 'budget_options',
//diff-add
      showIf: { price: { $lte: 200000 } }
    },
    {
      name: 'special_offers',
//diff-add
      showIf: { country: { $nin: ['US', 'GB'] } }
    }
  ]
}
```

#### Array Operators

For fields that contain arrays, use array-specific operators:

```typescript title="./resources/apartments.ts"
export default {
  columns: [
    {
      name: 'pet_policy',
//diff-add
      showIf: { amenities: { $includes: 'pet_friendly' } }
    },
    {
      name: 'security_deposit',
//diff-add
      showIf: { features: { $nincludes: 'furnished' } }
    }
  ]
}
```

#### Available Operators

The following operators are available for use in `showIf` conditions:

**Equality Operators:**
- `$eq` - Equal to (default if no operator specified)
  - `{ price: { $eq: 100000 } }` or `{ price: 100000 }`
- `$not` - Not equal to
  - `{ apartment_type: { $not: 'studio' } }`

**Comparison Operators:**
- `$gt` - Greater than
  - `{ square_meter: { $gt: 100 } }`
- `$gte` - Greater than or equal to
  - `{ price: { $gte: 500000 } }`
- `$lt` - Less than
  - `{ price: { $lt: 100000 } }`
- `$lte` - Less than or equal to
  - `{ price: { $lte: 200000 } }`

**Array Operators:**
- `$in` - Value is in array
  - `{ apartment_type: { $in: ['penthouse', 'apartment'] } }`
- `$nin` - Value is not in array
  - `{ country: { $nin: ['US', 'GB'] } }`
- `$includes` - Array includes value
  - `{ amenities: { $includes: 'pet_friendly' } }`
- `$nincludes` - Array does not include value
  - `{ features: { $nincludes: 'furnished' } }`

**Logical Operators:**
- `$and` - Logical AND operation
  - `{ $and: [{ price: { $gte: 500000 } }, { listed: true }] }`
- `$or` - Logical OR operation
  - `{ $or: [{ price: { $lt: 100000 } }, { listed: false }] }`

> ⚠️ **Warning**: When using `showIf` with complex conditions, ensure that:
> - `$and` and `$or` operators contain arrays of conditions
> - `$in` and `$nin` operators contain arrays of values
> - `$includes` and `$nincludes` operators are only used on columns marked as arrays (`isArray: { enabled: true }`)
### Page size 

use `options.listPageSize` to define how many records will be shown on the page

```typescript title="./resources/apartments.ts"
export default {
      resourceId: 'aparts',
      options: {
        ...
//diff-add
        listPageSize: 10,
      }
    }
  ]
```

### List Page Size Options
You can define available pagination sizes using options.listPageSizeOptions. This allows users to choose how many records they want to see per page in the list view.
```typescript title="./resources/apartments.ts"
export default {
      resourceId: 'aparts',
      options: {
        ...
        listPageSize: 10,
        // listPageSizeOptions can be a static array
        //diff-add
        listPageSizeOptions: [10, 20, 50],
        // OR a function for dynamic options based on user role
        //diff-add
        listPageSizeOptions: ({ adminUser }) => {
          //diff-add
          if (adminUser?.dbUser?.role === 'superadmin') {
            //diff-add
            return [50, 100, 500];
            //diff-add
          }
          //diff-add
          return [10, 20, 50];
          //diff-add
        },
      }
    }
  ]
```
#### How it works
- listPageSize defines the default number of records per page when the list is opened.
- listPageSizeOptions defines the available page size options shown to the user.

For example: listPageSizeOptions: [10, 20, 50] will allow switching between 10 / 20 / 50 records per page.

#### UI behavior
Page size switching is implemented via a select dropdown (select input) in the table pagination controls.
- User opens the select
- Chooses a value (e.g. 20)
- Table reloads with the new page size
> ☝️Notes 
If `listPageSizeOptions` is not provided (or resolves to an empty array), the page size select is not shown. The selected value updates the table immediately and triggers a data refetch. Use `listPageSize` to define the initial number of records per page, and `listPageSizeOptions` to define which page sizes the user can switch between.

### Virtual scroll

Set `options.listVirtualScrollEnabled` to true to enable virtual scrolling in the table. The default value is false. Enable this option if you need to display a large number of records on a single page.

```typescript title="./resources/apartments.ts"
export default {
      resourceId: 'aparts',
      options: {
        ...
//diff-add
        listVirtualScrollEnabled: true,
      }
    }
  ]
```
Additionally, you can configure `options.listBufferSize` to specify the number of rows to buffer for virtual scrolling. The default value is 30 rows.

```typescript title="./resources/apartments.ts"
export default {
      resourceId: 'aparts',
      options: {
        ...
        listVirtualScrollEnabled: true,
//diff-add
        listBufferSize: 20,
      }
    }
  ]
```

### Custom row click action

By default, when you click on a record in the list view, the show view will be opened. 

You can change this behavior by using `options.listTableClickUrl`.

To disable any action (don't open show) return null:

```typescript title="./resources/apartments.ts"
export default {
      resourceId: 'aparts',
      options: {
        ...
//diff-add
        listTableClickUrl: async (record, adminUser, resource) => null,
      }
    }
  ]
```

To open a custom page, return URL to the custom page (can start with https://, or relative adminforth path):

```typescript title="./resources/apartments.ts"
      options: {
        ...
//diff-add
        listTableClickUrl: async (record, adminUser, resource) => {
//diff-add
          return `https://google.com/search?q=${record.title}`;
//diff-add
        }
      }
```

If you wish to open the page in a new tab, add `target=_blank` get param to the returned URL:

```typescript title="./resources/apartments.ts"
      options: {
        ...
//diff-add
        listTableClickUrl: async (record, adminUser, resource) => {
//diff-add
          return `https://google.com/search?q=${record.name}&target=_blank`;
//diff-add
        }
      }
```

### How to open edit instead of show by click in list table
By using `options.listTableClickUrl` you can open edit view by clicking record, instead of show view:

```ts
      options: {
        ...
        //diff-add
        listTableClickUrl: async (record, adminUser, resource) => {
        //diff-add
          return `/resource/${resource.resourceId}/edit/${record[pkFileldName]}`;
        //diff-add
        }
      }
```

### Auto-refresh records

`options.listRowsAutoRefreshSeconds` might be used to silently refresh records that are loaded (no new records will be fetched if
they appear)
  
```typescript title="./resources/apartments.ts"
export default {
        resourceId: 'aparts',
        hooks: {
//diff-add
          list: {
//diff-add
            afterDatasourceResponse: async ({ response }: { response: any }) => { 
//diff-add
              response.forEach((r: any) => {
//diff-add
                // substitute random country on any load
//diff-add
                const countries = [ 'US', 'DE', 'FR', 'GB', 'NL', 'IT', 'ES', 'DK', 'PL', 'UA', 
//diff-add
                  'CA', 'AU', 'BR', 'JP', 'CN', 'IN', 'KR', 'TR', 'MX', 'ID']
//diff-add
                r.country = countries[Math.floor(Math.random() * countries.length)];
//diff-add
              })
//diff-add
              return { ok: true, error: "" }
//diff-add
            }
//diff-add
          }
        },
        options: {
          ...
//diff-add
          listRowsAutoRefreshSeconds: 1,
        }
      }
  ]
  ```

  ![alt text](<silent refresh.gif>)

### Move base actions out of three dots menu

If you want to move base record actions from the three dots menu, you can add `baseActionsAsQuickIcons`:

```ts
  options: {
    
    ...
    
    baseActionsAsQuickIcons: ['edit'],

    ...

  }
```

And `edit` action will be available as quick action:

![alt text](<threeDotsListMenu.png>)
      

     

## Show

### Next record button

By default, when a user opens a record from the list view, a **Next** button appears on the show page. It allows navigating through records one by one, respecting the current filters and sorting applied in the list. When the user reaches the last record on the current page, AdminForth automatically fetches the next page and continues navigation seamlessly.

To disable the Next button for a resource, set `showNextButton` to `false`:

```typescript title="./resources/apartments.ts"
export default {
  resourceId: 'aparts',
  options: {
//diff-add
    showNextButton: false,
  }
}
```

> ☝️ The Next button is only shown when the user navigates to the show page from the list view. Opening a record directly via URL will not display the button.

## Creating

### Fill with default values

Sometimes you want to generate some field value without asking user to fill it. For example createdAt oftenly store time of creation of the record. You can do this by using `fillOnCreate`:

```typescript title="./resources/apartments.ts" 

export default {
      name: 'apartments',
      fields: [
        ...
        {
          name: 'created_at',
          type: AdminForthDataTypes.DATETIME,
//diff-add
          showIn: {
//diff-add
            all: true,
//diff-add
            create: false,  // don't show field in create form
//diff-add
          },
//diff-add
          fillOnCreate: ({ initialRecord, adminUser }) => (new Date()).toISOString(),
        },
      ],
    },
    ...
  ],
```

Also you can assign adminUser ID by `adminUser.dbUser.id`:

```typescript title="./resources/apartments.ts"
export default {
      name: 'apartments',
      fields: [
        ...
        {
          name: 'created_by',
          type: AdminForthDataTypes.STRING,
//diff-add
          showIn: {
//diff-add
            all: true,
//diff-add
            create: false,  // don't show field in create form
//diff-add
          },
//diff-add
          fillOnCreate: ({ initialRecord, adminUser }) => adminUser.dbUser.id,
        },
      ],
    },
    ...
  ],
```

> Same effect can be achieved by using [hooks](/docs/tutorial/Customization/hooks/#example-modify-the-created-object-before-it-is-saved-to-the-database). But `fillOnCreate` might be shorter and more readable.

### Suggest default value in create form

You can suggest a default value for a field in the create form which user can instantly change even before creating record.
This might be used to give user some example value or to suggest some default value.

```typescript title="./resources/apartments.ts"
export default {
      name: 'apartments',
      fields: [
        ...
        {
          name: 'description',
//diff-add
          suggestOnCreate: 'Great apartment in the heart of the city',
        },
      ],
    },
    ...
```

A difference between `fillOnCreate` and `suggestOnCreate`:

* `fillOnCreate` is called on the backend when the record is saved to a database. Value returned by `fillOnCreate` will be saved to the database. 
* `suggestOnCreate` is just a single value that will be substituted in create form. User can change it before saving the record.
* `fillOnCreate` should be used when `showIn.create` is a `false` value because if it is `true`, the input will be shown in the create form but then(during actual save to db) it will be overwritten by the value returned by `fillOnCreate`.
* `suggestOnCreate` should be used with `showIn.create` set to true because if it is not set, the input will not be shown in the create form and default suggestion will not make sense.

### Normalize values before saving

Use the column-level `normalize` callback when a value must always be stored in a canonical form. For example, you can trim an email address and make it lowercase:

```typescript title="./resources/adminuser.ts"
export default {
  resourceId: 'adminuser',
  columns: [
    // ...
    {
      name: 'email',
      required: true,
      isUnique: true,
      type: AdminForthDataTypes.STRING,
//diff-add
      normalize: (value: string) => value.trim().toLowerCase(),
    },
  ],
};
```

AdminForth applies `normalize` on the backend whenever the column is present in a create or update payload. This includes records saved from the admin UI and records written with the [Data API](/docs/tutorial/Customization/dataApi). Normalization happens before backend validation and `beforeSave` hooks, so both receive the normalized value.

When `normalize` is configured on the column selected by `auth.usernameField`, AdminForth also normalizes the submitted username before looking up the user. The [Email Password Reset plugin](/docs/tutorial/Plugins/email-password-reset) applies the normalizer configured on its `emailField` throughout the reset flow as well. In the example above, a user saved as `admin@example.com` can therefore sign in or request a password reset with `  ADMIN@EXAMPLE.COM  `.

`normalize` does not transform existing database records or general filter/search values. Migrate existing data first if it is not already stored in the same canonical form.

### Link to create form with preset values

Sometimes you might need to create a link that will open the create form with some fields pre-filled. For example, you might want to create a link that will open the create form with the realtor_id field pre-filled with the current user's ID.

```html title="./resources/Dashboard.vue
<template>
  ...
  <LinkButton
    :to="{
      name: 'resource-create',
      params: {
        resourceId: 'aparts',
      },
      query: {
        values: atob_function(JSON.stringify({
          realtor_id: coreStore?.adminUser.dbUser.id 
        })),
      },
    }"
  >
    {{$t('Create new apartment')}}
  </LinkButton>
  ...
</template>

<script setup lang="ts">
import { LinkButton } from '@afcl';
import { useCoreStore } from '@/stores/core';
import { btoa_function } from '@/utils';

const coreStore = useCoreStore();
</script>
```

ALso if you want to disable ability to change such fields (but keep them as readonly) you can add `readonlyColumns` to the link:

```html title="./resources/Dashboard.vue
<template>
  ...
  <LinkButton
    :to="{
      name: 'resource-create',
      params: {
        resourceId: 'aparts',
      },
      query: {
        values: (JSON.stringify({
          realtor_id: coreStore?.adminUser.dbUser.id 
        })),
        //diff-add
        readonlyColumns: (JSON.stringify(['realtor_id'])),
      },
    }"
  >
    {{$t('Create new apartment')}}
  </LinkButton>
  ...
```

## Editing

You can set a column `editReadonly` so it will be shown in the edit form but will be disabled.  
This might be useful to better identify the record during editing or to show some additional information that should not be changed but can help to edit the record.

```typescript title="./resources/apartments.ts"
export default {
      name: 'apartments',
      fields: [
        ...
        {
          name: 'created_at',
          type: AdminForthDataTypes.DATETIME,
//diff-add
          editReadonly: true,
        },
      ],
    },
    ...
  ],
``` 

> `editReadonly` is check enforced both on fronted and backend. So it is safe to use it to make sure that data will be never changes.

### minValue and maxValue

You can add `minValue` and `maxValue` limits to columns, so it will show an error below an input when entered value is out of bounds.

```typescript title="./resources/apartments.ts"
export default {
      name: 'apartments',
      columns: [
        ...
        {
          name: 'square_meter',
          label: 'Square',
          minValue: 3,
          maxValue: 1000,
        },
      ],
    },
    ...
  ],
```

> `minValue` and `maxValue` checks are enforced both on frontend and backend.

### Input prefix and suffix

You can add prefix or suffix to inputs by adding `inputPrefix` or `inputSuffix` fields to a column.

```typescript title="./resources/users.ts"
export default {
      name: 'users',
      columns: [
        ...
        {
          name: "price",
          inputSuffix: "USD",
          allowMinMaxQuery: true,
        },
      ],
    },
    ...
  ],
```

These fields can only be used with following `AdminForthDataTypes`: `DECIMAL`, `FLOAT`, `INTEGER`, `STRING` and `JSON` (only if `JSON` column is an array with appropriate `itemType`).

### Editing note

You can add `editingNote` to a column to show a note below the input field.

```typescript title="./resources/adminuser.ts"
export default {
      name: 'adminuser',
      columns: [
        ...
        {
          name: "password",
          editingNote: { edit: "Leave empty to keep password unchanged" },
        },
      ],
    },
    ...
  ],
```

### Filling an array of values

Whenever you want to have a column to store not a single value but an array of values you have to set column as `AdminForthDataTypes.JSON`. This way when you are creating or editing a record you can type in a JSON array into a textfield. To simplify this process and allow you to create and edit separate items you can add `isArray` to a column.

```typescript title="./resources/adminuser.ts"
export default {
      name: 'adminuser',
      columns: [
        ...
        {
          name: "room_sizes",
          type: AdminForthDataTypes.JSON,
//diff-add
          isArray: {
//diff-add
            enabled: true,
//diff-add
            itemType: AdminForthDataTypes.FLOAT,
//diff-add
          },
        },
      ],
    },
    ...
  ],
```

Doing so, will result in UI displaying each item of the array as a separate input corresponding to `isArray.itemType` on create and edit pages.

`itemType` value can be any of `AdminForthDataTypes` except `JSON` and `TEXT`.

By default it is forbidden to store duplicate values in an array column. To change that you can add `allowDuplicateItems: true` to `isArray`, like so:

```typescript title="./resources/adminuser.ts"
export default {
      name: 'adminuser',
      columns: [
        ...
        {
          name: "room_sizes",
          type: AdminForthDataTypes.JSON,
          isArray: {
            enabled: true,
            itemType: AdminForthDataTypes.FLOAT,
//diff-add
            allowDuplicateItems: true,
          },
        },
      ],
    },
    ...
  ],
```

All validation rules, such as `minValue`, `maxValue`, `minLength`, `maxLength` and `validation` will be applied not to array itself but instead to each item.

Note: array columns can not be marked as `masked`, be a `primaryKey` and at the time can not be linked to a foreign resource.

### Foreign resources

When you want to create a connection between two resources, you need to add `foreignResource` to a column, like so:

```typescript title="./resources/adminuser.ts"
export default {
      name: 'adminuser',
      columns: [
        ...
        {
          name: "realtor_id",
          foreignResource: {
            resourceId: 'adminuser',
          },
        },
      ],
    },
    ...
  ],
```

This way, when creating or editing a record you will be able to choose value for this field from a dropdown selector and on list and show pages this field will be displayed as a link to a foreign resource.

### Unset label

When foreign resource column is not required, selector will have an 'Unset' option that will set field to `null`. You can change label for this option using `unsetLabel`, like so:

```typescript title="./resources/apartments.ts"
export default {
      name: 'apartments',
      columns: [
        ...
        {
          name: "realtor_id",
          foreignResource: {
            resourceId: 'adminuser',
//diff-add
            unsetLabel: 'No realtor',
          },
        },
      ],
    },
    ...
  ],
```

### Searchable fields 

Enable search in filter dropdown by specifying which fields to search:

```typescript title="./resources/apartments.ts"
export default {
      name: 'apartments',
      columns: [
        ...
        {
          name: "realtor_id",
          foreignResource: {
            resourceId: 'adminuser',
//diff-add
            searchableFields: ["id", "email"], 
//diff-add
            searchIsCaseSensitive: true, // default false
          },
        },
      ],
    },
    ...
  ],
```

### Polymorphic foreign resources

Sometimes it is needed for one column to be a foreign key for multiple tables. For example, given the following schema:

```prisma title="./schema.prisma"
...
model apartments {
  id                String     @id
  created_at        DateTime?
  title             String
  square_meter      Float?
  price             Decimal
  number_of_rooms   Int?
  realtor_id        String?
}

model houses {
  id                  String     @id
  created_at          DateTime?
  title               String
  house_square_meter  Float?
  land_square_meter   Float?
  price               Decimal
  realtor_id          String?
}

model sold_property {
  id                  String     @id
  created_at          DateTime?
  title               String
  property_id         String
  realtor_id          String?
}

```

Here, in `sold_property` table, column `property_id` can be a foreign key for both `apartments` and `houses` tables. If schema is set like this, the is no way to tell to what table exactly `property_id` links to. Also, if defined like usual, adminforth will link to only one of them. To make sure that `property_id` works as intended we need add one more column to `sold_property` and change the way foreign resource is defined in adminforth resource config.

```prisma title="./schema.prisma"
...

model sold_property {
  id                  String     @id
  created_at          DateTime?
  title               String
//diff-add
  property_type       String
  property_id         String
  realtor_id          String?
}

```

`property_type` column will be used to store what table id in `property_id` refers to. And in adminforth config for `sold_property` table, when describing `property_id` column, foreign resource field should be defined as follows:

```typescript title="./resources/sold_property.ts"
export default {
      name: 'sold_property',
      columns: [
        ...
        {
          name: "property_type",
          showIn: { create: false, edit: false },
        },
        {
          name: "property_id",
          foreignResource: {
            polymorphicResources: [
              {
                resourceId: 'apartments',
                whenValue: 'apartment',
              },
              {
                resourceId: 'houses',
                whenValue: 'house',
              },
            ],
            polymorphicOn: 'property_type',
          },
        },
      ],
    },
    ...
  ],
```

When defined like this, adminforth will use value in `property_type` to figure out to what table does id in `property_id` refers to and properly link them. When creating or editing a record, adminforth will figure out to what table new `property_id` links to and fill `property_type` on its own using corresponding `whenValue`. Note, that `whenValue` does not have to be the same as `resourceId`, it can be any string as long as they do not repeat withing `polymorphicResources` array. Also, since `whenValue` is a string, column designated as `polymorphicOn` must also be string. Another thing to note is that, `polymorphicOn` column (`property_type` in our case) must not be editable by user, so it must include both `create` and `edit` as `false` in `showIn` value. Even though, `polymorphicOn` column is no editable, it can be beneficial to set is as an enumerator. This will have two benefits: first, columns value displayed in table and show page can be changed to a desired one and second, when filtering on this column, user will only able to choose values provided for him.

If `beforeDatasourceRequest` or `afterDatasourceResponse` hooks are set for polymorphic foreign resource, they will be called for each resource in `polymorphicResources` array.

## Validation (create/edit view)
In cases when column values must follow certain format, you can add `validation` to it.
`validation` is an array of rules, each containing `regExp` or `validator function` that defines a format for a value and `message` that will be displayed in case when entered value does not pass the check.

### Frontend validation
We recommend to use this validation with regExp, because it validates fields in real time

```typescript title="./resources/adminuser.ts"
export default {
      name: 'adminuser',
      columns: [
        ...
        {
          name: 'email',
          required: true,
          isUnique: true,
          //diff-add
          validation: [
            //diff-add
            {
              //diff-add
              regExp: '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$',
              //diff-add
              message: 'Email is not valid, must be in format example@test.com',
              //diff-add
            },
            //diff-add
          ],
        },
      ],
    },
    ...
  ],
```

### Backend validation
There might be rare cases, when you want to have your own validation function. For this you can use `validator` callback:
```typescript title="./resources/adminuser.ts"
export default {
      name: 'adminuser',
      columns: [
        ...
        {
          name: 'email',
          required: true,
          isUnique: true,
          //diff-add
          validation: [
            //diff-add
            {
              //diff-add
              async validator(value: any, record: any) {
                //diff-add
                if (value.endsWith("@example.com")) {
                  //diff-add
                  return { isValid: false, message: 'Your email can`t end with `@example.com`' };
                  //diff-add
                }
                //diff-add
                return { isValid: true }
                //diff-add
              }
              //diff-add
            }
            //diff-add
          ],
        },
      ],
    },
    ...
  ],
```

>Avoid using a custom validator because every time you change a field (after a failed first save attempt), it will make an API call.

## Filtering

### Filter Options

You can specify the delay between filtering requests and filtering operator for a column using `filterOptions` field.

```typescript title="./resources/adminuser.ts"
export default {
      name: 'adminuser',
      columns: [
        ...
        {
          name: "title",
          required: true,
          maxLength: 255,
          minLength: 3,
//diff-add
          filterOptions: {
//diff-add
            debounceTimeMs: 500,
//diff-add
            substringSearch: false,
//diff-add
          },
        },
      ],
    },
    ...
  ],
```
`debounceTimeMs` field dictates how long (in milliseconds) to wait between inputs to send updated data request. By increasing this value, you can reduce the amount of requests set to backend. Default value for this field is set to 10ms.
`substringSearch` sets what comparison operator to use for text field. By default this field is set to `true`, which results in using case-insensitive `ILIKE` operator, that will look for records that have filter string anywhere inside field value. Setting this `substringSearch` to `false` will result in using more strict `EQ` operator, that will look for exact full-string matches.

You can also disabled multiselect on filter page for enumerator columns or foreign resource columns by adding `multiselect` field:

```typescript title="./resources/adminuser.ts"
export default {
      name: 'adminuser',
      columns: [
        ...
        {
          name: "parentUserId",
          foreignResource: {
            resourceId: "users",
          },
//diff-add
          filterOptions: {
//diff-add
            multiselect: false,
//diff-add
          },
        },
      ],
    },
    ...
  ],
```
This way, multiselect field displayed on filter page will be replaced with a default select field allowing only a single value to be selected.

---

## AdminForth Components Library


AFCL is a set of components which you can use as build blocks in your AdminForth application. 
AFCL allows to keep the design consistent with minimal efforts and build new pages faster.
AFCL components follow styling standard and respect theme colors.

Components set is always growing, so you can expect new components to be added in the future.

## Button

  
```js
import { Button } from '@/afcl'
```

```html
<Button @click="doSmth" 
    :loader="false" class="w-full">
  Your button text
</Button>

<Button @click="doSmth" 
    :loader="true" class="w-full mt-4">
  Your button text
</Button>
```

![AFCL Button](image-63.png)

loader prop would show loader when it's true.

### Variant

The `variant` prop controls the button style. Possible values are `primary` (default), `secondary` and `danger`.

  

```html
<Button @click="doSmth">
  Primary button
</Button>

<Button @click="doSmth" variant="secondary" class="mt-4">
  Secondary button
</Button>

<Button @click="doSmth" variant="danger" class="mt-4">
  Danger button
</Button>
```
  

> ☝️ The `mode` prop is deprecated, use `variant` instead.

## Button Group
### With active button

```ts
import { IconGridSolid, IconUserCircleSolid } from '@iconify-prerendered/vue-flowbite';
import { ButtonGroup } from '@/afcl'

const activeButton = ref('')

    ...

<ButtonGroup v-model="activeButton">  
  <template #button:Profile>
    
      <IconUserCircleSolid class="w-5 h-5 me-2"/>
      Profile
    
  </template>
  <template #button:Dashboard>
    
      <IconGridSolid class="w-5 h-5 me-2"/>
      Board
    
  </template>
</ButtonGroup>
```

![AFCL Button-group](ButtonGroup1.png)

### With solid color

```ts
  import { ButtonGroup } from '@/afcl'
  import { IconPlusOutline, IconCaretDownSolid } from '@iconify-prerendered/vue-flowbite';

    ...

    <ButtonGroup :solidColor="true">
        <template #button:Profile>
            
                <IconPlusOutline class="w-5 h-5 me-2"/>
                Add Local Passkey
            
        </template>
        <template #button:Dropdown>
            
                <IconCaretDownSolid class="w-5 h-5"/>
            
        </template>
    </ButtonGroup>

```

![AFCL Button-group](ButtonGroup2.png)

## Link

  

```js
import { Link } from '@/afcl'
```

```html
<Link to="/login">Go to login</Link>
```

![AFCL Link](image-58.png)

## LinkButton

Looks like button but works like link. Uses `router-link` under the hood.

  
```js
import { LinkButton } from '@/afcl'
```

```html
<LinkButton to="/login">Go to login</LinkButton>
```

![AFCL LinkButton](image-59.png)

## Select

```js
import { Select } from '@/afcl'

const selected = ref(null)
```

### Single

  
```html
<Select
  class="w-full"
  :options="[
    {label: 'Last 7 days', value: '7'}, 
    {label: 'Last 30 days', value: '30'}, 
    {label: 'Last 90 days', value: '90'},
    {label: 'None', value: null}
  ]"
  v-model="selected"
></Select>
```

![AFCL Select](image-60.png)

### Multiple

  

```js
//diff-remove
const selected = ref(null)
//diff-add
const selected = ref([])
```

```html
<Select
  class="w-full"
  :options="[
    {label: 'Last 7 days', value: '7'}, 
    {label: 'Last 30 days', value: '30'}, 
    {label: 'Last 90 days', value: '90'},
    {label: 'None', value: null}
  ]"
  v-model="selected"
//diff-add
  multiple
></Select>
```
  
  
  ![AFCL Select](image-61.png)
  

### Custom slots for item

You can customize item and selected item using slots.

  
```html
<Select
  class="w-full"
  :options="[
    {label: 'Last 7 days', value: '7', records: 110},
    {label: 'Last 30 days', value: '30', records: 320},
    {label: 'Last 90 days', value: '90', records: 310},
    {label: 'None', value: null}
  ]"
  v-model="selected"
>
//diff-add
  <template #item="{option}">
//diff-add
    
//diff-add
      {{ option.label }}
//diff-add
      {{ option.records }} records
//diff-add
    
//diff-add
  </template>
//diff-add
  <template #selected-item="{option}">
//diff-add
    {{ option.label }} 💫
//diff-add
  </template>
</Select>
```
  
  
    ![AFCL Select custom item](image-79.png)
  

### Extra item

You might need to put some extra item at bottom of list

  
```html
<Select
  class="w-full"
  :options="[
    {label: 'Last 7 days', value: '7'}, 
    {label: 'Last 30 days', value: '30'}, 
    {label: 'Last 90 days', value: '90'},
  ]"
  v-model="selected"
>
//diff-add
  <template #extra-item>
//diff-add
    <LinkButton to="/ranges">Manage ranges</LinkButton>
//diff-add
  </template>

</Select>
```
  
  
   ![AFCL Select extra item](image-45.png)
  

### Add classes to the input directly

You might need to put some extra item at bottom of list

  
```html
<Select
  class="w-full"
  :options="[
    {label: 'Last 7 days', value: '7'}, 
    {label: 'Last 30 days', value: '30'}, 
    {label: 'Last 90 days', value: '90'},
  ]"
  v-model="selected"
  //diff-add
  classesForInput="py-[4px] text-sm bg-white rounded"
>

</Select>
```
  
  
   ![AFCL Select](image-99.png)
  

## Input

  
```js
import { Input } from '@/afcl'
```

```html
<Input type="number" class="w-full">
  <template #suffix>
    USD
  </template>
</Input>
```

  
  
    ![AFCL Input](image-46.png)
  

  
```js
import { Input } from '@/afcl'
import { IconSearchOutline } from '@iconify-prerendered/vue-flowbite'
```

```html
<Input type="text" class="w-full">
  <template #rightIcon>
    <IconSearchOutline class="w-5 h-5 text-gray-400"/>
  </template>
</Input>
```

  
  
    ![AFCL Input](inputRightIcon.png)
  

## Textarea

  
```ts
import { Textarea } from '@/afcl'
```

```ts
    <Textarea
      v-model="textAreaInput"
      placeholder="Enter some text..."
      class="w-64"
    />
```
  
  
    ![AFCL Textarea](textarea.png)
  

## Tooltip
  
Wrap an element on which you would like to show a tooltip with the `Tooltip` component and add a `tooltip` slot to it.
  

  

```js
import { Tooltip } from '@/afcl'
```

```html
<Tooltip>
    
        <IconCardSearch class="w-5 h-5 me-2"/>
    

    <template #tooltip>
        Search for AdminForth
    </template>
</Tooltip>
```
  
  
    ![AFCL Tooltip](image-47.png)
  

## VerticalTabs

Wrap each tab lable in tamplate with v-slot value `tab:TAB_ALIAS`. Wrap each tab content in tamplate with v-slot value `TAB_ALIAS`. `TAB_ALIAS` is a unique identifier for each tab here. Place all templates inside `VerticalTabs` component.

```js
import { VerticalTabs } from '@/afcl'
import { IconGridSolid, IconUserCircleSolid } from '@iconify-prerendered/vue-flowbite';
```

  
  ```html
  <VerticalTabs>
    <template #tab:Profile>
      <IconUserCircleSolid class="w-5 h-5 me-2"/>
      Profile
    </template>
    <template #tab:Dashboard>
      <IconGridSolid class="w-5 h-5 me-2"/>
      Board
    </template>
    <template #Profile>
      Profile Tab
      This is some placeholder content the Profile tab's associated content
    </template>
    <template #Dashboard>
      Dashboard Tab Content 
    </template>
  </VerticalTabs>
  ```
  
  
  ![AFCL VerticalTabs](image-77.png)
  

## Checkbox

  

```ts
import { Checkbox } from '@/afcl'
const enable = ref(false)
```

```html
<Checkbox v-model="enable">
  Enable
</Checkbox>
```
  
  
  ![AFCL Checkbox](image-62.png)
  

## Card 

### Custom card
If you need custom card, you can make it without 

```ts
<Card>
  Total Profit
  $100,000
</Card>
```

![AFCL Checkbox](Card3.png)

### Standart card

```ts
import { Card } from '@/afcl'

  ...

  <Card
    title="This is a large card"
    description="Description text for large card. This is a large card. Very nice card. Big one. You can put here any content you want."
  >
  </Card>

  <Card
    size="md"
    title="This is a medium card"
    description="Description text for medium card. This is a medium card. Very nice card. Big one. You can put here any content you want."
  >
  </Card>

  <Card
    size="sm"
    title="This is a small card"
    description="Description text for small card. This is a small card. Very nice card. Big one. You can put here any content you want."
  >
  </Card>
```
![AFCL Checkbox](Card2.png)

## Toggle

  

```ts
import Toggle from '@/afcl/Toggle.vue';
```

```html
  <Toggle 
    :disabled="false" 
    @update:modelValue="toggleSwitchHandler"> 
    Click me 
  </Toggle>
```
  
  
  ![AFCL Checkbox](image-94.png)
  

## Dialog (Pop-up)

  

```ts
import { Dialog } from '@/afcl';
import { Button } from '@/afcl';
```

```html
<Dialog class="w-96">
  <template #trigger>
    <Button>Dialog Toggle</Button>
  </template>

  
    This is the first paragraph of dialog content.
    And this is the second paragraph.
  
</Dialog>
```
  
  
  ![AFCL Dialog](image-87.png)
  

### Header
You can add header to the dialog by using header prop.

  

```html
//diff-remove
<Dialog class="w-96">
//diff-add
<Dialog
//diff-add
  class="w-96"
//diff-add
  header="Dialog Header"
//diff-add
>
  <template #trigger>
    <Button>Dialog Toggle</Button>
  </template>

  
    This is the first paragraph of dialog content.
    And this is the second paragraph.
  
</Dialog>
```
  
  
  ![AFCL Dialog](image-88.png)
  

If you want to remove close button in header, you can add `:header-close-button="false"` prop to `<Dialog>`.

### Buttons
By default dialog will have just one "Close" button. If you want to change that, you can set `buttons` to a desirable array.

  
  
```html
<Dialog
  class="w-96"
  header="Dialog Header"
//diff-add
  :buttons="[
//diff-add
    { label: 'Save', onclick: (dialog) => { doSave(); dialog.hide(); } },
//diff-add
    { label: 'Close', onclick: (dialog) => dialog.hide() },
//diff-add
  ]"
>
  <template #trigger>
    <Button>Dialog Toggle</Button>
  </template>

  
    This is the first paragraph of dialog content.
    And this is the second paragraph.
  
</Dialog>
```
  
  
  ![AFCL Dialog](image-89.png)
  

Dialog component will render each button using afcl `Button` component. You can pass any props to those buttons by adding `options` field to a button item.

  
  
```html
<Dialog
  class="w-96"
  header="Dialog Header"
  :buttons="[
//diff-remove
    { label: 'Save', onclick: (dialog) => { doSave(); dialog.hide(); } },
//diff-add
    {
//diff-add
      label: 'Save',
//diff-add
      options: {
//diff-add
        disabled: savingIsAllowed,
//diff-add
      },
//diff-add
      onclick: (dialog) => { doSave(); dialog.hide(); },
//diff-add
    },
    { label: 'Close', onclick: (dialog) => dialog.hide() },
  ]"
>
  <template #trigger>
    <Button>Dialog Toggle</Button>
  </template>

  
    This is the first paragraph of dialog content.
    And this is the second paragraph.
  
</Dialog>
```
  
  
  ![AFCL Dialog](image-90.png)
  

### Dialog persistence
Default behavior of the Dialog component will allow user to close it by just clicking outside. You can prevent that by setting `clickToCloseOutside` to `false`.

  
  
```html
<Dialog
  class="w-96"
  header="Dialog Header"
  :buttons="[
    {
      label: 'Save',
      options: {
        disabled: savingIsAllowed,
      },
      onclick: (dialog) => { doSave(); dialog.hide(); },
    },
    { label: 'Close', onclick: (dialog) => dialog.hide() },
  ]"
//diff-add
  :click-to-close-outside="false"
>
  <template #trigger>
    <Button>Dialog Toggle</Button>
  </template>

  
    This is the first paragraph of dialog content.
    And this is the second paragraph.
  
</Dialog>
```
  
  
  

### Programatically open or close dialog

If you want to control dialog programmatically, you can use `ref` to get a reference to the dialog component. 

```html
<Dialog ref="confirmDialog" class="w-96">
  
    The dialog content goes here.
  
</Dialog>
```

Now you can open and close dialog by calling `open` and `close` methods.

```ts

const confirmDialog = ref(null);

const openDialog = () => {
  confirmDialog.value.open();
}

const closeDialog = () => {
  confirmDialog.value.close();
}
```

### Before open/close dialog handlers
If you want to run custom logic before the dialog opens or closes by passing callback props:

```ts
<Dialog 
  class="w-96" 
  :beforeCloseFunction="onBeforeOpen" 
  :beforeOpenFunction="onBeforeClose"
>
  <template #trigger>
    <Button>Dialog Toggle</Button>
  </template>

  
    This is the first paragraph of dialog content.
    And this is the second paragraph.
  
</Dialog>
```
Now you can pass before open/close functions:
```ts
const counter = ref(0);

function onBeforeOpen() {
  counter.value++;
  console.log(`custom open function called ${counter.value}`);
}

function onBeforeClose() {
  counter.value++;
  console.log(`custom close function called ${counter.value}`);
}
```

### Ask for extra confirmation before close

If you want dialog to ask user for conformation when he tryes to close dialog, you can add: 

```ts
<Dialog 
  ref="confirmDialog" 
  class="w-96"
  //diff-add
  :closable="false"
  //diff-add
  :askForCloseConfirmation="true"
  //diff-add
  closeConfirmationText='Are you sure you want to close this dialog?',
>
  
    The dialog content goes here.
  
</Dialog>
```

## Dropzone

```ts
import { Ref } from 'vue'
import { Dropzone } from '@/afcl'

const files: Ref<File[]> = ref([])

watch(files, (files) => {
  console.log('files selected', files);
  setTimeout(() => {
    // clear
    files.length = 0;
  }, 5000);
})
```

  

```html
<Dropzone
  :extensions="['.jpg', '.jpeg', '.png']"
  :maxSizeBytes="1024 * 1024 * 2"
  :multiple="false"
  v-model="files"
/>

```
  
  
    ![AFCL Dropzone](image-50.png)
  

## Table

  

```ts
import { Table } from '@/afcl'
```

```html

```
  
  
    ![AFCL Table](image-51.png)
  

### No even highlights

  

```html

```
  
  
    ![AFCL Table withut even highlights](image-52.png)
  

### Custom cell

```ts
import { Table } from '@/afcl'
const isoFlagToEmoji = (iso) => iso.toUpperCase().replace(/./g, char => String.fromCodePoint(char.charCodeAt(0) + 127397))
```

  

```html

//diff-add
  <template #cell:country="{item}">
//diff-add
    {{ isoFlagToEmoji(item.country) }}
//diff-add
  </template>

```
  
  
    ![AFCL Table with custom cell](image-78.png)
  

### Custom header

  
```html
        
//diff-add
<template #header:country>
//diff-add
    🌍 Geo
//diff-add
</template>

```
  
  
    ![AFCL Table with custom header](image-55.png)
  

### Pagination

Table provides front-end side pagination. You can set `pageSize` (default is 10) to set how many rows to show per page.
If there is less then `pageSize` rows, pagination will not be shown.

  

```html

```
  
  
  ![AFCL Table with pagination](image-56.png)
  

### Server-side pagination

To load pages dynamically, simply pass async callback to data:

```ts
async function loadPageData(data) {  
  const { offset, limit } = data;
  // in real app do await callAdminForthApi or await fetch to get date, use offset and limit value to slice data
  return {
    data: [
      { name: 'John', age: offset, country: 'US' },
      { name: 'Rick', age: offset+1, country: 'CA' },
      { name: 'Alice', age: offset+2, country: 'BR' },
    ],
    total: 3 // should return total amount of records in database
  }
}

 

```
> 👆 The page size is used as the limit for pagination.

### Sorting

Table supports column sorting out of the box.

- By default, columns are NOT sortable. Enable sorting per column with `sortable: true`.
- Clicking a sortable header cycles sorting in a tri-state order:
  - none → ascending → descending → none
  - When it returns to "none", the sorting is cleared.

Basic example (client-side sorting when `data` is an array):
```html

```

You can also predefine a default sort:

```html

```

Notes:
- Client-side sorting supports nested field paths using dot-notation, e.g. `user.name`.
- When a column is not currently sorted, a subtle double-arrow icon is shown; arrows switch up/down for ascending/descending.

#### Nested field path sorting

You can sort by nested properties of objects in rows using dot-notation in `fieldName`.

Example:

```html

```

Behavior details:
- The path is split on dots and resolved step by step: `user.address.city`.
- Missing or `null` nested values are pushed to the bottom for ascending order (and top for descending) because `null/undefined` are treated as greater than defined values in asc ordering.
- Works the same for client-side sorting and for server-side loaders: when using an async loader the same `sortField` (e.g. `user.address.city`) is passed so you can implement equivalent ordering on the backend.
- Date objects at nested paths are detected and compared chronologically.
- Numeric comparison is stable for mixed numeric strings via Intl.Collator with numeric option.

Edge cases to consider in your own data:
- Deeply missing branches like `user.profile.settings.locale` simply result in `undefined` and will follow the null ordering logic above.
- Arrays are not traversed; if you need array-specific sorting you should pre-normalize data into scalar fields before passing to the table.

### Server-side sorting

When you provide an async function to `data`, the table will pass the current sort along with pagination params.

Signature of the loader receives:

```ts
type LoaderArgs = {
  offset: number;
  limit: number;
  sortField?: string; // undefined when unsorted
  sortDirection?: 'asc' | 'desc'; // only when sortField is set
}
```

Example using `fetch`:

```ts
async function loadPageData({ offset, limit, sortField, sortDirection }) {
  const url = new URL('/api/products', window.location.origin);
  url.searchParams.set('offset', String(offset));
  url.searchParams.set('limit', String(limit));
  if (sortField) url.searchParams.set('sortField', sortField);
  if (sortField && sortDirection) url.searchParams.set('sortDirection', sortDirection);

  const { data, total } = callAdminForthApi('getProducts', {limit, offset, sortField, sortDirection});
  return { data, total };
}

```

Events you can listen to:

```html
 currentSortField = f"
  @update:sortDirection="(d) => currentSortDirection = d"
  @sort-change="({ field, direction }) => console.log('sort changed', field, direction)"
/>
```

### Table loading states

For tables where you load data externally and pass them to `data` prop as array (including case with front-end pagination) you might want to show skeleton loaders in table externaly using `isLoading` props.

For tables with server-side paganation which use async function in data prop you can listen for `@update:tableLoading` to get table internal loading state, in other words this event will let you know when server side function started and finished execution, so you might use it e.g. to disable some external filter buttons and so on.

```ts
import { Table, Button } from "@/afcl"
const isTableLoading = ref(false);
const tableState = ref("loading");

  ...

   loading === true ? tableState = 'loading' : tableState = 'loaded'"
  >
  

   Table state: {{ tableState }} 

  <Button @click="isTableLoading.value=!isTableLoading.value"> Toggle loading state</Button>
```
  ![AFCL Table](TableLoading.png)

### Making header and pagination sticky

If you want to make table header or pagination, you can add `makeHeaderSticky`, `makePaginationSticky`

```
  
```

### Don't block pagination on loading

Sometimes you might want to allow user switch between pages, even if old request wasn't finished. For these porpuses you can use `blockPaginationOnLoading` and `abortSignal` in data callback:
```ts
 

...

async function loadPageData(data, abortSignal) {  
  const { offset, limit } = data;
  // in real app do await callAdminForthApi or await fetch to get date, use offset and limit value to slice data
  await new Promise(resolve => setTimeout(resolve, offset === 500)) // simulate network delay
  if (abortSignal.abort) return; // since result won't be displayed, we stop computing
  
  return {
    data: [
      { name: 'John', age: offset, country: 'US' },
      { name: 'Rick', age: offset+1, country: 'CA' },
      { name: 'Alice', age: offset+2, country: 'BR' },
    ],
    total: 30 // should return total amount of records in database
  }
}

```

## ProgressBar

  
  ```html
   <ProgressBar
    :currentValue="2600"
    :minValue="0"
    :maxValue="5000"
    />
  ```
  
  
  ![ProgressBar](image-81.png)
  

### Custom labels

Custom labels in the ProgressBar component allow you to customize the text displayed on the left and right sides of the progress bar. You can also customize the format of the value and the progress text.

  
  ```html
  <ProgressBar
    :currentValue="1070"
    :minValue="0"
    :maxValue="5000"
    :leftLabel="'Level 2'"
    :rightLabel="'Level 3'"
    :formatter="(value: number) => `${value} points`"
    :progressFormatter="(value: number, percentage: number) => `${value} done`"
  />
  ```
  
  
  ![ProgressBar](image-80.png)
  

### Show progress animation

  
  ```html
   <ProgressBar
    :currentValue="2600"
    :minValue="0"
    :maxValue="5000"
    showAnimation
    />
  ```
  
  
  ![ProgressBar](image-96.png)
  

### Change height of the progress bar

  
  ```html
   <ProgressBar
    :currentValue="2600"
    :minValue="0"
    :maxValue="5000"
    height='6'
    />
  ```
  
  
  ![ProgressBar](image-97.png)
  

## Skeleton

Skeleton component is used to display a loading state for a component. You can use prop `type` to set the type of the skeleton.

  
  ```html
    
      <Skeleton class="w-full h-4" />
      <Skeleton class="w-full h-2" />
      <Skeleton class="w-full h-2" />
      <Skeleton class="w-full h-2" />
      <Skeleton class="w-full h-2" />
    
  ```
  
  
  ![Spinner](image-82.png)
  

### Skeleton image

  
  ```html
  <Skeleton type="image" class="w-full h-full" />
  ```
  
  
  ![Skeleton type](image-83.png)
  

### Skeleton input

  
  ```html
    
      <Skeleton type="input" class="w-full h-4" />
      <Skeleton type="input" class="w-full h-2" />
      <Skeleton type="input" class="w-full h-2" />
      <Skeleton type="input" class="w-full h-2" />
      <Skeleton type="input" class="w-full h-2" />
    
  ```
  
  
  ![Spinner](image-100.png)
  

### Skeleton video

  
  ```html
  <Skeleton type="video" class="w-full h-full" />
  ```
  
  
  ![Skeleton type video](image-84.png)
  

### Skeleton avatar

  
  ```html
  <Skeleton type="avatar" class="w-20 h-20" />
  ```
  
  
  ![Skeleton avatar](image-85.png)
  

## Spinner

Spinner component is used to display a loading state for a component.

  
  ```html
  <Spinner class="w-10 h-10" />
  ```
  
  
  ![Spinner](image-86.png)
  

## Country Flag

The Country Flag component displays national flags using ISO 3166-1 alpha-2 country codes.

  
  ```html
  <CountryFlag countryCode="ua" />
  ```
  
  
  ![Country Flag](image-92.png)
  

## Bar Chart

Under the hood AdminForth uses MIT-licensed [ApexCharts](https://apexcharts.com/). It has very rich variety of options, you can pass
any of native settings to `options` prop. Here we will only show some basics.

  
```html
<BarChart
  :data="[
    { count: 1, x: '02 Jun 2025'}, 
    { count: 5, x: '03 Jun 2025'}, 
    { count: 3, x: '04 Jun 2025'}, 
    { count: 4, x: '05 Jun 2025'}, 
    { count: 2, x: '06 Jun 2025'}, 
  ]"
  :series="[{
    name: $t('Added apartments'),
    fieldName: 'count',
    color: '#4E79A7',
  }]"
  :options="{
    chart: {
      height: 250,
    },
  }"
/>
```
  
  
    ![Bar chart](image-64.png)
  

### Y-axis labels

  
```html
<BarChart
  :data="[
    { count: 1, x: '02 Jun 2025'}, 
    { count: 5, x: '03 Jun 2025'}, 
    { count: 3, x: '04 Jun 2025'}, 
    { count: 4, x: '05 Jun 2025'}, 
    { count: 2, x: '06 Jun 2025'}, 
  ]"
  :series="[{
    name: $t('Added apartments'),
    fieldName: 'count',
    color: '#4E79A7',
  }]"
  :options="{
    chart: {
      height: 250,
    },
//diff-add
    yaxis: {
//diff-add
      stepSize: 1, // needed if your data is integer
//diff-add
      labels: {
//diff-add
        show: true,
//diff-add
        style: {
//diff-add
          fontFamily: 'Inter, sans-serif',
//diff-add
          cssClass: 'text-xs font-normal fill-gray-500 dark:fill-gray-400'
//diff-add
        }
//diff-add
      }
//diff-add
    }
  }"
/>
```
  
  
  ![BarChart y Axis labels](image-65.png)
  

### X-axis labels and formatting labels

  
```html
<BarChart
  :data="[
    { count: 1, x: '02 Jun 2025'}, 
    { count: 5, x: '03 Jun 2025'}, 
    { count: 3, x: '04 Jun 2025'}, 
    { count: 4, x: '05 Jun 2025'}, 
    { count: 2, x: '06 Jun 2025'}, 
  ]"
  :series="[{
    name: $t('Added apartments'),
    fieldName: 'count',
    color: '#4E79A7',
  }]"
  :options="{
    chart: {
      height: 250,
    },
//diff-add
    xaxis: {
//diff-add
      labels: {
//diff-add
        show: true,
//diff-add
        formatter: function (value) {
//diff-add
          return dayjs(value).format('DD MMM');
//diff-add
        },
//diff-add
        style: {
//diff-add
          fontFamily: 'Inter, sans-serif',
//diff-add
          cssClass: 'text-xs font-normal fill-gray-500 dark:fill-gray-400'
//diff-add
        }
//diff-add
      }
//diff-add
    }
  }"
/>
```
  
  
  ![BarChart x Axis labels](image-66.png)
  

### Grid

  
```html
<BarChart
  :data="[
    { count: 1, x: '02 Jun 2025'}, 
    { count: 5, x: '03 Jun 2025'}, 
    { count: 3, x: '04 Jun 2025'}, 
    { count: 4, x: '05 Jun 2025'}, 
    { count: 2, x: '06 Jun 2025'}, 
  ]"
  :series="[{
    name: $t('Added apartments'),
    fieldName: 'count',
    color: '#4E79A7',
  }]"
  :options="{
    chart: {
      height: 250,
    },
//diff-add
    grid: {
//diff-add
      show: true,
//diff-add
      borderColor: 'rgba(0, 0, 0, 0.1)',
//diff-add
      strokeDashArray: 4, 
//diff-add
      position: 'back',
//diff-add
      xaxis: {
//diff-add
        lines: {
//diff-add
          show: true
//diff-add
        }
//diff-add
      },
//diff-add
      yaxis: {  
//diff-add
        lines: {
//diff-add
          show: true
//diff-add
        }
//diff-add
      }
//diff-add
    }
  }"
/>
```
  
  
  ![BarChart grid](image-67.png)
  

### Data labels

  
```html
<BarChart
  :data="[
    { count: 1, x: '02 Jun 2025'}, 
    { count: 5, x: '03 Jun 2025'}, 
    { count: 3, x: '04 Jun 2025'}, 
    { count: 4, x: '05 Jun 2025'}, 
    { count: 2, x: '06 Jun 2025'}, 
  ]"
  :series="[{
    name: $t('Added apartments'),
    fieldName: 'count',
    color: '#4E79A7',
  }]"
  :options="{
    chart: {
      height: 250,
    },
//diff-add
    dataLabels: {
//diff-add
      formatter: function (value) {
//diff-add
        return `⬆️ ${value}`;
//diff-add
      },
//diff-add
      enabled: true,
//diff-add
      style: {
//diff-add
        fontSize: '12px',
//diff-add
        fontFamily: 'Inter, sans-serif',
//diff-add
      }
//diff-add
    }
  }"
/>
```
  
  
  ![BarChart data labels](image-36.png)
  

### Stacked bars and legend

  
```html
<BarChart
  :data="[
    { countCars: 2, countBikes: 3, x: '02 Jun 2025'}, 
    { countCars: 5, countBikes: 1, x: '03 Jun 2025'}, 
    { countCars: 3, countBikes: 4, x: '04 Jun 2025'}, 
    { countCars: 4, countBikes: 2, x: '05 Jun 2025'}, 
    { countCars: 2, countBikes: 3, x: '06 Jun 2025'},
  ]"
  :series="[
    {
      name: $t('Cars'),
      fieldName: 'countCars',
      color: '#4E79A7',
    },
    {
      name: $t('Bikes'),
      fieldName: 'countBikes',
      color: '#F28E2B',
    }
  ]"
  :options="{
    chart: {
      height: 250,
//diff-add
      stacked: true,
    },
//diff-add
    legend: {
//diff-add
      show: true,
//diff-add
    },
  }"
/>
```
  
  
  ![BarChart stacked bars](image-37.png)
  

### Horizontal bars

  
```html
<BarChart
  :data="[
    { countCars: 2, countBikes: 3, x: '02 Jun 2025'}, 
    { countCars: 5, countBikes: 1, x: '03 Jun 2025'}, 
    { countCars: 3, countBikes: 4, x: '04 Jun 2025'}, 
    { countCars: 4, countBikes: 2, x: '05 Jun 2025'}, 
    { countCars: 2, countBikes: 3, x: '06 Jun 2025'},
  ]"
  :series="[
    {
      name: $t('Cars'),
      fieldName: 'countCars',
      color: '#4E79A7',
    },
    {
      name: $t('Bikes'),
      fieldName: 'countBikes',
      color: '#F28E2B',
    }
  ]"
  :options="{
    chart: {
      height: 250,
      type: 'bar',
    },
//diff-add
    plotOptions: {
//diff-add
      bar: {
//diff-add
        horizontal: true,
//diff-add
      }
//diff-add
    },
    legend: {
      show: true,
    },
  }"
/>
```
  
  
![BarChart horizontal bars](image-38.png)
  

## Area Chart

```ts
import { AreaChart } from '@/afcl'
```

  
```html
<AreaChart
  :data="[
    { count: 1, x: '02 Jun 2025'}, 
    { count: 5, x: '03 Jun 2025'}, 
    { count: 3, x: '04 Jun 2025'}, 
    { count: 4, x: '05 Jun 2025'}, 
    { count: 2, x: '06 Jun 2025'}, 
  ]"
  :series="[{
    name: $t('Added apartments'),
    fieldName: 'count',
    color: '#4E79A7',
  }]"
  :options="{
    chart: {
      height: 250,
    },
  }"
/>

  
  ![AreaChart](image-68.png)
  

### Multiple lines

  
```html
<AreaChart
  :data="[
    { countCars: 2, countBikes: 3, x: '02 Jun 2025'}, 
    { countCars: 5, countBikes: 1, x: '03 Jun 2025'}, 
    { countCars: 3, countBikes: 4, x: '04 Jun 2025'}, 
    { countCars: 4, countBikes: 2, x: '05 Jun 2025'}, 
    { countCars: 2, countBikes: 3, x: '06 Jun 2025'},
  ]"
  :series="[
    {
      name: $t('Cars'),
      fieldName: 'countCars',
      color: '#4E79A7',
    },
    {
      name: $t('Bikes'),
      fieldName: 'countBikes',
      color: '#F28E2B',
    }
  ]"
  :options="{
    chart: {
      height: 250,
    },
  }"
/>
```
  
  
  ![AreaChart multiple lines](image-70.png)
  

### Stacked area

  
```html
<AreaChart
  :data="[
    { countCars: 2, countBikes: 3, x: '02 Jun 2025'}, 
    { countCars: 5, countBikes: 1, x: '03 Jun 2025'}, 
    { countCars: 3, countBikes: 4, x: '04 Jun 2025'}, 
    { countCars: 4, countBikes: 2, x: '05 Jun 2025'}, 
    { countCars: 2, countBikes: 3, x: '06 Jun 2025'},
  ]"
  :series="[
    {
      name: $t('Cars'),
      fieldName: 'countCars',
      color: '#4E79A7',
    },
    {
      name: $t('Bikes'),
      fieldName: 'countBikes',
      color: '#F28E2B',
    }
  ]"
  :options="{
    chart: {
      height: 250,
//diff-add
      stacked: true,
    },
  }"
/>
```
  
  
  ![AreaChart stacked area](image-69.png)
  

### Data labels

  
```html
<AreaChart
  :data="[
    { count: 2, x: '02 Jun 2025'}, 
    { count: 5, x: '03 Jun 2025'}, 
    { count: 3, x: '04 Jun 2025'}, 
    { count: 4, x: '05 Jun 2025'}, 
    { count: 2, x: '06 Jun 2025'},
  ]"
  :series="[
    {
      name: $t('Cars'),
      fieldName: 'count',
      color: '#4E79A7',
    },
  ]"
  :options="{
    chart: {
      height: 250,
    },
    dataLabels: {
      enabled: true,
      style: {
        fontSize: '12px',
        fontFamily: 'Inter, sans-serif',
      }
    },
    grid: {
      padding: {
        left: 10, // to fit the labels
        right: 10,
      },
    },
  }"
/>
```
  
  
  ![Area Chart Data Lables](image-71.png)
  

### Grid, x-axis and y-axis labels

See [Bar Chart](#bar-chart) for details, the config is the same.

## Pie Chart

```ts
import { PieChart } from '@/afcl'
```

### Basic

  
```html
<PieChart
  :data="[
    { amount: 5, label: 'Cars'},
    { amount: 3, label: 'Bikes'},
    { amount: 2, label: 'Trucks'},
    { amount: 1, label: 'Boats'},
  ]"
  :options="{
    chart: {
      height: 250,
    },
  }"
/>
```
  
  
  ![Pie Chart](image-75.png)
  

### Pie with data labels

  
```html
<PieChart
  :data="[
    { amount: 5, label: 'Cars'},
    { amount: 3, label: 'Bikes'},
    { amount: 2, label: 'Trucks'},
    { amount: 1, label: 'Boats'},
  ]"
  :options="{
    chart: {
      height: 250,
    },
//diff-add
    dataLabels: {
//diff-add
      enabled: true,
//diff-add
    },
//diff-add
    plotOptions: {
//diff-add
      pie: {
//diff-add
        dataLabels: {
//diff-add
          offset: -10, // Moves labels closer to or further from the slices
//diff-add
          minAngleToShowLabel: 10, // Ensures that small slices don't show labels
//diff-add
        },
//diff-add
        expandOnClick: true,
// diff-add
      },
// diff-add
    },
  }"
/>
```
  
  
  ![Pie Chart with data labels](image-76.png)
  

### Donut Chart

  
```html
<PieChart
  :data="[
    { amount: 5, label: 'Cars'},
    { amount: 3, label: 'Bikes'},
    { amount: 2, label: 'Trucks'},
    { amount: 1, label: 'Boats'},
  ]"
  :options="{
    chart: {
      height: 250,
  //diff-add
      type: 'donut',
    },
  }"
/>
```
  
  
  ![Donut Chart](image-72.png)
  

### Fill donut with total info

  
```html
<PieChart
  :data="[
    { amount: 5, label: 'Cars'},
    { amount: 3, label: 'Bikes'},
    { amount: 2, label: 'Trucks'},
    { amount: 1, label: 'Boats'},
  ]"
  :options="{
    chart: {
      height: 250,
      type: 'donut',
    },
//diff-add
    plotOptions: {
//diff-add
      pie: {
//diff-add
        donut: {
//diff-add
          labels: {
//diff-add
            total: {
//diff-add
              show: true,
//diff-add
              label: $t('Total wheels'),
//diff-add
              formatter: () => `11`,
//diff-add
            },
//diff-add
          },
//diff-add
        },
//diff-add
      },
    },
  }"
/>
```
  
  
  ![Donut Chart with total](image-73.png)
  

### Radial bar chart

  
```html
  <PieChart
  :data="[
    { amount: 80, label: 'Cars'},
    { amount: 50, label: 'Bikes'},
    { amount: 30, label: 'Trucks'},
    { amount: 70, label: 'Boats'},
  ]"
  :options="{
    chart: {
//diff-add
      height: '300px',
//diff-add
      width: '100%',
//diff-add
      type: 'radialBar',
//diff-add
      sparkline: {
//diff-add
        enabled: true,
//diff-add
      },
//diff-add
    },
//diff-add
    plotOptions: {
//diff-add
      radialBar: {
//diff-add
        track: {
//diff-add
          background: '#E5E7EB',
//diff-add
        },
//diff-add
        dataLabels: {
//diff-add
          name: {
//diff-add
            offsetY: -10
//diff-add
          },
//diff-add
          value: {
//diff-add
            offsetY: 2,
//diff-add
          }
//diff-add
        },
//diff-add
        hollow: {
//diff-add
          margin: 0,
//diff-add
          size: '32%',
//diff-add
        }
//diff-add
      },
//diff-add
    },
//diff-add
    legend: {
//diff-add
      show: true,
//diff-add
      position: 'bottom',
//diff-add
    },
    
  }"
/>
```
  
  
  ![Radial Chart](image-74.png)
  

## Treemap Chart

This example is based on the ApexCharts treemap demo “color range”.

  

```ts
import { TreeMapChart } from '@/afcl'

const deltaToColor = (delta: number) => {
  if (delta < -10) return '#B91C1C' // bright red
  if (delta < 0) return '#EF4444'   // red
  if (delta <= 10) return '#22C55E' // green
  return '#15803D'                 // very green
}

const formatDelta = (delta: number) => (delta > 0 ? `+${delta}%` : `${delta}%`)

const data = [
  { x: 'New Delhi', value: 218, delta: 12 },
  { x: 'Kolkata', value: 149, delta: -4 },
  { x: 'Mumbai', value: 184, delta: -14 },
  { x: 'Ahmedabad', value: 55, delta: 6 },
  { x: 'Bangalore', value: 84, delta: 9 },
  { x: 'Pune', value: 31, delta: -2 },
  { x: 'Chennai', value: 70, delta: 0 }
]

// Optional: precompute per-point color using delta
const dataWithColors = data.map((item) => ({
  ...item,
  fillColor: deltaToColor(item.delta),
}))

const series = [
  { name: 'Desktops', fieldName: 'value' },
]
```

```html
<TreeMapChart
  :data="dataWithColors"
  :series="series"
  :options="{
    chart: { height: 350 },
    dataLabels: {
      formatter: (text, { seriesIndex, dataPointIndex, w }) => {
        const point = w?.config?.series?.[seriesIndex]?.data?.[dataPointIndex]
        if (!point) return text
        return `${text} ${formatDelta(point.delta)}`
      },
    },
    plotOptions: {
      treemap: {
        distributed: false,
        enableShades: false,
      },
    },
    tooltip: {
      y: {
        formatter: (value, { seriesIndex, dataPointIndex, w }) => {
          const point = w?.config?.series?.[seriesIndex]?.data?.[dataPointIndex]
          if (!point) return value
          return `${point.value} (${formatDelta(point.delta)})`
        },
      },
    },
  }"
/>
```

  
  
  ![Treemap Chart](image-28.png)
  

## Mixed Chart

```ts
import { MixedChart } from '@/afcl'
```

### Basic

  
  ```html
  <MixedChart
    :data="[
      { x: '02 Jun 2025', avgPrice: 100, listedPrice: 100, unlistedPrice: 100},
      { x: '03 Jun 2025', avgPrice: 280, listedPrice: 130, unlistedPrice: 200},
      { x: '04 Jun 2025', avgPrice: 150, listedPrice: 90, unlistedPrice: 60},
      { x: '05 Jun 2025', avgPrice: 100, listedPrice: 100, unlistedPrice: 100},
      { x: '06 Jun 2025', avgPrice: 200, listedPrice: 290, unlistedPrice: 180},
      { x: '07 Jun 2025', avgPrice: 100, listedPrice: 100, unlistedPrice: 100},
    ]"
    :series="[
      { name: $t('Avg Price'), fieldName: 'avgPrice', type: 'line', color: COLORS[0] },
      { name: $t('Listed Price'), fieldName: 'listedPrice', type: 'column', color: COLORS[1] },
      { name: $t('Unlisted Price'), fieldName: 'unlistedPrice', type: 'area', color: COLORS[2] },
      
    ]"
    :options="{
      chart: {
        height: 350,
      },
      stroke: {
        width: [6, 0, 6],  // Line: 6px, Column: 0px (no border), Area: 6px
      },
      fill: {
        opacity: [1, 0.85, 0.25], // Line: 1, Column: 0.85, Area: 0.25
      },
    }"
  />
  ```

  
    ![Mixed Chart](image-91.png)
  

## Json Viewer

```ts
import { JsonViewer } from '@/afcl'
```

### Basic

  
  ```html
      <JsonViewer 
      :value="[
        {
          id: 1,
          name: 'Alice',
          meta: {
            age: 30,
            hobbies: ['reading', 'biking'],
          }
        },
        {
          id: 2,
          name: 'Bob',
        }
      ]" 
      :expandDepth="2" 
    />
  ```

  
    ![JSON Viewer](image-93.png)
  

## Modal

  

```ts
import { Modal, Button } from '@/afcl';
```

```html
  <Modal class="w-96" :closeByClickOutside="true" :closeByEsc="true" askForCloseConfirmation >
    <template #trigger>
      <Button>Modal Toggle</Button>
    </template>

    
      This is the first paragraph of modal content.
      And this is the second paragraph.
    
  </Modal>
```
  
  
  ![AFCL Dialog](image-98.png)
  

### Props: 
```ts
  closeByClickOutside?: boolean  // Close on click outside of modal (default is true)
  closeByEsc?: boolean // Close on Esc button click (default is true)
  beforeCloseFunction?: (() => void | Promise<void>) | null // Callback, that will be executed before open
  beforeOpenFunction?: (() => void | Promise<void>) | null // Callback, that will be executed before close
  askForCloseConfirmation?: boolean // Show extra popup to confirm close ( to avoid close by accident)
  closeConfirmationText?: string // Text that will be shown on close confirmation popup
  removeFromDomOnClose?: boolean // Remove modal from DOM on close ( default is false )
  backgroundCustomClasses?: string // allows to add custom classes to the gray background of modal (e.g. you can have bg-pink-500/60)
  modalCustomClasses?: string // allows to add custom classes to modal popup
```

## Date picker

```ts
import { DatePicker } from '@/afcl';
const datePickerValue = ref()
```

### Basic

```html
<DatePicker
  v-model:valueStart="datePickerValue"
  :column="{ type: 'datetime' }"
  label="Pick start"
/>
```

  
    ![Date Picker](image-95.png)

---

## Websocket


AdminForth provide own build-in websocket interface which allows to stream some data to frontend from backend.

If in production you run through a reverse proxy such as Nginx, ensure websocket upgrade is enabled on the `/afws` path under your AdminForth base URL, otherwise websocket will not work. See [Deploy in Docker > Nginx version](/docs/tutorial/deploy#nginx-version).

In two words, to subscribe to a topic from any frontend component you need to do next

```javascript
import websocket from '@/websocket';

const unsubscribe = websocket.subscribe('/topic-name', (data) => {
  // this callback called when we receive publish in topic from the websocket
  console.log(data);
});

// later, for example when the component is unmounted
unsubscribe();
```

On server you can publish data to the topic by calling

```javascript
admin.websocket.publish('/topic-name', {some: 'data'});
```

If you need to unsubscribe from a whole family of topics, for example when route changes can leave old dynamic subscriptions behind, you can use `unsubscribeByPrefix`:

```javascript
import websocket from '@/websocket';

websocket.unsubscribeByPrefix('/topic-name/');
```

This will unsubscribe from all topics whose name starts with the prefix.

It is useful for dynamic topics like `/topic-name/<resourceId>/<recordId>` where a stale subscription can update the wrong page if component unmount does not happen exactly when you expect.

Let's consider a real-world example.

## Usage example

Let's say we want to show realtor sum of all his properties in the AdminForth in header.

Create a component `PropertyCost.vue`:

```html title="./custom/PropertyCost.vue"
<template>
  
      <Tooltip>
        <template #tooltip>
          Your total property cost
        </template>
        <IconDollarOutline class="text-2xl opacity-50" />
         {{totalCost}}
      </Tooltip>
  
</template>

<script setup lang="ts">
import { onMounted, onUnmounted, Ref } from 'vue';
import { ref } from 'vue';
import websocket from '@/websocket';
import { IconDollarOutline } from '@iconify-prerendered/vue-flowbite';
import { Tooltip } from '@/afcl';

import type { AdminUser } from '@/types/Common';

const props = defineProps({
  adminUser: AdminUser,
});

const totalCost: Ref<number|null> = ref(null);
let unsubscribePropertyCost: (() => void) | undefined;

onMounted(() => {
  unsubscribePropertyCost = websocket.subscribe(`/property-cost/${props.adminUser!.pk}`, (data: any) => {
    // this callback called when we receive publish in topic from the websocket
    totalCost.value = data.totalCost;
  });
});

onUnmounted(() => {
  unsubscribePropertyCost?.();
});

</script>
```

Add this component into the header of the AdminForth:

```javascript title="./index.ts"
...
const admin = new AdminForth({
  ...
  customization: {
    ...
//diff-add      
    globalInjections: {
//diff-add
      header: '@@/PropertyCost.vue',
//diff-add
    }
  }
});
```

Now, in after-save hook on apartments we will calculate the sum price of all apartments for the realtor and send it to the frontend.

```javascript title="./resources/apartment.ts"
hooks: {
//diff-add
  edit: {
//diff-add
    afterSave: async ({ record, adminUser, resource, adminforth }) => {
//diff-add
      //  if realtor id is set, recalculate total cost of all apartments
//diff-add
      if (record.realtor_id) {
//diff-add
        const totalCost = (await adminforth.resource('aparts').list(Filters.EQ('realtor_id', record.realtor_id)))
//diff-add
          .map((r) => r.price).reduce((a, b) => a + b, 0);
//diff-add
        adminforth.websocket.publish(`/property-cost/${record.realtor_id}`, { type: 'message', totalCost });
//diff-add
      }
//diff-add
      return { ok: true }
//diff-add
    }
//diff-add
  },
}
```

### Initial loading

If you will try to load the page now it would not show up initial cost, but should show it once you re-save apartment.

To fix this we can do 2 ways:
- Create a dedicated API to load initial cost on PropertyCost component mount
- Catch connection to websocket, parse `realtor_id` from the topic and stream initial cost

Second way is more elegant and we will use it.

```javascript title="./index.ts"
...

const admin = new AdminForth({
  ...
  auth: {
//diff-add
    websocketSubscribed: async (topic, adminUser) => {
//diff-add
      const [subject, param] = /^\/(.+?)\/(.+)/.exec(topic)!.slice(1);
//diff-add
      if (subject === 'property-cost') {
//diff-add
        const userId = param;
//diff-add
        const totalCost = (await admin.resource('aparts').list(Filters.EQ('realtor_id', userId)))
//diff-add
          .map((r) => r.price).reduce((a, b) => a + b, 0);
//diff-add
        admin.websocket.publish(topic, { type: 'message', totalCost });
//diff-add
      }
//diff-add
    }
  }
  ...
});

```

> 👆 Please not that `adminUser` might be undefined in `websocketSubscribed` callback if unauthorized client subscribes to `/opentopic/` (see authorization section below)

### Subscribing authorization

Currently, any user can subscribe to the any topic and receive published messages.

However you can prevent some users from subscribing to some topics and prevent them to get data streamed to the topic. Or vise-versa you can prevent all users and allow only some users to subscribe to the topic.

In our example though topic already has user id in it, we should explicitly check that user can subscribe to his own topic using `config.auth.websocketTopicAuth`

```javascript title="./index.ts"
...

const admin = new AdminForth({
  ...
  auth: {
//diff-add
    websocketTopicAuth: async (topic: string, adminUser: AdminUser) => {
//diff-add
      if (!adminUser) {
//diff-add
        // don't allow anonymous users to subscribe
//diff-add
        return false;
//diff-add
      }
//diff-add
      const [subject, param] = /^\/(.+?)\/(.+)/.exec(topic)!.slice(1);
//diff-add
      logger.info(`Websocket user ${adminUser.username} tries to subscribe to topic ${subject} with param ${param}`);
//diff-add
      if (subject === 'property-cost') {
//diff-add
        return param === adminUser.dbUser.id;
//diff-add
      }
//diff-add
      // any other events are not allowed
//diff-add
      return false;
//diff-add
    },
    websocketSubscribed:...
  }
  ...
});
  
``` 

There is still method to bypass this websocketTopicAuth check by using special topic `/opentopic/`. In other words if topic starts with `/opentopic/` it will be allowed to subscribe by any user bypassing `websocketTopicAuth` call at all.
Internally AdminForth uses `/opentopic/` for menu badges and possibly for other internal purposes.

### Publish authorization

Best way to secure the data published to websoket is use websocketTopicAuth method. It will be called once on subscription and if it will not allow access it will completely prevent user from subscribing to the topic.

However you can move auth check to publish call. It has a third parameter of publish function. Imagine you rewrite `websocketTopicAuth` to allow all users to subscribe to any topic:

```typescript title="./index.ts"
...
websocketTopicAuth: async (topic: string, adminUser: AdminUser) => {
  return true;
},
...
```

(Or you are using `/opentopic/`)

Now you can move the check to publish call:

```typescript title="./index.ts"

admin.websocket.publish(topic, { type: 'message', totalCost }, async (adminUser: AdminUser): Promise<boolean> => {
  return adminUser.dbUser.id === record.realtor_id;
});

```

In this case during publish call it will check all users who subscribed to the topic and do actual publish to only those who are allowed to receive the message. This method requires more CPU resources and generally is not recommended.

---

## Connectors


## General logic
The connectors is distributed as a separate package and loaded by AdminForth automatically.
You do not need to instantiate or import the connector manually in your app config.

AdminForth resolves connectors by datasource URL scheme, so when it sees `sqlite://...` it tries to load `@adminforth/connector-sqlite`.

## Setup
### SQLite
```bash
pnpm add @adminforth/connector-sqlite
```

That is enough for connector wiring because connectors are integrated through the peer dependency system.

### Postgres
```bash
pnpm add @adminforth/connector-postgres
```

### MySQL
```bash
pnpm add @adminforth/connector-mysql
```
### Clickhouse
```bash
pnpm add @adminforth/connector-clickhouse
```

### Mongo
```bash
pnpm add @adminforth/connector-congo
```

### Qdrant
```bash
pnpm add @adminforth/connector-qdrant
```

## How peer dependency loading works

AdminForth keeps connectors optional and attempts to import only the connector that matches your datasource type.

For SQLite this means:

1. You set datasource URL to `sqlite://...`
2. AdminForth attempts to import `@adminforth/connector-sqlite`
3. Connector is used automatically for schema discovery and CRUD operations

No extra connector registration is required in the usual setup.

---

## Deploy in Docker


In general you can already run your `index.ts` file which we created in [Getting Started](/docs/tutorial/001-gettingStarted.md)
with `ts-node` command in any node environment.

It will start the server on configured HTTP port and you can use any proxy like Traefik/Nginx to expose it to the internet and add SSL Layer.

## Dockerfile

If you created your AdminForth application with `adminforth create-app` command you already have a `Dockerfile` in your project.

You can use it to build your AdminForth application in Docker container.

> ⚠️ Please note that `Dockerfile` has `npx adminforth bundle` command which pre-bundles your AdminForth SPA
> at build time. If you will remove it, your AdminForth application will still work, but will cause some downtime during app restart/redeploy because bundling will happen at runtime after you start the `index.ts` file. When `npx adminforth bundle` command is executed at build time, the call do `bundleNow()` inside of `index.ts` file will actually do nothing.

## Building the image

> Make sure that you have database url in your .env.prod file

Now you can build your image:

```bash
docker build -t myadminapp .
```

And run container with:

```bash
docker run -p 3500:3500 \
  -e ADMINFORTH_SECRET=CHANGEME \
  -v $(pwd)/db:/code/db \
  myadminapp
```

> `-v $(pwd)/db:/code/db` is needed only if you are using SQLite database.
> Pay attention, that ADMINFORTH_SECRET environment should be in deployed app as well

Now open your browser and go to `http://localhost:3500` to see your AdminForth application running in Docker container.

## Reducing docker image build time

By default `Dockerfile` created by adminforth CLI is configured in a way to rebuild adminforth SPA from scratch on every build:

```
RUN pnpm/npm adminforth bundle
```

If you want to speed up your build, you can use Docker cache for /tmp folder and change this line to:

```
RUN --mount=type=cache,target=/tmp pnpm/npm adminforth bundle
```

This will cache all /tmp folder between builds and speed up the build process significantly. However you need to ensure that your build daemon persists cache from `--mount=type=cache` mounts. Most of vendor CI build daemons like Github actions Default runner will not persist cache between builds so adding `--mount=type=cache` will not help in such case and you need to use dedicated caching solutions.

To verify build performance locally you can do next:
1) Modify any custom vue file
2) Run `docker build -t myadminapp .`. This populates docker cache with bundled SPA
3) Modify same cusom vue file again
4) Run `time docker build -t myadminapp .` and check resulting time.

First we recommend repeat steps 1-4 without `--mount=type=cache` on your docker daemon to see how much time it takes to build without cache and then add `--mount=type=cache` and repeat steps 1-4 again to see the difference in build times. Then experiment with your CI caching solution to achieve similar build times.

## Automating deployments with CI

If you are looking for a professional way to deploy your AdminForth application, you can follow our blog post [how to deploy your AdminForth application with Terraform From GitHub actions](https://adminforth.dev/blog/compose-aws-ec2-ecr-terraform-github-actions/)

## Adding SSL (https) to AdminForth

There are lots of ways today to put your application behind SSL gateway. You might simply put AdminForth instance behind free Cloudflare CDN, change 3500 port to 80 and Cloudflare will automatically add SSL layer and faster CDN for your application.

However as a bonus here we will give you independent way to add free LetsEncrypt SSL layer to your AdminForth application.

In a folder which contains folder of your AdminForth application (e.g. `adminforth-app`) create a file `compose.yml`:

```yaml title='./compose.yml'
version: '3.8'

services:
  traefik:
    image: "traefik:v2.5"
    command:
      - "--api.insecure=true"
      - "--providers.docker=true"
      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"
      - "--certificatesresolvers.myresolver.acme.httpchallenge=true"
      - "--certificatesresolvers.myresolver.acme.httpchallenge.entrypoint=web"
      - "--certificatesresolvers.myresolver.acme.email=demo@devforth.io" #  ☝️ replace with your email
      - "--certificatesresolvers.myresolver.acme.storage=/letsencrypt/acme.json"
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - "/var/run/docker.sock:/var/run/docker.sock:ro"
      - "./letsencrypt:/letsencrypt"
    labels:
      - "traefik.http.middlewares.redirect-to-https.redirectscheme.scheme=https"
      - "traefik.http.routers.http-catchall.rule=hostregexp(`{host:.+}`)"
      - "traefik.http.routers.http-catchall.entrypoints=web"
      - "traefik.http.routers.http-catchall.middlewares=redirect-to-https"
      - "traefik.http.routers.http-catchall.tls=false"

  adminforth:
    build: ./adminforth-app
    environment:
      - NODE_ENV=production
      - ADMINFORTH_SECRET=!CHANGEME! # ☝️ replace with your secret
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.adminforth.tls=true"
      - "traefik.http.routers.adminforth.tls.certresolver=myresolver"
      - "traefik.http.routers.adminforth.rule=PathPrefix(`/`)"
      - "traefik.http.services.adminforth.loadbalancer.server.port=3500"
      - "traefik.http.routers.adminforth.priority=1"
    # needed only if you are using SQLite
    volumes:
      - db:/code/db

# needed only if you are using SQLite
volumes:
  db:

networks:
  default:
    driver: bridge
```

Now pull this compose file and all directories to your server and run:

```bash
docker compose -p stack-my-app -f compose.yml up -d --build --remove-orphans --wait
```

> ☝️ You can also test this compose stack locally on your machine but SSL will not work,
> so locally you can ignore Chrome warning about SSL and test your AdminForth application.

## Subpath deployment

If you want to deploy your AdminForth application to a sub-folder like `https://mydomain.com/admin` you
should do the following:

1) Open `index.ts` file and set the same subpath in `ADMIN_BASE_URL` and `baseUrl`:

```ts title='./index.ts'
//diff-remove
const ADMIN_BASE_URL = '';
//diff-add
const ADMIN_BASE_URL = '/admin/';

export const admin = new AdminForth({
  baseUrl: ADMIN_BASE_URL,
  ...
});
```

2) Open `compose.yml` file and change `traefik.http.routers.adminforth.rule` to your subpath:

```yml title='./compose.yml'
      ...
       - "traefik.http.routers.adminforth.tls.certresolver=myresolver"
//diff-remove
      - "traefik.http.routers.adminforth.rule=PathPrefix(`/`)"
//diff-add
      - "traefik.http.routers.adminforth.rule=PathPrefix(`/admin/`)"
```

Redeploy compose.

Now you can access your AdminForth application by going to `https://mydomain.com/admin`.

If you want to automate the deployment process with CI follow [our docker - traefik guide](https://devforth.io/blog/onlogs-open-source-simplified-web-logs-viewer-for-dockers/)

## Nginx version

If you are using Nginx instead of traefik, proxy both regular HTTP traffic and AdminForth websocket endpoint.

AdminForth websocket always uses `<baseUrl>/afws`, where `<baseUrl>` is the same value you pass to `baseUrl: ADMIN_BASE_URL` in `index.ts`.

- If `ADMIN_BASE_URL = ''`, use `/afws`.
- If `ADMIN_BASE_URL = '/admin/'`, use `/admin/afws`.

For root deployment, the config can look like this:

```nginx
server {
  listen 80;
  server_name demo.adminforth.dev;

  charset utf-8;
  client_max_body_size 75M;

  gzip on;
  gzip_disable "msie6";
  gzip_vary on;
  gzip_proxied any;
  gzip_comp_level 8;
  gzip_buffers 16 8k;
  gzip_http_version 1.1;
  gzip_min_length 2000;
  gzip_types text/plain text/css application/json application/x-javascript text/xml application/xml application/xml+rss text/javascript application/vnd.ms-fontobject application/x-font-ttf font/opentype image/svg+xml image/x-icon;

  location /afws {
    proxy_http_version 1.1;
    proxy_read_timeout 220s;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Host $http_host;
    proxy_redirect off;
    proxy_pass http://127.0.0.1:3500;
  }

  location / {
      proxy_read_timeout 220s;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_set_header Host $http_host;
      proxy_redirect off;
      proxy_pass http://127.0.0.1:3500;
  }
}
```

If you deploy AdminForth under a subpath, use the same prefix in Nginx locations. For example, when `ADMIN_BASE_URL = '/admin/'`, the websocket path becomes `/admin/afws`:

```nginx
server {
  ...

  location /admin/afws {
      proxy_http_version 1.1;
      proxy_read_timeout 220s;
      proxy_set_header Upgrade $http_upgrade;
      proxy_set_header Connection "upgrade";
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_set_header Host $http_host;
      proxy_redirect off;
      proxy_pass http://127.0.0.1:3500;
  }

  location /admin/ {
      proxy_read_timeout 220s;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_set_header Host $http_host;
      proxy_redirect off;
      proxy_pass http://127.0.0.1:3500;
  }
}
```

If websocket upgrade is not configured on the correct `<baseUrl>/afws` path, realtime AdminForth features will not work behind Nginx.

# Environment variables best practices

Use `.env` file for sensitive variables like `OPENAI_API_KEY` locally.

Use `.env.prod` and `.env.local` for non-sensitive variables which are different for production and local environemnts (like NODE_ENV, SOME_EXTERNAL_API_BASE, etc).

Sensitive variables like `OPENAI_API_KEY` in production should be passed directly to docker container or use secrets from your vault.

# If you are not using Docker

You can actually ship your AdminForth application without Docker as well. 

Most important thing is remember in such case is to use `npx adminforth bundle` command after you installed node modules and before you do actual restart of your application to avoid downtimes.

---

## Email Adapters


Used to send emails.

[Email adapter base class](https://github.com/devforth/adminforth/blob/917d897c866975a4aee29273377f2c07cb6ddf81/adminforth/types/adapters/EmailAdapter.ts#L17)

## AWS SES Email Adapter

```bash
pnpm add @adminforth/email-adapter-aws-ses
```

Enables email delivery via [Amazon Simple Email Service (SES)](https://aws.amazon.com/ses/), suitable for high-volume, programmatic email sending.

## Mailgun Email Adapter

```bash
pnpm add @adminforth/email-adapter-mailgun
```

Allows sending transactional or marketing emails using [Mailgun](https://www.mailgun.com/), a developer-friendly email service.

---

## OAuth2 Adapters


Used to authenticate users via OAuth 2.0 providers.

[OAuth2Adapter source class](https://github.com/devforth/adminforth/blob/917d897c866975a4aee29273377f2c07cb6ddf81/adminforth/types/adapters/OAuth2Adapter.ts#L9)

## Google OAuth Adapter

```bash
pnpm add @adminforth/oauth-adapter-google
```

Supports Google sign-in to allow users to authenticate using their Google or Google Workspaces accounts.

## GitHub OAuth Adapter

```bash
pnpm add @adminforth/oauth-adapter-github
```

Enables authentication via GitHub accounts, useful for developer tools and open-source apps.

## Facebook OAuth Adapter

```bash
pnpm add @adminforth/oauth-adapter-facebook
```

Allows users to log in with Facebook credentials. Facebook OAuth is commonly used for social media integrations.

## Keycloak OAuth Adapter

```bash
pnpm add @adminforth/oauth-adapter-keycloak
```

Connects AdminForth to an open-source [Keycloak](https://www.keycloak.org/) identity provider for enterprise-grade SSO (Single Sign-On).

## Microsoft OAuth Adapter

```bash
pnpm add @adminforth/oauth-adapter-microsoft
```

Supports login through Microsoft accounts including Azure AD, Office365, and Outlook.com.

## Twitch OAuth Adapter

```bash
pnpm add @adminforth/oauth-adapter-twitch
```

Adds support for Twitch authentication, useful for streaming or creator-oriented platforms.

## Clerk OAuth Adapter

```bash
pnpm add @adminforth/oauth-adapter-clerk
```

Enables sign-in via [Clerk](https://clerk.com/) — a hosted authentication platform with built-in user management, MFA, and social logins.

---

## Image Generation Adapters


Used for image-generating AI tools.

## OpenAI Image Generation Adapter

```bash
pnpm add @adminforth/image-generation-adapter-openai
```

Uses OpenAI image generation model `gpt-image` to generate images from text prompts.

Up to the winter 2026 OpenAI models are one of the most powerful image generation models available, especially GPT-Image-1.5, which is why we started with them.

```ts
import ImageGenerationAdapterOpenAI from '@adminforth/image-generation-adapter-openai';

new ImageGenerationAdapterOpenAI({
  openAiApiKey: process.env.OPENAI_API_KEY as string,
  model: 'gpt-image-1',
  extraParams: {
    quality: 'high',
  },
}),
```

## Gemini (Nano Banana) Image Generation Adapter

```bash
pnpm add @adminforth/image-generation-adapter-nano-banana
```

```ts
import ImageGenerationAdapterNanoBanana from '@adminforth/image-generation-adapter-nano-banana';

new ImageGenerationAdapterNanoBanana({
  nanoBananaApiKey: process.env.GEMINI_API_KEY as string,
  model: 'gemini-3.1-flash-image-preview',
  attachImagesAllowedHosts: ['my-bucket.s3.eu-central-1.amazonaws.com'],
}),
```

### Restricting input image hosts (SSRF protection)

To use input images, the adapter downloads every URL passed in `inputFiles` from your server. If those URLs can be influenced by a user (for example they are built from a record field which the user can edit, or come from `attachFiles` of a plugin), an attacker can point them at internal addresses like `http://169.254.169.254/latest/meta-data/` or `http://localhost:9200/` and use your backend as a proxy to your private network — a classic SSRF.

`attachImagesAllowedHosts` closes this hole: only listed hosts are downloaded, anything else throws before the request is made. Always set it to the storage you actually serve images from:

```ts
new ImageGenerationAdapterNanoBanana({
  nanoBananaApiKey: process.env.GEMINI_API_KEY as string,
//diff-add
  attachImagesAllowedHosts: ['my-bucket.s3.eu-central-1.amazonaws.com'],
}),
```

Matching is case-insensitive: `example.com` matches that host only, while `.example.com` (or `*.example.com`) matches it and all its subdomains.

> ⚠️ When `attachImagesAllowedHosts` is not set, images are downloaded from **any** host. Leave it unset only if the adapter never receives URLs which depend on user input.

---

## Storage Adapters


Used for storing files.

[StorageAdapter source class](https://github.com/devforth/adminforth/blob/917d897c866975a4aee29273377f2c07cb6ddf81/adminforth/types/adapters/StorageAdapter.ts#L8)

## Amazon S3 Storage Adapter

```bash
pnpm add @adminforth/storage-adapter-amazon-s3
```

Stores uploaded files in [Amazon S3](https://aws.amazon.com/s3/), providing scalable cloud storage. 

## S3 compatible adapter
```bash
pnpm add @adminforth/storage-adapter-s3-compatible
```

Provides S3 compatible interface for object storage services such as MinIO, Wasabi, Cloudflare R2 or other third-party S3 providers.
### How the adapter works

The Amazon S3 adapter uses tagging to mark objects with the special tag `adminforth-candidate-for-cleanup`, and then creates a lifecycle rule that automatically expires objects with that tag.
But not all S3-compatible adapters support tagging, so this adapter has a built-in cleanup mechanism and you have two options:

**1) Pass an optional key/value adapter, where all object keys scheduled for deletion will be stored**

Why use it?

There are a few reasons to do so:

- When somebody uploads a file in a record and doesn't press the "Save" button, the file will be marked for deletion and you don't have to pay for storing it
- If you accidentally delete a file, you'll have a time window to restore it

>If you are using a key/value adapter, it is important to retain the object keys, because if the key-value storage is cleared, all objects marked for deletion will not be cleaned up and you'll have to pay for storing files you no longer use

>We recommend using `@adminforth/key-value-adapter-resource`, because chance, that database will be cleaed is low

>‼️If you are using LevelDB to store keys of objects that should/shouldn't be deleted, it is important to use a Docker volume on the deployed application so you will not lose this data after a redeployment

>‼️It is not recommended to use the same Key/value adapter for multiple adapter instances, because it can cause unpredictable behavior of the cleanup scheduler

**2) Don't use key/value adapter**

If you don't want to use a key/value adapter and you don't need to clean up files, you can simply not pass an adapter
> Note: if you don't pass an adapter, all connected files will be deleted immediately when you delete a record.

> If somebody uploaded a file and didn't save the record, you will pay for the storage until the file is removed manually

### Choosing Key/value adapter

Since the adapter uses a key/value adapter to store keys for deletion, it is important to use persistent storage, so the data will be safe:

- (⛔️) [RAM adapter](07-key-value-adapters.md#ram-adapter) - not recommended, because after an admin process restart (e.g. redeployment) all data and orphan file tracking info will be lost (and files will not be cleaned up)
- (✅) [LevelDB adapter](07-key-value-adapters.md#leveldb-adapter) - can be used, but you need to set up persistent storage in your Docker container by monting leveldb data directory into a volume, so data won't be lost between restarts
- (✅✅) [Redis adapter](07-key-value-adapters.md#redis-adapter) - Redis itself stores data in RAM memory but modern versions also able to persist it into disk. If you are running Redis in docker we recommend you to ensure that CI/CD pipeline does not force it to restarts during each redeployment, also ensure that you mount `/data` dir into volume. ()
- (✅✅✅) [Resource adapter](07-key-value-adapters.md#resource-based-adapter) - uses a database to store key/value pairs, so data will be safe between restarts, but you need to create an extra table for this storage. 

Please note that one adapter instance can be also reused for any other purposes or plugins, so if your application need KV adapter to multiple purposes, you can instantiate it once in dedicated utility file and reuse this instance in other places. Internally each KV method exposes 'collection' parameter which allows to separate data for different purposes or by different plugins. 

### Cloudflare R2 setup example

This adapter requires key/value adapter. For example, we will be using levelDb adapter.
```bash
pnpm add @adminforth/key-value-adapter-leveldb
```

1) Go to the [Cloudflare dashboard](https://dash.cloudflare.com/) and create new bucket. Get bucket URL.
2) Get R2 Access key id and Secret access key
3) Add in the .env file: 
```
R2_ACCESS_KEY_ID=your_access_key_id
R2_SECRET_ACCESS_KEY=your_secret_access_key
R2_ENDPOINT_URL=your_bucket_url
R2_BUCKET_NAME=your_bucket_name
R2_BUCKET_REGION=auto
```
4) Setup adapter:
```ts
  import LevelDBKeyValueAdapter from '@adminforth/key-value-adapter-leveldb';

  new AdminForthAdapterS3CompatibleStorage({
    accessKeyId: process.env.R2_ACCESS_KEY_ID as string,
    secretAccessKey: process.env.R2_SECRET_ACCESS_KEY as string,
    endpoint: process.env.R2_ENDPOINT_URL as string,
    bucket: process.env.R2_BUCKET_NAME as string,
    region: process.env.R2_BUCKET_REGION as string,
    s3ACL: "private",
    cleanupKeyValueAdapter: new LevelDBKeyValueAdapter({
      // ensure /stores/ folder is a persisted/backed up point, if you running in docker ensure ensure you mount /stores/ as volume
      dbPath: process.env.NODE_ENV === 'production' ? '/stores/cloudflare_r2_storage_keys' : './cloudflare_r2_storage_keys',
    });,
    forcePathStyle: true,
    cleanupCheckInterval: '30m',
    cleanupGracePeriod: '5d'
  }),
```

### MinIO setup

1) If you don't have running instanse, then run it with command
```bash
  docker run \
    -p 9000:9000 \
    -p 9001:9001 \
    -e MINIO_ROOT_USER=minioadmin \
    -e MINIO_ROOT_PASSWORD=minioadmin \
    minio/minio server /data --console-address ":9001"
```
2) Go to http://127.0.0.1:9000 and create bucket
3) Setup adapter: 
```ts
  import LevelDBKeyValueAdapter from '@adminforth/key-value-adapter-leveldb';

  new AdminForthAdapterS3CompatibleStorage({
    accessKeyId: 'minioadmin',
    secretAccessKey: 'minioadmin',
    endpoint: 'http://localhost:9000',
    bucket: 'adminforth-dev-demo',
    region: 'us-east-1',
    s3ACL: 'private',
    cleanupKeyValueAdapter: new LevelDBKeyValueAdapter({
      // ensure /stores/ folder is a persisted/backed up point, if you running in docker ensure ensure you mount /stores/ as volume
      dbPath: process.env.NODE_ENV === 'production' ? '/stores/minio_storage_keys' : './minio_storage_keys',
    }),
    forcePathStyle: true,
    cleanupCheckInterval: '30m',
    cleanupGracePeriod: '5d'
  }),
```

## Local Storage Adapter

```bash
pnpm add @adminforth/storage-adapter-local
```

Stores files locally on the server filesystem. It is suitable for development or small self-hosted setups, but cloud storage is generally a better production option for reliability and scalability.

---

## AI Completion Adapters


Used for AI-powered text completion.

[CompletionAdapter source class](https://github.com/devforth/adminforth/blob/917d897c866975a4aee29273377f2c07cb6ddf81/adminforth/types/adapters/CompletionAdapter.ts#L16)

Feel free to fork and implement other models, including Anthropic, Google Gemini, or any other AI model that supports text completion.

## Common `complete()` signature

All completion adapters implement the same `complete()` method signature from the shared `CompletionAdapter` interface.

```ts
complete({
  content: string,
  maxTokens: number,
  outputSchema?: any,
  reasoningEffort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh',
  tools?: CompletionTool[],
  onChunk?: (
    chunk: string,
    event?: {
      type: 'output' | 'reasoning';
      delta: string;
      text: string;
      source?: 'summary' | 'text';
    },
  ) => void | Promise<void>,
})
```

`reasoningEffort` is optional and defaults to `low` in the adapter implementation.

## Using `json_schema`

All completion adapters accept structured output through the shared `outputSchema` field in the request object. The example below uses the OpenAI adapter, but the same request shape is common for all completion adapters.

```ts
const adapter = new CompletionAdapterOpenAIResponses({
  openAiApiKey: process.env.OPENAI_API_KEY as string,
  model: 'gpt-5-mini',
});

const prompt = 'What is the capital of France? return json';

adapter.complete({
  content: prompt,
  maxTokens: 200,
  outputSchema: {
    name: 'capital_response',
    schema: {
      type: 'object',
      properties: {
        capital: { type: 'string' },
      },
      required: ['capital'],
    },
  },
}).then((resp) => {
  console.log(resp);
});
```

## Using streaming output and reasoning events

All completion adapters accept `onChunk` inside the request object. The example below uses the OpenAI adapter, but the callback signature is common for all completion adapters.

Streaming reasoning events depend on the selected model and provider response.

```ts
const adapter = new CompletionAdapterOpenAIResponses({
  openAiApiKey: process.env.OPENAI_API_KEY as string,
  model: 'gpt-5-mini',
});

await adapter.complete({
  content: 'Think step by step and write a short answer about how ABS brakes work',
  maxTokens: 300,
  reasoningEffort: 'medium',
  onChunk: async (chunk, event) => {
    if (!event) return;

    if (event.type === 'reasoning') {
      console.log('Reasoning chunk:', event.delta);
      return;
    }

    console.log('Output chunk:', event.delta);
  },
});
```

Then output will be like:

```ts
{ content: '{"capital":"Paris"}', finishReason: 'stop' }
```

## OpenAI Responses Completion Adapter

```bash
pnpm add @adminforth/completion-adapter-openai-responses
```

Integrates AdminForth with OpenAI's Responses API to provide AI-powered completion and conversational features.

The older `@adminforth/completion-adapter-open-ai-chat-gpt` package is deprecated. Use this package instead.

```ts
import CompletionAdapterOpenAIResponses from '@adminforth/completion-adapter-openai-responses';

new CompletionAdapterOpenAIResponses({
  openAiApiKey: process.env.OPENAI_API_KEY as string,
  model: 'gpt-5.2',
  extraRequestBodyParameters: {
    temperature: 0.7,
    reasoning: {
      effort: 'medium',
    },
  },
}),
```

You can specify any GPT model you need. The default is `gpt-5-nano` as it is cheapest though may behave weakly.

By default, this adapter uses the OpenAI `responses` API (`v1/responses`) unless `useCompletionApi` is set to `true`. If `useCompletionApi` is `true`, it uses the older Chat Completions API (`v1/chat/completions`). 

### Using with OpenAI-compatible API providers (for example based on self-hosted vLLM docker images)

Adapter can run OpenAI-compatible providers by setting `baseUrl`, for example you can use OVH AI Endpoints:

```ts
new CompletionAdapterOpenAIResponses({
  openAiApiKey: process.env.OVH_AI_ENDPOINTS_ACCESS_TOKEN as string,
  baseUrl: 'https://oai.endpoints.kepler.ai.cloud.ovh.net/v1',
  model: 'gpt-oss-20b',
  useCompletionApi: true,
  extraRequestBodyParameters: {
    store: false,
  },
}),
```

If `useCompletionApi` is omitted, the adapter keeps the current default behavior:

- official OpenAI uses the `responses` API
- custom `baseUrl` providers use the Chat Completions API. 

This is because many OpenAI-compatible providers do not yet support the `responses` API or support it unstably (for example OVH AI Endpoints still - Apr 2026 does not fully support the `responses`, so `useCompletionApi: false` may work unstably there, though you can re-test it by manually enabling it by setting `useCompletionApi: true` and checking if it works).
Any 3rd-party API providers might have next reasones of pure `responses` API compatibility:

1) If they use vLLM open-source software under the hood they might have outdated version
2) Custom non-vLLM implmentation might have reliable chat API implementation while give less priority to responses API as it is more complex and new.

We recommend you to try responses API first by setting `false` in `useCompletionApi` because it gives rich features set, including summarization and better structured outputs, and if it does not work for your provider, then set it to `true` to have less features but working implementation.

## Google Gemini Completion Adapter

```bash
pnpm add @adminforth/completion-adapter-google-gemini
```

Integrates AdminForth with Google Gemini models to provide AI-powered completion and conversational features.

```ts
import CompletionAdapterGoogleGemini from '@adminforth/completion-adapter-google-gemini';

new CompletionAdapterGoogleGemini({
  geminiApiKey: process.env.GEMINI_API_KEY as string,
  model: 'gemini-3-pro-preview',
  extraRequestBodyParameters: {
    temperature: 0.7,
  },
}),
```

You can specify any Gemini model you need. The default is `gemini-3-flash-preview`.

## Adding extra request body params

There might be cases where you want to add extra body params to the request sent to the AI provider. For those cases you can use `extraRequestBodyParameters`:

```ts
import CompletionAdapterGoogleGemini from '@adminforth/completion-adapter-google-gemini';

new CompletionAdapterGoogleGemini({
  geminiApiKey: process.env.GEMINI_API_KEY as string,
  model: 'gemini-3-pro-preview',
  extraRequestBodyParameters: {
    temperature: 0.7,
    responseMimeType: 'application/json',
  },
}),
```

---

## Image Analysis Adapters


Used for AI-powered image analysis.

[ImageVisionAdapter source class](https://github.com/devforth/adminforth/blob/1efdc19e3bb7a5fc3b19106704e4ae8bb7c73276/adminforth/types/adapters/ImageVisionAdapter.ts#L1)

These adapters can analyze image content, extract text from images, identify objects, describe scenes, and provide detailed image insights.

## OpenAI Vision Adapter

```bash
pnpm add @adminforth/image-vision-adapter-openai --save
```

Integrates AdminForth with OpenAI to provide advanced AI-powered image analysis. It can describe image content, read and extract text from images, identify objects and people, and provide detailed visual insights.

---

## Key-value Adapters


Key-value adapters are used to store data in a key-value format. They provide a simple and efficient way to manage data where quick access to values based on unique keys is required.

[Key-value adapter source class](https://github.com/devforth/adminforth/blob/86bb9236fed9e844fdb07688318c050641f9eb1c/adminforth/types/adapters/KeyValueAdapter.ts#L6)

## RAM Adapter

```bash
pnpm add @adminforth/key-value-adapter-ram
```

The RAM adapter is a simple in-memory key-value store. It keeps data in process memory, so it is not suitable for multi-process deployments because each process would have its own isolated store. In that case you need a centralized KV adapter such as Redis.

Pros:

- Simplest to use and does not require an external daemon.

Cons:

- Suitable for single-process installations only.

## Redis Adapter

```bash
pnpm add @adminforth/key-value-adapter-redis
```

Redis uses in-memory storage with $O(1)$ get complexity. It is a great fit for lightweight workloads that fit in RAM, and it also works well for multi-process or replica-based installations as a centralized store. If persistence across restarts is important, configure Redis persistence separately.

```ts
import RedisKeyValueAdapter from '@adminforth/key-value-adapter-redis';

const adapter = new RedisKeyValueAdapter({
  redisUrl: 'redis://localhost:6379/0', // where "/0" - is database number from 0 to 15; Redis can have up to 16 databases"
});

adapter.set('test-key', 'test-value', 120);
```

## LevelDB Adapter

```bash
pnpm add @adminforth/key-value-adapter-leveldb
```

LevelDB uses disk storage with $O(\log n)$ get complexity. It is a good fit for large or persistent KV datasets that still require fast lookups but do not efficiently fit in RAM. This is a single-process adapter only, so multiple admin processes should not point to the same LevelDB directory.

You can use replicas with isolated disks, but in that case the state will also be isolated between replicas.

```ts
import LevelDBKeyValueAdapter from '@adminforth/key-value-adapter-leveldb';

const adapter = new LevelDBKeyValueAdapter({
  dbPath: './testdb',
});

adapter.set('test-key', 'test-value', 120);
```

## Resource-based adapter
```bash
pnpm add @adminforth/key-value-adapter-resource
```

Resource adapter uses adminforth resource to store key/value pairs.

### Setup

1) Add schema in `./schema.prisma` file

```
model key_values {
  key String @id
  value String
  collection String?
  expire_at DateTime? //optional column

  @@index([key])
  @@index([collection])
}
```

2) Apply migration
```bash
pnpm makemigration --name add-adminforth-key-value-tables ; pnpm migrate:local
```

3) Create resource

```ts title="./resources/key_value_resource.ts"
import AdminForth, { AdminForthDataTypes } from 'adminforth';
import type { AdminForthResourceInput, AdminUser } from 'adminforth';

async function allowedForSuperAdmins({ adminUser }: { adminUser: AdminUser }): Promise<boolean> {
  return adminUser.dbUser.role === 'superadmin';
}

export default {
  dataSource: 'maindb',
  table: 'key_values',
  resourceId: 'key_values',
  label: 'Key values',
  columns: [
    {
      name: 'key',
      primaryKey: true,
      type: AdminForthDataTypes.STRING,
    },
    {
      name: 'value',
      type: AdminForthDataTypes.STRING,
    },
    {
      name: 'collection',
      type: AdminForthDataTypes.STRING,
    },
    {
      name: 'expire_at',
      type: AdminForthDataTypes.DATETIME,
    }
  ],
  options: {
    allowedActions: {
      list: allowedForSuperAdmins,
      show: allowedForSuperAdmins,
      create: false,
      edit: false,
      delete: false,
    },
  },
} as AdminForthResourceInput;
```

4) Register resource

```ts title="./index.ts"
import key_value_resource from './resources/key_value_resource.js';

export const admin = new AdminForth({
  ...
  resources: [
    ...
    key_value_resource,
  ],
  ...
});

```

5) Create instance of adapter

```ts
import ResourceKeyValueAdapter from '@adminforth/key-value-adapter-resource'

const adapter = new ResourceKeyValueAdapter({
  resourceId: 'key_values',
  keyField: 'key',
  valueField: 'value',
  collectionField: 'collection',
  expireField: 'expire_at'
})
```

---

## Captcha Adapters


Used to add captcha to the login screen.

[Captcha adapter source class](https://github.com/devforth/adminforth/blob/65153408a119314dad339f452700e0937952034a/adminforth/types/adapters/CaptchaAdapter.ts#L5)

## Cloudflare Adapter

```bash
pnpm add @adminforth/login-captcha-adapter-cloudflare
```

## reCaptcha Adapter

```bash
pnpm add @adminforth/login-captcha-adapter-recaptcha
```

---

## Telegram Chat Surface Adapter


Chat surface adapters connect external chat products to the [Agent plugin](/docs/tutorial/Plugins/agent/). They only receive and send chat messages. User linking is handled through OAuth connected accounts.

For Telegram you need both adapters:

```bash
pnpm add @adminforth/chat-surface-adapter-telegram
pnpm add @adminforth/oauth-adapter-telegram
```

Create a Telegram bot with BotFather and copy the token:

1. Open [BotFather](https://t.me/BotFather).
2. Click **Open** and open it in the Telegram app.
3. Select or Create your bot.
4. Copy the bot token shown at the top.

Add the token to `.env`:

```env title=".env"
TELEGRAM_BOT_TOKEN=your_bot_token
TELEGRAM_BOT_USERNAME=your_bot_username_without_at
TELEGRAM_WEBHOOK_SECRET=your_random_secret
```

The webhook secret confirms that the request came through Telegram.

## External identity `externalUserId`

External chat accounts are resolved through OAuth connected accounts. The Telegram OAuth adapter writes the Telegram user id into `externalUserId` on the external identities resource. The Agent plugin then uses that field to map incoming Telegram messages to AdminForth users.

Add the field to your external identities resource:

```ts
{
  name: 'externalUserId',
  type: AdminForthDataTypes.STRING,
},
```

Also add the matching column to your database schema and run a migration. For example, with Prisma and PostgreSQL:

```prisma title="schema.prisma"
model AdminUserExternalIdentity {
  // existing fields
  externalUserId String?
}
```

Then create and apply the migration using your app's migration scripts:

```bash
pnpm makemigration --name add-external-identity-external-user-id
pnpm migrate:local
```

Configure the OAuth plugin with Telegram OAuth:

```ts title="./resources/adminuser.ts"
import OAuthPlugin from '@adminforth/oauth';
import TelegramOauthAdapter from '@adminforth/oauth-adapter-telegram';

new OAuthPlugin({
  emailField: 'email',
  externalIdentityResource: {
    resourceId: 'admin_user_external_identities',
    phoneField: 'phone',
    fullNameField: 'fullName',
    avatarUrlField: 'avatarUrl',
    metaField: 'meta',
  },
  adapters: [
    new TelegramOauthAdapter({
      clientID: process.env.TELEGRAM_CLIENT_ID as string,
      clientSecret: process.env.TELEGRAM_CLIENT_SECRET as string,
      redirectUri: process.env.TELEGRAM_OAUTH_REDIRECT_URI as string,
      scopes: ['openid', 'profile', 'phone'],
    }),
  ],
});
```

Then register the Telegram chat surface adapter in the Agent plugin:

```ts
import AdminForthAgent from '@adminforth/agent';
import TelegramChatSurfaceAdapter from '@adminforth/chat-surface-adapter-telegram';

new AdminForthAgent({
  modes: [
    // your modes
  ],
  sessionResource: {
    // your session resource config
  },
  turnResource: {
    // your turn resource config
  },
  //diff-add
  chatSurfaceAdapters: [
    //diff-add
    new TelegramChatSurfaceAdapter({
      //diff-add
      botToken: process.env.TELEGRAM_BOT_TOKEN as string,
      //diff-add
      botUsername: process.env.TELEGRAM_BOT_USERNAME,
      //diff-add
      webhookSecret: process.env.TELEGRAM_WEBHOOK_SECRET,
      //diff-add
    }),
    //diff-add
  ],
  //diff-add
  chatExternalIdentityResource: {
    //diff-add
    resourceId: 'admin_user_external_identities',
    //diff-add
    surfaces: {
      //diff-add
      telegram: {
        //diff-add
        provider: 'AdminForthAdapterTelegramOauth2',
        //diff-add
      },
      //diff-add
    },
    //diff-add
  },
});
```

External chat users are resolved through OAuth connected accounts. Configure OAuth `externalIdentityResource` and Agent `chatExternalIdentityResource`, then let users connect Telegram from **Connected Accounts**.

The `provider` value must match the Telegram OAuth adapter class name. Users must connect Telegram in **Settings -> Connected Accounts** before the Telegram bot can identify them.

## Adapter options

All options for `new TelegramChatSurfaceAdapter(options)`:

- `botToken` (string, required) — Telegram bot token from BotFather.
- `botUsername` (string, optional) — bot username. OAuth connected accounts are used for user linking.
- `webhookSecret` (string, required) — secret token configured in Telegram `setWebhook`.
- `streamingMode` (`draft` | `typing` | `off`, optional) — streaming behavior for Telegram responses.
  - Default: `draft`.
  - Note: Telegram drafts work only in private chats. In non-private chats the adapter automatically falls back from `draft` to `typing`.
- `draftUpdateIntervalMs` (number, optional) — throttle for draft preview updates.
  - Default: `650`.

The plugin exposes this webhook endpoint:

```txt
/adminapi/v1/agent/surface/telegram/webhook
```

Set it in Telegram:

```bash
curl -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-domain.com/adminapi/v1/agent/surface/telegram/webhook",
    "secret_token": "'"${TELEGRAM_WEBHOOK_SECRET}"'"
  }'
```

Telegram does not provide a user time zone in message updates, so the adapter sends `UTC` as `userTimeZone`.

---

## CLI Commands


> **CLI Reference**: A list of all available CLI commands for AdminForth.

## Usage

To use a command, write it in format like:

```bash
pnpx adminforth <command> [...options]
```

For example: `pnpx adminforth create-app --app-name myadmin --db "sqlite://.db.sqlite"`

## Commands

### `create-app`

> Create a new AdminForth application with initial project structure and configuration.

**Description:**

The `create-app` command scaffolds a brand new AdminForth application in a specified directory. The `create-app` command guides you through setup using command-line arguments or interactive prompts, generates the necessary configuration and project files, installs dependencies, and sets up the development environment.

**Usage:**

```bash
pnpx adminforth create-app [--app-name <name>] [--db <database_url>]
```

**Options:**

- **`--app-name`**: The name of your new application. This becomes the project directory. Defaults to `adminforth-app`.
- **`--db `**: The connection URL for your database. Currently PostgreSQL, MongoDB, SQLite, MySQL, Clickhouse are supported. If not provided, defaults to `sqlite://.db.sqlite`.

**Example:**

```bash
pnpx adminforth create-app --app-name my-app --db sqlite://mydb.sqlite
```

**Result:**

Creates a folder `my-app/` with the entire AdminForth app ready to go.

---

### `create-plugin`

> Scaffold a new plugin for an AdminForth application.

**Description:**

The `create-plugin` command sets up a fresh AdminForth plugin project by generating the required files, installing dependencies, and preparing the environment for local development and testing.

**Usage:**

```bash
pnpx adminforth create-plugin [--plugin-name <name>]
```

**Options:**

- **`--plugin-name`**: The name of your new plugin. This becomes the folder name and is used in generated files. If not provided, you'll be prompted.

**Example:**

```bash
pnpx adminforth create-plugin --plugin-name my-awesome-plugin
```

**Result:**

Creates a folder with all the necessary files for your plugin and instructions for linking it into an AdminForth project.

### `generate-models`

> Generate TypeScript models from your AdminForth resources.

**Description:**

The `generate-models` command scans the current working directory for a valid AdminForth instance and automatically generates a TypeScript file containing model type definitions for all defined resources. The `generate-models` command inspects the resource columns and maps them to appropriate TypeScript types.

**Usage:**

```bash
pnpx adminforth generate-models [--env-file=<path>]
```

**Options:**

- **`--env-file=<path>`**: (optional) Path to a custom `.env` file to load environment variables. Defaults to `.env`.

**Example:**

```bash
pnpx adminforth generate-models --env-file=.env.dev
```

**Result:**

A file like this will be generated:

```ts
export type User = {
  id: number;
  name: string;
  email: string;
};

export type Product = {
  id: number;
  title: string;
  price: number;
};
```

---

### `bundle`

> Build the AdminForth Single Page Application (SPA) for production.

**Description:**

The `bundle` command bundles the AdminForth front-end (SPA) using your current AdminForth instance. The `bundle` command calls the `bundleNow()` method from your AdminForth admin entry point.

**Usage:**

```bash
pnpx adminforth bundle
```

**Output:**

The `bundle` command generates output files (typically JavaScript/CSS assets) in the directory configured by your AdminForth project (usually `dist` or `public`).

### `component`

The `component` command is an interactive CLI tool that scaffolds and injects Vue components into your AdminForth plugin.

The `component` command helps you generate:
- Custom field components (`fields`)
- CRUD page injections (`crudPage`)
- Login page injections (`login`)
- Global UI injections (`global`)

---

#### 🔤 Custom Fields (`fields`)

The `component fields` flow generates components for specific fields in views such as:
- `list`
- `show`
- `edit`
- `create`
- `filter`

The `component fields` flow prompts you to select a **resource**, then a **column**, and finally injects a file like:
```bash
custom/UserEmailShow.vue
```
The `component fields` flow auto-updates the config.

Usage shortcut:
```bash
pnpx adminforth component fields.show.user.email
```

---

#### ➖ CRUD Page Injections (`crudPage`)

The `component crudPage` flow adds components to entire CRUD pages (not just fields).

The `component crudPage` flow supports views:
- `list`
- `show`
- `edit`
- `create`

The `component crudPage` flow then asks:
- Where to inject (top, bottom, dropdown, etc.)
- Optional name (e.g. "ExportButton")
- Whether the component is "thin" (coexists with existing layout)

Generated example:
```bash
custom/OrderShowBottomExportButton.vue
```

#### 🔐 Login Page Injections (`login`)

The `component login` flow places a component before or after the login form.

The `component login` flow prompts for:
- Injection type: `beforeLogin` or `afterLogin`
- Purpose (for naming)
- Updates `index.ts` automatically

Example file:
```bash
custom/CustomLoginSocials.vue
```

---

#### 🌐 Global Injections (`global`)

The `component global` flow injects into:
- `userMenu`
- `header`
- `sidebar`
- `everyPageBottom`

The `component global` flow asks for:
- Location
- Description (for naming)

Example:
```bash
custom/CustomGlobalSupportLink.vue
```

---

#### 🛠️ Notes

- All components are placed under a `custom/` folder
- Code uses Handlebars templates (`.vue.hbs`)
- Config file `index.ts` must exist and export `admin`

If the generated component file already exists, the `component` command shows a warning and does not overwrite the existing file.

---

### `resource`

> Generate and register a new AdminForth resource based on an existing database table.

**Description:**

The `resource` command helps you scaffold a new resource file for a selected table in your database and automatically integrates it into the AdminForth application. The `resource` command fetches available tables, lets you select one interactively, generates a corresponding resource file using a template, and injects the result into your application’s index file.

**Usage:**

```bash
pnpx adminforth resource
```

**Result:**

- Prompts the user to select a table, such as `users`, from the available databases.
- Creates a file like `resources/users.ts` (or `users_maindb.ts` if needed).
- Injects this resource into the application’s `index.ts` file.
- Adds a navigation menu item with label "Users" and default icon.

**Example Output:**

```
🔍 Choose a table to generate a resource for:
> maindb.users
  maindb.posts
  ...
✅ Generated resource file: ./resources/users.ts
✅ Injected resource "users" into index
```

### `help` `--help` `-h`

> Display a list of all available AdminForth CLI commands.

**Description:**

The `help` command outputs a summary of all supported AdminForth commands in the terminal with brief descriptions. The `help` command is useful as a quick reference for developers to understand what functionality is available.

**Usage:**

```bash
adminforth help
```

**Output:**

```
Available commands:
  create-app         Create a new AdminForth app
  create-plugin      Create a plugin for your AdminForth app
  generate-models    Generate TypeScript models from your databases
  bundle             Bundles your AdminForth app SPA for production
  component          Scaffold a custom Vue component
  resource           Scaffold a custom resource
```

The `help` output is typically displayed by running `adminforth` with no arguments or explicitly running `adminforth help`.

---

### `version` `--version` `-v`

> Show the current version of the AdminForth CLI.

**Description:**

The `version` command displays the version number of the currently installed AdminForth CLI. The `version` command is useful for verifying which version you are using, especially when troubleshooting or checking compatibility.

**Usage:**

```bash
adminforth version
```

**Example Output:**

```
AdminForth CLI version: 1.6.2
```

---

## Usage of the logger


There are cases when you might want to debug an Adminforth app or add custom logs.

## Adding custom logs

> These logs are used only on the backend.

> ❗️Do not combine them with `console.log()` because it can cause an unpredictable order of logs.

To add a custom log, import the logger and use the desired level:

```ts
import { logger } from 'adminforth';

logger.trace("This is trace log");
logger.debug("This is debug log");
logger.info("This is info log");
logger.warn("This is warn log");
logger.error("This is error log");
```

Depending on the active log level, some messages will be filtered out.

## Changing logging level and debugging the Adminforth SPA

There are three types of logs: user logs, Adminforth logs, and database logs.
Use separate environment variables to control each type.

Logger has 5 debug levels:

```ts
"trace"
"debug"
"info"
"warn"
"error"
```

By default, the logger uses the `info` level.

To change it, set the environment variable for the logger you want to see:

- `DEBUG_LEVEL=trace` - user logs at `trace` level
- `AF_DEBUG_LEVEL=debug` - Adminforth logs at `debug` level
- `DB_DEBUG_LEVEL=trace` - database logs at `trace` level

Or run the Adminforth app like this:

```bash
DB_DEBUG_LEVEL=trace pnpm start
```

And the logs will be visible as well.

## Single-line logs

By default, log records that contain additional data objects are printed across multiple lines (pretty-printed).
If you prefer each log record to be printed on a single line (for example, to make logs easier to grep or to fit
log collectors), set the `AF_LOG_SINGLE_LINE` environment variable:

```bash
AF_LOG_SINGLE_LINE=true pnpm start
```

Accepted truthy values are `true` and `1`. When unset, logs use the default multi-line pretty format.

## Catching unhandled API handler errors (work only with express v4)

Express 4.x.x doen't have build-in error handler, so adminforth comes with build-in one. When an unhandled error is thrown inside an AdminForth API endpoint handler (built-in or custom), AdminForth logs the
error and responds with `500 Internal server error`. If you also want to forward these errors somewhere — for example
to report them to an external error-tracking service like [Sentry](https://sentry.io/), or to do your own custom
logging — set the `expressErrorCallback` option in your AdminForth config:

```ts
import AdminForth from 'adminforth';
import * as Sentry from '@sentry/node';

export const admin = new AdminForth({
  // ...rest of your config
  expressErrorCallback: ({ error, extra, adminforth }) => {
    Sentry.captureException(error, {
      extra: {
        requestUrl: extra.requestUrl,
        query: extra.query,
      },
    });
  },
});
```

>In express 5.x.x errors are handled automatically and this param is not supported

---

## Agent

> TODO: this plugin tutorial is in progress, some information might be missing, we are actively working on it now. If you have any questions regarding this plugin, please reach out to us in GitHub issues

# Agent Plugin

This plugin adds an AI agent with a chat surface to AdminForth which is capable of default skills like searching/editing data and extending with custom skills. 

It stores session history in your own resources and generates responses using one of the configured `modes`.

## Installation

```bash
pnpm add @adminforth/agent --save
pnpm add @adminforth/completion-adapter-openai-responses --save
```

Add your LLM credentials to `.env`:

```env title=.env
...
OPENAI_API_KEY=your_key
```

Each mode accepts any AdminForth completion adapter, so you can replace the OpenAI adapter with another adapter from [List of adapters](/docs/tutorial/ListOfAdapters/).

## Setup

First create two resources for sessions and turns:

```ts title="./resources/agent_resources/sessions.ts"
import AdminForth, { AdminForthDataTypes } from 'adminforth';
import type { AdminForthResourceInput, AdminUser } from 'adminforth';
import { randomUUID } from 'crypto';

async function allowedForSuperAdmins({ adminUser }: { adminUser: AdminUser }): Promise<boolean> {
  return adminUser.dbUser.role === 'superadmin';
}

export default {
  dataSource: 'maindb',
  table: 'sessions',
  resourceId: 'sessions',
  label: 'Sessions',
  columns: [
    {
      name: 'id',
      primaryKey: true,
      type: AdminForthDataTypes.STRING,
      fillOnCreate: () => randomUUID(),
      showIn: {
        edit: false,
        create: false,
      },
    },
    {
      name: 'title',
      type: AdminForthDataTypes.STRING,
    },
    {
      name: 'turns',
      type: AdminForthDataTypes.INTEGER,
    },
    {
      name: 'asker_id',
      type: AdminForthDataTypes.STRING,
    },
    {
      name: 'created_at',
      type: AdminForthDataTypes.DATETIME,
      fillOnCreate: () => (new Date()).toISOString(),
      showIn: {
        edit: false,
        create: false,
      },
    },
  ],
  options: {
    allowedActions: {
      list: allowedForSuperAdmins,
      show: allowedForSuperAdmins,
      create: false,
      edit: false,
      delete: false,
    },
  },
} as AdminForthResourceInput;
```

```ts title="./resources/agent_resources/turns.ts"
import AdminForth, { AdminForthDataTypes } from 'adminforth';
import type { AdminForthResourceInput, AdminUser } from 'adminforth';
import { randomUUID } from 'crypto';

async function allowedForSuperAdmins({ adminUser }: { adminUser: AdminUser }): Promise<boolean> {
  return adminUser.dbUser.role === 'superadmin';
}

export default {
  dataSource: 'maindb',
  table: 'turns',
  resourceId: 'turns',
  label: 'Turns',
  columns: [
    {
      name: 'id',
      primaryKey: true,
      type: AdminForthDataTypes.STRING,
      fillOnCreate: () => randomUUID(),
      showIn: {
        edit: false,
        create: false,
      },
    },
    {
      name: 'session_id',
      type: AdminForthDataTypes.STRING,
    },
    {
      name: 'created_at',
      type: AdminForthDataTypes.DATETIME,
      fillOnCreate: () => (new Date()).toISOString(),
      showIn: {
        edit: false,
        create: false,
      },
    },
    {
      name: 'prompt',
      type: AdminForthDataTypes.TEXT,
    },
    {
      name: 'response',
      type: AdminForthDataTypes.TEXT,
    },
    {
      name: 'checkpoint_id',
      type: AdminForthDataTypes.STRING,
      showIn: {
        list: false,
        show: true,
        edit: false,
        create: false,
        filter: false,
      },
    },
  ],
  options: {
    allowedActions: {
      list: allowedForSuperAdmins,
      show: allowedForSuperAdmins,
      create: false,
      edit: false,
      delete: false,
    },
  },
} as AdminForthResourceInput;
```

`asker_id` must store the current admin user's primary key, and `created_at` should be filled automatically because the plugin sorts sessions and turns by it. The `turns` field can stay nullable, but the plugin configuration still expects it. The optional `checkpoint_id` field stores the checkpoint attached to each visible turn and enables editing or forking old messages when `checkpointResource` is configured.

Add matching tables to your schema:

```prisma title='./schema.prisma'
model sessions {
  id         String   @id
  title      String
  turns      Int?
  asker_id   String
  created_at DateTime
}

model turns {
  id            String   @id
  session_id    String
  created_at    DateTime
  prompt        String?
  response      String?
  checkpoint_id String?
}
```

Run migration:

```bash
pnpm makemigration --name add-adminforth-agent-tables ; pnpm migrate:local
```

Register both resources in your app:

```ts title="./index.ts"
import sessions_resource from './resources/agent_resources/sessions.js';
import turns_resource from './resources/agent_resources/turns.js';

export const admin = new AdminForth({
  ...
  resources: [
    ...
    sessions_resource,
    turns_resource,
  ],
  ...
});
```

Then attach the plugin once in `index.ts` as global plugin:

Configure the plugin with `modes`. The legacy top-level `completionAdapter` setup is no longer used.

```ts title="./index.ts"
import AdminForthAgent from '@adminforth/agent';
import CompletionAdapterOpenAIResponses from '@adminforth/completion-adapter-openai-responses';

...

globalPlugins: [
  ...
  new AdminForthAgent({
    // optional, can be used to suggest example prompts in the UI
    // placeholderMessages: async ({ adminUser, httpExtra }) => {
    //   return [
    //     'What is a cars count in SQLite',
    //     'Build average car price by days chart in SQLite',
    //   ];
    // },
    modes: [
      {
        name: 'Balanced',
        completionAdapter: new CompletionAdapterOpenAIResponses({
          openAiApiKey: process.env.OPENAI_API_KEY as string,
          model: 'gpt-5.4-mini',
          extraRequestBodyParameters: {
            reasoning: {
              effort: 'medium',
            },
          },
        }),
      },
      {
        name: 'Fast',
        completionAdapter: new CompletionAdapterOpenAIResponses({
          openAiApiKey: process.env.OPENAI_API_KEY as string,
          model: 'gpt-5.4-mini',
          extraRequestBodyParameters: {
            reasoning: {
              effort: 'low',
            },
          },
        }),
      },
      {
        name: 'Smart Thinking',
        completionAdapter: new CompletionAdapterOpenAIResponses({
          openAiApiKey: process.env.OPENAI_API_KEY as string,
          model: 'gpt-5.4',
          extraRequestBodyParameters: {
            reasoning: {
              effort: 'xhigh',
            },
          },
        }),
      },
    ],
    maxTokens: 10000,
    sessionResource: {
      resourceId: 'sessions',
      idField: 'id',
      titleField: 'title',
      turnsField: 'turns',
      askerIdField: 'asker_id',
      createdAtField: 'created_at',
    },
    turnResource: {
      resourceId: 'turns',
      idField: 'id',
      sessionIdField: 'session_id',
      createdAtField: 'created_at',
      promptField: 'prompt',
      responseField: 'response',
      // optional
      // debugField: 'debug',
      checkpointIdField: 'checkpoint_id',
    },
    // optional, see the "Persistent checkpointer" section below
    // checkpointResource: { ... },
  }),
]
```

Each item in `modes` defines a user-selectable preset in the chat UI. The selected mode is sent to the backend and the plugin uses that mode's `completionAdapter` for the response.

The plugin adds a chat surface to the admin UI, keeps session history per admin user, and shows a mode picker when `modes` are configured.

## Chat surfaces (Telegram, etc.)

By default, the Agent plugin exposes a chat surface inside the AdminForth admin UI.
If you want to talk to the same agent from external chat products (Telegram, Slack, Teams, etc.), configure both:

- a **chat surface adapter** that receives messages from the external chat product
- an **OAuth adapter** for the same provider so users can connect that external account in **Connected Accounts**

For example, Telegram Agent access needs both `@adminforth/chat-surface-adapter-telegram` and `@adminforth/oauth-adapter-telegram`.

Register adapters through `chatSurfaceAdapters`:

```ts
import AdminForthAgent from '@adminforth/agent';
import TelegramChatSurfaceAdapter from '@adminforth/chat-surface-adapter-telegram';

new AdminForthAgent({
  // ...modes, sessionResource, turnResource, etc.
  chatSurfaceAdapters: [
    new TelegramChatSurfaceAdapter({
      botToken: process.env.TELEGRAM_BOT_TOKEN as string,
      webhookSecret: process.env.TELEGRAM_WEBHOOK_SECRET,
    }),
  ],
  chatExternalIdentityResource: {
    resourceId: 'admin_user_external_identities',
    surfaces: {
      telegram: {
        provider: 'AdminForthAdapterTelegramOauth2',
      },
    },
  },
});
```

External chat users are resolved through the OAuth external identities resource. The `provider` value in `chatExternalIdentityResource.surfaces` must match the OAuth adapter class that writes connected accounts, for example `AdminForthAdapterTelegramOauth2`.

Users connect their Telegram account from **Settings -> Connected Accounts**. After that, messages from the Telegram bot can be matched to the AdminForth user through the external identity `externalUserId`.

For Telegram setup, including required user fields, webhook URL, environment variables, and adapter options, see:

- [Telegram Chat Surface Adapter](https://adminforth.dev/docs/tutorial/Adapters/chat-surface-adapter-telegram/)

## Debugging agent turns

Agent debug traces are optional and are intended for auditability and debugging. When enabled, they let you reconstruct why an agent produced a response or made a change by storing the full execution sequence for the turn: LLM steps, tool calls, tool inputs and outputs, token usage, and cache information.

By default, only the user prompt and agent response are persisted. Full debug traces are not stored unless you configure a `debugField`, because they can be large and may significantly increase database size.

Add a `debug` JSON column to the turns resource:

```ts title="./resources/agent_resources/turns.ts"
import AdminForth, { AdminForthDataTypes } from 'adminforth';
import type { AdminForthResourceInput, AdminUser } from 'adminforth';
import { randomUUID } from 'crypto';

async function allowedForSuperAdmins({ adminUser }: { adminUser: AdminUser }): Promise<boolean> {
  return adminUser.dbUser.role === 'superadmin';
}

export default {
  dataSource: 'maindb',
  table: 'turns',
  resourceId: 'turns',
  label: 'Turns',
  columns: [
    {
      name: 'id',
      primaryKey: true,
      type: AdminForthDataTypes.STRING,
      fillOnCreate: () => randomUUID(),
      showIn: {
        edit: false,
        create: false,
      },
    },
    {
      name: 'session_id',
      type: AdminForthDataTypes.STRING,
    },
    {
      name: 'created_at',
      type: AdminForthDataTypes.DATETIME,
      fillOnCreate: () => (new Date()).toISOString(),
      showIn: {
        edit: false,
        create: false,
      },
    },
    {
      name: 'prompt',
      type: AdminForthDataTypes.TEXT,
    },
    {
      name: 'response',
      type: AdminForthDataTypes.TEXT,
    },
    //diff-add
    {
      //diff-add
      name: 'debug',
      //diff-add
      type: AdminForthDataTypes.JSON,
      //diff-add
      components: {
        //diff-add
        show: {
          //diff-add
          file: '@@/TurnDebugShow.vue',
        //diff-add
        },
      //diff-add
      },
      //diff-add
      showIn: {
        //diff-add
        list: false,
        //diff-add
        show: true,
        //diff-add
        edit: false,
        //diff-add
        create: false,
        //diff-add
        filter: false,
      //diff-add
      },
    //diff-add
    },
  ],
  options: {
    allowedActions: {
      list: allowedForSuperAdmins,
      show: allowedForSuperAdmins,
      create: false,
      edit: false,
      delete: false,
    },
  },
} as AdminForthResourceInput;
```

Add the matching field to your schema:

```prisma title="./schema.prisma"
model turns {
  id         String   @id
  session_id String
  created_at DateTime
  prompt     String?
  response   String?
  debug      Json? //diff-add
}
```

If you use SQLite with Prisma, store the same field as text:

```prisma title="./schema.prisma"
model turns {
  id         String   @id
  session_id String
  created_at DateTime
  prompt     String?
  response   String?
  debug      String? //diff-add
}
```

AdminForth should still define this resource column as `AdminForthDataTypes.JSON`; the SQLite connector serializes it into the text column and parses it back for the renderer.

Run migration:

```bash
pnpm makemigration --name add-adminforth-agent-turn-debug ; pnpm migrate:local
```

Tell the plugin where to store debug data:

```ts title="index.ts"
new AdminForthAgent({
  modes: [
    ...
  ],
  sessionResource: {
    resourceId: 'sessions',
    idField: 'id',
    titleField: 'title',
    turnsField: 'turns',
    askerIdField: 'asker_id',
    createdAtField: 'created_at',
  },
  turnResource: {
    resourceId: 'turns',
    idField: 'id',
    sessionIdField: 'session_id',
    createdAtField: 'created_at',
    promptField: 'prompt',
    responseField: 'response',
    //diff-add
    debugField: 'debug',
  },
})
```

The `debugField` value must match the turns resource column name. You can use another column name, but then use the same name in the resource, database schema, and `debugField`.

Create a renderer in your app custom folder:

```vue title="./custom/TurnDebugShow.vue"
<template>
  
    
      Agent Debug
      
        {{ debugSequences.length }} sequences,
        {{ totalToolCalls }} tool calls,
        {{ totalUncachedInputTokens.toLocaleString() }} uncached input tokens,
        {{ totalCachedInputTokens.toLocaleString() }} cached input tokens,
        {{ totalOutputTokens.toLocaleString() }} output tokens
      
    

    <JsonViewer :value="debugSequences" :expandDepth="2" />
  
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { JsonViewer } from '@/afcl';
import type { AdminForthResourceColumnCommon } from '@/types/Common';

type DebugToolCall = {
  toolName: string;
};

type DebugSequence = {
  uncachedInputTokens?: number;
  cachedInputTokens?: number;
  outputTokens?: number;
  cachedTokens: number;
  promptTokens: number;
  reasoningTokens: number;
  textTokens: number;
  toolCalls: DebugToolCall[];
};

const props = defineProps<{
  column: AdminForthResourceColumnCommon;
  record: Record<string, DebugSequence[]>;
}>();

const debugSequences = computed(() => props.record[props.column.name] ?? []);
const totalToolCalls = computed(() =>
  debugSequences.value.reduce((sum, sequence) => sum + sequence.toolCalls.length, 0),
);
const totalUncachedInputTokens = computed(() =>
  debugSequences.value.reduce((sum, sequence) => sum + sequenceUncachedInputTokens(sequence), 0),
);
const totalCachedInputTokens = computed(() =>
  debugSequences.value.reduce((sum, sequence) => sum + sequenceCachedInputTokens(sequence), 0),
);
const totalOutputTokens = computed(() =>
  debugSequences.value.reduce((sum, sequence) => sum + sequenceOutputTokens(sequence), 0),
);

function sequenceUncachedInputTokens(sequence: DebugSequence) {
  return sequence.uncachedInputTokens ?? Math.max(sequence.promptTokens - sequenceCachedInputTokens(sequence), 0);
}

function sequenceCachedInputTokens(sequence: DebugSequence) {
  return sequence.cachedInputTokens ?? sequence.cachedTokens;
}

function sequenceOutputTokens(sequence: DebugSequence) {
  return sequence.outputTokens ?? sequence.reasoningTokens + sequence.textTokens;
}
</script>
```

# Using with self-hosted models

`CompletionAdapterOpenAIResponses` when works with agent plugin, under the hood uses the LangChain internal proxy called `OpenAIChat` (in LangChain they call it "provider"). This proxy is capable with a fresh versions of OpenAI-compatible Responses APIs, for example [self-hosted latest versions of vLLM installations](https://devforth.io/insights/self-hosted-gpt-real-response-time-token-throughput-and-cost-on-l4-l40s-and-h100-for-gpt-oss-20b/)
To use them, just point the adapter to your local vLLM server:

```ts
completionAdapter: new CompletionAdapterOpenAIResponses({
  openAiApiKey: process.env.MY_API_KEY as string, // if you use authorization
  baseUrl: 'http://my_local_vllm_server:8000/v1',  
  model: 'gpt-oss-120b',
})
```

However some of 3rd party providers might serve outdated vLLM and still don't fully support the Responses API needed for langchain internal implmentation, for example [OVH AI Endpoints](https://www.ovhcloud.com/en/public-cloud/ai-endpoints/) in Responses mode still don't play well with langchain proxy (25 Apr 2026)

In that case you can try to use the OpenAI Chat Completions API mode of the plugin, which is less efficient but more compatible with older APIs, you can force Chat Completions API mode with `useCompletionApi: true`:

```ts
completionAdapter: new CompletionAdapterOpenAIResponses({
  openAiApiKey: process.env.OVH_AI_ENDPOINTS_ACCESS_TOKEN as string,
  baseUrl: 'https://oai.endpoints.kepler.ai.cloud.ovh.net/v1',
  model: 'gpt-oss-120b',
  useCompletionApi: true,
})
```

OVH AI Endpoints still does not fully support the OpenAI `responses` API, so `useCompletionApi: false` may work unstably there.

## Turn on audio chat support
If you want to have an ability to talk with agent usng voice, you can setup it:

1) Install audio adapter:

```bash
pnpm add @adminforth/audio-adapter-openai
```

2) Import it in your users resource and add to the plugin config

```ts title="index.ts"
  //diff-add
  import OpenAIAudioAdapter from '@adminforth/audio-adapter-openai'

  ...

  new AdminForthAgent({
    ...
    //diff-add
    audioAdapter: new OpenAIAudioAdapter({
      //diff-add
      apiKey: process.env.OPENAI_API_KEY as string,,
      //diff-add
      defaultVoice: 'alloy',
      //diff-add
      defaultSpeed: 1.25,
    //diff-add
    }),
    ...
  }),
  ...

```

## Writing own skills

You can write own skills by following [SKILL.md Agennt Skills](https://agentskills.io/)

For example we will write a skill which can summarizes backoffice data stats like record counts by resources and send it to user email.

It may handle prompts like

```
Please send record counts for all resources to my email
```

Or:

```
Please send record counts to all admin users
```

### Writing custom tools

To define a custom tool, register an API endpoint with `admin.express.endpoint`. The endpoint schema makes the API visible in OpenAPI, and the endpoint `handler` gives the agent a direct function it can call as a tool.

`admin.express.withSchema` is useful when you already have a regular Express route and want it to appear in the generated OpenAPI document. However, a route registered only with `withSchema` is not a directly callable agent tool, because it does not register a direct OpenAPI handler. For agent tools, use `admin.express.endpoint`.

By default, `admin.express.endpoint` applies AdminForth authorization. The endpoint handler receives `adminUser` from the user who is controlling the agent. In other words, all permissions and access rights of the agent are defined by that admin user. At the same time, actions done by the agent are automatically attributed in the audit log to the admin user who is controlling the agent.

If a tool is risky, you can attach AdminForth agent metadata directly to the endpoint with the `agent` field.

```ts
type AgentRiskLevel = 'safe' | 'danger';

type AgentToolMeta = {
  riskLevel?: AgentRiskLevel;
  confirmation?: {
    title?: string;
    message?: string;
    confirmLabel?: string;
  };
};
```

Use it in `.endpoint(...)` like this:

- `riskLevel: 'safe'` marks the tool as low-risk.
- `riskLevel: 'danger'` marks the tool as dangerous.
- `confirmation` customizes the confirmation dialog shown before the tool is executed.

This metadata is rendered into the generated OpenAPI document, so the agent can understand that a tool is dangerous and requires an explicit confirmation UI before execution.

This example uses the same email adapter pattern shown in the Email Invite and Email Password Reset plugins. The transport below uses Mailgun only to keep the snippet short; you can replace it with SES or any other adapter from [List of adapters](/docs/tutorial/ListOfAdapters/).

```ts title="./api.ts"
import { Filters, type IAdminForth } from 'adminforth';
import EmailAdapterMailgun from '@adminforth/email-adapter-mailgun';

const agentEmailAdapter = new EmailAdapterMailgun({
  apiKey: process.env.MAILGUN_API_KEY as string,
  domain: process.env.MAILGUN_DOMAIN as string,
  baseUrl: process.env.MAILGUN_REGION_URL || 'api.mailgun.net',
});
const agentSendFrom = process.env.AGENT_SEND_FROM_EMAIL as string;

function escapeHtml(value: string) {
  return value
    .replace(/&/g, '&amp;')
    .replace(/</g, '&lt;')
    .replace(/>/g, '&gt;');
}

function renderEmailHtml(body: string) {
  return `<html><body><pre style="font-family: sans-serif; white-space: pre-wrap;">${escapeHtml(body)}</pre></body></html>`;
}

type SendEmailBody = {
  userId: string;
  subject: string;
  body: string;
  htmlBody?: string;
};

export function initApi(app: Express, admin: IAdminForth) {
  admin.express.endpoint({
    method: 'POST',
    path: '/send_email_to_user',
    description: 'Send an email to one AdminForth user by id. Use this after the user row is resolved.',
    agent: {
      riskLevel: 'danger',
      confirmation: {
        title: 'Send email to user',
        message: 'This action will send a real email to the selected user.',
        confirmLabel: 'Send email',
      },
    },
    request_schema: {
      type: 'object',
      additionalProperties: false,
      required: ['userId', 'subject', 'body'],
      properties: {
        userId: { type: 'string' },
        subject: { type: 'string', minLength: 1 },
        body: { type: 'string', minLength: 1 },
        htmlBody: { type: 'string', minLength: 1 },
      },
    },
    response_schema: {
      type: 'object',
      additionalProperties: false,
      required: ['ok'],
      properties: {
        ok: { type: 'boolean' },
        email: { type: 'string' },
        error: { type: 'string' },
      },
    },
    handler: async ({ body, response }) => {
      const { userId, subject, body: emailBody, htmlBody } = body as SendEmailBody;

      await agentEmailAdapter.validate();

      const user = await admin.resource('adminuser').get(
        Filters.EQ('id', userId),
      );

      if (!user) {
        response.setStatus(404, 'User not found');
        return { ok: false, error: 'User not found' };
      }

      const result = await agentEmailAdapter.sendEmail(
        agentSendFrom,
        user.email as string,
        emailBody,
        htmlBody ?? renderEmailHtml(emailBody),
        subject,
      );

      if (!result.ok) {
        response.setStatus(500, 'Failed to send email');
        return { ok: false, error: result.error ?? 'Failed to send email' };
      }

      return { ok: true, email: user.email };
    },
  });
}
```

## Define skills instructions

Custom skills live in your app's custom directory. The agent loads project skills from:

- `custom/skills/<skill_name>/SKILL.md`

Also it can load skills from plugins, it allows other plugins to expose their own skills and tools:

- `custom/plugins/adminforth-agent/skills/<skill_name>/SKILL.md`

Each skill needs YAML frontmatter with `name` and `description`. The `description` is the discovery surface, so include the phrases the admin is likely to type in chat. Skills are not loaded automcatically, agent loads them 
on demand once understands that `description` of the skill matches the user intent, so keep the description clear and concise.

Tools are also not loaded automatically, the agent loads them only if they are mentioned in the skill instructions. Then agent calls `fetch_tool_schema` meta tool to load actual schema of your custom tool.

Tool names are derived from route paths. If you want the tool name to be exactly `send_email_to_user`, register the route as `/send_email_to_user`.

The example below creates a minimal user skill which:

- resolves a user row
- reads the `total` count for each resource with `get_resource_data`
- sends the final report by email with `send_email_to_user`

Create the skill in your app custom folder:

```md title="./custom/skills/email_resource_counts/SKILL.md"
---
name: email_resource_counts
description: Email record counts for each AdminForth resource to a user. Use when the user asks to send resource counts or all-record statistics by email.
---

# Involved tools

Use `send_email_to_user` to send the final report after you have one exact target user row.

# Instructions

- For each resource in system use fetch data default skill to collect total count of records in each resource.
- Create both a plain text report and an HTML report in format `Resource Label (resourceId): count` for each resource on a new line, sort resources by count in descending order.
- Use modern, stylish but compatible html formatting in the email.
- Call `send_email_to_user` with the resolved user primary key, the final subject, the final plain text `body`, and the final HTML markup in `htmlBody`.
- After the tool succeeds, tell the user the email was sent and include a short summary in chat.
```

This way allows to extend your agent with literally any custom instructions and tools and make it do complex tasks related to your backoffice data and operations.

## Standard skills

The plugin ships with bundled skills from `plugins/adminforth-agent/custom/skills/`. These are available out of the box and can be combined with your own custom skills.

| Folder | Skill name | Description |
| --- | --- | --- |
| `analyze_data` | `analyze_data` | Analyze AdminForth resource data, summarize trends, and create charts from fetched rows. Prefer server-side aggregation when possible and return Vega-Lite specs for charts. |
| `fetch_data` | `fetch_data` | Fetch one or more exact records with filters after inspecting the resource schema. This skill is for finding rows, not for aggregations. |
| `mutate_data` | `mutate_data` | Create, update, delete, or run actions on records. Before any mutation it must show the exact target row and ask the user for confirmation. |

## Persistent agent memory

The plugin stores visible chat history in the `sessions` and `turns` resources. This is what users see in the chat sidebar and in old conversations.

The agent also needs its own internal conversation state to continue an existing chat. If you do not configure `checkpointResource`, that internal state is kept only in the Node.js process memory. This is fine for local testing and for new chats, but it is not durable:

- after a server restart, users can still see old chat messages because `sessions` and `turns` are stored in your database
- after a server restart, users can continue an old chat, but the agent will treat it like a new conversation because its internal state was lost
- new chats will work normally again until the next restart

For production, configure `checkpointResource` so the agent can safely continue old chats after restarts and deployments.

You can use your own table and field names. The plugin does not require a specific schema name, only a mapping for these logical fields:

- `idField`
- `threadIdField`
- `checkpointNamespaceField`
- `checkpointIdField`
- `parentCheckpointIdField`
- `rowKindField`
- `taskIdField`
- `sequenceField`
- `createdAtField`
- `checkpointPayloadField`
- `metadataPayloadField`
- `writesPayloadField`
- `schemaVersionField`

Create a resource for checkpoint rows:

```ts title="./resources/agent_resources/checkpoints.ts"
import { AdminForthDataTypes } from 'adminforth';
import type { AdminForthResourceInput } from 'adminforth';

export default {
  dataSource: 'maindb',
  table: 'agent_checkpoints',
  resourceId: 'agent_checkpoints',
  label: 'Agent Checkpoints',
  recordLabel: (record) => record.id,
  options: {
    allowedActions: {
      create: false,
      edit: false,
    },
  },
  columns: [
    {
      name: 'id',
      primaryKey: true,
      type: AdminForthDataTypes.STRING,
      showIn: {
        edit: false,
        create: false,
      },
    },
    {
      name: 'thread_id',
      type: AdminForthDataTypes.STRING,
    },
    {
      name: 'checkpoint_namespace',
      type: AdminForthDataTypes.STRING,
    },
    {
      name: 'checkpoint_id',
      type: AdminForthDataTypes.STRING,
    },
    {
      name: 'parent_checkpoint_id',
      type: AdminForthDataTypes.STRING,
    },
    {
      name: 'row_kind',
      type: AdminForthDataTypes.STRING,
      enum: [
        { value: 'checkpoint', label: 'Checkpoint' },
        { value: 'writes', label: 'Writes' },
      ],
    },
    {
      name: 'task_id',
      type: AdminForthDataTypes.STRING,
    },
    {
      name: 'sequence',
      type: AdminForthDataTypes.INTEGER,
    },
    {
      name: 'created_at',
      type: AdminForthDataTypes.DATETIME,
      showIn: {
        edit: false,
        create: false,
      },
    },
    {
      name: 'checkpoint_payload',
      type: AdminForthDataTypes.JSON,
      showIn: {
        list: false,
      },
    },
    {
      name: 'metadata_payload',
      type: AdminForthDataTypes.JSON,
      showIn: {
        list: false,
      },
    },
    {
      name: 'writes_payload',
      type: AdminForthDataTypes.JSON,
      showIn: {
        list: false,
      },
    },
    {
      name: 'schema_version',
      type: AdminForthDataTypes.INTEGER,
    },
  ],
} as AdminForthResourceInput;
```

Add a matching table to your schema:

```prisma title='./schema.prisma'
model agent_checkpoints {
  id                   String   @id
  thread_id            String
  checkpoint_namespace String
  checkpoint_id        String
  parent_checkpoint_id String?
  row_kind             String
  task_id              String?
  sequence             Int
  created_at           DateTime
  checkpoint_payload   String?
  metadata_payload     String?
  writes_payload       String?
  schema_version       Int

  @@index([thread_id, checkpoint_namespace, checkpoint_id])
}
```

The payload fields can be stored as strings. The plugin serializes and deserializes checkpoint JSON on its own. The composite index on `(thread_id, checkpoint_namespace, checkpoint_id)` is recommended because the checkpointer filters rows by these columns.

Run migration:

```bash
pnpm makemigration --name add-adminforth-agent-checkpoints ; pnpm migrate:local
```

Register the resource in your app:

```ts title="./index.ts"
import checkpoints_resource from './resources/agent_resources/checkpoints.js';
import sessions_resource from './resources/agent_resources/sessions.js';
import turns_resource from './resources/agent_resources/turns.js';

export const admin = new AdminForth({
  ...
  resources: [
    ...
    sessions_resource,
    turns_resource,
    checkpoints_resource,
  ],
  ...
});
```

Then connect it to the plugin:

```ts title="index.ts"
new AdminForthAgent({
  modes: [
    ...
  ],
  sessionResource: {
    resourceId: 'sessions',
    idField: 'id',
    titleField: 'title',
    turnsField: 'turns',
    askerIdField: 'asker_id',
    createdAtField: 'created_at',
  },
  turnResource: {
    resourceId: 'turns',
    idField: 'id',
    sessionIdField: 'session_id',
    createdAtField: 'created_at',
    promptField: 'prompt',
    responseField: 'response',
    checkpointIdField: 'checkpoint_id',
  },
  checkpointResource: {
    resourceId: 'agent_checkpoints',
    idField: 'id',
    threadIdField: 'thread_id',
    checkpointNamespaceField: 'checkpoint_namespace',
    checkpointIdField: 'checkpoint_id',
    parentCheckpointIdField: 'parent_checkpoint_id',
    rowKindField: 'row_kind',
    taskIdField: 'task_id',
    sequenceField: 'sequence',
    createdAtField: 'created_at',
    checkpointPayloadField: 'checkpoint_payload',
    metadataPayloadField: 'metadata_payload',
    writesPayloadField: 'writes_payload',
    schemaVersionField: 'schema_version',
  },
});
```

If your existing checkpoint table already uses different column names, keep your schema and only change the field mapping in `checkpointResource`.

## Reverse proxy and CDN configuration for streaming

The agent streams responses from `<baseURL>/adminapi/v1/agent/response` using server-sent events, where `<baseURL>` is your AdminForth base path or an empty string when deployed at the domain root. Voice mode also streams from `<baseURL>/adminapi/v1/agent/speech-response` after uploading the recorded audio. If your proxy buffers responses, the UI will receive the answer only after generation is finished.

For Nginx, disable response buffering on both endpoints. The critical line is `proxy_buffering off;`.

```nginx
location <baseURL>/adminapi/v1/agent/response {
  proxy_http_version 1.1;
  proxy_read_timeout 600s;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header Host $http_host;
  proxy_set_header Connection "";
  proxy_buffering off;  # required for streaming
  proxy_pass http://127.0.0.1:3500;
}

location <baseURL>/adminapi/v1/agent/speech-response {
  proxy_http_version 1.1;
  proxy_read_timeout 600s;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header Host $http_host;
  proxy_set_header Connection "";
  proxy_buffering off;  # required for streaming voice responses
  proxy_pass http://127.0.0.1:3500;
}
```

Traefik forwards streaming responses immediately by default. The line that must stay off these routes is any buffering middleware attachment such as `traefik.http.routers.adminforth-agent.middlewares=buffering@docker`. If your main router uses extra middlewares, create a dedicated router for the agent stream endpoints and do not attach buffering to it:

```yaml title='./compose.yml'
services:
  adminforth:
    labels:
      - "traefik.enable=true"
      - "traefik.http.services.adminforth.loadbalancer.server.port=3500"

      - "traefik.http.routers.adminforth.rule=PathPrefix(`/`)"
      - "traefik.http.routers.adminforth.tls=true"
      - "traefik.http.routers.adminforth.tls.certresolver=myresolver"
      - "traefik.http.routers.adminforth.middlewares=secure-headers,buffering@docker"

      - "traefik.http.routers.adminforth-agent.rule=Path(`<baseURL>/adminapi/v1/agent/response`) || Path(`<baseURL>/adminapi/v1/agent/speech-response`)"
      - "traefik.http.routers.adminforth-agent.priority=100"
      - "traefik.http.routers.adminforth-agent.service=adminforth"
      - "traefik.http.routers.adminforth-agent.tls=true"
      - "traefik.http.routers.adminforth-agent.tls.certresolver=myresolver"
      # keep buffering OFF for SSE
      # do not add:
      # - "traefik.http.routers.adminforth-agent.middlewares=buffering@docker"
```

  Replace `<baseURL>` with the same base path you use for AdminForth. For example, when `ADMIN_BASE_URL = '/admin/'`, the endpoints become `/admin/adminapi/v1/agent/response` and `/admin/adminapi/v1/agent/speech-response`.

### CDN

  Cloudflare by default buffers responses, which breaks streaming. To fix it, create a page rule for your domain with a "Response Body Buffering" setting turned off for the agent stream endpoints (`<baseURL>/adminapi/v1/agent/response` and `<baseURL>/adminapi/v1/agent/speech-response`).

  If Cloudflare returns a 403 response with `cf-mitigated: challenge` for `<baseURL>/adminapi/v1/agent/speech-response`, the request was blocked before it reached AdminForth. Create a WAF or bot rule exception for authenticated requests to this endpoint, because browser `fetch` calls with `multipart/form-data` cannot complete an HTML challenge page.

![alt text](image-6.png)

---

## Two-Factor Authentication Plugin

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Two-Factor Authentication Plugin

The Two-Factor Authentication Plugin provides an additional layer of security to the application by requiring users to provide a second form of authentication in addition to their password. This plugin supports  authenticator apps.

Plugin supports next 2FA methods:
- TOTP (Time-based One-Time Password) via authenticator apps (Google Authenticator, Authy, Microsoft Authenticator, etc)
- Upgrade to Passkeys (WebAuthn) alongside TOTP (with TOTP as alternative method)

Also it supports both:

- Multi-Factor Authentication (MFA): asking for 2FA on every login (or single WebAuthn passkey login)
- Step-Up MFA: asking for 2FA again on critical operations (custom actions, secure save etc)

## Installation

``` bash
pnpm add @adminforth/two-factors-auth --save
```

To import:

```ts title="/adminuser.ts"
import TwoFactorsAuthPlugin from '@adminforth/two-factors-auth';
```

Plugin required some additional setup, to make it work properly. It should be added to the resource auth resource. In our example we will add it to the user resource .

```ts title='./schema.prisma'
model adminuser {
  id            String     @id
  created_at    DateTime
  email         String   @unique
  role          String
  password_hash String
//diff-add
  secret2fa     String?
}
```

Then:

```bash
pnpm makemigration --name add-2fa-secret ; pnpm migrate:local
```

And add it to `adminuser.ts`

```ts tittle="./resources/adminuser.ts"
{
    table: 'adminuser',
//diff-add
    plugins: [
//diff-add
        new TwoFactorsAuthPlugin ({ twoFaSecretFieldName: 'secret2fa', timeStepWindow: 1 }),
//diff-add
    ],
    columns: [
        ...
//diff-add
        {
//diff-add
            name: 'secret2fa',
//diff-add
            showIn: { all: false },
//diff-add
            backendOnly: true,
//diff-add
        }
    ],
  }
```

> 💡 **Note**: Time-Step Size
>
> By default, `timeStepWindow` is set to `1`, which means the Two-Factor Authentication Plugin will check the current 30-second time-step, as well as one step before and after, to validate a TOTP code. This aligns with [RFC 6238](https://www.rfc-editor.org/rfc/rfc6238) best practices to accommodate slight clock drift between the server and the user's device.
>
> For example, if a code is generated between **12:00:00** and **12:00:30**, it will typically expire at **12:00:30**. However, with a `timeStepWindow` of `1`, the plugin will continue to accept it up to **12:00:59** (the “next” 30-second step), preventing users from being locked out if their device clock is a few seconds off. Once the clock hits **12:01:00**, that previous code will be treated as expired.
>
> If you find users frequently encountering code mismatches due to clock drift, you can increase `timeStepWindow` to `2`. **However, be cautious: larger windows can reduce overall security!**
>
> ❗ With a `timeStepWindow` set to `0`, the plugin will pass all the expired codes, which is not secure and should only be used for testing purposes.

Thats it! Two-Factor Authentication is now enabled:
![alt text](image-1.png)

## Disabling Two-Factor Authentication locally

If it is not convenient to enter the code every time during local development, you can disable Two-Factor Authentication for the dev environment using `usersFilterToApply` option:

```ts title='./index.ts'

    plugins: [
        new TwoFactorsAuthPlugin ({
          twoFaSecretFieldName: 'secret2fa',
//diff-add
          usersFilterToApply: (adminUser: AdminUser) => {
//diff-add
            // if this method returns true, 2FA will be enforced for this user, if returns false - 2FA will be disabled
//diff-add
            if (process.env.NODE_ENV === 'development') {
//diff-add
              return false;
//diff-add
            }
//diff-add
            return true;
//diff-add
          },
        }),
    ],
```

> Note: you can enable it temporarey while testing two-factor authentication flow locally and then disable.

## Select which users should use Two-Factor Authentication

By default plugin enforces Two-Factor Authentication for all users.

If you wish to enforce 2FA only for specific users, you can again use `usersFilterToApply` option:

```ts title='./adminuser.ts'
  usersFilterToApply: (adminUser: AdminUser) => {
    // disable 2FA for users which email is 'adminforth' or 'adminguest'
    return !(['adminforth', 'adminguest'].includes(adminUser.dbUser.email));
  },
```

Other users (for whom this function returns false) will not be even suggested to setup 2FA and it will be not requested for them, nor on login, nor on step-up MFA requests (such requests will be automatically passed for them without any popups)

### Control 2FA per-user via DB field

You can even add a boolean column to the user table to store whether the user should use 2FA or not:

In `schema.prisma`:

```ts title='./schema.prisma'
model adminuser {
  id            String     @id
  created_at    DateTime
  email         String   @unique
  role          String
  password_hash String
  secret2fa     String?
  //diff-add
  use2fa        Boolean?  @default(false)
}
```

Then run:

```bash
pnpm makemigration --name add-use2fa ; pnpm migrate:local
```

Then in `adminuser.ts`:

```ts title='./adminuser.ts'
{
    resourceId: 'adminuser',
    ...
    columns: [
        ...
        {
            name: 'use2fa',
        }
        ...
    ],
    options: {
      allowedActions: {
        delete: async ({ adminUser }: { adminUser: AdminUser }) => {
          // only superadmin can delete users
          return adminUser.dbUser.role === 'superadmin';
        },
        create: async ({ adminUser }: { adminUser: AdminUser }) => {
          // only superadmin can create users
          return adminUser.dbUser.role === 'superadmin';
        },
        edit: async ({ adminUser, meta }: { adminUser: AdminUser }) => {
          // user can modify only his own record
          const { oldRecord } = meta;
          return adminUser.dbUser.id === oldRecord.id;
        },
      }
    },
    plugins: [
        new TwoFactorsAuthPlugin ({
          twoFaSecretFieldName: 'secret2fa',
          usersFilterToApply: (adminUser: AdminUser) => {
            return adminUser.dbUser.use2fa;
          },
        }),
    ],
}
```

## Allow Specific Users to Skip Two-Factor Authentication Setup

By default, all users are required to setup Two-Factor Authentication if it is enabled (enforced).

If you want to allow specific users to **skip** the 2FA setup (but still suggest it as optional possibility), you can use the `usersFilterToAllowSkipSetup` option:

```ts title='./adminuser.ts'
...
plugins: [
  new TwoFactorsAuthPlugin ({
    twoFaSecretFieldName: 'secret2fa',
    ...
  //diff-add
    usersFilterToAllowSkipSetup: (adminUser: AdminUser) => {
      //diff-add
      // allow skip setup 2FA for users which email is 'adminforth' or 'adminguest'
      //diff-add
      return (['adminforth', 'adminguest'].includes(adminUser.dbUser.email));
      //diff-add
    },
  }),
],
...
```

So such users will have suggestion to setup 2FA, but will be able to skip it with "Skip for now" button.

## Calling 2FA modal from backend
If you wan't to call 2FA verification modal from the backend for verification, you can use

```ts
t2fa.verifyAuto(adminUser);
```
This method opens 2FA verification modal at the frontend and then returns verification result.
The modal is shown only in the same browser tab/window which made the backend request.
Because of this, `verifyAuto` must be called from a browser-initiated request handled by AdminForth request context, for example from an endpoint wrapped with `admin.express.authorize`.
 
Here is an example:

```ts title="./api.ts"
  //diff-add
  app.get(`${admin.config.baseUrl}/api/test2faCall/`,
  //diff-add
    admin.express.authorize(
      //diff-add
      async (_req: IAdminUserExpressRequest, res: Response) => {
        //diff-add
        const { adminUser } = _req;
        //diff-add
        //diff-add
        const t2fa = admin.getPluginByClassName('TwoFactorsAuthPlugin');
        //diff-add
        const verifyResult = await t2fa.verifyAuto(adminUser);
        //diff-add
        if (verifyResult.ok) {
          //diff-add
          //some critical action
          //diff-add
          res.json({ ok: "true" });
        //diff-add
        }
        //diff-add
        res.json({ok: "false", message: "Verification failed"})
      //diff-add
      }
    //diff-add
    )
  //diff-add
  );
```

Under the hood, this metod uses websocket.

## Manual Step-Up MFA (Two-Factor re-authentication on critical operations)
But if you websocket doesn't work in you application, or you wan't to perform verification manually, here are manual verification examples

### Request 2FA on custom Actions

You might want to to allow to call some custom critical/money related actions with additional 2FA approval. This eliminates risks caused by user cookies theft by some virous/doorway software after login.

To do it, first, create frontend custom component which wraps and intercepts click event to menu item, and in click handler do a call to `get2FaConfirmationResult` frontend API exposed by this plugin. This is awaitable call wich shows 2FA popup and asks user to authenticate with 2nd factor (if passkey is enabled it will be suggested first, with ability to fallback to TOTP)

```ts title='/custom/RequireTwoFaGate.vue'
<template>
  
    <slot />  <!-- render action default content - button/icon -->
  
</template>

<script setup lang="ts">
  import { useTwoFactorsAuth } from '@/custom/plugins/TwoFactorsAuthPlugin/use2faApi.ts';

  const { get2FaConfirmationResult } = useTwoFactorsAuth();
  const emit = defineEmits<{ (e: 'callAction', payload?: any): void }>();
  const props = defineProps<{ disabled?: boolean; meta?: Record<string, any> }>();

  async function onClick() {
    if (props.disabled) {
      return;
    }
  
    const verificationResult = await get2FaConfirmationResult(); // this will ask user to enter code
    emit('callAction', { verificationResult }); // then we pass this verification result to action (from fronted to backend)
  }
</script>
```

Now we need to use verification result which we got from user on frontend, inside of backend action handler and verify that it is valid (and not expired):

```ts title='/adminuser.ts'
options: {
  actions: [
    {
      name: 'Auto submit',
      icon: 'flowbite:play-solid',
      allowed: () => true,
      action: async ({ recordId, adminUser, adminforth, response, extra }) => {
        //diff-add
        const verificationResult = extra?.verificationResult
        //diff-add
        if (!verificationResult) {
          //diff-add
          return { ok: false, error: 'No verification result provided' };
        //diff-add
        }
        //diff-add
        const t2fa = adminforth.getPluginByClassName<TwoFactorsAuthPlugin>('TwoFactorsAuthPlugin');
        //diff-add
        const result = await t2fa.verify(verificationResult, {
        //diff-add
          adminUser: adminUser,
        //diff-add
          userPk: adminUser.pk,
        //diff-add
          extra: extra,
        //diff-add
        });

        //diff-add
        if (!result?.ok) {
          //diff-add
          return { ok: false, error: result?.error ?? 'Provided 2fa verification data is invalid' };
          //diff-add
        }
        //diff-add
        await adminforth
        //diff-add
          .getPluginByClassName<AuditLogPlugin>('AuditLogPlugin')
          //diff-add
          .logCustomAction({
            //diff-add
            resourceId: 'aparts',
            //diff-add
            recordId: null,
            //diff-add
            actionId: 'visitedDashboard',
            //diff-add
            oldData: null,
            //diff-add
            data: { dashboard: 'main' },
            //diff-add
            user: adminUser,
            //diff-add
          });

          //your critical action logic 
      
        return { ok: true, successMessage: 'Auto submitted' };
      },
      showIn: { showButton: true, showThreeDotsMenu: true, list: true },
      //diff-add
      customComponent: '@@/RequireTwoFaGate.vue',
    },
  ],
}
```

### Request 2FA for create/edit (secure save gating)

To protect create and edit operations, use a Save Interceptor injected on the page to gate the save with 2FA, and forward the result to the backend for verification. This avoids wrapping the Save button and works with the default UI.

Frontend (Save Interceptor component injected via pageInjections):

```vue title='/custom/SaveInterceptor.vue'
<script setup>
import { useAdminforth } from '@/adminforth';
import { useTwoFactorsAuth } from '@/custom/plugins/TwoFactorsAuthPlugin/use2faApi.ts';

const { get2FaConfirmationResult } = useTwoFactorsAuth();
const { registerSaveInterceptor } = useAdminforth();

registerSaveInterceptor(async ({ action, values, resource }) => {
  // action is 'create' or 'edit'
  const confirmationResult = await get2FaConfirmationResult('Confirm to save changes');
  if (!confirmationResult) {
    return { ok: false, error: 'Two-factor authentication cancelled' };
  }
  // Pass data to backend; the view will forward extra.confirmationResult to meta.confirmationResult
  return { ok: true, extra: { confirmationResult } };
  else {
    throw new Error('No Two-Factor Authentication modal found, please ensure you have latest version of @adminforth/two-factors-auth installed and instantiated on resource');
  }
  return { ok: false, error: 'Two-factor authentication code is required' };
});
</script>

<template></template>
```

Resource injection (edit/create):

```ts
options: {
  pageInjections: {
    edit: { bottom: [{ file: '@@/SaveInterceptor.vue' }] },
    create: { bottom: [{ file: '@@/SaveInterceptor.vue' }] },
  }
}
```
Note: You can use any injection which executes JS on a page where Save bottom is rendered, not only bottom

Backend (resource hook verification):

```ts
// Inside resource config
hooks: {
  edit: {
    beforeSave: async ({ adminUser, adminforth, response, extra }) => {
      const t2fa = adminforth.getPluginByClassName('TwoFactorsAuthPlugin');
      if (!t2fa) {
        return { ok: false, error: 'TwoFactorsAuthPlugin is not configured' };
      }

      const confirmationResult = extra?.body?.meta?.confirmationResult;
      if (!confirmationResult) {
        return { ok: false, error: 'Two-factor authentication confirmation result is missing' };
      }

      const verifyRes = await t2fa.verify(confirmationResult, {
        adminUser,
        userPk: adminUser.pk,
        extra
      });
      if (!verifyRes || 'error' in verifyRes) {
        return { ok: false, error: verifyRes?.error || 'Two-factor verification failed' };
      }
      return { ok: true };
    },
  },
  create: {
    beforeSave: async ({ adminUser, adminforth, response, extra }) => {
      const t2fa = adminforth.getPluginByClassName('TwoFactorsAuthPlugin');
      if (!t2fa) {
        return { ok: false, error: 'TwoFactorsAuthPlugin is not configured' };
      }

      const confirmationResult = extra?.body?.meta?.confirmationResult;
      if (!confirmationResult) {
        return { ok: false, error: 'Two-factor authentication confirmation result is missing' };
      }

      const verifyRes = await t2fa.verify(confirmationResult, {
        adminUser,
        userPk: adminUser.pk,
        extra
      });
      if (!verifyRes || 'error' in verifyRes) {
        return { ok: false, error: verifyRes?.error || 'Two-factor verification failed' };
      }
      return { ok: true };
    },
  },
}
```

This approach ensures 2FA cannot be bypassed by calling the API directly:
- The client collects verification via the Save Interceptor and forwards it under `meta.confirmationResult`.
- The server validates it in `beforeSave` with access to `extra.cookies` and the `adminUser`.

### Request 2FA from custom components

Imagine you have some button which does some API call

```ts
<template>
  <Button @click="callAdminAPI">Call critical API</Button>
</template>
  

<script setup lang="ts">
import { callApi } from '@/utils';
import { useTwoFactorsAuth } from '@/custom/plugins/TwoFactorsAuthPlugin/use2faApi.ts';

const { get2FaConfirmationResult } = useTwoFactorsAuth();

async function callAdminAPI() {
  const verificationResult = await get2FaConfirmationResult();

  const res = await callApi({
    path: '/myCriticalAction',
    method: 'POST',
    body: {
      param: 1
    },
  });
}
</script>
```

On backend you have simple express api

```ts
app.post(`${ADMIN_BASE_URL}/myCriticalAction`,
  admin.express.authorize(
    async (req: any, res: any) => {

      // ... your critical logic ...

      return res.json({ ok: true, successMessage: 'Action executed' });
    }
  )
);
```

You might want to protect this call with a second factor also. To do it, we need to make this change

```ts
<template>
  <Button @click="callAdminAPI">Call critical API</Button>
</template>
  

<script setup lang="ts">
import { callApi } from '@/utils';
import { useAdminforth } from '@/adminforth';
import { useTwoFactorsAuth } from '@/custom/plugins/TwoFactorsAuthPlugin/use2faApi.ts';

const { get2FaConfirmationResult } = useTwoFactorsAuth();
const { alert } = useAdminforth();

async function callAdminAPI() {
  // diff-add
  const verificationResult = await get2FaConfirmationResult();

  const res = await callApi({
    path: '/myCriticalAction',
    method: 'POST',
    body: {
      param: 1,
  // diff-add
      verificationResult: String(verificationResult)
    },
  });

  // diff-add
  if (!res?.ok) {
  // diff-add
    alert({ message: res.error, variant: 'danger' });
  // diff-add
  }
}
</script>

```

And on API call we need to verify it:

```ts
app.post(`${ADMIN_BASE_URL}/myCriticalAction`,
  admin.express.authorize(
    async (req: any, res: any) => {

      // diff-add
      const { adminUser } = req;
      // diff-add
      const { param, verificationResult } = req.body ?? {};
      // diff-add
      const t2fa = admin.getPluginByClassName<TwoFactorsAuthPlugin>('TwoFactorsAuthPlugin');
      // diff-add
      const verifyRes = await t2fa.verify(verificationResult, {
      // diff-add
        adminUser: adminUser,
      // diff-add
        userPk: adminUser.pk,
      //diff-add
        extra: {...req.headers, ...req.cookies, response: res},
      //diff-add
      });
      // diff-add
      if (!('ok' in verifyRes)) {
      // diff-add
        return res.status(400).json({ ok: false, error: verifyRes.error || 'Verification failed' });
      // diff-add
      }
      // diff-add
      await admin.getPluginByClassName<AuditLogPlugin>('AuditLogPlugin').logCustomAction({
      // diff-add
        resourceId: 'aparts',
      // diff-add
        recordId: null,
      // diff-add
        actionId: 'myCriticalAction',
      // diff-add
        oldData: null,
      // diff-add
        data: { param },
      // diff-add
        user: adminUser,
      // diff-add
      });

      // ... your critical logic ...

      return res.json({ ok: true, successMessage: 'Action executed' });
    }
  )
);
```

### Step-Up Authentication Grace Period

By default, step-up authentication is required every time the user performs a critical operation.

Most of critical operation should not be often and should be carefully prefiltered. For example small money transfers should be confirmed without 2FA request (you implement it in logics), while big ones e.g. > threshold should require 2FA every time.

If it is still inconvenient for admins who perform multiple critical actions in a short period to confirm 2FA often. To reduce the issue (by lowering security level), you can enable grace period between step-up authentication requests:

```ts title='./adminuser.ts'
    new TwoFactorsAuthPlugin ({
      twoFaSecretFieldName: 'secret2fa',
      ...
      //diff-add
      stepUpMfaGracePeriodSeconds: 300, // 5 minutes grace period
      ...
    }),
```

This configuration still remembers user browser fingerprint and IP address, and if at least one of them changes, it will ask for 2FA again, ignoring grace period. 

Any popups asking for 2FA would be automatically resolved during grace period without user interaction if both browser fingerprint and IP address are the same as during last successful 2FA and time since last 2FA is less than grace period.

> 💡** Note ** We strongly do not recommend using this feature because it increases blast radius for MitB, Cookie parsing/decoding Stealer malwares and Remote Browser Control (device controlling attacks). None of these attacks are fixed compleately by 2FA when you are not using grace period, but using grace period makes these attacks easier to perform.
> Instead we recommend to reducing number of critical operations requiring 2FA by carefully prefiltering them.

> For example when user upgraded to Webauthn (Passkey) and uses Passkey to confirm operation, any of device-controlling attacks has blast radius of single operation only, because Passkey is used per one operation and cannot be reused later without a new user guesture, but when grace period is used, attacker might wait for user to confirm operation once and then perform multiple operations during grace period without 2FA.

> 💡** Interesting fact **: for those of your admins who use TOTP, even without grace period, device controlling attacks have blast radius of multiple operations, because TOTP code can be reused multiple times during its validity period (30 seconds). 
> This plugin, even when Webauthn is activated, still allows users to confirm any action with TOTP (mainly  to prevent "Lost account" scenarios), but at moment of victim device controlling attack, the negative TOTP's impact will happen only in case if admin enters TOTP code, so if admin uses Passkey at exact operation blast radius is limited to single operation only.

## Custom label prefix in authenticator app

By default label prefix in Authenticator app is formed from Adminforth [brandName setting](/docs/tutorial/Customization/branding/) which is best behaviour for most admin apps (always remember to configure brandName correctly e.g. "RoyalFinTech Admin") 
If you want to have custom label prefix for some reason: 

```ts label="./adminuser"
  plugins: [
    new TwoFactorsAuthPlugin ({
      twoFaSecretFieldName: 'secret2fa',
        ...
      customBrandPrefix: "TechStore",
    }),
  ],
```

## TOTP setup / login validity period

When a user logs in with password, the plugin issues a short-lived temporary login session (stored in a cookie) during which the user must either complete the initial 2FA setup (scan the QR code and enter the code) or enter the OTP code. By default this session lives only **1 minute**.

If your users don't have enough time to scan the QR code and enter the code (or you simply want a more relaxed flow), you can increase it with the `totpSetupValidityPeriod` option:

```ts title='./adminuser.ts'
    new TwoFactorsAuthPlugin ({
      twoFaSecretFieldName: 'secret2fa',
      ...
      //diff-add
      totpSetupValidityPeriod: '5m', // e.g. '5m', '10m', '15m'. Default is '1m'
      ...
    }),
```

This value controls both the lifetime of the temporary login JWT and the expiry of the temporary cookie, so they stay in sync.

## Passkeys setup (WebAuthn) alongside TOTP

If you want to use both passkeys and TOTP simultaneously, you can set them up as follows:

First, you need to create a passkeys table in your schema.prisma file:
<Tabs
  defaultValue="sqlite"
  values={[
    {label: 'SQlite', value: 'sqlite'},
    {label: 'Postgres', value: 'postgres'},
    {label: 'MySql', value: 'mysql'},
    {label: 'Clickhouse', value: 'clickhouse'},
  ]}>
  <TabItem value="sqlite">
    ```ts title='./schema.prisma'
      //diff-add
      model passkeys {
        //diff-add
        id                      String @id
        //diff-add
        credential_id           String  
        //diff-add
        user_id                 String
        //diff-add
        meta                    String
        //diff-add
        @@index([user_id])
        //diff-add
        @@index([credential_id])
        //diff-add
      }
    ```
  </TabItem>
  <TabItem value="postgres">
    ```ts title='./schema.prisma'
      //diff-add
      model passkeys {
        //diff-add
        id                      String @id
        //diff-add
        credential_id           String  
        //diff-add
        user_id                 String
        //diff-add
        meta                    Json
        //diff-add
        @@index([user_id])
        //diff-add
        @@index([credential_id])
        //diff-add
      }
    ```
  </TabItem>
  <TabItem value="mysql">
    ```ts title='./schema.prisma'
      //diff-add
      model passkeys {
        //diff-add
        id                      String @id
        //diff-add
        credential_id           String  
        //diff-add
        user_id                 String
        //diff-add
        meta                    Json
        //diff-add
        @@index([user_id])
        //diff-add
        @@index([credential_id])
        //diff-add
      }
    ```
  </TabItem>
  <TabItem value="clickhouse">
    ```ts title='./schema.prisma'
      //diff-add
      model passkeys {
        //diff-add
        id                      String @id
        //diff-add
        credential_id           String  
        //diff-add
        user_id                 String
        //diff-add
        meta                    Json
        //diff-add
        @@index([user_id])
        //diff-add
        @@index([credential_id])
        //diff-add
      }
    ```
  </TabItem>
</Tabs>

>☝️Use Json data type, if it's possible for the meta field
And make migration:

```bash
pnpm makemigration --name add-passkeys ; pnpm migrate:local
```

Next, you need to create a new resource for passkeys:

```ts title='./resources/passkeys.ts'
  import { AdminForthDataTypes, AdminForthResourceInput } from "adminforth";
  import { randomUUID } from "crypto";

  export default {
    dataSource: 'maindb',
    table: 'passkeys',
    resourceId: 'passkeys',
    label: 'Passkeys',
    columns: [
      {
        name: 'id',
        label: 'ID',
        primaryKey: true,
        showIn: { all: false},
        fillOnCreate: () => randomUUID(),
      },
      {
        name: 'credential_id',
        label: 'Credential ID',
      },
      {
        name: 'user_id',
        label: 'User ID',
      },
      {
        name: "meta",
        type: AdminForthDataTypes.JSON,
        label: "Meta",
      }
    ],
    plugins: [],
    options: {
      // The passkey table holds login credentials, not business data: the plugin manages every
      // row through its own endpoints, so nobody should reach it through the resource API.
      allowedActions: { all: false },
    },
  } as AdminForthResourceInput;
```

Add the new resource to index.ts:

```ts title='./index.ts'
    ...
  //diff-add
  import passkeysResource from './resources/passkeys.js';
    ...

  resources: [
    ...
    //diff-add
    passkeysResource,
    ...
  ],
```
To use passkey you need to use Key-Value adapter. For example:
```bash
pnpm add @adminforth/key-value-adapter-ram
```

Now, update the settings of the Two-Factor Authentication plugin:

```ts tittle='./resources/adminuser.ts'

  //diff-add
  import RamKeyValueAdapter from '@adminforth/key-value-adapter-ram'

  ...

  plugins: [
    new TwoFactorsAuthPlugin ({ 
      twoFaSecretFieldName: 'secret2fa', 
      timeStepWindow: 1,       
      //diff-add
      passkeys: {
        //diff-add
        keyValueAdapter: new RamKeyValueAdapter(),
        //diff-add
        credentialResourceID: "passkeys",
        //diff-add
        credentialIdFieldName: "credential_id",
        //diff-add
        credentialMetaFieldName: "meta",
        //diff-add
        credentialUserIdFieldName: "user_id",
        //diff-add
        settings: {
          // diff-add
          expectedOrigin: "http://localhost:3500",   // important, set it to your backoffice origin (starts from scheme, no slash at the end)
          //diff-add
          // relying party config
          //diff-add
          rp: {
              //diff-add
              name: "New Reality",
              
              //diff-add
              // optionaly you can set expected id explicitly if you need to:
              //diff-add
              // id: "localhost",
              //diff-add
            },
            //diff-add
            user: {
              //diff-add
                nameField: "email",
                //diff-add
                displayNameField: "email",
                //diff-add
            },
            //diff-add
            authenticatorSelection: {
              // diff-add
              // impacts a way how passkey will be created
              // diff-add
              // - platform - using browser internal authenticator (e.g. Google Chrome passkey / Google Password Manager )
              // diff-add
              // - cross-platform - using external authenticator (e.g. Yubikey, Google Titan etc)
              // diff-add
              // - both - plging will show both options to the user
              // diff-add
              // Can be "platform", "cross-platform" or "both"
              // diff-add
                authenticatorAttachment: "both",
                //diff-add
                requireResidentKey: true,
                //diff-add
                userVerification: "required",
                //diff-add
            },
            //diff-add
        },
        //diff-add
      } 
    }),
  ],
```

> ☝️ most likely you should set `passkeys.settings.expectedOrigin` from your process.env depending on your env (e.g. http://localhost:3500 for local dev, https://admin.yourproduct.com for production etc)

> 💡**Note** By default `passkeys.settings.rp.id` is generated from the expectedOrigin so you don't need to set it
> unless you know what you are doing. Manual setting might be needed for sub-domains isolation.
> By default, if you set expected origin to https://localhost:3500 it will use "localhost" as rpid
> If you set origin to https://myadmin.myproduct.com -> it will use  "myadmin.myproduct.com"  as rpid 

The setup is complete. To create a passkey:

> 1) Go to the user menu
> 2) Click settings
> 3) Select "passkeys"

 ![alt text](Passkeys1.png)

> 4) Add passkey

 ![alt text](Passkeys2.png)

After adding passkey you can use passkey, instead of TOTP:

 ![alt text](Passkeys3.png)

> 💡 **Note**: Adding a passkey does not remove the option to use TOTP. If you lose access to your passkey, you can log in using TOTP and reset your passkey.

---

## Foreign Inline List

Foreign inline list plugin allows to display a list (table) of items from a foreign table in the show view.

## Usage

Import plugin:

```bash
pnpm add @adminforth/foreign-inline-list --save
```

```ts title="./resources/adminuser.ts"
import ForeignInlineListPlugin from '@adminforth/foreign-inline-list';
import { AdminForthResource, AdminForthResourceColumn } from 'adminforth';
```

In [Getting Started](<../001-gettingStarted.md>) we created a `'aparts'` resource which has a field `'realtor_id'`.
This field refers to record from `'adminuser'` resource. To remind you, we configured this relation using `foreignResource` setting in the column configuration:

```typescript title="./resources/apartments.ts"
// 
export default {
  resourceId: 'aparts',
  ...
  columns: [
    ...
    {
      name: 'realtor_id',
      foreignResource: {
        resourceId: 'adminuser',  // this means that aparts.realtor_id refers to primary key of 'adminuser' resource
                              // this is Many-To-One relatin: many aparts can refer to one user
      }
    }
  ],
}
```

This means that we can display a list of apartments in the user's show view.

Add to your `'adminuser'` resource configuration the plugin instance:

```ts title="./resources/adminuser.ts"
{ 
    ...
    resourceId: 'adminuser',
    ...
//diff-add
    plugins: [
//diff-add
      new ForeignInlineListPlugin({
//diff-add
        foreignResourceId: 'aparts',
//diff-add
        modifyTableResourceConfig: (resourceConfig: AdminForthResource) => {
//diff-add
          // hide column 'square_meter' from both 'list' and 'filter'
//diff-add
          const column = resourceConfig.columns.find((c: AdminForthResourceColumn) => c.name === 'square_meter')!.showIn = { all: false };
//diff-add
          resourceConfig.options!.listPageSize = 1;
//diff-add
          // feel free to console.log and edit resourceConfig as you need
//diff-add
        },
//diff-add
      }),
//diff-add
    ],
}
```

You can use the `modifyTableResourceConfig` callback to modify which columns to show in the list and filter of the foreign table.

![alt text](ForeignInlineList.png)

> 👆 To make plugin work, the specified resource (defined with `foreignResourceId`) should have one (and only one) column that refers to the current resource on which you add a plugin.
> In our case we add plugin to `adminuser` resource, so the `aparts` resource should have one column with `foreignResource.resourceId` equal to `adminuser` resourceId.

## Default filters

If you need to add default filters for the foreign resource based on your current record (for example show apartment only from Italy, when user have country Italy), you can use defaultFilters callback:
>👆 This example won't work until you'll add counrty field in your adminuser resource and it's only for demonstrating concept of callback

```ts title="./resources/adminuser.ts"

  ...

  new ForeignInlineListPlugin({

    ...
      //diff-add
      defaultFilters: (record: any) => {
        //diff-add
        return [
          //diff-add
          {
            //diff-add
            field: "country",
            //diff-add
            operator: AdminForthFilterOperators.EQ,
            //diff-add
            value: record.country,
            //diff-add
          }
          //diff-add
        ]
        //diff-add
      }

    ...

  })

  ...

```

>👆It also makes sense to modify the table resource and hide the country field from filters, because this value is hardcoded and equals the country from the record:  

```ts title="./resources/adminuser.ts"

  ...

  new ForeignInlineListPlugin({

    ...

    //diff-add
    modifyTableResourceConfig: (resourceConfig: AdminForthResource) => {
      //diff-add
      const column = resourceConfig.columns.find((c: AdminForthResourceColumn) => c.name === 'country')!.showIn = {
        //diff-add
        list: true,
        //diff-add
        show: true,
        //diff-add
        edit: true,
        //diff-add
        create: true,
        //diff-add
        filter: false
        //diff-add
      };
      //diff-add
    },

    defaultFilters: (record: any) => {
      return [
        {
          field: "country",
          operator: AdminForthFilterOperators.EQ,
          value: record.country,
        }
      ]
    }

    ...

  })

  ...
  
```

## Show table from another resource without any filters applied

There might be cases when you want to remove the default filter applied by the plugin and then use the `defaultFilters` callback to apply your own custom filters.

```ts title="./resources/adminuser.ts"

plugins: [
//diff-add
  new ForeignInlineListPlugin({
//diff-add
    foreignResourceId: 'aparts',
//diff-add
    disableForeignListResourceRefColumn: true
//diff-add
  }),
//diff-add
    ],

```

This setup will show, in the show view for each record, the `aparts` resource without any filters. And you don’t have to modify the `aparts` resource.

## Cascade delete for foreign resources

There might be cases when you want to control what happens with child records when a parent record is deleted.
You can configure this behavior in the `foreignResource` section using the `onDelete` option.

```ts title="./resources/apartments.ts"

export default {
  resourceId: 'aparts',
  ...
  columns: [
    ...
    {
      name: 'realtor_id',
      foreignResource: {
        resourceId: 'adminuser', 
        //diff-add
        onDelete: 'cascade' // cascade or setNull
      }
    }
  ],
}

```

#### The onDelete option supports two modes:

- `cascade`: When a parent record is deleted, all related child records will be deleted automatically.
- `setNull`: When a parent record is deleted, child records will remain, but their foreign key will be set to null.

---

## Audit Log

AuditLog plugin allows to log all changes in the resources done from the admin panel. 
It will allow you to figure out who and when made changes in the data. 
Requires separate table in the database to store logs.

## Installation

```bash
pnpm add @adminforth/audit-log --save
```

Create `auditLogs.ts` in `resources` folder:

```ts title="./resources/auditLogs.ts"
import AuditLogPlugin from '@adminforth/audit-log';
import { AdminForthDataTypes } from 'adminforth'
```

[Getting Started](<../001-gettingStarted.md>) will be used as base for this example.

## Creating table for storing activity data
For the first, to track records changes, we need to set up the database and table with certain fields inside where tracked data will be stored.

First of all you should create this table in your own database `./schema.prisma`:

```ts title='./schema.prisma'
model audit_logs {
  id                String      @id
  created_at        DateTime  /// timestamp of applied change
  resource_id       String    /// identifier of resource where change were applied
  user_id           String    /// identifier of user who made the changes
  action            String    /// type of change (create, edit, delete)
  diff              String?   /// delta betwen before/after versions
  record_id         String?   /// identifier of record that been changed
}
```

And `prisma migrate`:

```bash
pnpm makemigration --name add-audit-logs ; pnpm migrate:local
```

Also to make this code start 

## Setting up the resource and dataSource for plugin
Logger sets up for all the resources by default. But you can exclude unwanted resources with option "excludeResourceIds". In this example, we'll exclude resource "adminuser" from logging.

Also, it excludes itself to avoid infinte logging loop.

Add this code in `auditLogs.ts`:

```ts title='./resources/auditLogs.ts'

import AuditLogPlugin from "@adminforth/audit-log/index.js";
import { AdminForthDataTypes } from "adminforth";
import { randomUUID } from "crypto";

export default {
  dataSource: 'maindb', 
  table: 'audit_logs',
  columns: [
    { name: 'id', primaryKey: true, required: false, fillOnCreate: ({initialRecord}: any) => randomUUID(),
      showIn: {
        list: false,
        edit: false,
        create: false,
        filter: false,
      } },
    { name: 'created_at', required: false },
    { name: 'resource_id', required: false },
    { name: 'user_id', required: false, 
        foreignResource: {
        resourceId: 'adminuser',
      } },
    { name: 'action', required: false },
    { name: 'diff', required: false, type: AdminForthDataTypes.JSON, showIn: {
        list: false,
        edit: false,
        create: false,
        filter: false,
      } },
    { name: 'record_id', required: false },
  ],
  options: {
    allowedActions: {
      edit: false,
      delete: false,
      create: false
    }
  },
  plugins: [
    new AuditLogPlugin({
      // if you want to exclude some resources from logging
      //excludeResourceIds: ['adminuser'],
      resourceColumns: {
        resourceIdColumnName: 'resource_id',
        resourceActionColumnName: 'action',
        resourceDataColumnName: 'diff',
        resourceUserIdColumnName: 'user_id',
        resourceRecordIdColumnName: 'record_id',
        resourceCreatedColumnName: 'created_at'
      }
    }),
  ],
}
```

Then you need to import `./resources/auditLogs`:

```ts title="./index.ts"
//diff-add
import auditLogsResource from "./resources/auditLogs"

... new AdminForth({
  dataSources: [...],
    ...
  resources: [
    apartmentsResource,
    usersResource,
//diff-add
    auditLogsResource
  ],
    ...
]
```

Also, we need to add it to menu:
```ts
menu: [
  ...
//diff-add
  {
//diff-add
      label: 'Audit Logs',
//diff-add
      icon: 'flowbite:search-outline',
//diff-add
      resourceId: 'audit_logs',
//diff-add
  }
]
```

That's it! Now you can see the logs in the table 

![alt text](AuditLog.png)

<!-- See [API Reference](/docs/api/plugins/audit-log/types/type-aliases/PluginOptions.md) for more all options. -->

## Logging custom actions

Audit log is able to catch only standard actions like `create`, `update`, `delete` or custom bulk actions.

If you have a custom, self coded actions in your API, you can log them by calling `logCustomAction` method of `AuditLogPlugin` instance:

```ts title="./resources/index.ts"
import type { IAdminUserExpressRequest, ITranslateExpressRequest } from 'adminforth';
import express from 'express';

....

app.get(`${ADMIN_BASE_URL}/api/dashboard/`,
  admin.express.authorize(
    async (req: IAdminUserExpressRequest, res: express.Response) => {

      admin.getPluginByClassName<AuditLogPlugin>('AuditLogPlugin').logCustomAction({
        resourceId: 'aparts',
        recordId: null, // recordId can be null if not applicable
        actionId: 'visitedDashboard', // any random string you want to useto identify this action 
        oldData: null, // old data, can be null if not applicable
        data: { dashboard: 'main' }, // new data or any data you want to log
        user: req.adminUser,
        headers: req.headers //required if you want log client ip
      })

      ....

```

## Logging client ip address

Audit log can also log the client's IP address if needed.

First, you need to migrate the `audit_logs` table in `./schema.prisma`:

```ts title='./schema.prisma'
model audit_logs {
  id                String      @id
  created_at        DateTime  /// timestamp of applied change
  resource_id       String    /// identifier of resource where change were applied
  user_id           String    /// identifier of user who made the changes
  action            String    /// type of change (create, edit, delete)
  diff              String?   /// delta betwen before/after versions
  record_id         String?   /// identifier of record that been changed
//diff-add
  ip_address        String?   /// client ip address
}
```

And `prisma migrate`:

```bash
pnpm makemigration --name add-ip-address-to-audit-logs ; pnpm migrate:local
```

Also, update the resource configuration in `./resources/auditLogs.ts`:

```ts title='./resources/auditLogs.ts'
  export default {
    dataSource: 'maindb', 
    table: 'audit_logs',
    columns: [
      ...
      { name: 'action', required: false },
      { name: 'diff', required: false, type: AdminForthDataTypes.JSON, showIn: {
          list: false,
          edit: false,
          create: false,
          filter: false,
        } },
      { name: 'record_id', required: false },
      //diff-add
      { name: 'ip_address', required: false },
    ],
    ...
    plugins: [
      new AuditLogPlugin({
        resourceColumns: {
          resourceIdColumnName: 'resource_id',
          resourceActionColumnName: 'action',
          resourceDataColumnName: 'diff',
          resourceUserIdColumnName: 'user_id',
          resourceRecordIdColumnName: 'record_id',
          resourceCreatedColumnName: 'created_at'
//diff-add
          resourceIpColumnName: "ip_address",
        }
      }),
    ],
  }
```
## Logging client ip country

Audit log can also log the client's country if needed.

First, you need to migrate the `audit_logs` table in `./schema.prisma`:

```ts title='./schema.prisma'
model audit_logs {
  id                String      @id
  created_at        DateTime  /// timestamp of applied change
  resource_id       String    /// identifier of resource where change were applied
  user_id           String    /// identifier of user who made the changes
  action            String    /// type of change (create, edit, delete)
  diff              String?   /// delta betwen before/after versions
  record_id         String?   /// identifier of record that been changed
  ip_address        String?   /// client ip address
//diff-add
  country           String?   /// client country

//diff-add
  @@index([ip_address])       /// index for fast lookups by IP
}
```

And `prisma migrate`:

```bash
pnpm makemigration --name add-ip-address-to-audit-logs ; pnpm migrate:local
```

Update the resource configuration in `./resources/auditLogs.ts`:

```ts title='./resources/auditLogs.ts'
  export default {
    dataSource: 'maindb', 
    table: 'audit_logs',
    columns: [
      ...
      { name: 'action', required: false },
      { name: 'diff', required: false, type: AdminForthDataTypes.JSON, showIn: {
          list: false,
          edit: false,
          create: false,
          filter: false,
        } },
      { name: 'record_id', required: false },
      { name: 'ip_address', required: false },
       //diff-add
      { 
        //diff-add
        name: "country",
        //diff-add
        required: false,
        //diff-add
        components: {
        //diff-add
          list: '@/renderers/CountryFlag.vue'
        //diff-add
          show: '@/renderers/CountryFlag.vue'
        //diff-add
        }, 
         //diff-add
      },
    ],
    ...
    plugins: [
      new AuditLogPlugin({
        resourceColumns: {
          resourceIdColumnName: 'resource_id',
          resourceActionColumnName: 'action',
          resourceDataColumnName: 'diff',
          resourceUserIdColumnName: 'user_id',
          resourceRecordIdColumnName: 'record_id',
          resourceCreatedColumnName: 'created_at'
          resourceIpColumnName: "ip_address",
//diff-add
          resourceCountryColumnName: "country",
        }
      }),
    ],
  }
```

### Providing Country Headers

If your deployed app has header with user country in ISO 3166-1 alpha-2 format, you can specify this header, so country will be taken from it: 

```ts
plugins: [
      new AuditLogPlugin({
        //diff-add
        isoCountryCodeRequestHeader: 'CF-IPCountry',
        resourceColumns: {
          resourceIdColumnName: 'resource_id',
          resourceActionColumnName: 'action',
          resourceDataColumnName: 'diff',
          resourceUserIdColumnName: 'user_id',
          resourceRecordIdColumnName: 'record_id',
          resourceCreatedColumnName: 'created_at'
          resourceIpColumnName: "ip_address",
          resourceCountryColumnName: "country",
        }
      }),
    ],
```

---

## Upload


This plugin allows you to upload files to Amazon S3 bucket.

## Installation

```
pnpm add @adminforth/upload --save
```

Plugin needs some storage adapter to store files and serve them for preview.

### Using Amazon S3 storage adapter

Amazon S3 is probably the most popular storage service.

```
pnpm add @adminforth/storage-adapter-amazon-s3 --save
```

1. Go to https://aws.amazon.com and login.
2. Go to Services -> S3 and create a bucket. Put in bucket name e.g. `my-reality-bucket`. 
Leave all settings unchanged (ACL Disabled, Block all public access - checked)
3. Go to bucket settings, Permissions, scroll down to Cross-origin resource sharing (CORS) and put in the following configuration:

```json
[
    {
        "AllowedHeaders": [
            "*"
        ],
        "AllowedMethods": [
            "HEAD",
            "PUT",
            "GET"
        ],
        "AllowedOrigins": [
            "http://localhost:3500"
        ],
        "ExposeHeaders": []
    }
]
```

> ☝️ In AllowedOrigins add all your domains. For example if you will serve admin on `https://example.com/admin` you should add 
> `"https://example.com"` to AllowedOrigins:
>
> ```json
> [
>      "https://example.com",
>      "http://localhost:3500"
> ]
> ```
> Every character matters, so don't forget to add `http://` or `https://`!

4. Go to Services -> IAM and create a new user. Put in user name e.g. `my-reality-user`.
5. Attach existing policies directly -> `AmazonS3FullAccess`. Go to your user -> `Add permissions` -> `Attach policies directly` -> `AmazonS3FullAccess`
6. Go to Security credentials and create a new access key. Save `Access key ID` and `Secret access key`.
7. Add credentials in your `.env` file:

```ts title=".env"
...
NODE_ENV=development 

//diff-add
AWS_ACCESS_KEY_ID=your_access_key_id
//diff-add
AWS_SECRET_ACCESS_KEY=your_secret_access_key
```

8. Add credentials in your `.env.local` file:

```ts title=".env.local"
...
//diff-add
AWS_REGION=your_bucket_region
//diff-add
AWS_BUCKET_NAME=your_bucket_name
```

Now add a column for storing the path to the file in the database, add this statement to the `./schema.prisma`:

```ts title="./schema.prisma"
model apartments {
  id                String     @id
  created_at        DateTime? 
  title             String 
  square_meter      Float?
  price             Decimal
  number_of_rooms   Int?
  description       String?
  country           String?
  listed            Boolean
  realtor_id        String?
//diff-add
  apartment_image   String?
}
```

Migrate prisma schema:

```bash
pnpm makemigration --name add-apartment-image ; pnpm migrate:local
```

Add column to `aparts` resource configuration:

```ts title="./resources/apartments.ts"
//diff-add
import UploadPlugin from '@adminforth/upload';
//diff-add
import AdminForthAdapterS3Storage from '@adminforth/storage-adapter-amazon-s3'
//diff-add
import { randomUUID } from 'crypto';

export const admin = new AdminForth({
  ...
  resourceId: 'aparts',
  columns: [
    ...
//diff-add
    {
//diff-add
      name: 'apartment_image',
//diff-add
      showIn: { all: true, filter: false }, // for create and edit pages plugin put's it's own file dropzone widget, for show and list pages it put's preview
//diff-add
    }
    ...
  ],
  plugins: [
    ...
  //diff-add
    new UploadPlugin({
    //diff-add
      storageAdapter: new AdminForthAdapterS3Storage({
      //diff-add
        bucket: process.env.AWS_BUCKET_NAME,
      //diff-add
        region: process.env.AWS_REGION,
      //diff-add
        accessKeyId: process.env.AWS_ACCESS_KEY_ID,
      //diff-add
        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
    //diff-add
      }),
    //diff-add
      pathColumnName: 'apartment_image',
    //diff-add
      allowedFileExtensions: ['jpg', 'jpeg', 'png', 'gif', 'webm', 'webp'],
    //diff-add
      maxFileSize: 1024 * 1024 * 20, // 20 MB
    //diff-add
      filePath: ({originalFilename, originalExtension, contentType}) => 
    //diff-add
            `aparts/${new Date().getFullYear()}/${randomUUID()}-${originalFilename}.${originalExtension}`,
  //diff-add
    })
//diff-add
  ]
  
  ...

});
```

Here you can see how the plugin works:

![alt text](upload_gif.gif)

This setup will upload files to S3 bucket with private ACL and save path to file (relative to bucket root) in `apartment_image` column.

Once you will go to show or list view of `aparts` resource you will see preview of uploaded file by using presigned temporary URLs
which are generated by plugin:

![alt text](Upload.png)

> ☝ When upload feature is used on record which already exists in database (from 'edit' page), filePath callback will
> receive additional parameter `record` with all values of record. Generally we don't recommend denormalizing any state
> of record into s3 path (and instead store links to unique path on s3 in the record field, like in example above).
> But if you are 100% sure this kind of sate will be static, you might link to it:
>
> ```ts
> filePath: ({originalExtension, record}) => `game_images/${record.static_game_code}.${originalExtension}`
> ```
>
> ! Please note that when upload is done from create view, record will be `undefined`.

If you want to draw such images in main non-admin app e.g. Nuxt, you should generate presigned URLs by yourself. Here is NodeJS an example of how to do it:

```ts
import AWS from 'aws-sdk';

const s3 = new AWS.S3({
  accessKeyId: process.env.AWS_ACCESS_KEY_ID,
  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
  region: 'us-east-1',
});

export async function getPresignedUrl(s3Path: string): Promise<string> {
  return s3.getSignedUrlPromise('getObject', {
    Bucket: 'my-bucket',
    Key: s3Path,
    Expires: 60 * 60, // 1 hour
  });
}
```

Alternatively, if you don't want to generate presigned URLs, you might want to make all objects public. Then you will be able  concatenate backet base domain and path stored in db, and use it as source of image. Let's consider how to do it.

#### S3 upload with public access

1. First of all go to your bucket settings, Permissions, scroll down to Block public access (bucket settings for this bucket) and uncheck all checkboxes.
2. Go to bucket settings, Permissions, Object ownership and select "ACLs Enabled" and "Bucket owner preferred" radio buttons.

Then you can change ACL in plugin configuration:

```ts title="./index.ts"

  new UploadPlugin({
      storageAdapter: new AdminForthAdapterS3Storage({
        bucket: process.env.AWS_BUCKET_NAME,
        region: process.env.AWS_REGION,
        accessKeyId: process.env.AWS_ACCESS_KEY_ID,
        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
//diff-add
        s3ACL: 'public-read',
      }),
      pathColumnName: 'apartment_image',
      allowedFileExtensions: ['jpg', 'jpeg', 'png', 'gif', 'webm', 'webp'],
      maxFileSize: 1024 * 1024 * 20, // 20 MB
      filePath: ({originalFilename, originalExtension, contentType}) => 
            `aparts/${new Date().getFullYear()}/${randomUUID()}-${originalFilename}.${originalExtension}`,
    })
      
```

Now every uploaded file will be public so in your custom app you can easily concatenate bucket URL with `filePath` to get public URL:

```ts
export async function getPublicUrl(filePath: string): string {
  return `https://my-bucket.s3.${region}.amazonaws.com/${filePath}`
}
```

For preview in AdminForth plugin will still use presigned URLs, but you can change it by providing `previewUrl` function in plugin configuration:

```ts title="./index.ts"

  preview: {
//diff-add
      previewUrl: ({filePath}) => `https://my-bucket.s3.us-east-1.amazonaws.com/${filePath}`, 
  }
```
> Make sure that you change "my-bucket" and "us-east-1" to your own settings.

Also you might want to put CDN in front of your bucket, for example [CloudFlare](https://developers.cloudflare.com/support/third-party-software/others/configuring-an-amazon-web-services-static-site-to-use-cloudflare/). In this case
we recommend route all AdminForth previews over CDN as well for faster worm up and better performance.
If for example your domain is `my-domain.com` and you bucket has name `static.my-domain.com` you should change preview URL like this:

```ts title="./index.ts"

  preview: {
//diff-remove
      previewUrl: ({filePath}) => `https://my-bucket.s3.us-east-1.amazonaws.com/${filePath}`,

//diff-add
      previewUrl: ({filePath}) => `https://static.my-domain.com/${filePath}`,
  }
```

Also you will have to enable static website hosting in your bucket settings and set index.html and error.html to empty strings.

### Using local storage adapter

The local storage adapter saves files directly on the server’s filesystem and serves them through Express routes. It supports both public and private modes (with presigned URLs).

```
pnpm add @adminforth/storage-adapter-local --save
```

```ts title="./index.ts"
import LocalStorageAdapter from '@adminforth/storage-adapter-local';

new UploadPlugin({
  storageAdapter: new LocalStorageAdapter({
    fileSystemFolder: "./db/uploads",
    adminServeBaseUrl: "static/source",
    mode: "public", // or "private"
    signingSecret: process.env.ADMINFORTH_SECRET,
  }),
  pathColumnName: 'apartment_image',
  allowedFileExtensions: ['jpg', 'jpeg', 'png', 'gif', 'webm', 'webp'],
  maxFileSize: 1024 * 1024 * 20, // 20 MB
  filePath: ({originalFilename, originalExtension, contentType}) => 
        `aparts/${new Date().getFullYear()}/${randomUUID()}-${originalFilename}.${originalExtension}`,
})
```
> adminServeBaseUrl defines the public path prefix. If your AdminForth base URL is /admin, files will be accessible under /admin/static/source/&lt;key&gt;.

## Content types and who can upload

The content type a file is stored with is derived from its extension on the backend, never taken from the browser. The storage replays that content type when the file is served back, so a client which asks for `text/html` would be able to store a page that executes scripts on your admin origin with the session of whoever opens it.

The plugin knows the common image, video, audio, document, archive and font extensions. If an extension can't be resolved to a content type, no upload URL is issued, and `allowedFileExtensions` is validated at startup, so a typo or an unknown extension fails fast:

```
Upload plugin can't resolve content type for extension "jpgg". Provide contentTypeByExtension in plugin options
```

Use `contentTypeByExtension` to add extensions the plugin doesn't know, or to override the built-in mapping:

```ts title="./index.ts"
new UploadPlugin({
  ...
  allowedFileExtensions: ['jpg', 'png', 'dwg'],
  //diff-add
  contentTypeByExtension: {
  //diff-add
    dwg: 'application/acad',
  //diff-add
  },
})
```

:::warning
Mapping an extension to a content type which browsers execute (`text/html`, `image/svg+xml`, `application/xhtml+xml`, ...) allows anyone who can upload files to run scripts on your admin panel origin with the session of the user who opens the file. Only do it if your storage serves files from a separate origin or with `Content-Disposition: attachment`.
:::

Requesting an upload URL requires permission to write the record the file belongs to: `edit` on the target record when editing an existing one, `create` otherwise. Users who can only view the resource get `403` even if they call the API directly, and `maxFileSize` is enforced on the backend as well, not only in the browser.

## Image generation

Upload plugin supports AI generation for images. Yo use it you need to install image generation adapter.
For example for OpenAI models like `gpt-image-1.5` (or old `DALL-E` models):

```bash
pnpm add @adminforth/image-generation-adapter-openai
```

```ts title="./index.ts"
import ImageGenerationAdapterOpenAI from '@adminforth/image-generation-adapter-openai';

new UploadPlugin({
  ...
//diff-add
  generation: {
//diff-add
    countToGenerate: 2,  // how much images generate in one shot
//diff-add
    adapter: new ImageGenerationAdapterOpenAI({
  //diff-add
      openAiApiKey: process.env.OPENAI_API_KEY as string,
  //diff-add
      model: 'gpt-image-1.5', 
  //diff-add
    }),
//diff-add
    generationPrompt: "Generate image for apartment with title {{title}} and description {{description}}",
//diff-add
    outputSize: '1536x1024' // size of generated image

},
```

Here is how it works:

![alt text](demoImgGen-1.gif)

You can also pass additional parameters to [OpenAI API call](https://platform.openai.com/docs/api-reference/images/createEdit) by using `extraParams` property:

```ts title="./apartments.ts"
new ImageGenerationAdapterOpenAI({
  //diff-add
    openAiApiKey: process.env.OPENAI_API_KEY as string,
  //diff-add
    model: 'gpt-image-1.5', 
  //diff-add
    extraParams: {
  //diff-add
      moderation: 'low',
  //diff-add
      quality: 'high',  
  //diff-add
    },
  //diff-add
    outputSize: '1536x1024' // size of generated image
}),
```

## Images editing or post-processing

You can not only generate images from text, but also edit, post-process or improve existing images. E.g. remove texts, add objects, change colors, etc.

Create a new column `apartment_source` in `apartments` table, and put another instance of `UploadPlugin` in the same resource configuration.

Now tweak the current UploadPlugin configuration in a next way:

```ts title="./apartments.ts"
generation: {
  adapter: new ImageGenerationAdapterOpenAI({
    openAiApiKey: process.env.OPENAI_API_KEY as string,
  }),

  attachFiles: ({ record, adminUser }: { record: any; adminUser: AdminUser }) => {
    // attach apartment source image to generation, image should be public
    return [`https://tmpbucket-adminforth.s3.eu-central-1.amazonaws.com/${record.apartment_source}`];
  },
  generationPrompt: "Remove text from the image",
  countToGenerate: 3,
  outputSize: '1024x1024',
}
```

`attachFiles` function can return an array of URLs to images which will be used as input for image generation. 
URLs can be absolute HTTP URLs (should be public in this case) or data-URLs (`data:image/png;base64,<base64 content of image>`).

For example you can use `getKeyAsDataURL` function from any storage adapter to get image as data-URL:

```ts title="./apartments.ts"

import { StorageAdapter } from 'adminforth'

let sourceAdapter: StorageAdapter = null;

columns: [
  ...
  {
    name: 'source_image',
  },
  {
    name: 'destination_image',
  }
],
plugins: [ 
  ...
  new UploadPlugin({
    pathColumnName: 'apartment_source',
    storageAdapter: (sourcesAdapter = new LocalStorageAdapter({
      fileSystemFolder: "./db/uploads",
      mode: "public",
      adminServeBaseUrl: "static/source",
      signingSecret: process.env.ADMINFORTH_SECRET, // secret used to generate presigned URLs
    }), sourcesAdapter),
  }),
  new UploadPlugin({
    pathColumnName: 'apartment_image',
    storageAdapter: new LocalStorageAdapter({
      fileSystemFolder: "./db/uploads",
      mode: "public",
      adminServeBaseUrl: "static/source",
      signingSecret: process.env.ADMINFORTH_SECRET, // secret used to generate presigned URLs
    }),
    generation: {
      attachFiles: ({ record }) => {
        // get picture stored in apartment_source column as data-URL
        return [sourceAdapter.getKeyAsDataURL(record.apartment_source)];
      },
      generationPrompt: "Remove text from the image",
      countToGenerate: 3,
      outputSize: '1024x1024',
    }
  })
]
```

With thus setup you can upload image to `apartment_source` column, save entity and then generate new image by clicking on `Generate` button in the `apartment_image` to remove any text from the image.

### Rate limits

You can set rate limits for image generation per IP address:

```ts title="./index.ts"
new UploadPlugin({
  ...
  generation: {
    ...
  //diff-add
    rateLimit: {
      limit: '5/12h', // up to 5 times per 12 hour 
      errorMessage: 'You exhausted your image generation limit 5 times per 12 hours, please try again later',
    }
      ...
});
```

### Preview Image Size Configuration

You can set the maximum width for the preview image in the `./resources/apartments.ts` file by adding the `maxWidth` property to the `preview` configuration:

```ts title="./resources/apartments.ts"
  ...
  new UploadPlugin({
    storageAdapter: new AdminForthAdapterS3Storage({
        bucket: process.env.AWS_BUCKET_NAME,
        region: process.env.AWS_REGION,
        accessKeyId: process.env.AWS_ACCESS_KEY_ID,
        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
        s3ACL: "public-read",
    }),
    pathColumnName: 'apartment_image',
    allowedFileExtensions: ['jpg', 'jpeg', 'png', 'gif', 'webm', 'webp'],
    maxFileSize: 5 * 1024 * 1024, // 5MB
    filePath: ({originalFilename, originalExtension, contentType}) => 
      `aparts/${new Date().getFullYear()}/${randomUUID()}-${originalFilename}.${originalExtension}`,
    preview: {
      // Global width settings (applies to all views if specific view settings not provided)
      maxWidth: '200px',  // Maximum width for preview images
      minWidth: '200px',  // Minimum width for preview images

      // List view specific settings
      maxListWidth: '300px',  // Maximum width in list view
      minListWidth: '100px',  // Minimum width in list view

      // Show/detail view specific settings
      maxShowWidth: '200px',  // Maximum width in show view
      minShowWidth: '200px',  // Minimum width in show view
    
      ...
    }

  })
  
  ...

});
```

## Using plugin for uploading avatar

Let's say, that you want to use upload plugin for uploading avatar for each user.
To do this add avatar column to the user resource:

```ts title="./schema.prisma"
  model adminuser {
    id            String     @id
    email         String     @unique
    password_hash String
    role          String
    created_at    DateTime
    //diff-add
    avatar        String?
  }
```

Then make migration:

```bash
  pnpm makemigration --name add-user-avatar-field ; pnpm migrate:local
```

Add this column to the users resource:

```ts title="./resources/adminuser.ts"

...

columns: [
  
  ...

  //diff-add
  {
    //diff-add
    name: "avatar",
    //diff-add
    type: AdminForthDataTypes.STRING,
    //diff-add
    showIn: ["show", "edit", "create" ],
    //diff-add
  },

  ...

]

...

plugins: [

  ...

  //diff-add
  new UploadPlugin({
      //diff-add
    pathColumnName: "avatar",
      //diff-add
    storageAdapter: new AdminForthAdapterS3Storage({
      //diff-add
      bucket: process.env.AWS_BUCKET_NAME,
      //diff-add
      region: process.env.AWS_REGION,
      //diff-add
      accessKeyId: process.env.AWS_ACCESS_KEY_ID as string,
      //diff-add
      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY as string,
      //diff-add
    }),
    //diff-add
    allowedFileExtensions: [
      //diff-add
      "jpg",
      //diff-add
      "jpeg",
      //diff-add
      "png",
      //diff-add
      "gif",
      //diff-add
      "webm",
      //diff-add
      "exe",
      //diff-add
      "webp",
      //diff-add
    ],
    //diff-add
    maxFileSize: 1024 * 1024 * 20, // 20MB
    //diff-add
    filePath: ({ originalFilename, originalExtension, contentType, record }) => {
      //diff-add
      return `aparts/${new Date().getFullYear()}/${originalFilename}.${originalExtension}`
      //diff-add
    },
    //diff-add
    preview: {
      //diff-add
      maxWidth: "200px",
      //diff-add
    },
    //diff-add
  }),

  ...

]

```

And finally add this callback:

```ts title="./index.ts"

  auth: {

    ...
    //diff-add
    avatarUrl: async (adminUser)=>{
      //diff-add
      const plugin = admin.getPluginsByClassName('UploadPlugin').find(p => p.pluginOptions.pathColumnName === 'avatar') as any; 
      //diff-add
      if (!plugin) {
        //diff-add
        throw new Error('Upload plugin for avatar not found');
        //diff-add
      }
      //diff-add
      if (adminUser.dbUser.avatar === null || adminUser.dbUser.avatar === undefined || adminUser.dbUser.avatar === '') {
        //diff-add
        return undefined;
        //diff-add
      }
      //diff-add
      const imageUrl = await plugin.getFileDownloadUrl(adminUser.dbUser.avatar || '', 3600);
      //diff-add
      return imageUrl;
      //diff-add
    },

    ...

  }

```

And now you can easily update avatar for each user

# API

If you wish to reuse Upload plugin for advanced tasks like upload custom files from frontend/backend
 (including presigned frontend upload), see [05-1-upload-api.md](05-1-upload-api.md).

---

## Upload API


The Upload plugin exposes an API for both backend-only uploads and direct browser uploads using presigned URLs. You can:

- Upload from the backend (Node.js `Buffer`) and either create a new record or update an existing one.
- Generate a presigned upload URL on the backend, send it to the frontend, and upload directly from the browser to your storage provider using an HTTP `PUT` request (raw file as body, plus any `uploadExtraParams` as headers).
  - After the file is uploaded, it is considered **temporary** and can be auto-deleted until you commit it.
  - You can commit by calling `commitUrlToNewRecord` or `commitUrlToUpdateExistingRecord` from your custom API.
  - Or (only for custom create/edit components on the same resource) you can commit by writing `filePath` into the `pathColumnName` field using `update:recordFieldValue`.

> Note: for presigned browser uploads the upload is performed via an HTTP `PUT` request with the raw file as the request body.
> `uploadExtraParams` (if returned) must be sent as **HTTP headers** during that upload.

## Uploading from backend (Buffer API)

This API is useful when files are produced entirely on the backend (for example, reports generated by a background job or files received from a webhook), so you don't need to send them through the browser.

> ⚠️ For large files we **do not** recommend sending the data to your backend and then uploading again from there. Instead, use the presigned upload API from the frontend (see the next section).

### uploadFromBufferToNewRecord

Uploads a file from a Node.js `Buffer`, automatically creates a record in the resource, and returns both the stored file path and a preview URL.

```ts title="./some-backend-service.ts"
import { admin } from './admin'; // your AdminForth instance

...
plugins: [
  new UploadPlugin({
    id: 'my_reports_plugin', // unique identifier for your plugin instance
    ....
  })
]
...

const plugin = admin.getPluginById('my_reports_plugin');

const { path, previewUrl } = await plugin.uploadFromBufferToNewRecord({
  filename: 'report.pdf',
  contentType: 'application/pdf',
  buffer, // Node.js Buffer with file content
  adminUser, // current admin user or system user
  // or if you are using non-adminforth handlers, e.g. public API
  // adminUser: { isExternalUser: true, pk: null, dbUser: {}, username: 'empty' },
  recordAttributes: {
    title: 'Generated report',
    listed: false,
  },
});
```

- Uses the configured storage adapter (S3, local, etc.) to store the file.
- Automatically creates a new record and stores the file path into the column defined by `pathColumnName`, together with any extra `recordAttributes` you pass.
- Returns an object `{ path, previewUrl }`, where `previewUrl` is the same URL used for previews inside AdminForth.

> `previewUrl` is an absolute URL which you can use in emails / blogs / other places.

### uploadFromBufferToExistingRecord

If you already have a record and only want to replace the file referenced in its `pathColumnName` field, use `uploadFromBufferToExistingRecord`. It uploads a file from a Node.js `Buffer`, updates the existing record, and returns the new file path and preview URL.

```ts title="./some-backend-service.ts"
const plugin = admin.getPluginById('my_reports_plugin');

const { path, previewUrl } = await plugin.uploadFromBufferToExistingRecord({
  recordId: existingRecordId, // primary key of the record to update
  filename: 'report.pdf',
  contentType: 'application/pdf',
  buffer,        // Node.js Buffer with file content
  adminUser,     // current admin user or system user
  // or if you are using non-adminforth handlers, e.g. public API
  // adminUser: { isExternalUser: true, pk: null, dbUser: {}, username: 'empty' },
  extra: {},     // optional extra meta for your hooks / audit
});
```

- Uses the same storage adapter and validation rules as `uploadFromBufferToNewRecord` (file extension whitelist, `maxFileSize`, `filePath` callback, etc.).
- Does **not** create a new record – it only updates the existing one identified by `recordId`, replacing the value in `pathColumnName` with the new storage path.
- If the generated `filePath` is the same as the current value in the record, it throws an error to help you avoid CDN/browser caching issues. To force a refresh, make sure your `filePath` callback produces a different key (for example, include a timestamp or random UUID).

> ⚠️ The same recommendation about large files applies here: avoid using `uploadFromBufferToExistingRecord` for very large uploads; prefer a presigned upload flow from the frontend instead.

## Presigned uploading from the frontend

For files that originate in the browser (drag & drop, file input, custom SPA, etc.), the recommended approach is a **direct upload** from the frontend to your storage provider using a presigned URL. The flow looks like this:

1. Your custom or admin frontend sends a request to your backend.
2. The backend calls `plugin.getUploadUrl(...)` and returns `{ uploadUrl, filePath, uploadExtraParams, pathColumnName }` to the frontend.
3. The frontend uploads the file directly to `uploadUrl` using `XMLHttpRequest` with method `PUT` (sending the file as the request body and attaching `uploadExtraParams` as request headers). This allows tracking upload progress.
4. After the upload completes, you **commit** the uploaded file to a record using either:
   - `plugin.commitUrlToUpdateExistingRecord` (update existing record), or
   - `plugin.commitUrlToNewRecord` (create new record), or
   - by writing `filePath` into the column named by `pathColumnName` and letting the plugin’s hooks mark the file as permanent. This should be done only from custom edit/create components on same resource as plugin installed.

By default, files uploaded via `getUploadUrl` are treated as **temporary** and candidates for auto-deletion. They become permanent only after you commit them or write them to `pathColumnName`.

### Getting a presigned upload URL (getUploadUrl)

On the backend (Express, same style as other custom APIs):

```ts title="./index.ts"
import type { IAdminUserExpressRequest } from 'adminforth';
import express from 'express';

...

app.post(
  `${ADMIN_BASE_URL}/api/uploads/get-url-existing`,
  admin.express.authorize(async (req: IAdminUserExpressRequest, res: express.Response) => {
    const { recordId, filename, contentType, size } = req.body;

    const plugin = admin.getPluginById('my_reports_plugin');

    const { uploadUrl, filePath, uploadExtraParams, pathColumnName } = await plugin.getUploadUrl({
      recordId, // can be undefined for new records
      filename, // e.g. file.name
      contentType, // e.g. file.type
      size, // optional, will be validated against maxFileSize to drop error earlier
    });

    res.json({ uploadUrl, filePath, uploadExtraParams, pathColumnName });
  }),
);
```

On the frontend:

```ts title="./some-frontend.ts"
const file = input.files[0];

// 1) Ask your backend to generate upload URL
const { uploadUrl, filePath, uploadExtraParams } = await fetch('/api/uploads/get-url-existing', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    recordId,               // omit for new record flow
    filename: file.name,
    contentType: file.type,
    size: file.size,
  }),
}).then(r => r.json());

// 2) Direct upload from browser to storage
await new Promise<void>((resolve, reject) => {
  const xhr = new XMLHttpRequest();

  xhr.upload.onprogress = (e) => {
    if (e.lengthComputable) {
      const pct = Math.round((e.loaded / e.total) * 100);
      console.log('Upload progress:', `${pct}%`);
    }
  };

  xhr.addEventListener('error', () => reject(new Error('Upload failed: network error')));
  xhr.addEventListener('abort', () => reject(new Error('Upload aborted')));
  xhr.addEventListener('loadend', () => {
    const ok = xhr.readyState === 4 && xhr.status >= 200 && xhr.status < 300;
    if (!ok) {
      return reject(new Error(`Upload failed: HTTP ${xhr.status}`));
    }
    resolve();
  });

  xhr.open('PUT', uploadUrl, true);
  xhr.setRequestHeader('Content-Type', file.type || 'application/octet-stream');

  if (uploadExtraParams) {
    Object.entries(uploadExtraParams).forEach(([key, value]) => {
      xhr.setRequestHeader(key, String(value));
    });
  }

  xhr.send(file);
});
```

### Committing to an existing record (commitUrlToUpdateExistingRecord)

From your backend API (called after the browser upload finishes):

```ts title="./index.ts"
import type { IAdminUserExpressRequest } from 'adminforth';
import express from 'express';

...

app.post(
  `${ADMIN_BASE_URL}/api/uploads/commit-existing`,
  admin.express.authorize(async (req: IAdminUserExpressRequest, res: express.Response) => {
    const { recordId, filePath } = req.body;

    const plugin = admin.getPluginById('my_reports_plugin');

    const adminUser = req.adminUser; // current admin user
    // or if you are using non-adminforth handlers, e.g. public API
    // adminUser: { isExternalUser: true, pk: null, dbUser: {}, username: 'empty' },

    const { path, previewUrl } = await plugin.commitUrlToUpdateExistingRecord({
      recordId,
      filePath,
      adminUser,
      extra: req.extra, // optional HTTP context
    });

    res.json({ path, previewUrl });
  }),
);
```

Or for custom non-authorized APIs (e.g. public API for external users), make sure to pass an `adminUser` object with `isExternalUser: true` to indicate that this is not a real admin user from your database:

```ts title="./index.ts"
...
app.post(
  `${ADMIN_BASE_URL}/api/uploads/commit-existing-public`,
  async (req: express.Request, res: express.Response) => {
    const { recordId, filePath } = req.body;

    const plugin = admin.getPluginById('my_reports_plugin');

    const adminUser = { isExternalUser: true, pk: null, dbUser: {}, username: 'empty' };
    // or if you are using non-adminforth handlers, e.g. public API
    // adminUser: { isExternalUser: true, pk: null, dbUser: {}, username: 'empty' },

    const { path, previewUrl } = await plugin.commitUrlToUpdateExistingRecord({
      recordId,
      filePath,
      adminUser,
      extra: {}, // optional extra context
    });

    res.json({ path, previewUrl });
  },
);
```

This updates only the existing record (no new record is created) and replaces the value in `pathColumnName` with `filePath`. If the path is the same as the current value, an error is thrown to avoid caching issues.

### Committing and creating a new record (commitUrlToNewRecord)

If you want the upload to create a new record:

```ts title="./index.ts"
import type { IAdminUserExpressRequest } from 'adminforth';
import express from 'express';

...

app.post(
  `${ADMIN_BASE_URL}/api/uploads/commit-new`,
  admin.express.authorize(async (req: IAdminUserExpressRequest, res: express.Response) => {
    const { filePath, recordAttributes } = req.body;

    const plugin = admin.getPluginById('my_reports_plugin');

    const adminUser = req.adminUser; // current admin user
    // or if you are using non-adminforth handlers, e.g. public API
    // adminUser: { isExternalUser: true, pk: null, dbUser: {}, username: 'empty' },

    const { path, previewUrl, newRecordPk } = await plugin.commitUrlToNewRecord({
      filePath,
      adminUser,
      extra: req.extra,
      recordAttributes, // e.g. { title: 'Generated report', listed: false }
    });

    res.json({ path, previewUrl, newRecordPk });
  }),
);
```

This will:

- Mark the uploaded key as **not** a deletion candidate.
- Create a new record with `pathColumnName` set to `filePath` (plus any extra `recordAttributes`).
- Return both `previewUrl` and the new record primary key.

## Uploading to one field from another (custom create/edit components)

Sometimes you want to upload a file from one field (custom editor) but store the final path in another field that is handled by an Upload plugin instance. The recommended way is to:

1. Call your backend to get a presigned URL via `getUploadUrl`.
2. Upload from the browser directly to storage.
3. Emit `update:recordFieldValue` from the custom component with `{ fieldName: pathColumnName, fieldValue: filePath }` so the other field is updated.

> Note: if the target UploadPlugin column is hidden on the current page (`showIn.create: false` / `showIn.edit: false`), the backend rejects such updates by default.
> To allow this, set the target column config to `allowModifyWhenNotShowInCreate: true` and/or `allowModifyWhenNotShowInEdit: true`.

This lets you reuse the same Upload plugin instance (and its preview logic) while controlling the UX from a different field.

Example Vue custom editor that uploads an avatar and writes the result into another field handled by Upload plugin:

```html title="./custom/AvatarUploader.vue"
<template>
  
    <input type="file" accept="image/*" @change="onFileChange" />
    
  
</template>

<script setup lang="ts">
import { ref } from 'vue';

const props = defineProps<{ record: any }>();

const emit = defineEmits([
  'update:value',             // optional: current column value
  'update:recordFieldValue',  // update another field in the record
]);

const preview = ref<string | null>(null);

async function onFileChange(e: Event) {
  const input = e.target as HTMLInputElement;
  const file = input.files?.[0];
  if (!file) return;

  // 1) Ask backend for presigned URL
  const { uploadUrl, filePath, uploadExtraParams, pathColumnName } = await fetch(
    '/api/uploads/avatar/get-url',
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        recordId: props.record.id, // undefined for create
        filename: file.name,
        contentType: file.type,
        size: file.size,
      }),
    },
  ).then(r => r.json());

  // 2) Direct upload to storage
  await new Promise<void>((resolve, reject) => {
    const xhr = new XMLHttpRequest();

    xhr.upload.onprogress = (e) => {
      if (e.lengthComputable) {
        const pct = Math.round((e.loaded / e.total) * 100);
        console.log('Upload progress:', `${pct}%`);
      }
    };

    xhr.addEventListener('error', () => reject(new Error('Upload failed: network error')));
    xhr.addEventListener('abort', () => reject(new Error('Upload aborted')));
    xhr.addEventListener('loadend', () => {
      const ok = xhr.readyState === 4 && xhr.status >= 200 && xhr.status < 300;
      if (!ok) {
        return reject(new Error(`Upload failed: HTTP ${xhr.status}`));
      }
      resolve();
    });

    xhr.open('PUT', uploadUrl, true);
    xhr.setRequestHeader('Content-Type', file.type || 'application/octet-stream');

    if (uploadExtraParams) {
      Object.entries(uploadExtraParams).forEach(([key, value]) => {
        xhr.setRequestHeader(key, String(value));
      });
    }

    xhr.send(file);
  });

  // 3) Tell AdminForth to store filePath in the target field
  emit('update:recordFieldValue', {
    fieldName: pathColumnName, // target UploadPlugin field
    fieldValue: filePath,
  });

  // optional local preview
  preview.value = URL.createObjectURL(file);
}
</script>
```

On the backend, `/api/uploads/avatar/get-url` can look like this:

```ts title="./index.ts"
import type { IAdminUserExpressRequest } from 'adminforth';
import express from 'express';

...

app.post(
  `${ADMIN_BASE_URL}/api/uploads/avatar/get-url`,
  admin.express.authorize(async (req: IAdminUserExpressRequest, res: express.Response) => {
    const { recordId, filename, contentType, size } = req.body;

    const plugin = admin.getPluginById('my_reports_plugin');

    const { uploadUrl, filePath, uploadExtraParams, pathColumnName } = await plugin.getUploadUrl({
      recordId, // can be undefined for create pages
      filename,
      contentType,
      size, // optional
    });

    res.json({ uploadUrl, filePath, uploadExtraParams, pathColumnName });
  }),
);
```

> ⚠️ Do not call `commitUrlToUpdateExistingRecord` or `commitUrlToNewRecord` from the same resource’s `beforeSave`/`afterSave` hooks, as it would create an infinite loop of updates/creates. These methods are intended to be called from your own API endpoints after the browser upload finishes.

## Handling Internal vs. External Links (isInternalUrl)

Have you ever encountered a situation where a user pastes a beautiful image directly from Google Images into the Markdown editor, but your system tries to save it as if it were a file from your own S3 bucket? Previously, this could lead to "broken" paths and corrupted data in your database.

### You can easily use this method in your code:
Imagine you are building a custom preview page or a specialized plugin, and you need to know: Is this file something we manage in our storage, or is it just a link to an external resource?

```ts title="./index.ts"
// Get the upload plugin instance
const uploadPlugin = admin.getPluginById('my_s3_storage');

const urlFromEditor = "https://my-bucket.s3.eu-central-1.amazonaws.com/apartments/flat.png";
const externalUrl = "https://images.unsplash.com/photo-1503376780353-7e6692767b70";

// Check the first link
if (await uploadPlugin.isInternalUrl(urlFromEditor)) {
  console.log("✅ This is our file. We can extract the path and manage it in S3.");
  const path = uploadPlugin.getPathFromUrl(urlFromEditor); 
  // Result: "capartmentsars/flat.png"
}

// Check the second link
if (!(await uploadPlugin.isInternalUrl(externalUrl))) {
  console.log("🌐 This is an external link.");
}
```

---

## Markdown


The Markdown plugin enables Markdown support in AdminForth, allowing users to create and edit fields using Markdown syntax and save rich content in Markdown syntax. 

Also, it allows previewing of Markdown fields in the show page.

## Installation

To install the plugin:

```bash
pnpm add @adminforth/markdown --save
```

### Usage

Instantiate the plugin in your apartments resource file for 'description' field.

```typescript title="./resources/apartments.ts"
import MarkdownPlugin from '@adminforth/markdown';

// ... existing resource configuration ...

plugins: [
  new MarkdownPlugin({fieldName: "description"}),
]
```

> Please note that plugin can only work on TEXT and STRING fields

Here is how it looks in the create view:

![alt text](markdown-edit.png)

Here is how it looks in show view:

![alt text](markdown-show-1.png)

### Images in Markdown

First, you need to create resource for images:
```prisma title="schema.prisma"
model description_image {
    id          String   @id
    created_at  DateTime
    resource_id String
    record_id   String
    image_path  String
}
```

```bash
pnpm makemigration --name add_description_image ; pnpm migrate:local
```

```bash
pnpm add @adminforth/upload --save
pnpm add @adminforth/storage-adapter-local --save
```

```typescript title="./resources/description_images.ts"
import AdminForthStorageAdapterLocalFilesystem from "@adminforth/storage-adapter-local";
import { AdminForthResourceInput } from "adminforth";
import UploadPlugin from "@adminforth/upload";
import { randomUUID } from 'crypto';

export default {
  dataSource: "maindb",
  table: "description_image",
  resourceId: "description_images",
  label: "Description images",
  columns: [
    {
      name: "id",
      primaryKey: true,
      required: false,
      fillOnCreate: ({ initialRecord }: any) => randomUUID(),
      showIn: {
        create: false,
      },
    },
    {
      name: "created_at",
      required: false,
      fillOnCreate: ({ initialRecord }: any) => new Date().toISOString(),
      showIn: {
        create: false,
      },
    },
    { name: "resource_id", required: false },
    { name: "record_id", required: false },
    { name: "image_path", required: false },
  ],
  plugins: [
    new UploadPlugin({
      pathColumnName: "image_path",
      
      // rich editor plugin supports only 'public-read' ACL images for SEO purposes (instead of presigned URLs which change every time)
      storageAdapter: new AdminForthStorageAdapterLocalFilesystem({
        fileSystemFolder: "./db/uploads/description_images", // folder where files will be stored on disk
        adminServeBaseUrl: "static/source", // the adapter not only stores files, but also serves them for HTTP requests
        mode: "public", // public if all files should be accessible from the web, private only if could be accesed by temporary presigned links
        signingSecret: process.env.ADMINFORTH_SECRET, // secret used to generate presigned URLs
      }),
  
      allowedFileExtensions: [
        "jpg",
        "jpeg",
        "png",
        "gif",
        "webm",
        "exe",
        "webp",
      ],
      maxFileSize: 1024 * 1024 * 20, // 20MB

      filePath: ({ originalFilename, originalExtension, contentType }) =>
        `description_images/${new Date().getFullYear()}/${randomUUID()}/${originalFilename}.${originalExtension}`,

      preview: {
        // Used to display preview (if it is image) in list and show views instead of just path
        // previewUrl: ({s3Path}) => `https://tmpbucket-adminforth.s3.eu-central-1.amazonaws.com/${s3Path}`,
        // show image preview instead of path in list view
        // showInList: false,
      },
    }),
  ],
} as AdminForthResourceInput;
```
Next, add new resource to `index.ts`:

```typescript title="./index.ts"
// diff-add
import descriptionImage from './resources/description_images.js';

...

  resources: [
    usersResource,
    apartments,
    // diff-add
    descriptionImage
  ],
```

Next, add attachments to Markdown plugin:

```typescript title="./resources/apartments.ts"
import MarkdownPlugin from '@adminforth/markdown';

// ... existing resource configuration ...

plugins: [
  new MarkdownPlugin({
    fieldName: "description",
// diff-add
    attachments: {
// diff-add
        attachmentResource: "description_images",
// diff-add
        attachmentFieldName: "image_path",
// diff-add
        attachmentRecordIdFieldName: "record_id",
// diff-add
        attachmentResourceIdFieldName: "resource_id",
// diff-add
      },
    }),
]
```

### Markdown Top Panel
The Markdown plugin also provides a convenient top panel with formatting buttons, allowing users to quickly apply Markdown syntax without typing it manually.

![alt text](markdown-top-panel.png)

By default, the toolbar includes common formatting actions such as:
- Bold
- Italic
- Underline
- Strikethrough
- Headings (H1, H2, H3)
- Lists (ordered and unordered)
- Links
- Code blocks

If some buttons are unnecessary for your use case, you can easily disable them using the topPanelSettings option.

```typescript title="./resources/apartments.ts"
import MarkdownPlugin from '@adminforth/markdown';

// ... existing resource configuration ...

plugins: [
  new MarkdownPlugin({
  fieldName: "description",
  // diff-add
  topPanelSettings: {
    // diff-add
    bold: false, //disable bold button
  },
})
]
```

>👆 Full list of buttons you can enable or disable via topPanelSettings:
bold, italic, underline, strike, h1, h2, h3, ul, ol, link, codeBlock 

## Change size of show view markdown text
By default in markdown plugin turned cumpact preview mode, but you can turn it off:

```ts
  new MarkdownPlugin({
    fieldName: 'description',
    //diff-add
    compactShowPreview: false,        
    ...
  })

```

## Limiting height of the markdown renderer on show view
If you have really long markdown text and you don't wan't it to take the whole space on show view page, you can use `maxShowViewContainerHeightPx`, that will add max-height to the markdown renderer and button `show more`, so you can expand it.

```ts
  new MarkdownPlugin({
    fieldName: 'description',
    compactShowPreview: false,       
    //diff-add
    maxShowViewContainerHeightPx: 400, 
    ...
  })

```

---

## Email Password Reset

# Email password reset

Plugin allows to reset password for admin users who forgot their password by sending email with reset link signed with secured JWT token.

> ⚠️ if users created manually in backoffice, ensuring that email is valid is responsibility of the admin which might be a security risk
> (if email is mistyped then, person who owns mistyped email can reset password and get access)

> ⚠️ If user with email does not exist, plugin will still show to user success message to prevent email enumeration.

## Email normalization

The plugin applies the column's [`normalize`](/docs/tutorial/Customization/standardPagesTuning/#normalize-values-before-saving) callback before validating and looking up the submitted email. It uses the normalized value in the reset token, for token confirmation, and as the email delivery address.

For example, configure the email column to make password reset and login insensitive to surrounding whitespace and letter case:

```typescript title="./resources/adminuser.ts"
{
  name: 'email',
  required: true,
  isUnique: true,
  normalize: (value: string) => value.trim().toLowerCase(),
}
```

Installation:

```bash
pnpm add @adminforth/email-password-reset
pnpm add @adminforth/email-adapter-aws-ses
```

Import plugin:

```typescript
import EmailResetPasswordPlugin from '@adminforth/email-password-reset';
```

## SES

To Setup SES, you need to have an AWS account and SES service enabled. You can follow the steps below to setup SES.

1. Go to the AWS Management Console and open the Amazon SES console at [https://console.aws.amazon.com/ses/](https://console.aws.amazon.com/ses/).
2. Make sure you are in the correct region. You can change the region from the top right corner. For example, if you are in the `us-east-1` region, you can see the region name US East (N. Virginia) in the top right corner.

3. Add your email address (any email), and verify it.
4. Add some domain you own and verify it by creating DNS records which AWS suggests. This will be used as the domain for sending emails. e.g. if you want to send from no-reply@devforth.io you need to verify `devforth.io`. 

Add plugin to user resource:

```typescript ./resources/adminuser.ts
import EmailResetPasswordPlugin from '@adminforth/email-password-reset';
import EmailAdapterAwsSes from '@adminforth/email-adapter-aws-ses';

...
plugins: [
  ...
  new EmailResetPasswordPlugin({
    // field in user resource which contains email
    emailField: 'email',

    // field in user resource which contains password constrains. Should be virtual field
    passwordField: 'password',

    // domain part should be verified in SES
    sendFrom: 'no-reply@devforth.io',

    // origin(s) of your admin panel that reset links are allowed to point to.
    // Required: the origin is never taken from the request, so an attacker
    // cannot make the plugin email a valid reset link to a host they control.
    // Pass an array if the panel is served on multiple origins.
    expectedOrigin: 'https://admin.example.com',

    adapter: new EmailAdapterAwsSes({
      // region where SES is setup
      region: "eu-central-1",
      accessKeyId: process.env.AWS_ACCESS_KEY_ID as string,
      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY as string,
    }),
  }),
]
```

Make sure to place your AWS credentials in `.env` file/environment.

```bash /.env
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
```

## Mailgun

To Setup Mailgun, you need to have an account and Mailgun service enabled. You can follow the steps below to setup Mailgun.

1. Go to [https://www.mailgun.com/](https://www.mailgun.com/) and create an account.
2. Add your email address (any email), and verify it.
3. Add your domain (any domain) and verify it.
4. Add your API key.

Add plugin to user resource:

```typescript ./resources/adminuser.ts
import EmailResetPasswordPlugin from '@adminforth/email-password-reset';
import EmailAdapterMailgun from '@adminforth/email-adapter-mailgun';
...
plugins: [
  ...
  new EmailResetPasswordPlugin({
    // field in user resource which contains email
    emailField: 'email',

    // field in user resource which contains password constrains. Should be virtual field
    passwordField: 'password',

    // domain part should be verified in Mailgun
    sendFrom: 'no-reply@devforth.io',

    // origin(s) of your admin panel that reset links are allowed to point to.
    // Required: the origin is never taken from the request, so an attacker
    // cannot make the plugin email a valid reset link to a host they control.
    // Pass an array if the panel is served on multiple origins.
    expectedOrigin: 'https://admin.example.com',

    adapter: new EmailAdapterMailgun({
      apiKey: process.env.MAILGUN_API_KEY as string,
      domain: process.env.MAILGUN_DOMAIN as string,
      //baseUrl is optional, if not provided, will default to "https://api.mailgun.net" but if you are using Mailgun EU, you should use "https://api.eu.mailgun.net" instead
      baseUrl: process.env.MAILGUN_REGION_URL as string,
    }),
  }),
]
```

Make sure to place your Mailgun credentials in `.env` file/environment.

```bash /.env
MAILGUN_API_KEY=your-api-key
MAILGUN_DOMAIN=your-domain
MAILGUN_REGION_URL=your-region-url # optional
```

## Password reset page injection
If you want create custom header, or want to add some data under input, you can add:

``` ts title='./resources/users'
  new EmailResetPasswordPlugin({
    ...
  //diff-add
    pageInjection: {
    //diff-add  
      panelHeader: "@@/YourCustomHeader";
    //diff-add
      underInputs: "@@/YourUnderInput";
    //diff-add
    }
    ...
  })
```

---

## Import Export

# Import-Export

Import Export is a plugin that allows you to import and export resource data as CSV or Excel (`.xlsx`) files.

This plugin is mostly useful for the following use cases:

* Move data from one environment to another (e.g. from development to production)
* Export data for various purposes (e.g. backup, analysis)

There are two export modes:
- Classic (REST)
- Upload

If you are exporting light datasets (less than 5 MiB), you can use classic mode. It returns the data in JSON format in the API response.
You can increase the maximum dataset size with the `classicalUploadLimitMiB` param (5 MiB is the default). But if you set a big limit, the export can consume all the RAM of your server and crash it.

So if you want to export big databases, use the `exportViaUpload` param. It uses the Background Jobs plugin and AWS S3 multipart upload, so it does not overload the server.

## Installation

To install the plugin:

```bash
pnpm add @adminforth/import-export --save
```

## Setup

To use the plugin, you need to import it and instantiate the `ImportExport` class:

```typescript
import ImportExport from '@adminforth/import-export';
```

Add the plugin instantiation to the `plugins` array of the resource where you want to use it:

```typescript

export default {
  resourceId: 'aparts',
  plugins: [
    ...
    new ImportExport({}),
  ],
  ...
}
```

CSV import and export are enabled by default.

## File format

Set `fileFormat` on each plugin instance to choose the format used by both import and export:

```typescript
new ImportExport({
  fileFormat: 'xlsx',
})
```

Supported values are:

- `'csv'` (default)
- `'xlsx'`

For XLSX imports, the first row of each non-empty worksheet is treated as the column header. Rows from multiple worksheets are combined, but all non-empty worksheets must have the same columns in the same order.

Both classic and upload export support XLSX. A background XLSX export that exceeds Excel's limit of 1,048,575 data rows per worksheet is automatically split into multiple worksheets, with the header repeated on each worksheet.

## Export-only mode

Import is enabled by default. To expose only the export action, set `importEnabled` to `false`:

```typescript
new ImportExport({
  importEnabled: false,
})
```

This removes the import action from the resource UI and does not register the import endpoints. Export remains available in the selected `fileFormat`.

## Upload export

1) First, set up the Background Jobs plugin: go to the [Background Jobs Plugin page](/docs/tutorial/Plugins/background-jobs) and complete the setup.

2) Install the AWS S3 adapter:

```bash
pnpm add @adminforth/storage-adapter-amazon-s3
```

3) Update the plugin setup:

```typescript
import ImportExport from '@adminforth/import-export';
import AdminForthAdapterS3Storage from '@adminforth/storage-adapter-amazon-s3'
```

Add the plugin instantiation to the `plugins` array of the resource where you want to use it:

```typescript

export default {
  resourceId: 'aparts',
  plugins: [
    ...
    new ImportExport({
      fileFormat: 'xlsx', // optional; defaults to 'csv'
      exportViaUpload: {
        storageAdapter: new AdminForthAdapterS3Storage({
          bucket: process.env.AWS_BUCKET_NAME as string,
          region: process.env.AWS_REGION as string,
          accessKeyId: process.env.AWS_ACCESS_KEY_ID as string,
          secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY as string,
          s3ACL: "public-read"
        })
      }
    }),
  ],
  ...
}
```

The upload mode supports the same `fileFormat` values as classic export. You can also tune memory usage and database read size:

```typescript
new ImportExport({
  exportViaUpload: {
    storageAdapter,
    bufferSizeMb: 10, // defaults to 5 MiB; minimum is 5 MiB
    readChunkSize: 500, // defaults to 100 records
  },
})
```

---

## Open Signup


Open Signup plugin allows users to register in adminforth by them-selfs without admin. 
This is useful when you want to allow anyone to sign up and assign some low-level permissions to them.

## Installation

To install the plugin:

```bash
pnpm add @adminforth/open-signup --save
```

## Usage

To use the plugin, instantiate to to user resource:

```typescript title="./resources/adminuser.ts"
import OpenSignupPlugin from '@adminforth/open-signup';
```

Like this:

```typescript title="./resources/adminuser.ts"
new OpenSignupPlugin({
    emailField: 'email',
    passwordField: 'password',
    passwordHashField: 'password_hash',
    defaultFieldValues: {
      role: 'user',
    },
    expectedOrigin: process.env.OPEN_SIGHNUP_ORIGIN || 'http://localhost:3500',
  }),
```

Please note that in this mode users will be able to sign up without email verification. For enabling email verification, see below.

## Email verification

First, you need to migrate the `adminuser` table in `./schema.prisma`:

```ts title='./schema.prisma'
model adminuser {
  ...
  //diff-add
  email_confirmed Boolean? @default(false)
}
```

And prisma migrate:

```bash
pnpm makemigration --name add-email-confirmed-to-adminuser ; pnpm migrate:local

```

Next, install the `@adminforth/email-adapter-aws-ses` package:

```bash
pnpm add @adminforth/email-adapter-aws-ses --save
```

Also, update the resource configuration in `./resources/adminuser.ts`:

```ts title='./resources/adminuser.ts'
...
//diff-add
import EmailAdapterAwsSes from '@adminforth/email-adapter-aws-ses';

export default {
  dataSource: 'maindb',
  table: 'adminuser',
  resourceId: 'adminuser',
  label: 'Users',
  recordLabel: (r) => `👤 ${r.email}`,
  columns: [
    ...
    //diff-add
    { name: 'email_confirmed' }
  ],
  ...
  plugins: [
    ...
    new OpenSignupPlugin({
      emailField: "email",
      passwordField: "password",
      passwordHashField: "password_hash",
      defaultFieldValues: {
        role: "user",
      },
      //diff-add
      confirmEmails: {
        //diff-add
        emailConfirmedField: "email_confirmed",
        //diff-add
        sendFrom: "no-reply@devforth.io",
        //diff-add
        adapter: new EmailAdapterAwsSes({
          //diff-add
          region: "eu-central-1",
          //diff-add
          accessKeyId: process.env.AWS_ACCESS_KEY_ID as string,
          //diff-add
          secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY as string,
          //diff-add
        }),
        //diff-add
      },
    }),
    ...
  ],
  ...
}
```

---

## Internationalization (i18n)


This plugin allows you translate your AdminForth application to multiple languages.
Main features:
- Stores all translation strings in your application in a single AdminForth resource. You can set [allowed actions](/docs/tutorial/Customization/limitingAccess/) only  to Developers/Translators role if you don't want other users to see/edit the translations.
- Supports AI completion adapters to help with translations. For example, you can use OpenAI via the Responses API to generate translations. Supports correct pluralization, even for Slavic languages.
- Supports any number of languages.
- Supports BCP47 language codes (e.g., `en-GB`, `pt-BR`) for regional language variants.
- Configurable primary language.

Under the hood it uses vue-i18n library and provides several additional facilities to make the translation process easier.

## Installation

To install the plugin:

```bash
pnpm add @adminforth/i18n --save
pnpm add @adminforth/completion-adapter-openai-responses --save
```

For example lets add translations to next 4 languages: Ukrainian, Japanese, French, Spanish. Also we will support basic translation for English.

Add a model for translations, if you are using prisma, add something like this:

```ts title='./schema.prisma'
model translations {
    id              String   @id
    en_string       String
    created_at      DateTime
    uk_string       String?  // translation for Ukrainian language
    ja_string       String?  // translation for Japanese language
    fr_string       String?  // translation for French language
    es_string       String?  // translation for Spanish language
    ptBR_string      String?  // Brazilian Portuguese translation using BCP47 code (pt-BR)
    category        String
    source          String?
    completedLangs   String?
    
    // we need both indexes on en_string+category and separately on category
    @@index([en_string, category])
    @@index([category])
    @@index([completedLangs])
}
```

If you want more languages, just add more fields like `uk_string`, `ja_string`, `fr_string`, `es_string` to the model.

> 💡 **Tip**: For regional language variants, you can also use BCP47 codes like `en-GB`, `pt-BR`, `fr-CA` and add corresponding fields like `enGB_string`, `ptBR_string`, `frCA_string`.

Next, add resource for translations:

```ts title='./resources/translations.ts'

import AdminForth, { AdminForthDataTypes, AdminForthResourceInput } from "adminforth";
import CompletionAdapterOpenAIResponses from "@adminforth/completion-adapter-openai-responses";
import I18nPlugin from "@adminforth/i18n";
import { randomUUID } from 'crypto';

export default {
  dataSource: "maindb",
  table: "translations",
  resourceId: "translations",
  label: "Translations",

  recordLabel: (r: any) => `✍️ ${r.en_string}`,
  plugins: [
    new I18nPlugin({
      supportedLanguages: ['en', 'uk', 'ja', 'fr', 'pt-BR'],

      // names of the fields in the resource which will store translations
      translationFieldNames: {
        en: 'en_string',
        uk: 'uk_string',
        ja: 'ja_string',
        fr: 'fr_string',
        'pt-BR': 'ptBR_string',

      },

      // name of the field which will store the category of the string
      // this helps to categorize strings and deliver them efficiently
      categoryFieldName: 'category',

      // optional field to store the source (e.g. source file name)
      sourceFieldName: 'source',

      // optional field store list of completed translations
      // will hel to filter out incomplete translations
      completedFieldName: 'completedLangs',

      // optional: set primary language (defaults to 'en' if not specified)
      // primaryLanguage: 'fr', // Uncomment to set French as primary language

      completeAdapter: new CompletionAdapterOpenAIResponses({
        openAiApiKey: process.env.OPENAI_API_KEY as string,
        model: 'gpt-5-nano',
        extraRequestBodyParameters: {
          // for UI translation it is better to lower down the temperature. Less creative and more accurate
          temperature: 0.5,
        },
      }),
    }),

  ],
  options: {
    listPageSize: 30,
  },
  columns: [
    {
      name: "id",
      fillOnCreate: ({ initialRecord, adminUser }: any) => randomUUID(),
      primaryKey: true,
      showIn: { all: false },
    },
    {
      name: "en_string",
      type: AdminForthDataTypes.STRING,
      label: 'English',
    },
    {
      name: "created_at",
      fillOnCreate: ({ initialRecord, adminUser }: any) => new Date().toISOString(),
      showIn: {
        all: false,
        show: true,
        edit: false,
      },
    },
    {
      name: "uk_string",
      type: AdminForthDataTypes.STRING,
      label: 'Ukrainian',
    },
    {
      name: "ja_string",
      type: AdminForthDataTypes.STRING,
      label: 'Japanese',
    },
    {
      name: "fr_string",
      type: AdminForthDataTypes.STRING,
      label: 'French',
    },
    { 
      name: "ptBR_string",
      type: AdminForthDataTypes.STRING,
      label: "Portuguese (BR)"
    },
    {
      name: "completedLangs",
    },
    {
      name: "source",
      showIn: {
        list: false,
        edit: false,
        create: false,
      },
      type: AdminForthDataTypes.STRING,
    },
    {
      name: "category",
      showIn: {
        edit: false,
        create: false,
      },
      type: AdminForthDataTypes.STRING,
    }
  ],
} as AdminForthResourceInput;
```

Add `OPENAI_API_KEY` to your `.env` file:

```bash
OPENAI_API_KEY=your_openai_api_key
```

Also add the resource to main file and add menu item in `./index.ts`:

```ts title='./index.ts'

//diff-add
import translations from "./resources/translations";
...

const adminForth = new AdminForth({
  ...
  resources: [
    ...
//diff-add
    translations,
  ],
  menu: [
    ...
//diff-add
    {
//diff-add
      label: 'Translations',
//diff-add
      icon: 'material-symbols:translate',
//diff-add
      resourceId: 'translations',
//diff-add
    },
  ],
  ...
});

```

> ⚠️ **Important**: Since version 2.0.0, this plugin requires the Background Jobs plugin to be set up. Go to the [Background Jobs Plugin page](/docs/tutorial/Plugins/background-jobs) and complete the setup.

This is it, now you should restart your app and see the translations resource in the menu. 

You can add translations for each language manually or use Bulk actions to generate translations with AI completion adapter.

For simplicity you can also use filter to get only untranslated strings and complete them one by one (filter name "Fully translated" in the filter).

## Primary Language Configuration

The `primaryLanguage` option allows you to set the default language for your application. This is particularly useful when your application's primary language is not English.

### How Primary Language Works

- **Default Language**: The language shown to users by default
- **Fallback Chain**: When a translation is missing, the system falls back to: `requested language` → `primaryLanguage` → `English`
- **Translation Source**: English (`en_string`) is always used as the source for AI translations, regardless of the primary language setting

### Example: Portuguese as Primary Language

```ts title='./resources/translations.ts'
export default {
  // ... other configuration
  plugins: [
    new I18nPlugin({
      // Set Portuguese as the primary language
      primaryLanguage: 'pt-BR',
      
      supportedLanguages: ['pt-BR', 'en', 'en-GB', 'es', 'fr'],
      translationFieldNames: {
        'pt-BR': 'ptBR_string',
        en: 'en_string',
        'en-GB': 'enGB_string',
        es: 'es_string',
        fr: 'fr_string',
      },
      
      // ... rest of configuration
    }),
  ],
  // ... rest of configuration
} as AdminForthResourceInput;
```

## Translation for custom components

To translate custom components, you should simply wrap all strings in $t function. For example:

Now create file `CustomLoginFooter.vue` in the `custom` folder of your project:

```html title="./custom/CustomLoginFooter.vue"
<template>
  
//diff-remove
    By logging in, you agree to our Terms of Service and Privacy Policy
//diff-add
    {{$t('By logging in, you agree to our')}} {{$t('Terms of Service')}} {{$t('and')}} {{$t('Privacy Policy')}}
  
</template>
```

### Variables in frontend translations

You can use variables in translations in same way like you would do it with vue-i18n library. 

This is generally helps to understand the context of the translation for AI completion adapters and simplifies the translation process, even if done manually.

For example if you have string "Showing 1 to 10 of 100 entries" you can of course simply do

```html
{{ $t('Showing')}} {{from}} {{$t('to')}} {{to}} {{$t('of')}} {{total}} {{$t('entries') }}
``` 

And it will form 4 translation strings. But it is much better to have it as single string with variables like this:

```html
{{ $t('Showing {from} to {to} of {total} entries', { from, to, total } ) }}
```

For example, let's add user greeting to the header.

```html title="./custom/Header.vue"
<template>
  
    
      {{ $t('Welcome, {name}', { name: adminUser.username }) }}
    
  
</template>

<script setup lang="ts">
import type { AdminForthResourceColumnCommon, AdminForthResourceCommon, AdminUser } from '@/types/Common';

const props = defineProps<{
    column: AdminForthResourceColumnCommon;
    record: any;
    meta: any;
    resource: AdminForthResourceCommon;
    adminUser: AdminUser
}>();
</script>
```

How to use such component

```typescript title="./index.ts"

const adminForth = new AdminForth({
  ...
  customization{ 
    globalInjections: {
      header: {
        file: '@@/Header.vue',
      },
    }
  },
  ...
});

```

### HTML in translations

Sometimes you might want to have HTML in translations. You can use `i18n-t` translation component for this. For example:

```html

  <i18n-t keypath="Showing {from} to {to} of {total} Entries" tag="p"  >
    <template v-slot:from>
      {{ from }}
    </template>
    <template v-slot:to>
      {{ to }}
    </template>
    <template v-slot:total>
      {{ totalRows }}
    </template>
  </i18n-t>

```

### Pluralization

Frontend uses same pluralization rules as vue-i18n library. You can use it in the same way. For example:

```html
{{ $t('Apartment last 7 days | Apartments last 7 days', data.totalAparts) }}
```

For English it will use 2 pluralization forms (1 and other), for Slavic languages, LLM adapter will be instructed to generate 4 forms via Pipe: for zero, for one, for 2-4 and for 5+:

![alt text](image-4.png)

> 🚧 Cheaper LLM models like `gpt-5-nano` might still purely generate pluralisation slavic forms, even despite the fact plugin carefully
instructs the model and gives it examples. So if you are using cheap model we recommend reviewing generated translations for plurals and fixing them manually. You can use filter with '|' parameter to filter out strings with pluralisation.

## Limiting access to translating

If you want to limit access to translations resource only to developers or translators, you can use [limiting access](/docs/tutorial/Customization/limitingAccess/) feature. 

Please note that access to "Translate selected" bulk action which uses LLM AI translation adapter is determined by allowedActions.edit permission of resource.

## Proofreading checkboxes

You can enable didicated checkboxes for proofreading translations. This will allow proofreaders to check each translation and mark it "reviewed" or "not reviewed".

TO enable this options add TEXT column to the resource.

If using prisma, add something like this:

```ts title='./schema.prisma'
model translations {
  ...
    completedLangs   String?
  //diff-add
    reviewed          String? 
    
    // we need both indexes on en_string+category and separately on category
    @@index([en_string, category])
    @@index([category])
    @@index([completedLangs])
}  
```

And add column to the resource:

```ts title='./resources/translations.ts'
{
  ...
  columns: [
    ...
    {
      name: "reviewed",
      type: AdminForthDataTypes.JSON, // should be JSON type
      label: 'Reviewed',
      showIn: {
        all: false
      },
    },
  ],
}
```

Now just add `reviewedCheckboxesFieldName` to the plugin options:

```ts title='./resources/translations.ts'
  plugins: [
    new I18nPlugin({
      ...
      reviewedCheckboxesFieldName: 'reviewed',
    }),
  ],
```
This will add checkboxes to the translations resource:

![alt text](image-5.png)

## Translations in custom APIs

Sometimes you need to return a translated error or success message from your API. You can use special `tr` function for this.

For simple example let's move previous example to format string on the backend side:

```html title="./custom/Header.vue"
<template>
  
    
      {{ greeting }}
    
  
</template>

<script setup lang="ts">
import type { AdminForthResourceColumnCommon, AdminForthResourceCommon, AdminUser } from '@/types/Common';
import { callApi } from '@/utils';
import { ref, onMounted } from 'vue';
import { useAdminforth } from '@/adminforth';

const greeting: Ref<string> = ref('');

const { alert } = useAdminforth();

onMounted(async () => {
  try {
    const data = await callApi({path: '/api/greeting', method: 'GET'});
    greeting.value = data.text;
  } catch (error) {
    alert({
      message: `Error fetching data: ${error.message}`,
      variant: 'danger',
      timeout: 'unlimited'
    });
    return;
  }
})
</script>
```

And on the backend side you can use tr function to translate the string:

```ts title="./index.ts"
import type { IAdminUserExpressRequest, ITranslateExpressRequest } from 'adminforth';
import express from 'express';

....

  app.get(`${ADMIN_BASE_URL}/api/greeting`, 
    admin.express.authorize(
      admin.express.translatable(
        async (req: IAdminUserExpressRequest & ITranslateExpressRequest, res: express.Response) => {
          res.json({
            text: await req.tr('Welcome, {name}', 'customApis', { name: req.adminUser.username }),
          });
        }
      )
    )
  );

  // serve after you added all api
  admin.discoverDatabases();
  admin.express.serve(app)
```

As you can see we should use `admin.express.translatable` middleware which will inject `tr` function to the request object.
First param is the string to translate, second is the category of the string (actually you can use any string here), and the third is the variables object.

If you don't use params, you can use `tr` without third param:

```typescript
{
  text: await tr('Welcome, dear user', 'customApis'),
}
```

> 🔄 **Fallback Behavior**: The `tr` function automatically handles fallbacks when translations are missing. It follows this chain: `requested language` → `primaryLanguage` → `English`. This ensures users always see content in a language they can understand, even if specific translations are missing.

> 🙅‍♂️ Temporary limitation: For now all translations strings for backend (adminforth internal and for from custom APIs)
 appear in Translations resource and table only after they are used. So greeting string will appear in the Translations table only after the first request to the API which reaches the `tr` function call. 
> So to collect all translations you should use your app for some time and make sure all strings are used at
> In future we plan to add backend strings collection in same way like frontend strings are collected.

### Pluralisation in backend translations

In same way you can use pluralisation in backend translations:

```ts title="./index.ts"
await req.tr('{count} apartment last 7 days | {count} apartments last 7 days', 'customApis', { count: totalAparts }, totalAparts) 
```

Please pay attention that you should pass `totalAparts` as last argument to `tr` function. 

If you don't have parameters, you can pass empty object as 3rd argument:

```ts title="./index.ts"
await req.tr('Apartment last 7 days | Apartments last 7 days', 'customApis', {}, totalAparts) 
```

Pluralisation rules are the same as in frontend

## Translating messages within bulk action

The `label`, `bulkConfirmationMessage`, and `bulkSuccessMessage` fields of bulk actions are static strings and are translated automatically by AdminForth. However, a **dynamic** success message returned from inside `bulkHandler` must be translated manually using the `tr` helper that is injected into the handler.

Let's rework the bulk action from the [Actions example](/docs/tutorial/Customization/Actions/#dedicated-bulk-handler) to use translations:

```ts title="./resources/apartments.ts"
{
  name: 'Mark as listed',
  icon: 'flowbite:eye-solid',
  showIn: {
    showThreeDotsMenu: true,
    bulkButton: true,
  },
  action: async ({ recordId, adminforth }) => {
    await adminforth.resource('aparts').update(recordId, { listed: true });
    return { ok: true, successMessage: 'Marked as listed' };
  },
  bulkHandler: async ({ recordIds, tr }) => {
    const db = adminforth.resource('aparts').dataConnector.client;
    db.prepare(
      `UPDATE aparts SET listed = 1 WHERE id IN (${recordIds.map(() => '?').join(',')})`
    ).run(...recordIds);
//diff-remove
    return { ok: true, successMessage: `Marked ${recordIds.length} apartments as listed` };
//diff-add
    return { ok: true, successMessage: await tr('Marked {count} apartments as listed', 'apartments', { count: recordIds.length }) };
  },
  bulkConfirmationMessage: 'Are you sure you want to mark selected apartments as listed?',
}
```

## Different scripts (writing systems) / regions / variants / dialects

### Scripts (Writing systems)

For some languages you may want translations in a specific, non-default script (or want the choice to be deterministic).

For example, Serbian (`sr`) is written in both Cyrillic and Latin scripts. If you use only `sr`, an LLM may pick a script inconsistently (or default to Cyrillic). To force a particular script, use `translateLangAsBCP47Code`:

```ts
translateLangAsBCP47Code: { sr: 'sr-Latn' }
```

Alternatively, you can or course use the script-tagged BCP47 code directly in `supportedLanguages`:

```diff
--- supportedLanguages: ['en', 'sr']
+++ supportedLanguages: ['en', 'sr-Latn']
```

However, in this case `sr-Latn` becomes the language identifier everywhere. For example if you expose language codes to an external app (e.g., in URLs or subdomains), you may end up with URLs like `https://my.site/sr-Latn/my-page`, which is sometimes undesirable. You can work around this by remapping `sr-Latn ↔ sr` in the external system, but we generally recommend `translateLangAsBCP47Code` as the dedicated, internal way to keep a clean ISO 639-1 code while translating as a specific BCP47 tag.

If you want to support both scripts explicitly, include both in `supportedLanguages`:

```ts
supportedLanguages: ['en', 'sr-Latn', 'sr-Cyrl']
```

### Dialects and national standards

European Portuguese and Brazilian Portuguese differ, so it’s common to use BCP47 region subtags to distinguish them.

To support both:

```ts
supportedLanguages: ['en', 'pt-BR', 'pt-PT']
```

If you only want one version (e.g. Brazilian Portuguese) but still want to keep a clean `pt` code in your API/URLs, use `translateLangAsBCP47Code`:

```ts
supportedLanguages: ['en', 'pt']
translateLangAsBCP47Code: { pt: 'pt-BR' }
```

LLM adapters generally understand the BCP47 tags you provide.

### Variants

More rarely, you may need a specific language variant. For example, British English typically uses standard BrE spelling, but the Oxford English Dictionary variant (OED) differs in some cases:

| Standard BrE | Oxford (OED) |
| --- | --- |
| colour | colour |
| organise | organize |
| realise | realize |

You can use `translateLangAsBCP47Code` to request a specific variant:

```ts
supportedLanguages: ['en']
translateLangAsBCP47Code: { en: 'en-GB-oed' }
```

As any BCP47 tag it is also supported in `supportedLanguages` directly, but again this will make the full tag (e.g., `en-GB-oed`) appear in your API/URLs external systems unless you remap it externally.

## Translating external application

You can use this module not only to translate admin area of your application but also to translate other parts like SEO-facing or user-facing services.
This will allow you to reuse the same functionality and AI completion adapters for all your translations and manage them in one place. 
For example in this app we will consider translating a Nuxt.js SEO-centric frontend which we want to translate with [nuxt i18n](https://i18n.nuxtjs.org/).

To do it you need to use 2 exposed methods from the plugin: `feedCategoryTranslations` and `getCategoryTranslations`. 

First of all, at some step, e.g. CI pipeline you should get all translation strings from your external app and feed them an own rest API like `'/feed-nuxt-strings'`, this API might look like this

```ts title="./index.ts"
  app.post(`${ADMIN_BASE_URL}/feed-nuxt-strings`, 
    async (req, res) => {
      // req.body will be an array of objects like:
      // [{
      //    path: 'Login',
      //    file: 'src/views/Login.vue:35',
      // }]

      const messagesForFeed = req.body.missingKeys.map((mk: any) => {
        return {
          en_string: mk.path,
          source: mk.file,
        };
      });

      admin.getPluginByClassName<I18nPlugin>('I18nPlugin').feedCategoryTranslations(
        messagesForFeed,
        'seoApp'
      )

      res.json({
        ok: true
      });
    }
  );

```

For extracting i18n messages we use [vue-i18n-extract](https://github.com/Spittal/vue-i18n-extract) package. 
You can add extract command to `package.json`:

```json
{
  "scripts": {
    "i18n:extract": "echo '{}' > i18n-empty.json && vue-i18n-extract report --vueFiles './?(pages|components)/**/*.?(js|vue)' --output ./i18n-messages.json --languageFiles 'i18n-empty.json' --add",
    "i18n:feed-to-local-backoffice": "npm run i18n:extract && curl -X POST -H 'Content-Type: application/json' -d @i18n-messages.json http://localhost:3000/feed-nuxt-strings"
  }
}
```

> For plain non-nuxt apps `--vueFiles './?(pages|components)/**/*.?(js|vue)'` should be replaced with `--vueFiles './src/**/*.?(js|vue)'`

Make sure to replace `localhost:3000` with AdminForth API URL.

So locally you can run `npm run i18n:feed-to-local-backoffice` to extract messages from your Nuxt.js app and feed them to AdminForth.

Next part. When we will need translations on the nuxt instance, we should use [vue-i18n's lazy loading feature](https://vue-i18n.intlify.dev/guide/advanced/lazy):

```typescript title="./your-nuxt-app-source-file.ts"
const { locale, setLocaleMessage, } = useI18n();
const { data: messages } = await useFetch(
  useRuntimeConfig().public.adminUrl + `api/translations/?lang=${locale.value}`,
  {
    method: 'GET',
  }
);
if (messages.value) {
  setLocaleMessage(locale.value, messages.value);
} else {
  console.error('Translations or language data are missing.');
}
```

Here is how API for messages will look:

```ts title="./index.ts"
app.get(`${ADMIN_BASE_URL}/api/translations/`, 
  async (req, res) => {
    const lang = req.query.lang as string;
    const messages = await admin.getPluginByClassName<I18nPlugin>('I18nPlugin').getCategoryTranslations('seoApp', lang);
    res.json(messages);
  }
);
```

Also in `nuxt.config.ts` you can set `prefix_except_default` strategy and put it in `i18n` config as this:

```
  ...
  i18n: {
    locales: ['en', 'uk', 'ja', 'fr'],
    defaultLocale: 'en',
    strategy: 'prefix_except_default',
    detectBrowserLanguage: false,
  },
  ...
```

#### Feeding messages during build time

For Dockerized pipelines you can feed messages when building the image in Docker build time:

```dockerfile
FROM node:22-alpine
WORKDIR /app
ADD package.json /app
ADD package-lock.json /app
RUN true | npm ci
ADD . /app
RUN --mount=type=cache,target=/app/node_modules/.cache true | npm run build

//diff-add
# Run i18n extraction and API call
//diff-add
RUN npm run i18n:extract && \
//diff-add
    curl -X POST -H 'Content-Type: application/json' -d @i18n-messages.json http://adminforth:3000/bo/api/feed-nuxt-strings

CMD ["node", ".output/server/index.mjs"]
EXPOSE 3000
```

This assumes that `http://adminforth:3000/` is the name of the Docker service running AdminForth. 

This will work if you are building the image in the same Docker network as AdminForth. Otherwise you might need use absolute URL of the AdminForth instance.

> 👆 The example method is just a stub, please make sure you not expose endpoint to public or add some simple authorization on it,
> otherwise someone might flood you with dump translations requests.

### Get language names

Also you can use handy method to get language names in native and English form with emoji flags:

```typescript title="./api.ts"
const languages = await admin.getPluginByClassName<I18nPlugin>('I18nPlugin').languagesList();
```

Response will look like this:

```
  "languages": [
    {
        "code": "en",
        "nameOnNative": "English",
        "nameEnglish": "English",
        "emojiFlag": "🇺🇸",
        "svgFlagB64": "data:image/svg+xml;base64,..."
    },
    {
        "code": "uk",
        "nameOnNative": "Українська",
        "nameEnglish": "Ukrainian",
        "emojiFlag": "🇺🇦",
        "svgFlagB64": "data:image/svg+xml;base64...
    },
    {
        "code": "ja",
        "nameOnNative": "日本語",
        "nameEnglish": "Japanese",
        "emojiFlag": "🇯🇵",
        "svgFlagB64": "data:image/svg+xml;base64..."
    },
  ]
```

### Disable translation for admin (external app only)

If you want to use this plugin only for external app, and not backoffice, which is probably the case, you can disable translation for admin by setting `externalAppOnly` to `true`:

```ts title="./resources/translations.ts"
    new I18nPlugin({
    //diff-add
      externalAppOnly: true,
      supportedLanguages: ['en', 'uk', 'ja', 'fr'],
      ...
    }),
```

---

## OAuth Authentication


The OAuth plugin enables OAuth2 sign-in and connected external accounts in AdminForth. Users can sign in with Google, GitHub, Facebook, Telegram, or another OAuth2 provider. Logged-in users can also connect additional provider accounts from **Settings -> Connected Accounts**.

OAuth should be configured with an external identities resource. That resource stores stable provider identity data (`provider`, `subject`) and optional profile fields. Agent chat surfaces use the same connected accounts to resolve Telegram, Slack, Teams, or other external chat users.

:::warning
Using OAuth without `externalIdentityResource` is deprecated. Configure an external identities resource for new projects.
:::

## Installation

Install the plugin and at least one OAuth adapter:

```bash
pnpm add @adminforth/oauth --save
pnpm add @adminforth/oauth-adapter-google --save
```

If you want Agent chat surfaces, install the OAuth adapter for the same provider as the chat surface. For example, Telegram chat surface support requires both:

```bash
pnpm add @adminforth/chat-surface-adapter-telegram --save
pnpm add @adminforth/oauth-adapter-telegram --save
```

## External Identities Resource

Create a resource that stores connected OAuth accounts. The default field names are:

- `adminUserId` — links the external identity to the AdminForth user
- `provider` — adapter class name, for example `AdminForthAdapterGoogleOauth2`
- `subject` — stable provider account id
- `externalUserId` — chat-specific user id, such as Telegram ID, Slack ID, or Teams ID

The defaults can be overridden in plugin options when your schema uses different field names.

### Migration example (Prisma)

If you're using Prisma, add the model to your `schema.prisma`:

```prisma title="./schema.prisma"
model AdminUserExternalIdentity {
  id             String   @id @default(uuid())
  adminUserId    String
  provider       String
  subject        String
  externalUserId String?
  email          String?
  phone          String?
  fullName       String?
  avatarUrl      String?
  meta           Json?
  createdAt      DateTime @default(now())

  @@unique([provider, subject])
  @@index([adminUserId])
}
```

Then create and apply the migration (example commands from `dev-demo`):

```bash
pnpm makemigration --name add-admin-user-external-identities ; pnpm migrate:local
```

```ts title="./resources/adminUserExternalIdentities.ts"
import { AdminForthDataTypes, type AdminForthResourceInput } from 'adminforth';
import { randomUUID } from 'crypto';

export default {
  dataSource: 'maindb',
  table: 'AdminUserExternalIdentity',
  resourceId: 'admin_user_external_identities',
  label: 'Admin User External Identities',
  columns: [
    {
      name: 'id',
      type: AdminForthDataTypes.STRING,
      primaryKey: true,
      fillOnCreate: () => randomUUID(),
      showIn: { create: false, edit: false },
    },
    { name: 'adminUserId', type: AdminForthDataTypes.STRING, required: true },
    { name: 'provider', type: AdminForthDataTypes.STRING, required: true },
    { name: 'subject', type: AdminForthDataTypes.STRING, required: true },
    { name: 'externalUserId', type: AdminForthDataTypes.STRING },
    { name: 'email', type: AdminForthDataTypes.STRING },
    { name: 'phone', type: AdminForthDataTypes.STRING },
    { name: 'fullName', type: AdminForthDataTypes.STRING },
    { name: 'avatarUrl', type: AdminForthDataTypes.STRING },
    { name: 'meta', type: AdminForthDataTypes.JSON },
    {
      name: 'createdAt',
      type: AdminForthDataTypes.DATETIME,
      fillOnCreate: () => new Date().toISOString(),
      showIn: { create: false, edit: false },
    },
  ],
} satisfies AdminForthResourceInput;
```

Then register the resource in `index.ts`:

```ts title="./index.ts"
//diff-add
import adminUserExternalIdentitiesResource from "./resources/adminUserExternalIdentities";

... new AdminForth({
  dataSources: [...],
    ...
  resources: [
    apartmentsResource,
    usersResource,
//diff-add
    adminUserExternalIdentitiesResource,
  ],
    ...
})
```

## Configuration

This example configures Google OAuth. See [OAuth2 Providers](#oauth2-providers) for provider setup details.

```typescript title="./resources/adminuser.ts"
import OAuthPlugin from '@adminforth/oauth';
import AdminForthAdapterGoogleOauth2 from '@adminforth/oauth-adapter-google';

plugins: [
  new OAuthPlugin({
    emailField: 'email',
    externalIdentityResource: {
      resourceId: 'admin_user_external_identities',
      emailField: 'email',
      phoneField: 'phone',
      fullNameField: 'fullName',
      avatarUrlField: 'avatarUrl',
      metaField: 'meta',
    },
    adapters: [
      new AdminForthAdapterGoogleOauth2({
        clientID: process.env.GOOGLE_CLIENT_ID as string,
        clientSecret: process.env.GOOGLE_CLIENT_SECRET as string,
      }),
    ],
  }),
]
```

`adminUserIdField`, `providerField`, `subjectField`, and `externalUserIdField` default to `adminUserId`, `provider`, `subject`, and `externalUserId`. Configure them only when your resource uses different field names.

### Google Provider Setup

1. Go to the [Google Cloud Console](https://console.cloud.google.com) and log in.
2. Create a new project or select an existing one.
3. Go to `APIs & Services` -> `Credentials`.
4. Create credentials for OAuth 2.0 client IDs.
5. Select application type: "Web application".
6. Add your application's name and redirect URI.
7. In "Authorized redirect URIs", add `https://your-domain/oauth/callback` (for production) and `http://localhost:3500/oauth/callback`(for local, where 3500 - is your app port). Include `baseUrl` when your AdminForth app uses it, for example `https://your-domain/base/oauth/callback`.
8. Add the credentials to your `.env` file:

```bash
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
```

## Connected Accounts

When `externalIdentityResource` is configured, AdminForth adds **Connected Accounts** to the user settings menu. A logged-in user can connect additional external accounts there. This is also how Agent chat surfaces identify external users: for example, a Telegram bot message is matched to the AdminForth user through the Telegram OAuth identity stored in the external identities resource.

## Email Confirmation

The plugin supports automatic email confirmation for OAuth users. To enable this:

1. Add the `email_confirmed` field to your database schema:

```prisma title='./schema.prisma'
model adminuser {
  // ... existing fields ...
  email_confirmed Boolean @default(false)
}
```

2. Run the migration:

```bash
pnpm makemigration --name add-email-confirmed-to-adminuser ; pnpm migrate:local
```

3. Configure the plugin with `emailConfirmedField`:

```typescript title="./resources/adminuser.ts"
new OAuthPlugin({
  // ... adapters configuration ...
  emailField: 'email',
  emailConfirmedField: 'email_confirmed'  // Enable email confirmation tracking
}),
```

When using OAuth:
- New users will have their email automatically confirmed (`email_confirmed = true`)
- Existing users will have their email marked as confirmed upon successful OAuth login
- The `email_confirmed` field must be a boolean type

## Open Signup

By default, users must exist in the system before they can log in with OAuth. You can enable automatic user creation for new OAuth users with the `openSignup` option:

```typescript title="./resources/adminuser.ts"
new OAuthPlugin({
  // ... adapters configuration ...
  openSignup: {
    enabled: true,
    defaultFieldValues: { // Set default values for new users
      role: 'user',
    },
  },
}),
```

## UI Customization

You can customize the UI of the OAuth login buttons by using the `iconOnly` and `pill` options.

```typescript title="./resources/adminuser.ts"
new OAuthPlugin({
  // ... adapters configuration ...
  iconOnly: true, // Show only provider icons without text
  pill: true, // Use pill-shaped buttons instead of rectangular
}),
```

## OAuth2 Providers

### Facebook Adapter

Install Adapter:

```
pnpm add @adminforth/oauth-adapter-facebook --save
```

1. Go to the [Facebook Developers](https://developers.facebook.com/)
2. Go to `My apps`
3. Create a new project or select an existing one (choose Authenticate and request data from users with Facebook Login)
4. Go to `Use Cases` - `Authenticate and request data from users with Facebook Login` -> `Customize` and add email permissions 
5. Go to `App Settings` -> `Basic`
6. Get App ID and App secret
7. Add the credentials to your `.env` file:

```bash
FACEBOOK_CLIENT_ID=your_facebook_client_id
FACEBOOK_CLIENT_SECRET=your_facebook_client_secret
```

Add the adapter to your plugin configuration:

```typescript title="./resources/adminuser.ts"
import AdminForthAdapterFacebookOauth2 from '@adminforth/oauth-adapter-facebook';

// ... existing resource configuration ...
plugins: [
  new OAuthPlugin({
    adapters: [
      ...
      new AdminForthAdapte# OAuth AuthenticationrFacebookOauth2({
        clientID: process.env.FACEBOOK_CLIENT_ID,
        clientSecret: process.env.FACEBOOK_CLIENT_SECRET,
      }),
    ],
  }),
]
```

### GitHub Adapter

Install Adapter:

```
pnpm add @adminforth/oauth-adapter-github --save
```

1. Go to the [GitHub Apps](https://github.com/settings/apps)
2. Create a new app or select an existing one
3. Go to the `Permisiions & events` -> `Account permissions` -> `Email addresses` and change to `Read-only`
3. Go to the `General` and click to `Generate a new client secret` button and copy secret
4. Add the credentials to your `.env` file:

```bash
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret
```

Add the adapter to your plugin configuration:

```typescript title="./resources/adminuser.ts"
import AdminForthAdapterGithubOauth2 from '@adminforth/oauth-adapter-github';

// ... existing resource configuration ...
plugins: [
  new OAuthPlugin({
    adapters: [
      ...
      new AdminForthAdapterGithubOauth2({
        clientID: process.env.GITHUB_CLIENT_ID,
        clientSecret: process.env.GITHUB_CLIENT_SECRET,
      }),
    ],
  }),
]
```

### Telegram Adapter

Install Adapter:

```
pnpm add @adminforth/oauth-adapter-telegram --save
```

Create Telegram OpenID Connect credentials in BotFather:

1. Open [BotFather](https://t.me/BotFather).
2. Click **Open** and open it in the Telegram app.
3. Select or Create your bot.
4. Open **Login Widget**.
5. Click **Switch to OpenID Connect Login**.
6. Copy the client ID and client secret shown at the top.
7. Set **Redirect URI** to `https://example.com/oauth/callback`.

Add the credentials to your `.env` file:

```bash
TELEGRAM_CLIENT_ID=your_telegram_client_id
TELEGRAM_CLIENT_SECRET=your_telegram_client_secret
```

Add the adapter to your plugin configuration:

```typescript title="./resources/adminuser.ts"
import AdminForthAdapterTelegramOauth2 from '@adminforth/oauth-adapter-telegram';

// ... existing resource configuration ...
plugins: [
  new OAuthPlugin({
    adapters: [
      ...
      new TelegramOauthAdapter({
        clientID: process.env.TELEGRAM_CLIENT_ID as string,
        clientSecret: process.env.TELEGRAM_CLIENT_SECRET as string,
        redirectUri: 'https://example.com/oauth/callback',
        scopes: ['openid', 'profile', 'phone'],
      }),
    ],
  }),
]
```

Register the same `redirectUri` in BotFather under **Login Widget → Redirect URI**.

If you use `@adminforth/chat-surface-adapter-telegram`, users must connect Telegram from **Settings → Connected Accounts** before the Telegram bot can identify them.

### Keycloak Adapter

Install Adapter:

```
pnpm add @adminforth/oauth-adapter-keycloak --save
```

If you need a basic Keycloak setup which tested with AdminForth, you can follow [this minimal KeyClock setup example](/blog/keycloak-setup-example).

1. Update your `.env` file with the following Keycloak configuration:

```bash
KEYCLOAK_CLIENT_ID=your_keycloak_client_id
KEYCLOAK_CLIENT_SECRET=your_keycloak_client_secret
KEYCLOAK_URL=http://localhost:8080
KEYCLOAK_REALM=your_keycloak_realm
```

2. Add the adapter to your plugin configuration:

```typescript title="./resources/adminuser.ts"
import AdminForthAdapterKeycloakOauth2 from '@adminforth/oauth-adapter-keycloak';

// ... existing resource configuration ...
plugins: [
  new OAuthPlugin({
    adapters: [
      ...
      new AdminForthAdapterKeycloakOauth2({
          name: "Keycloak",
          clientID: process.env.KEYCLOAK_CLIENT_ID,
          clientSecret: process.env.KEYCLOAK_CLIENT_SECRET,
          keycloakUrl: process.env.KEYCLOAK_URL,
          realm: process.env.KEYCLOAK_REALM,
          useOpenIdConnect: true,
      }),
    ],
  }),
]
```

### Microsoft Adapter

Install Adapter:

```
pnpm add @adminforth/oauth-adapter-microsoft --save
```

1. In the Microsoft [Azure Portal](https://portal.azure.com/), search for and click [App registrations](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade), then `New registration`.
2. Give your application a name. This name will be visible to your users.
3. Set the audience for the app to `Accounts in my organizational directory and personal Microsoft accounts`. This allows your user to log in using any Microsoft account.
5. Set the Redirect URI platform to Web and enter your project's redirect URI.
6. Go to your app and search `API permissions`, click `Add a permission`, select `Microsoft Graph`, select `Delegated permissions`, enable permissions: `offline_access`, `openid`, `profile`, `User.Read`, click `Add permissions`.
7. Serch `Certificates & secrets`, click `New client secret` and create client secret.
6. Get Application ID and Client Secret.
7. Add the credentials to your `.env` file:

```bash
MICROSOFT_CLIENT_ID=your_application_id
MICROSOFT_CLIENT_SECRET=your_microsoft_client_secret
```

Add the adapter to your plugin configuration:

```typescript title="./resources/adminuser.ts"
import AdminForthAdapterMicrosoftOauth2 from '@adminforth/oauth-adapter-microsoft';

// ... existing resource configuration ...
plugins: [
  new OAuthPlugin({
    adapters: [
      ...
      new AdminForthAdapterMicrosoftOauth2({
        clientID: process.env.MICROSOFT_CLIENT_ID,
        clientSecret: process.env.MICROSOFT_CLIENT_SECRET,
        useOpenIdConnect: true,
      }),
    ],
  }),
]
```

### Twitch Adapter

Install Adapter:

```
pnpm add @adminforth/oauth-adapter-twitch --save
```

1. Go to the [Twitch dashboard](https://dev.twitch.tv/console/)
2. Create a new app or select an existing one
3. In `OAuth Redirect URLs` add `https://your-domain/oauth/callback` (`http://localhost:3500/oauth/callback`)
4. Go to the app and copy `Client ID`, click to `Generate a new client secret`(in Twitch this button can be used only once for some time, becouse of this dont lose it) button and copy secret .
5. Add the credentials to your `.env` file:

```bash
TWITCH_CLIENT_ID=your_twitch_client_id
TWITCH_CLIENT_SECRET=your_twitch_client_secret
```

Add the adapter to your plugin configuration:

```typescript title="./resources/adminuser.ts"
import AdminForthAdapterTwitchOauth2 from '@adminforth/oauth-adapter-twitch';

// ... existing resource configuration ...
plugins: [
  new OAuthPlugin({
    adapters: [
      ...
      new AdminForthAdapterTwitchOauth2({
        clientID: process.env.TWITCH_CLIENT_ID,
        clientSecret: process.env.TWITCH_CLIENT_SECRET,
      }),
    ],
  }),
]
```

### Clerk Adapter

Install Adapter:

```bash
pnpm add @adminforth/oauth-adapter-clerk --save
```

1. Go to the [Clerk Dashboard](https://dashboard.clerk.com) and open your application.
2. In the left sidebar, go to **Configure** → **Developers** → **OAuth Applications**.
3. Click **Add OAuth Application** and give it a name.
4. Copy the **Client Secret** from the OAuth application creation modal.
5. After copying, Clerk redirects you to the application page, where you can copy the **Client ID** and **Domain**.
6. Add the credentials to your `.env` file:
7. In **Redirect URLs**, add `https://your-domain/oauth/callback` and `http://localhost:3500/oauth/callback`. Include `baseUrl` when your AdminForth app uses it, for example `https://your-domain/base/oauth/callback`.
8. In **Scopes**, check the **openid** checkbox.

```bash
CLERK_CLIENT_ID=your_clerk_client_id
CLERK_CLIENT_SECRET=your_clerk_client_secret
CLERK_DOMAIN=https://your-app.clerk.accounts.dev
```

Add the adapter to your plugin configuration:

```typescript title="./resources/adminuser.ts"
import AdminForthAdapterClerkOauth2 from '@adminforth/oauth-adapter-clerk';

// ... existing resource configuration ...
plugins: [
  new OAuthPlugin({
    adapters: [
      ...
      new AdminForthAdapterClerkOauth2({
        clientID: process.env.CLERK_CLIENT_ID as string,
        clientSecret: process.env.CLERK_CLIENT_SECRET as string,
        domain: process.env.CLERK_DOMAIN as string,
      }),
    ],
  }),
]
```

### Need custom provider?

Just fork any existing adapter e.g. [Google](https://github.com/devforth/adminforth-oauth-adapter-google) and adjust it to your needs. 

This is really easy, you have to change less then 10 lines of code in this [file](https://github.com/devforth/adminforth-oauth-adapter-google/blob/main/index.ts)

Then just publish it to npm and install it in your project.

Links to adapters:
[Google](https://github.com/devforth/adminforth-oauth-adapter-google)
[GitHub](https://github.com/devforth/adminforth-oauth-adapter-github)
[Facebook](https://github.com/devforth/adminforth-oauth-adapter-facebook)
[Keycloak](https://github.com/devforth/adminforth-oauth-adapter-keycloak)

## Starting OAuth flow from an external page

If you have an external website with a "Sign in" button that should open the AdminForth OAuth flow directly — without showing the login form first — use the `start_oauth` query parameter:

```
https://your-admin.example.com/login?start_oauth=google
https://your-admin.example.com/login?start_oauth=clerk
```

The value must match the provider name (case-insensitive). AdminForth will immediately redirect the user to the OAuth provider, skipping the login page entirely.

The provider name is derived from the adapter class name — for example `AdminForthAdapterOauth2Google` → `google`, `AdminForthAdapterOauth2Clerk` → `clerk`.

If the specified provider is not found, an error toast is shown on the login page. If `start_oauth` is provided without a value (`?start_oauth`), nothing happens and the regular login form is displayed.

## Fill user full name

If you have a fullName field in your users resource, you can add it to the plugin setup:

```ts

plugins: [
  ...

  new OAuthPlugin({

    ...

    userFullNameField: 'fullName'

    ...

  }),
]

```

This field will be automatically filled with the name that the provider returns, if this field was empty.

> ☝️Not all providers return full name or even if they do, there is no guarantee that they will be correct

> Google Adapter: returns fullName, but if there is no last name - it will return only first name

>Facebook: returns fullName

>Github: returns name or fullName (depends of what user added in name field)

>Keycloak: returns fullName

>Microsoft: returns fullName

>Twitch: return only users display name

## Automatically save users avatar

If you want to automatically upload users avatar from the provider, you can use userAvatarField prop.

Example:

First of all you'll need to create avatar field in your database:

Update schema prisma file:

``` title="./schema.prisma"

model adminuser {
  id            String     @id
  email         String     @unique
  password_hash String
  role          String
  created_at    DateTime
  //diff-add
  avatar        String 
}

```

And make migration:

```bash
pnpm makemigration --name add-avatar-field ; pnpm migrate:local
```

Then add this field to users resource and install upload plugin:

```ts title="./resources/adminuser"
//diff-add
import UploadPlugin from '@adminforth/upload';

...

columns: [

  ...
    //diff-add
    {
      //diff-add
      name: "avatar",
      //diff-add
      type: AdminForthDataTypes.STRING,
      //diff-add
      showIn: {
        //diff-add
        list: true,
        //diff-add
        show: true
        //diff-add
      },
      //diff-add
    },

  ...

],

  ...

plugins: [

  ...

  //diff-add
  new UploadPlugin({
      //diff-add
    pathColumnName: "avatar",
      //diff-add
    storageAdapter: new AdminForthAdapterS3Storage({
      //diff-add
      bucket: process.env.AWS_BUCKET_NAME,
      //diff-add
      region: process.env.AWS_REGION,
      //diff-add
      accessKeyId: process.env.AWS_ACCESS_KEY_ID as string,
      //diff-add
      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY as string,
      //diff-add
    }),
    //diff-add
    allowedFileExtensions: [
      //diff-add
      "jpg",
      //diff-add
      "jpeg",
      //diff-add
      "png",
      //diff-add
      "gif",
      //diff-add
      "webm",
      //diff-add
      "exe",
      //diff-add
      "webp",
      //diff-add
    ],
    //diff-add
    maxFileSize: 1024 * 1024 * 20, // 20MB
    //diff-add
    filePath: ({ originalFilename, originalExtension, contentType, record }) => {
      //diff-add
      return `aparts/${new Date().getFullYear()}/${originalFilename}.${originalExtension}`
      //diff-add
    },
    //diff-add
    preview: {
      //diff-add
      maxWidth: "200px",
      //diff-add
    },
    //diff-add
  }),

  ...

]

...

```

Then update your plugin setup:

```ts title="./resources/adminuser.ts"

...

plugins: [

  ...

  new OAuthPlugin({
    //diff-add
    userAvatarField: "avatar",

    ...

  })

  ...

]

...

```

And finally add this callback:

```ts title="./index.ts"

  auth: {

    ...
    //diff-add
    avatarUrl: async (adminUser)=>{
      //diff-add
      const plugin = admin.getPluginsByClassName('UploadPlugin').find(p => p.pluginOptions.pathColumnName === 'avatar') as any; 
      //diff-add
      if (!plugin) {
        //diff-add
        throw new Error('Upload plugin for avatar not found');
        //diff-add
      }
      //diff-add
      if (adminUser.dbUser.avatar === null || adminUser.dbUser.avatar === undefined || adminUser.dbUser.avatar === '') {
        //diff-add
        return undefined;
        //diff-add
      }
      //diff-add
      const imageUrl = await plugin.getFileDownloadUrl(adminUser.dbUser.avatar || '', 3600);
      //diff-add
      return imageUrl;
      //diff-add
    },

    ...

  }

```

---

## Inline Create


The Inline Create plugin enables inline create in AdminForth, allowing users to create records directly in the list view.

## Installation

To install the plugin:

```bash
pnpm add @adminforth/inline-create --save
```

### Usage

Configure the plugin in your apartments resource file:

```typescript title="./resources/apartments.ts"
import InlineCreatePlugin from '@adminforth/inline-create';

// ... existing resource configuration ...

plugins: [
  new InlineCreatePlugin({}),
]
```

Here is how it looks:

![alt text](localhost_3000_resource_providers.png)

---

## List In-Place Edit

# List in place edit

The List in Place Edit plugin allows you to edit records directly in the list view.

## Usage

First, install the plugin:

```bash
pnpm add @adminforth/list-in-place-edit --save
```

Import plugin:

```ts title="./resources/apartments.ts"
import ListInPlaceEditPlugin from "@adminforth/list-in-place-edit";
```

Now instantiate the plugin and add it to the configuration:

```ts title="./resources/apartments.ts"

{
  ...
  plugins: [
    new ListInPlaceEditPlugin({
      columns: ["title", "description"],
    }),
  ],
}
```

Here is how it looks:

![alt text](list-in-place.png)

---

## Text Complete


This plugin allows you to auto-complete text and string fields using OpenAI GPT models via the Responses API.

## Installation

```
pnpm add @adminforth/text-complete --save
pnpm add @adminforth/completion-adapter-openai-responses --save
```

Go to https://platform.openai.com/, open `Dashboard` -> `API keys` -> `Create new secret key`. Paste value in your `.env` file:

```env title=.env
...
OPENAI_API_KEY=your_key
```

Add plugin installation to any text or string column.

For example let's add it for title and description in `aparts` resource configuration which we created in [Getting Started](../001-gettingStarted.md) tutorial.

```ts title="./resources/apartments.ts"
//diff-add
import TextCompletePlugin from '@adminforth/text-complete';
//diff-add
import CompletionAdapterOpenAIResponses from "@adminforth/completion-adapter-openai-responses";

export const admin = new AdminForth({
  ...
  resourceId: 'aparts',
  columns: [
    ...
  ],
  plugins: [
    ...
//diff-add
    new TextCompletePlugin({
//diff-add
      fieldName: 'title',
//diff-add
      adapter: new CompletionAdapterOpenAIResponses({
//diff-add
        openAiApiKey: process.env.OPENAI_API_KEY as string,
//diff-add
        model: 'gpt-5-nano', // default "gpt-5-nano"
//diff-add
        extraRequestBodyParameters: {
//diff-add
            temperature: 0.7 //Model temperature
//diff-add
        }
//diff-add
      }),
//diff-add
    }),
//diff-add
    new TextCompletePlugin({
//diff-add
      fieldName: 'description',
//diff-add
      adapter: new CompletionAdapterOpenAIResponses({
//diff-add
        openAiApiKey: process.env.OPENAI_API_KEY as string,
//diff-add
      }),
//diff-add
      // expert: {
//diff-add
        // maxTokens: 50, // token limit to generate for each completion. 50 is default
//diff-add
        // promptInputLimit: 500, // Limit in characters of edited field to be passed to Model. 500 is default value
//diff-add
        // debounceTime: 300, // Debounce time in milliseconds. 300 is default value
//diff-add
      // }
//diff-add
    }),

  ]

  ...

});
```

Here is how it looks:

!![alt text](dashboard_test2.gif)

## Initial prompt

If you want to generate field by your own prompt, you can use `initialPrompt` property in plugin configuration.

```ts title="./resources/apartments.ts"
    new TextCompletePlugin({
      fieldName: 'description',
//diff-add
      initialPrompt: `I need to introduce apartment '{{title}}' to people who have a pets and afraid that apartment is not pet friendly. I need short but very attractive description if it. It should have CTAs and Emojis. write \n\n once you are done.`,
//diff-add
      expert: {
//diff-add
        stop: ['\n\n'],
//diff-add
        maxTokens: 500,
//diff-add
      },
    }),
```

> **Note:** `{{title}}` is a placeholder for the value of the field `title`. It will be replaced with the actual value of the field when generating the prompt. You can use any field name from your resource configuration.
> **Note:** `stop` is a property of the model that tells it when to stop generating text. In this case, we are telling it to stop when it sees `\n\n`.

---

## Foreign Inline Show

Allows to add an inline show of connected foreign resource records on a adminforth show page.

Foreign inline show plugin allows to display a show of items from a foreign table in the show view.

## Usage

Import plugin:

```bash
pnpm add @adminforth/foreign-inline-show --save
```

```ts title="./resources/apartments.ts"
import { AdminForthDataTypes, AdminForthResourceInput } from 'adminforth';
import ForeignInlineShowPlugin from '@adminforth/foreign-inline-show';
```

In [Getting Started](<../001-gettingStarted.md>) we created a `'aparts'` resource which has a field `'realtor_id'`.
This field refers to record from `'adminuser'` resource. To remind you, we configured this relation using `foreignResource` setting in the column configuration:

```typescript title="./resources/apartments.ts"
// 
export default {
  resourceId: 'aparts',
  ...
  columns: [
    ...
    {
      name: 'realtor_id',
      foreignResource: {
        resourceId: 'adminuser',  // this means that aparts.realtor_id refers to primary key of 'adminuser' resource
                              // this is Many-To-One relatin: many aparts can refer to one user
      }
    }
  ],
}
```

This means that we can display a show of user in the apartments show view.

Add to your `'apartments'` resource configuration the plugin instance:

```ts title="./resources/apartments.ts"
{ 
    ...
    resourceId: 'aparts',
    ...
//diff-add
    plugins: [
//diff-add
      new ForeignInlineShowPlugin({
//diff-add
        foreignResourceId: 'adminuser',
//diff-add
      }),
//diff-add
    ],
}
```

![alt text](ForeignInlineShow.png)

> 👆 To make plugin work, the specified resource (defined with `foreignResourceId`) should have one (and only one) column that refers to the current resource on which you add a plugin.
> In our case we add plugin to `adminuser` resource, so the `aparts` resource should have one column with `foreignResource.resourceId` equal to `adminuser` resourceId.

---

## Email Invite


Email Invite plugin allows administrators to create users without setting passwords. Instead, the plugin sends an email invitation to the newly created user, asking them to set their own password. This is more secure and user-friendly than having administrators set passwords for users.

## Installation

To install the plugin:

```bash
pnpm add @adminforth/email-invite --save
```

You'll also need an email adapter. For AWS SES:

```bash
pnpm add @adminforth/email-adapter-aws-ses --save
```

## SES

To Setup SES, you need to have an AWS account and SES service enabled. You can follow the steps below to setup SES.

1. Go to the AWS Management Console and open the Amazon SES console at [https://console.aws.amazon.com/ses/](https://console.aws.amazon.com/ses/).
2. Make sure you are in the correct region. You can change the region from the top right corner. For example, if you are in the `us-east-1` region, you can see the region name US East (N. Virginia) in the top right corner.

3. Add your email address (any email), and verify it.
4. Add some domain you own and verify it by creating DNS records which AWS suggests. This will be used as the domain for sending emails. e.g. if you want to send from no-reply@devforth.io you need to verify `devforth.io`. 

## Basic Usage

```typescript title="./resources/adminuser.ts"
import EmailInvitePlugin from '@adminforth/email-invite';
import EmailAdapterAwsSes from '@adminforth/email-adapter-aws-ses';
import { logger } from 'adminforth'

export default {
  dataSource: 'maindb',
  table: 'adminuser',
  resourceId: 'adminuser',
  columns: [
    { name: 'id', primaryKey: true },
    { name: 'email', required: true },
    { name: 'password_hash', showIn: [] }, // Hide from UI

    { name: 'role' },

    {
          name: 'password',
          virtual: true,
          required: { create: true },
          editingNote: { edit: 'Leave empty to keep password unchanged' },
          minLength: 8,
          type: AdminForthDataTypes.STRING,
          showIn: {
// hide password column - but don't remove whole column it because it has constrains for password field!
// diff-remove
            show: false,
// diff-remove
            list: false,
// diff-remove
            filter: false,
// diff-add
            all: false,
          },
          masked: true,
        },

    // ... other columns
  ],
  hooks: {
    create: {
      beforeSave: async ({ record, adminUser, resource }: { record: any, adminUser: AdminUser, resource: AdminForthResource }) => {
// since we don't show password input in resource - no sense to hande it in hook anymore!       
//diff-remove   
          record.password_hash = await AdminForth.Utils.generatePasswordHash(record.password);
          return { ok: true };
        }
    },
    edit: {
      beforeSave: async ({ oldRecord, updates, adminUser, resource }: { oldRecord: any, updates: any, adminUser: AdminUser, resource: AdminForthResource }) => {
        logger.info('Updating user', updates);
        if (oldRecord.id === adminUser.dbUser.id && updates.role) {
          return { ok: false, error: 'You cannot change your own role' };
        }
// also no sense to have updatres - we dont allow edit password by admin anymore
//diff-remove  
        if (updates.password) {
//diff-remove  
          updates.password_hash = await AdminForth.Utils.generatePasswordHash(updates.password);
//diff-remove  
        }
        return { ok: true }
      },
    },
  },
  plugins: [
    //diff-add
    new EmailInvitePlugin({
     //diff-add
      emailField: 'email',
     //diff-add
      passwordField: 'password',
     //diff-add
      sendFrom: 'noreply@yourapp.com',
     //diff-add
      adapter: new EmailAdapterAwsSes({
     //diff-add
        region: 'us-east-1',
     //diff-add
        accessKeyId: process.env.AWS_ACCESS_KEY_ID,
     //diff-add
        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
     //diff-add
      }),
     //diff-add
    }),
  ],
};
```

Please note that previously (in defauklt CLI setup) we needed it to allow admins to set passwords when created new users (to invite them). Also Admens were able to edit passwords of users.
Now since we added this plugin, user will have email link on which he will get form to enter password by hiumself.
Please note that the form for user will still use constraints from password virtual field, that is why we just hid it using showIn - not remove it.

To allow users to edit their passwords please use [email password reset plugin](https://adminforth.dev/docs/tutorial/Plugins/email-password-reset/)

## Email Confirmation boolean flag

This plugin can write into the database the fact that invited user was able to set password and as a result confirmed that he owns his email.
To enable email this behaviour, first add a boolean field to your user table:

```prisma title="./schema.prisma"
model adminuser {
  id             String   @id @default(cuid())
  email          String   @unique
  password_hash  String
  role           String   @default("user")
  //diff-add
  email_confirmed Boolean? @default(false)
  // ... other fields
}
```

Run the migration:

```bash
pnpm makemigration --name add-email-confirmed ; pnpm migrate:local
```

Then update your resource configuration:

```typescript title="./resources/adminuser.ts"
export default {
  // ... existing config
  columns: [
    { name: 'id', primaryKey: true },
    { name: 'email', required: true },
    { name: 'password_hash', showIn: [] },
    { name: 'role' },
    //diff-add
    { name: 'email_confirmed', type: AdminForthDataTypes.BOOLEAN },
    // ... other columns
  ],
  plugins: [
    new EmailInvitePlugin({
      emailField: 'email',
      sendFrom: 'noreply@yourapp.com',
      passwordField: 'password',
      adapter: new EmailAdapterAwsSes(/* ... */),
      //diff-add
      emailConfirmedField: 'email_confirmed', // Enable email confirmation
    }),
  ],
};
```

## Mailgun usage example
If you want to use this plugin with Mailgun, first install it:

```bash
pnpm add @adminforth/email-adapter-mailgun
```

Then, in the adapter options, add:

``` ts
//diff-add
import EmailAdapterMailgun from "@adminforth/email-adapter-mailgun";
 
...

  plugins: [
    new EmailInvitePlugin({
      emailField: 'email',
      passwordField: 'password',
      sendFrom: 'noreply@yourapp.com',
      //diff-add
      adapter: new EmailAdapterMailgun({
      //diff-add
        apiKey: process.env.MAILGUN_API_KEY as string,
      //diff-add
        domain: process.env.MAILGUN_DOMAIN as string,
      //diff-add
        baseUrl: process.env.MAILGUN_REGION_URL as string,
      //diff-add
      }),
    }),
  ],

```

---

## Bulk AI Flow


This plugin allows filling fields in multiple selected records based on data from other fields using LLM.
This also supports vision tasks so you can ask it to e.g. detect dominant color on image or describe what is on the image. Plugin supports classification to enum options automatically.

## Installation

To install the plugin:

```bash
pnpm add @adminforth/bulk-ai-flow --save
```

You'll also need an image vision adapter:

```bash
pnpm add @adminforth/image-vision-adapter-openai --save
```

## Vision mode

This mode covers next generations:

```
- Image(one or many fields) -> to -> Text/Number/Enum/Boolean(one or many fields)
- Image(one or many fields) + Text/Number/Enum/Boolean(one or many fields) -> to -> Text/Number/Enum/Boolean(one or many fields)
```

Lets try both. Add a column for storing the URL or path to the image in the database, add this statement to the `./schema.prisma`:

```ts title="./schema.prisma"
model apartments {
  id                String     @id
  created_at        DateTime?
  title             String
  square_meter      Float?
  price             Decimal
  number_of_rooms   Int?
  description       String?
  country           String?
  listed            Boolean
  realtor_id        String?
//diff-add
  apartment_image   String?
}
```

Migrate prisma schema:

```bash
pnpm makemigration --name add-apartment-image-url ; pnpm migrate:local
```

We will also attach [upload plugin](/docs/tutorial/Plugins/upload/) to this field.

Add credentials in your `.env` file:
```ts title=".env"
...

//diff-add
OPENAI_API_KEY=your_secret_openai_key

...
```

Add column to `aparts` resource configuration:

```ts title="./resources/apartments.ts"
//diff-add
import BulkAiFlowPlugin  from '@adminforth/bulk-ai-flow';
//diff-add
import AdminForthImageVisionAdapterOpenAi from '@adminforth/image-vision-adapter-openai';
//diff-add
import UploadPlugin from '@adminforth/upload';
//diff-add
import { randomUUID } from 'crypto';
//diff-add
import AdminForthAdapterS3Storage from '@adminforth/storage-adapter-amazon-s3'

export const admin = new AdminForth({
  ...
  resourceId: 'aparts',
  columns: [
    ...
//diff-add
    {
//diff-add
        name: 'apartment_image',
//diff-add
        label: 'Image',
//diff-add
        showIn: { list: false, create: true, edit: true},
//diff-add
    }
    ...
  ],
  plugins: [
    ...
  //diff-add
      new UploadPlugin({
  //diff-add
        storageAdapter: new AdminForthAdapterS3Storage({
  //diff-add
          bucket: process.env.AWS_BUCKET_NAME,
  //diff-add
          region: process.env.AWS_REGION,
  //diff-add
          accessKeyId: process.env.AWS_ACCESS_KEY_ID,
  //diff-add
          secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
  //diff-add
          s3ACL: 'public-read',
  //diff-add
        }),
  //diff-add
        pathColumnName: 'apartment_image',
  //diff-add
        allowedFileExtensions: ['jpg', 'jpeg', 'png', 'gif', 'webm', 'webp'],
  //diff-add
        filePath: ({originalFilename, originalExtension, contentType}) => 
  //diff-add
              `aparts/${new Date().getFullYear()}/${randomUUID()}-${originalFilename}.${originalExtension}`,
  //diff-add
      }),

      //diff-add
      new BulkAiFlowPlugin({
      //diff-add
        actionName: 'Analyze',
      //diff-add
        attachFiles: async ({ record }: { record: any }) => {
      //diff-add
        if (!record.apartment_image) {
      //diff-add
          return [];
      //diff-add
        }
      //diff-add
          return [`https://tmpbucket-adminforth.s3.eu-central-1.amazonaws.com/${record.apartment_image}`];
      //diff-add
        },
      //diff-add
        visionAdapter: new AdminForthImageVisionAdapterOpenAi(
      //diff-add
          {
      //diff-add
            openAiApiKey:  process.env.OPENAI_API_KEY as string,
      //diff-add
            model: 'gpt-5-mini',
      //diff-add
          }
      //diff-add
        ),
      //diff-add
        fillFieldsFromImages: { 
      //diff-add
          'description': 'describe what is in the image, also take into account that price is {{price}}', 
      //diff-add
          'country': 'In which country it can be located?', 
      //diff-add
          'number_of_rooms': 'How many rooms are in the apartment? Just try to guess what is a typical one. If you do not know, just guess',
      //diff-add
          'square_meter': 'Try to guess what is the typical square of the apartment in square meters? If you do not know, just guess',
      //diff-add
          'listed': 'Is the apartment should be listed for sale? If you do not know, just guess, return boolean value',
      //diff-add
        },
      //diff-add
      }),
      //diff-add
    ],

  
  ...

});
```
> ⚠️ Make sure your attachFiles function returns a valid array of image URLs or an empty array. Returning anything else may cause an error.

## Usage
1. Select fields you want to fill
2. Click on the three dots menu
3. Click analyze 
![alt text](Bulk-vision-1.png)
4. Wait for finish analyze
5. Check and edit result
![alt text](Bulk-vision-2.png)
6. Save changhes
![alt text](Bulk-vision-3.png)

## Text-to-Text Processing
This is the most basic plugin usage. You can connect any text completion adapter to fill one or several string/number/boolean fields from other fields.

### Example: Translate Names to English
Normalize user names by translating them from any language to English for internal processing.

```ts
import CompletionAdapterOpenAIResponses from '@adminforth/completion-adapter-openai-responses';

// Add to your resource plugins array
new BulkAiFlowPlugin({
  actionName: 'Translate surnames',
  textCompleteAdapter: new CompletionAdapterOpenAIResponses({
    openAiApiKey: process.env.OPENAI_API_KEY as string,
    model: 'gpt-5-nano',
    extraRequestBodyParameters: {
      temperature: 0.7
    }
  }),
  fillPlainFields: {
    'full_name_en': 'Translate this name to English: {{users_full_name}}',
  },
}),
```

## Image-to-Text Analysis (Vision)
Analyze images and extract information to fill text, number, enum, or boolean fields.

### Example: Age Detection from Photos

```ts
import AdminForthImageVisionAdapterOpenAi from '@adminforth/image-vision-adapter-openai/index.js';

// Add to your resource plugins array
new BulkAiFlowPlugin({
  actionName: 'Guess age',
  visionAdapter: new AdminForthImageVisionAdapterOpenAi({
    openAiApiKey: process.env.OPENAI_API_KEY as string,
    model: 'gpt-5-mini',
  }),
  fillFieldsFromImages: { 
    'age': 'Analyze the image and estimate the age of the person. Return only a number.',
  },
  attachFiles: async ({ record }) => {
    if (!record.image_url) {
      return [];
    }
    return [`https://users-images.s3.eu-north-1.amazonaws.com/${record.image_url}`];
  },
}),
```

## Text-to-Image generation or image editing
Generate new images based on existing data and/or images using AI image generation adapters.

### Example: Creating Cartoon Avatars

```ts
import ImageGenerationAdapterOpenAI from '@adminforth/image-generation-adapter-openai/index.js';

// Add to your resource plugins array
new BulkAiFlowPlugin({
  actionName: 'Generate cartoon avatars',
  imageGenerationAdapter: new ImageGenerationAdapterOpenAI({
    openAiApiKey: process.env.OPENAI_API_KEY as string,
    model: 'gpt-image-1.5',
  }),
  attachFiles: async ({ record }) => {
    if (!record.user_photo) {
      return [];
    }
    return [`https://bulk-ai-flow-playground.s3.eu-north-1.amazonaws.com/${record.users_photo}`];
  },
  generateImages: {
    users_avatar: {
      prompt: 'Transform this photo into a cartoon-style avatar. Maintain the person\'s features but apply cartoon styling. Do not add text or logos.',
      outputSize: '1024x1024',
      countToGenerate: 2,
      rateLimit: '3/1h'
    },
  },
  bulkGenerationRateLimit: "1/1h"
}),
```

## Image generation quality

`ImageGenerationAdapterOpenAI` accepts an `extraParams` object that is passed directly to the OpenAI API. The most useful option here is `quality`, which controls the fidelity and cost of each generated image:

| Value | Description |
|-------|-------------|
| `'low'` | Fastest generation, lowest cost. Good for drafts or high-volume batch jobs where speed matters more than visual fidelity. |
| `'medium'` | Balanced quality and speed. A sensible default for most use cases. |
| `'high'` | Best image quality, slowest and most expensive. Use for final promotional assets or when visual detail is critical. |

```ts
new ImageGenerationAdapterOpenAI({
  openAiApiKey: process.env.OPENAI_API_KEY as string,
  model: 'gpt-image-1',
  //diff-add
  extraParams: {
  //diff-add
    quality: 'low', // 'low' | 'medium' | 'high'
  //diff-add
  },
}),
```

> ☝️ `'low'` quality is a great starting point when processing large datasets — you can always re-run generation with `'high'` for selected records once you're happy with the prompts.

## Rate Limiting and Best Practices

- Use `rateLimit` for individual image generation operations and for the bulk image generation
```ts
  new BulkAiFlowPlugin({
  ...

  generateImages: {
    users_avatar: {
      ... //image re-generation limits
      //diff-add
      rateLimit: '1/5m' // one request per 5 minutes
    }
  },

  ...

  //diff-add
  rateLimits: { // bulk generation limits
  //diff-add
    fillFieldsFromImages: "5/1d", // 5 requests per day
  //diff-add
    fillPlainFields: "3/1h",      // 3 requests per one hour
  //diff-add
    generateImages: "1/2m",       // 2 request per one minute
  //diff-add
  }

  ...

  })
```

- Consider using lower resolution (`512x512`) for faster generation and lower costs
- Test prompts thoroughly before applying to large datasets

## Comparing new and old images

If you want to compare a generated image with an image stored in your storage, you need to add the preview prop in your upload plugin setup:

```ts
  new UploadPlugin({
        ...
    //diff-add
    preview: {
    //diff-add
      previewUrl: ({filePath}) => `https://static.my-domain.com/${filePath}`,
    //diff-add
    }
        ...
  })
```
After generation, you’ll see a button labeled "old image". Clicking it will open a pop-up where you can compare the generated image with the stored one:

![alt text](Bulk-vision-4.png)

## Extra data fields

When creating default prompts, you can use Handlebars to pass data from the record into the prompt:

```ts
  ...
  fillPlainFields: { 
    description: 'Create a description based on the apartment name: {{title}}.'
  },
  ...
```

Each record will receive a unique prompt based on its own title.

If you want to add extra data fields for use in your prompt, implement the `provideAdditionalContextForRecord` callback:

```ts
provideAdditionalContextForRecord({ record, adminUser, resource }) {
  const extraData: any = {};
  if (record.country === 'Spain') {
    // Your logic
    // e.g. extraData.discount = '10%';
  } else {
    // Your logic
  }
  return extraData;
},
fillPlainFields: { 
  description: 'Create a description based on the apartment name: {{title}}. Also include the fact that the apartment has a discount of {{extraData.discount}}.'
},
```

## Allow users to edit generation prompts

If you want to let users adjust generation prompts for their unique cases, add this to the plugin setup:

```ts
...
//diff-add
askConfirmationBeforeGenerating: true,
...
```

The user will now see a popup with a "Start generation" button and an "Edit prompts" button, allowing them to modify the prompt before running it.

![alt text](Bulk-vision-5.png)
![alt text](Bulk-vision-6.png)

> ☝️ Updated prompts are stored in the user's local storage. Changes are local to that browser and do not affect other users or devices.

## Processing big sets of data ( filtered records )

There might be cases when you want to process more records than can fit your list view.
Here you can use the `recordSelector` param.
It can be `checkbox` (default) or `filtered`.
`filtered` uses all filtered records for generation, so you can even process the whole resource.

```ts
        new BulkAiFlowPlugin({          
          actionName: 'Generate description and Price',

          //diff-add
          recordSelector: 'filtered', // default is 'checkbox'

          ...

        });
```
>❗️❗️❗️ Using `recordSelector: 'filtered'` might be expensive. Before processing large data sets, we recommend starting with smaller sets to make sure everything is fine.

## Limiting amount of parallel requests using p-limit

If you are processing large sets of data, you might want to limit the number of parallel requests. For this, you can use the `concurrencyLimit` param:

```ts
        new BulkAiFlowPlugin({          
          actionName: 'Generate description and Price',

          //diff-add
          concurrencyLimit: 5, //default is 10

          ...

        });
```

And there won't be more than 5 parallel requests being handled.

## Controlling page size in the generation dialog

When users trigger bulk generation, records are displayed as cards in a paginated dialog. By default, 6 cards are shown per page. Use `pageSize` to tune this — lower values help when cards contain large images or long text, keeping the dialog fast and reviewable:

```ts
new BulkAiFlowPlugin({
  actionName: 'Generate description and Price',

  //diff-add
  pageSize: 10, // default is 6

  // ...
}),
```

## Confirming long-running generations

For very large datasets, you can pause generation at specific checkpoints so users can review results before continuing.
Use the `askConfirmation` option to define confirmation breakpoints by processed record count.

```ts
new BulkAiFlowPlugin({
  actionName: 'Generate descriptions',
  // ...adapters + fields

  //diff-add
  askConfirmation: [
    { afterRecords: 10 },
    { afterRecords: 30 },
    { everyRecords: 1000 },
  ],
});
```

**How it works:**
- `afterRecords: N` — show a confirmation once, after the first $N$ records.
- `everyRecords: N` — show a confirmation after every $N$ records.

---

## Universal Search (Legacy)

# Universal Search (legacy)
> **Deprecated:** Prefer the [**Quick Filters**](/docs/tutorial/Plugins/quick-filters) plugin. It provides the same functionality and more.

Ephemeral, debounced multi‑column search for List pages. A lightweight input (injected at `beforeActionButtons`) sends the term with each list request; a hook expands it server‑side into a single `OR` filter group over your configured columns. The term never enters the standard filter store, so:

- No extra badge count
- No URL pollution
- No UI filter chips to manage

Ideal for quick, multi‑field lookup without opening the filter panel.

## Installation

```bash
pnpm add @adminforth/universal-search --save
```

## Basic Usage

Add the plugin to any resource. Place it inside the `plugins` array. It injects a component at the `beforeActionButtons` list page injection point (already available in AdminForth if you are on a recent version).

```ts title="./resources/apartments.ts"
// diff-add
import UniversalSearchPlugin from '@adminforth/universal-search';

export const admin = new AdminForth({
  ...,
  resources: [
    {
      resourceId: 'aparts',
      table: 'apartments',
      columns: [
        { name: 'id', primaryKey: true },
        { name: 'title' },
        { name: 'description' },
        { name: 'country' },
        { name: 'price' },
      ],
      plugins: [
        // diff-add
        new UniversalSearchPlugin({
        // diff-add
          columns: [
        // diff-add
            { name: 'title' },
        // diff-add
            { name: 'description' },
        // diff-add
            { name: 'country', caseSensitive: true },
        // diff-add
            { name: 'price', exact: true },
        // diff-add
          ],
        // diff-add
          debounceMs: 400,          // optional (default 500)
        // diff-add
          placeholder: 'Search apartments…' // optional (default empty string)
        // diff-add
        }),
      ]
    }
  ]
});
```

Type into the input and (after debounce) the backend receives the term (as an internal field) and the plugin hook rewrites it into a single composite filter like this:

```json
{
  "operator": "or",
  "subFilters": [
    { "field": "title",       "operator": "ilike", "value": "%pent%" },
    { "field": "description", "operator": "ilike", "value": "%pent%" },
    { "field": "country",     "operator": "like",  "value": "%pent%" }
  ]
}
```

`price` (marked `exact`) will be compared for exact match (no wildcards). Numeric heuristics may be applied in future versions (current implementation sends the same OR group regardless of numeric content — adjust logic in hook if you need number detection).

Press Enter to apply immediately without waiting for the debounce delay. Clearing the input removes the universal filter group entirely.

## Options

```ts
new UniversalSearchPlugin({
  columns: [
    {
      name: string;            // required column name
      caseSensitive?: boolean; // default false
      exact?: boolean;         // exact match (no wildcards)
      searchBy?: 'valueOnly' | 'keyOnly' | 'both'  (reserved; not exposed yet in public docs)
    }
  ],
  debounceMs?: number;         // default 500
  placeholder?: string;        // input placeholder (default "")
});
```

Notes:
- The virtual field name (`_universal_search`) and ephemeral behavior are fixed and not configurable.
- The input does not create visible filters; clearing it removes internal search state.

## Debounce Behavior

- Default delay: 500 ms (configurable via `debounceMs`).
- Enter key: applies immediately.
- Input cleared: universal OR filter group removed.

## How It Works Internally

1. Component writes the current term to a transient global (`adminforth.__universalSearchTerm`).
2. List request body includes `__universal_search_term`.
3. Plugin `beforeDatasourceRequest` hook adds a temporary virtual filter.
4. Hook expands that virtual filter to an `OR` group across configured columns.
5. The expanded group is executed; the temporary filter is not shown in the UI.

This means the UI stays clean while the backend still receives a standard filter structure.

## Roadmap / Future Enhancements

- Optional multi-term splitting (turn "foo bar" into two groups)
- Enum label / foreign key label search exposure
- Loading indicator & progress feedback
- Optional persistence of the last term per resource

## License

MIT

---

## Login Captcha


(this plugin experemental and not yet fully tested)

This plugin provides a captcha for the login page to enhance security.

## Installation

To install the plugin, run the following command:

```bash
pnpm add @adminforth/login-captcha
```

You will also need to install a captcha adapter. For example, to use the Cloudflare adapter, run:

```bash
pnpm add @adminforth/login-captcha-adapter-cloudflare
```

## Usage

To use the plugin, add it to your user resource file. Here's an example:

```ts title="./resources/adminuser.ts"
// Import the plugin and adapter
import CaptchaPlugin from "@adminforth/login-captcha";
import CaptchaAdapterCloudflare from "@adminforth/login-captcha-adapter-cloudflare";

...

// Add the plugin to the `plugins` array
plugins: [
    new CaptchaPlugin({ 
      captchaAdapter: new CaptchaAdapterCloudflare({
        siteKey: "YOUR_SITE_KEY", // Replace with your site key
        secretKey: "YOUR_SECRET_KEY", // Replace with your secret key
      }),
    }),
]
```

## Preventing token reuse

A captcha token stays valid at the provider for a short period, which means the same token could be replayed for several logins. To prevent this, pass an optional [key-value adapter](/docs/tutorial/Adapters/key-value-adapters) via `keyValueAdapter`. Each token is recorded once it has been used for a successful login, and any later attempt with the same token is rejected.

```bash
pnpm add @adminforth/key-value-adapter-ram
```

```ts title="./resources/adminuser.ts"
// Import the plugin, captcha adapter and a key-value adapter
import CaptchaPlugin from "@adminforth/login-captcha";
import CaptchaAdapterCloudflare from "@adminforth/login-captcha-adapter-cloudflare";
import RamKeyValueAdapter from "@adminforth/key-value-adapter-ram";

...

plugins: [
    new CaptchaPlugin({
      captchaAdapter: new CaptchaAdapterCloudflare({
        siteKey: "YOUR_SITE_KEY", // Replace with your site key
        secretKey: "YOUR_SECRET_KEY", // Replace with your secret key
      }),
      // Store used tokens to prevent them from being replayed
      keyValueAdapter: new RamKeyValueAdapter(),
      // Optional: how long (in seconds) a used token is remembered. Should be at least as long
      // as the captcha provider keeps the token valid. Defaults to 300 (5 minutes).
      tokenTimeToLiveSeconds: 300,
    }),
]
```

You can use any of the available [key-value adapters](/docs/tutorial/Adapters/key-value-adapters) (RAM, Redis, LevelDB or Resource-based). For multi-process or replicated deployments use a centralized adapter such as Redis, so used tokens are shared across all processes.

## Result

After setting up the plugin, your login page will include a captcha. Below is an example of how it will look:

![Login Captcha Example](LoginCaptcha1.png)

---

## User Soft Delete

# User soft delete

Allows to deactivate users accound without deleting it.

## Instalation

To install the plugin:

```bash
pnpm add @adminforth/user-soft-delete --save
```

## Setting up
First of all you need to add extra row in your users table:

``` .title="./schema.prisma"
model adminuser {
  id            String     @id
  email         String     @unique
  password_hash String
  role          String
  created_at    DateTime
  //diff-add
  is_active     Boolean
  //diff-add
  @@index([is_active])
}
```

and make migration:

```bash
pnpm makemigration --name add-active-field-to-users ; pnpm migrate:local
```

To setup the plugin in users resource add:

```ts .title="./adminuser"
import UserSoftDelete from "@adminforth/user-soft-delete";

    ...

columns[

    ...
    //diff-add
    {
        //diff-add
        name: "is_active",
        //diff-add
        type: AdminForthDataTypes.BOOLEAN,
        //diff-add
        label: "Is Active",
        //diff-add
        fillOnCreate: () => true,
        //diff-add
        filterOptions: {
            //diff-add
            multiselect: false,
            //diff-add
        },
        //diff-add
        showIn: {
            //diff-add
            list: true,
            //diff-add
            filter: true,
            //diff-add
            show: true,
            //diff-add
            create: false,
            //diff-add
            edit: true,
            //diff-add
        },
        //diff-add
    },

    ...

]

    ...

plugins: [
    
    ...
//diff-add
    new UserSoftDelete({
        //diff-add
        activeFieldName: "is_active",
        //diff-add
        //in canDeactivate we pass a function, that specify adminusers roles, which can seactivate other adminusers  
        //diff-add
        canDeactivate: async (adminUser: AdminUser) => {
            //diff-add
        if (adminUser.dbUser.role === "superadmin") {
            //diff-add
            return true;
            //diff-add
        }
        //diff-add
        return false;
        //diff-add
        }
        //diff-add
    }),

    ...
 
]
```

> ☝️Note that by default deactivated users hidden by filters, so if you want to see them, you'll have to change filters

---

## Clone Row

# Clone row

Allows to create a copy of record quickly, by substituting default values to create form

## Instalation

To install the plugin:

```bash
pnpm add @adminforth/clone-row --save
```

## Setting up

To setup the plugin just add it to your resource:

```ts .title="./resources/apartments.ts"
import CloneRow from "@adminforth/clone-row";

    ...

plugins: [
    
    ...
//diff-add
    new CloneRow({}),
    ...

]
```

## Options

### `makeCloneButtonAsQuickAction`

By default, the Clone action appears in the **three-dots dropdown menu** of each row. Set `makeCloneButtonAsQuickAction: true` to display it as a standalone icon button directly in the row actions area, next to other quick-action buttons like Approve:

```ts
new CloneRow({
  makeCloneButtonAsQuickAction: true,
}),
```

---

## Many to Many

# Many2Many

This plugin lets you manage many-to-many relationships.

## Installation

Install the plugin:

```bash
pnpm add @adminforth/many2many
```

## Setting up

Let's say we want to implement a relationship where every apartment can have many realtors and each realtor can have many apartments.
We'll also need a junction resource to connect realtors and apartments.

First, create the `realtors` table and the junction table `realtorsAparts`:

```ts title="./schema.prisma"
//diff-add
model realtors {
  //diff-add
  id            String @id
  //diff-add
  name          String
  //diff-add
  surname       String
  //diff-add
}
//diff-add
model realtorsAparts {
  //diff-add
  id            String @id
  //diff-add
  realtorId     String
  //diff-add
  apartmentId   String
  //diff-add
}
```

Migrate the Prisma schema:

```bash 
pnpm makemigration --name add-realtors-and-realtorsAparts; pnpm migrate:local
```

Now create a resource for the realtors:

```ts title="./resources/realtors.ts"
import { AdminForthDataTypes, AdminForthResourceInput } from 'adminforth';

export default {
  dataSource: 'maindb',
  table: 'realtors',
  resourceId: 'realtors', 
  label: 'Realtors',
  recordLabel: (r) => ` ${r.name}`,
  columns: [
    {
      name: 'id',
      type: AdminForthDataTypes.STRING,
      label: 'Identifier',
      showIn: {
        list: false,
        edit: false,
        create: false,
      },
      primaryKey: true,
      fillOnCreate: ({ initialRecord, adminUser }) => Math.random().toString(36).substring(7),
    },
    {
      name: 'name',
      required: true,
      showIn: { all: true },
      type: AdminForthDataTypes.STRING,
      maxLength: 255,
      minLength: 3,
    },
    {
      name: "surname",
      required: true,
      showIn: { all: true },
      type: AdminForthDataTypes.STRING,
      maxLength: 100,
      minLength: 3,
    }
  ],
  options: {
    listPageSize: 12,
    allowedActions: {
      edit: true,
      delete: true,
      show: true,
      filter: true,
    },
  },
} as AdminForthResourceInput;
```

And one for the junction table `realtorsAparts`:

```ts title="./resources/realtorsAparts.ts"
import { AdminForthDataTypes, AdminForthResourceInput } from 'adminforth';

export default {
  dataSource: 'maindb',
  table: 'realtorsAparts',
  resourceId: 'realtorsAparts', 
  label: 'Realtors-aparts',
  columns: [
    {
      name: 'id',
      type: AdminForthDataTypes.STRING,
      label: 'Identifier',
      showIn: {
        list: false,
        edit: false,
        create: false,
      },
      primaryKey: true,
      fillOnCreate: ({ initialRecord, adminUser }) => Math.random().toString(36).substring(7),
    },
    {
      name: 'realtorId',
      foreignResource: { 
        resourceId: 'realtors', 
        searchableFields: ['name'], 
        searchIsCaseSensitive: true 
      }
    },
    {
      name: 'apartmentId',
      foreignResource: { 
        resourceId: 'aparts',
        searchableFields: ['title'],
        searchIsCaseSensitive: true 
      }
    },
  ],
  options: {
    listPageSize: 12,
    allowedActions: {
      edit: true,
      delete: true,
      show: true,
      filter: true,
    },
  },
} as AdminForthResourceInput;
```

Now add the plugin resources to the main config file:

```ts title="./index.ts"

//diff-add 
import realtorsResource from './resources/realtors.js';
//diff-add 
import realtorsApartsResource from './resources/realtorsAparts.js';

  ...

dataSources: [
    {
      id: 'maindb',
      url: `${process.env.DATABASE_URL}`
    },
  ],
  resources: [
    ...
    //diff-add
    realtorsResource,
    //diff-add
    realtorsApartsResource
  ]

  ...

  menu: [

    ...
    //diff-add
    {
      //diff-add
      label: 'Realtors',
      //diff-add
      resourceId: 'realtors'
      //diff-add
    },
    //diff-add
    {
      //diff-add
      label: 'Realtors-aparts',
      //diff-add
      resourceId: 'realtorsAparts'
      //diff-add
    },

    ...

  ]

```

Finally, add the plugin to the `apartments` resource:

```ts title="./resources/apartments.ts"
//diff-add
import Many2ManyPlugin from '@adminforth/many2many';

  ...

  plugins: [
    ...

    //diff-add
    new Many2ManyPlugin({
      //diff-add
      linkedResourceId: 'realtors',
      //diff-add
    })

    ...
  ]

  ...

```

The plugin is set up. Create some records in the `realtors` table:
![alt text](Many2Many-1.png)
Now, when creating an apartment, you can select (link) one or more realtors.
![alt text](Many2Many-2.png)
After saving the record, rows in the junction table are created automatically:
![alt text](Many2Many-3.png)

## Disable automatic cleanup of the junction table
By default, when you delete a realtor or an apartment, all related rows in the junction table are deleted automatically. To avoid this behavior, add:

```ts

  ...

    new Many2ManyPlugin({
      linkedResourceId: 'realtors',
      //diff-add
      dontDeleteJunctionRecords: true, // prevents automatic deletion of related junction rows
    })

  ...

```

## Making editable fields for the both resources

There might be cases, when you want to make fields editable on both resources. For these cases you can just create second instance of plugin on the second resource and it will allow you to use this plugin from the both resources.

```ts title="./resources/apartments.ts"
//diff-add
import Many2ManyPlugin from '@adminforth/many2many';

  ...

  plugins: [
    ...

    //diff-add
    new Many2ManyPlugin({
      //diff-add
      linkedResourceId: 'realtors',
      //diff-add
    })

    ...
  ]

  ...

```

and

```ts title="./resources/realtors.ts"
//diff-add
import Many2ManyPlugin from '@adminforth/many2many';

  ...

  plugins: [
    ...

    //diff-add
    new Many2ManyPlugin({
      //diff-add
      linkedResourceId: 'aparts',
      //diff-add
    })

    ...
  ]

  ...

```

---

## Background Jobs

# Background jobs
BackgroundJobsPlugin adds a durable background job system to AdminForth. Jobs are stored in your data store through a resource, executed by registered handlers, and automatically resumed after server restarts.

## Setup
> ‼️ Note, that before deploying this plugin, you should create volume for the level db and pass is as `levelDbPath` param, so background jobs will be saved between redeploys
First, install the plugin:
```bash
pnpm add @adminforth/background-jobs
```

Then create a resource for jobs:

```ts title="./resources/jobs.ts"
import AdminForth, { AdminForthDataTypes } from 'adminforth';
import type { AdminForthResourceInput, AdminUser } from 'adminforth';
import { randomUUID } from 'crypto';
import BackgroundJobsPlugin from '@adminforth/background-jobs';

async function allowedForSuperAdmin({ adminUser }: { adminUser: AdminUser }): Promise<boolean> {
  return adminUser.dbUser.role === 'superadmin';
}

export default {
  dataSource: 'maindb',
  table: 'jobs',
  resourceId: 'jobs',
  label: 'Jobs',
  options: {
    allowedActions: {
      edit: allowedForSuperAdmin,
      delete: allowedForSuperAdmin,
    },
  },
  columns: [
    {
      name: 'id',
      primaryKey: true,
      type: AdminForthDataTypes.STRING,
      fillOnCreate: ({ initialRecord, adminUser }) => randomUUID(),
      showIn: {
        edit: false,
        create: false,
      },
    },
    {
      name: 'name',
      type: AdminForthDataTypes.STRING,
    },
    {
      name: 'created_at',
      type: AdminForthDataTypes.DATETIME,
      showIn: {
        edit: false,
        create: false,
      },
      fillOnCreate: ({ initialRecord, adminUser }) => (new Date()).toISOString(),
    },
    {
      name: 'finished_at',
      type: AdminForthDataTypes.DATETIME,
      showIn: {
        edit: false,
        create: false,
      },
    },
    {
      name: 'started_by',
      type: AdminForthDataTypes.STRING,
      foreignResource: {
        resourceId: 'adminuser',
        searchableFields: ["id", "email"],
      }
    },
    {
      name: 'state',
      type: AdminForthDataTypes.JSON,
    },
    {
      name: 'progress',
      type: AdminForthDataTypes.STRING,
    },
    {
      name: 'status',
      type: AdminForthDataTypes.STRING,
      enum: [
        {
          label: 'IN_PROGRESS',
          value: 'IN_PROGRESS',
        },
        {
          label: 'DONE',
          value: 'DONE',
        },
        {
          label: 'DONE_WITH_ERRORS',
          value: 'DONE_WITH_ERRORS',
        },
        {
          label: 'CANCELLED',
          value: 'CANCELLED',
        }
      ]
    },
    {
      name: 'job_handler_name',
      type: AdminForthDataTypes.STRING,
    },
  ],
  plugins: [
    new BackgroundJobsPlugin({
      createdAtField: 'created_at',
      finishedAtField: 'finished_at',
      startedByField: 'started_by',
      stateField: 'state',
      progressField: 'progress',
      statusField: 'status',
      nameField: 'name',
      jobHandlerField: 'job_handler_name',
      levelDbPath: process.env.NODE_ENV === 'production' ? '/stores/background_job_plugin' : './background_jobs',
    })
  ]
} as AdminForthResourceInput;
```

Then add the table schema:

```
model jobs {
  id          String @id
  created_at  DateTime
  finished_at DateTime?
  started_by  String
  name        String
  state       String?
  progress    String
  status      String
  job_handler_name String
}
```

Then create a migration.

## Usage
The plugin saves tasks and keeps executing them after a server restart, so you should register job task handlers when the AdminForth application starts.

```ts title="./index.ts"
  //diff-add
  import BackgroundJobsPlugin from '@adminforth/background-jobs';
  //diff-add
  import jobs_resource from './resources/jobs.js';
  
  ...

  resources: [

    ...

    //diff-add
    jobs_resource,

    ...

  ],

  ...

  admin.express.serve(app);

  admin.discoverDatabases().then(async () => {
    if (await admin.resource('adminuser').count() === 0) {
      await admin.resource('adminuser').create({
        email: 'adminforth',
        password_hash: await AdminForth.Utils.generatePasswordHash('adminforth'),
        role: 'superadmin',
      });
    }
  });

  //diff-add
  const backgroundJobsPlugin = admin.getPluginByClassName<BackgroundJobsPlugin>('BackgroundJobsPlugin');
  
  //diff-add
  backgroundJobsPlugin.registerTaskHandler({
    //diff-add
    // job handler name
    //diff-add
    jobHandlerName: 'example_job_handler',
    //diff-add
    //handler function
    //diff-add
    handler: async ({ jobId, setTaskStateField, getTaskStateField, getState }) => {
      //diff-add
      const state = await getState();
      //diff-add
      console.log('State of the task at the beginning of the job handler:', state);
      //diff-add
      for (let second = 0; second < 3; second++) {
        //diff-add
        let taskCounter = await getTaskStateField('task_counter');
        //diff-add
        await new Promise(resolve => setTimeout(resolve, 1000));
        //diff-add
        taskCounter += 1;
        //diff-add
        await setTaskStateField('task_counter', taskCounter);
        //diff-add
      }
      //diff-add
      await backgroundJobsPlugin.updateJobFieldsAtomically(jobId, async () => {
        //diff-add
        const jobState = await backgroundJobsPlugin.getJobState(jobId);
        //diff-add
        await backgroundJobsPlugin.setJobStateField(jobId, 'counter', jobState.counter + 1);
        //diff-add
        await backgroundJobsPlugin.setJobStateField(jobId, 'commited_tasks', `${jobState.commited_tasks}${state.task_number} `);
        //diff-add
      });
      //diff-add
    },
    //diff-add
    // limit of tasks that are running in parallel
    //diff-add
    parallelLimit: 2
    //diff-add
  })

  ...

```

After registering a handler, you can create a job. For example:

```ts title="./index.ts"

  ...

  if (fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) {
    const app = express();
    app.use(express.json());

    //diff-add
    app.post(`${ADMIN_BASE_URL}/api/create-job/`,
    //diff-add
      admin.express.authorize(
        //diff-add
        async (req: any, res: any) => {
          //diff-add
          const backgroundJobsPlugin = admin.getPluginByClassName<BackgroundJobsPlugin>('BackgroundJobsPlugin');
          //diff-add
          if (!backgroundJobsPlugin) {
            //diff-add
            res.status(404).json({ error: 'BackgroundJobsPlugin not found' });
            //diff-add
            return;
            //diff-add
          }
          //diff-add
          const jobId = await backgroundJobsPlugin.startNewJob(
            //diff-add
            'Example Job', //job name
            //diff-add
            req.adminUser, // adminuser
            //diff-add
            [
              //diff-add
              { state: { task_number: 1, task_counter: 0 } },
              //diff-add
              { state: { task_number: 2, task_counter: 0 } },
              //diff-add
              { state: { task_number: 3, task_counter: 0 } },
              //diff-add
              { state: { task_number: 4, task_counter: 0 } },
              //diff-add
              { state: { task_number: 5, task_counter: 0 } },
              //diff-add
              { state: { task_number: 6, task_counter: 0 } },
              //diff-add
            ], //initial tasks
            //diff-add
            'example_job_handler', //job handler name
            //diff-add
            { counter: 0, commited_tasks: 'Commited tasks:' }, //initial job state
            //diff-add
          )
          //diff-add
          res.json({ok: true, message: 'Job started' });
          //diff-add
        }
        //diff-add
      ),
      //diff-add
    );

  ...

```

## Run more tasks before job finishes
If you need to react when the whole job is almost finished and add more tasks, use the `beforeJobFinish` callback.

The callback is called when all currently scheduled tasks are done, before the job is marked as `DONE` or `DONE_WITH_ERRORS`, and before `onAllTasksDone` is called.
This means you can use it as a continuation hook: add more tasks with `addNewTasksToExistingJob`, and the same job will keep running.
After those new tasks finish, `beforeJobFinish` is called again.

`finishAttemptNumber` starts from `1` and increments every time the job reaches this candidate-finish point again. Use it to avoid accidental infinite continuations.

```ts title="./index.ts"
  ...

  backgroundJobsPlugin.registerTaskHandler({
    jobHandlerName: 'import-users',
    handler: async ({ jobId, setTaskStateField, getTaskStateField, getState }) => {
      // task logic
    },
    beforeJobFinish: async ({ jobId, failedTasks, succeededTasks, finishAttemptNumber }) => {
      console.log('job reached finish point', {
        jobId,
        failedTasks,
        succeededTasks,
        finishAttemptNumber,
      });

      if (finishAttemptNumber > 1) {
        return;
      }

      await backgroundJobsPlugin.addNewTasksToExistingJob(jobId, [
        { state: { userId: 'user-1001' } },
        { state: { userId: 'user-1002' } },
      ]);
    },
  });

```

In this example, the job runs its initial tasks, calls `beforeJobFinish` with `finishAttemptNumber: 1`, appends two more tasks, runs them, and then calls `beforeJobFinish` again with `finishAttemptNumber: 2`.
If the second callback does not add more tasks, the job is marked as finished and `onAllTasksDone` is called if it was registered.

## Custom job state renderer
There may be cases where you need to display the state of job tasks. For this, you can register a custom component.

1) You need to create a custom vue component:
```vue title="./custom/JobCustomComponent.vue"
<template>
  
    
      
        Job state
        
      

      
        Tasks
        
      
    
  
</template>

<script setup lang="ts">
import { computed, onMounted, onUnmounted, ref } from 'vue';
import type { AdminForthComponentDeclarationFull } from 'adminforth';
import { Table } from '@/afcl';

type JobTask = {
  state: {
    task_number: number;
    task_counter: number;
  };
  status: 'SCHEDULED' | 'IN_PROGRESS' | 'DONE' | 'FAILED';
};

const tasks = ref<JobTask[]>([]);
const unsubscribeCallbacks: Array<() => void> = [];
const jobStateColumns = [
  { label: 'Field', fieldName: 'field' },
  { label: 'Value', fieldName: 'value' },
];
const taskColumns = [
  { label: 'Task', fieldName: 'taskNumber' },
  { label: 'State', fieldName: 'status' },
  { label: 'task_counter', fieldName: 'taskCounter' },
];
const taskStatusLabels: Record<JobTask['status'], string> = {
  SCHEDULED: 'pending',
  IN_PROGRESS: 'running',
  DONE: 'done',
  FAILED: 'failed',
};

const props = defineProps<{
  meta: any;
  getJobTasks: (limit?: number, offset?: number, fieldsToReturn?: string[]) => Promise<JobTask[]>;
  subscribeToJobStateFields: (fieldNames: string[]) => () => void;
  subscribeToJobTaskFields: (fieldNames: string[]) => () => void;
  job: {
    id: string;
    name: string;
    status: 'IN_PROGRESS' | 'DONE' | 'DONE_WITH_ERRORS' | 'CANCELLED';
    state: {
      counter: number;
      commited_tasks: string;
    };
    progress: number;
    createdAt: Date;
    customComponent?: AdminForthComponentDeclarationFull;
  };
}>();

const jobStateRows = computed(() => [
  { field: 'counter', value: props.job.state.counter },
  { field: 'commited_tasks', value: props.job.state.commited_tasks },
]);

const taskRows = computed(() => tasks.value.map((task) => ({
  taskNumber: task.state.task_number,
  status: taskStatusLabels[task.status],
  taskCounter: task.state.task_counter,
})));

async function loadTasks() {
  tasks.value = await props.getJobTasks(100, 0);
}

onMounted(async () => {
  await loadTasks();

  unsubscribeCallbacks.push(props.subscribeToJobStateFields(['counter', 'commited_tasks']));
  unsubscribeCallbacks.push(props.subscribeToJobTaskFields(['task_counter']));
});

onUnmounted(() => {
  unsubscribeCallbacks.forEach((unsubscribe) => unsubscribe());
});
</script>
```

2) Now register this component explicitly:

```ts title="./index.ts"
export const admin = new AdminForth({
  baseUrl: ADMIN_BASE_URL,
  auth: {
    usersResourceId: 'adminuser',
    usernameField: 'email',
    passwordHashField: 'password_hash',
    rememberMeDuration: '30d', 
    loginBackgroundImage: 'https://images.unsplash.com/photo-1534239697798-120952b76f2b?q=80&w=3389&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D',
    loginBackgroundPosition: '1/2',
    loginPromptHTML: async () => { 
      const adminforthUserExists = await admin.resource("adminuser").count(Filters.EQ('email', 'adminforth')) > 0;
      if (adminforthUserExists) {
        return "Please use adminforth as username and adminforth as password"
      }
    },
  },

  //diff-add
  componentsToExplicitRegister: [
    //diff-add
    { 
      //diff-add
      file: '@@/JobCustomComponent.vue',
      //diff-add
      meta: {
        //diff-add
        label: 'Job Custom Component',
        //diff-add
      }
      //diff-add
    }
    //diff-add
  ],
  ...

```

3) Finally, register this component alongside the job task handler:

```ts title="./index.ts"
  ...

  const backgroundJobsPlugin = admin.getPluginByClassName<BackgroundJobsPlugin>('BackgroundJobsPlugin');
  
  backgroundJobsPlugin.registerTaskHandler({
    jobHandlerName: 'example_job_handler', // Handler name
    handler: async ({ jobId, setTaskStateField, getTaskStateField, getState }) => { //handler function
      const state = await getState();
      console.log('State of the task at the beginning of the job handler:', state);

      for (let second = 0; second < 3; second++) {
        let taskCounter = await getTaskStateField('task_counter');
        await new Promise(resolve => setTimeout(resolve, 1000));
        taskCounter += 1;
        await setTaskStateField('task_counter', taskCounter);
      }

      await backgroundJobsPlugin.updateJobFieldsAtomically(jobId, async () => {
        const jobState = await backgroundJobsPlugin.getJobState(jobId);
        await backgroundJobsPlugin.setJobStateField(jobId, 'counter', jobState.counter + 1);
        await backgroundJobsPlugin.setJobStateField(jobId, 'commited_tasks', `${jobState.commited_tasks}${state.task_number} `);
      });
    },
    parallelLimit: 2 //parallel tasks limit. 2 menans 2 tasks can run at a time
  })

  //diff-add
  backgroundJobsPlugin.registerTaskDetailsComponent({
    //diff-add
    jobHandlerName: 'example_job_handler', // Handler name
    //diff-add
    component: { 
      //diff-add
      file: '@@/JobCustomComponent.vue'  //custom component for the job details
      //diff-add
    },
    //diff-add
  })

```

### Reactive updates for job state and task state

You can activate automatic reactive updates for task state and job state on the frontend when you call backend state mutation methods like `setJobStateField` and `setTaskStateField`.

To avoid unnecessary high-volume backend updates for data that might not be needed on the frontend, all reactive updates are disabled by default, and you need to specify which fields to subscribe to.

Use `subscribeToJobStateFields(['fieldName1', 'fieldName2'])` for specific job state fields and
`subscribeToJobTaskFields(['fieldName1', 'fieldName2'])` for specific task state fields.

The plugin applies incoming updates to the reactive `job` prop and to the task objects returned by
`getJobTasks()`. Task field subscriptions receive updates for that field from every task
in the open job. Both helpers return an unsubscribe function, though the plugin also automatically unsubscribes from
remaining field subscriptions when the job dialog closes.

## Frontend API
### Job info popup
If you want to immediately open the job info popup, return the job ID from the API that creates the job:

For example:

```ts
  ...
//diff-add
  import { useBackgroundJobApi } from '@/custom/plugins/BackgroundJobsPlugin/useBackgroundJobApi.ts';
 
 //diff-add
  const backgroundJobApi = useBackgroundJobApi();

  const res = await callAdminForthApi({
    path: `/plugin/${props.meta.pluginInstanceId}/translate-selected-to-languages`,
    method: 'POST',
    body: { 
      selectedIds: listOfIds,
      selectedLanguages: Object.keys(checkedLanguages.value).filter(lang => checkedLanguages.value[lang]),
    },
    silentError: true,
  });

  if (res.ok) {
    const jobId = res.jobId;
    if (jobId) {
      //diff-add
      backgroundJobApi.openJobInfoPopup(jobId);
    }
  }

```

### Filtering task fields you are getting on the frontend

Sometimes task state fields can be very complex and big, so when you run such a task with a big dataset and then fetch the tasks on the frontend, it can overload the browser with information you are not using. For those cases you can use the `fieldsToReturn` param in your custom component on the frontend to receive only the fields that you need.

```vue title="./custom/JobCustomComponent.vue"

...

async function loadTasks() {
  /**
   * props.getJobTasks will return only 'task_number' and 'task_counter',
   * so if you have data you don't want to send to the frontend, you can use this param
   */
  tasks.value = await props.getJobTasks(100, 0, ['task_number', 'task_counter']);
}

...

```

## Queued jobs and concurrency limit

Running several long jobs at the same time can overload the server, so jobs are queued instead of being started unconditionally.

`startNewJob` counts the jobs of the same `jobHandlerName` which are already running. If the handler has a free concurrency slot the job starts immediately, exactly as before. If the limit is already reached the job and all its tasks are created in the `QUEUED` status, and the job is started automatically later, when a running job of the same handler finishes.

Each **jobHandlerName** has one FIFO queue, shared by all its jobs regardless of their job names. So
`'Export users'` and `'Export orders'` of one handler do not run at the same time: the second one waits until the first finishes, and queued jobs are always started oldest first.

How many jobs of one handler may run at the same time is defined by `concurrencyLimit` of the handler.
It defaults to `1`, so by default only one job per handler runs at a time:

```ts title="./index.ts"
  backgroundJobsPlugin.registerTaskHandler({
    jobHandlerName: 'example_job_handler',
    handler: async ({ jobId, setTaskStateField, getTaskStateField, getState }) => {
      ...
    },
    // limit of tasks of one job that are running in parallel
    parallelLimit: 2,
    //diff-add
    // limit of jobs of this handler that are running at the same time, default is 1
    //diff-add
    concurrencyLimit: 1,
  })
```

With `concurrencyLimit: 1` the first call below starts processing right away and the second one, made while
the first job is still running, creates a `QUEUED` job which starts when the first one finishes:

```ts title="./index.ts"
  const jobId = await backgroundJobsPlugin.startNewJob(
    'Example Job', //job name
    req.adminUser, // adminuser
    [
      { state: { task_number: 1, task_counter: 0 } },
      { state: { task_number: 2, task_counter: 0 } },
    ], //initial tasks
    'example_job_handler', //job handler name
    { counter: 0 }, //initial job state
  )
```

Use `queueNewJob` when a job must always go through the queue, even if a slot is free. It has the same signature as `startNewJob` and always creates the job in the `QUEUED` status.

When a job reaches a terminal status (`DONE`, `DONE_WITH_ERRORS` or `CANCELLED`) it frees its slot and the oldest queued job of the same handler is started automatically. The same happens after an application
restart: jobs which were `IN_PROGRESS` are resumed first, and queued jobs are started only for handlers
which still have a free slot.

If you want full control over when a queued job starts, create it with `autoStart: false` and start it yourself later:

```ts
// job stays in QUEUED status, nothing is processed
await backgroundJobsPlugin.queueNewJob(
  'Example Job', req.adminUser, tasks, 'example_job_handler', {}, { autoStart: false },
)

// starts the oldest queued job of the handler if the concurrency limit allows it,
// returns the started job id or null
await backgroundJobsPlugin.startNextQueuedJob('example_job_handler')

// starts as many queued jobs of the handler as the concurrency limit allows
await backgroundJobsPlugin.startQueuedJobs('example_job_handler')
```

:::info
A job never jumps the queue: `startNewJob` starts a job immediately only when the handler has a free slot
**and** no other job is waiting in its queue. Otherwise the job is queued behind the ones created earlier.
:::

## Backend API

The plugin provides some handy methods that can be used in different situations:

```ts
//always create a job in QUEUED status, it is started by the queue of the handler when it has a free slot
queueNewJob(jobName: string, adminUser: AdminUser, tasks: taskType[], jobHandlerName: string, initialState?: Record<string, any>, options?: { autoStart?: boolean })
//start the oldest queued job of the handler if concurrencyLimit allows, returns started job id or null
startNextQueuedJob(jobHandlerName: string)
//start as many queued jobs of the handler as concurrencyLimit allows, returns started job ids
startQueuedJobs(jobHandlerName: string)
//set key:value to the job state in the DB
setJobStateField(jobId: string, key: string, value: any)
//get job field from the state in db
getJobStateField(jobId: string, key: string)
//get job state from the db
getJobState(jobId: string)
//add task to the running job
addNewTasksToExistingJob(jobId: string, tasks: taskType[])
//delete task from the running job (if not started yet)
deleteTasksFromExistingJob(jobId: string, taskIndex: number)
/**
 * 
 * executes code atomically. If you have many tasks that can update task state,
 * use this method to avoid invalid task state writes.
 * 
 **/
updateJobFieldsAtomically(jobId: string, updateFunction: () => Promise<void>) 

//for example
backgroundJobsPlugin.updateJobFieldsAtomically(jobId, async () => {
  // Do all set / get field operations in this function to make the state update atomic and avoid conflicts
  // when two parallel tasks get the same value before setting it.
  // Don't do long awaits in this callback, since it has an exclusive lock.
  let totalUsedTokens = await backgroundJobsPlugin.getJobStateField(jobId, 'totalUsedTokens');
  totalUsedTokens += promptCost;
  await backgroundJobsPlugin.setJobStateField(jobId, 'totalUsedTokens', totalUsedTokens);
})

```

---

## Quick Filters

# Quick filters
Allows you to add search input or select with preseted filters at the list view

## Setup

First, install the plugin:
```bash
pnpm add @adminforth/quick-filters
```
Then add it to yours resource:

```ts title="./resources/apartments.ts"
import QuickFiltersPlugin from '@adminforth/quick-filters';
```

And finally add it to list of plugins:

```ts title="./resources/apartments.ts"
  plugins: [
    ...
    //diff-add
    new QuickFiltersPlugin({
      //diff-add
      filters: [
        //diff-add
        {
          //diff-add
          name: 'Listing',
          //diff-add
          enum: [
            //diff-add
            { label: 'Listed', filters: () => Filters.EQ('listed', true) },
            //diff-add 
            { label: 'Not listed', filters: () => Filters.EQ('listed', false) },
            //diff-add
          ]
          //diff-add
        },
        //diff-add
        {
          //diff-add
          name: 'Title',
          //diff-add
          searchInput: (searchVal) => Filters.ILIKE('title', searchVal)
          //diff-add
        },
        //diff-add
      ]
      //diff-add
    }),
    ...
  ]
```

![alt text](quick-filters.png)

---

## Auto Remove Plugin


This plugin removes records from resources based on **count-based** or **time-based** rules.

It is designed for cleaning up:

* old records
* logs
* demo/test data
* temporary entities

---

## Installation

To install the plugin:

```ts
npm install @adminforth/auto-remove
```

Import it into your resource:
```ts
import AutoRemovePlugin from '../../plugins/adminforth-auto-remove/index.js';
```

## Plugin Options

```ts
export interface PluginOptions {
 createdAtField: string;

  /**
   * - count-based: Delete items > keepAtLeast
   * - time-based: Delete age > deleteOlderThan
   */
  mode: AutoRemoveMode;

  /**
   * for count-based mode (100', '1k', '10k', '1m')
   */
  keepAtLeast?: HumanNumber;

  /**
   * Minimum number of items to always keep in count-based mode.
   * This acts as a safety threshold together with `keepAtLeast`.
   * Example formats: '100', '1k', '10k', '1m'.
   * 
   * Validation ensures that minItemsKeep <= keepAtLeast. 
  */
  minItemsKeep?: HumanNumber;

  /**
   * Max age of item for time-based mode ('1d', '7d', '1mo', '1y')
   */
  deleteOlderThan?: HumanDuration;

  /**
   * Interval for running cleanup (e.g. '1h', '1d')
   * Default '1d'
   */
  interval?: HumanDuration;
}
```
---

## Usage
To use the plugin, add it to your resource file. Here's an example:

for count-based mode
```ts
new AutoRemovePlugin({
        createdAtField: 'created_at',   
        mode: 'count-based',            
        keepAtLeast: '200',                  
        interval: '1mo',                  
        minItemsKeep: '180',       
      }),
```

for time-based mode
```ts
new AutoRemovePlugin({
        createdAtField: 'created_at',
        mode: 'time-based',
        deleteOlderThan: '3mo',
        interval: '1mo',  
      }),
```

---

## Result
After running **AutoRemovePlugin**, old or excess records are deleted automatically:

- **Count-based mode:** keeps the newest `keepAtLeast` records, deletes older ones.  
  Example: `keepAtLeast = 500` → table with 650 records deletes 150 oldest.

- **Time-based mode:** deletes records older than `deleteOlderThan`.  
  Example: `deleteOlderThan = '7d'` → removes records older than 7 days.

- **Manual cleanup:** `POST /plugin/{pluginInstanceId}/cleanup`, returns `{ "ok": true }`.

Logs show how many records were removed per run.

---

## Rich Editor

# Rich editor

Under the hood this plugin uses [Quill](https://quilljs.com/). Quill is a free, open source WYSIWYG editor built for the modern web.

This plugin allows you to use Quill editor in your AdminForth application.

## Usage

First, install the plugin:

```bash
pnpm add @adminforth/rich-editor --save
```

Import plugin:

```ts title="./resources/apartments.ts"
import RichEditorPlugin from "@adminforth/rich-editor";
```

Now instantiate the plugin and add it to the configuration:

```ts title="./resources/apartments.ts"

{
  ...
  resourceId: 'aparts',
  columns: [
    ...
    {
      name: 'description',
//diff-add
      type: AdminForthDataTypes.TEXT, // like plain AdminForthDataTypes.TEXT but renders HTML in show/list views
      components: {
        show: "@/renderers/RichText.vue",
        list: "@/renderers/RichText.vue",
      },
      ...
    }
    ...
  ],
  ...
  plugins: [
    ...
//diff-add
    new RichEditorPlugin({
//diff-add
      htmlFieldName: 'description',
//diff-add
    }),
    ...
  ],
}
```

Now you can see Quill editor in the `description` field in the edit view:

![alt text](image-2.png)

# Multiple editors in one resource

If you need multiple fields in one resource which happens rarely, just add multiple instances of the plugin:

```ts title="./resources/apartments.ts"
{
  ...
  resourceId: 'promotion',
  columns: [
    ...
    {
      name: 'short_description',
      type: AdminForthDataTypes.TEXT,
      components: {
        list: "@/renderers/RichText.vue",
        show: "@/renderers/RichText.vue",
      }
      ...
    },
    {
      name: 'full_description',
      type: AdminForthDataTypes.TEXT,
      components: {
        list: "@/renderers/RichText.vue",
        show: "@/renderers/RichText.vue",
      }
      ...
    }
    ...
  ],
  ...
  plugins: [
    ...
    new QuillEditorPlugin({
      htmlField: 'short_description',
    }),
    new QuillEditorPlugin({
      htmlField: 'full_description',
    }),
    ...
  ],
}
```

## Completion

First, install the completion adapter:

```bash
pnpm add @adminforth/completion-adapter-openai-responses --save
```

To get completion suggestions for the text in the editor, you can use the `completion` option. This option is an object with the following properties:

```ts title="./resources/apartments.ts"
//diff-add
  import CompletionAdapterOpenAIResponses from "@adminforth/completion-adapter-openai-responses";

  new RichEditorPlugin({
      htmlFieldName: 'description',
//diff-add
      completion: {
//diff-add
        adapter: new CompletionAdapterOpenAIResponses({
//diff-add
          openAiApiKey: process.env.OPENAI_API_KEY as string,
//diff-add
          model: 'gpt-5-nano', //gpt-5-nano is a default (cheapest one)
          extraRequestBodyParameters: {
//diff-add
            temperature: 0.7 //Model temperature
//diff-add
          }
//diff-add
        }),
//diff-add
        expert: {
//diff-add
          debounceTime: 250,
//diff-add
        }
//diff-add
      }
    }),
```

![alt text](gptDemo.gif)

### Images in Rich editor

First, you need to create resource for images:
```prisma title="schema.prisma"
model description_image {
    id          String   @id
    created_at  DateTime
    resource_id String
    record_id   String
    image_path  String
}
```

```bash
pnpm makemigration --name add_description_image ; pnpm migrate:local
```

```bash
pnpm add @adminforth/upload --save
pnpm add @adminforth/storage-adapter-local --save
```

```typescript title="./resources/description_images.ts"
import AdminForthStorageAdapterLocalFilesystem from "@adminforth/storage-adapter-local";
import { AdminForthResourceInput } from "adminforth";
import UploadPlugin from "@adminforth/upload";
import { randomUUID } from 'crypto';

export default {
  dataSource: "maindb",
  table: "description_image",
  resourceId: "description_images",
  label: "Description images",
  columns: [
    {
      name: "id",
      primaryKey: true,
      required: false,
      fillOnCreate: ({ initialRecord }: any) => randomUUID(),
      showIn: {
        create: false,
      },
    },
    {
      name: "created_at",
      required: false,
      fillOnCreate: ({ initialRecord }: any) => new Date().toISOString(),
      showIn: {
        create: false,
      },
    },
    { name: "resource_id", required: false },
    { name: "record_id", required: false },
    { name: "image_path", required: false },
  ],
  plugins: [
    new UploadPlugin({
      pathColumnName: "image_path",
      
      // rich editor plugin supports only 'public-read' ACL images for SEO purposes (instead of presigned URLs which change every time)
      storageAdapter: new AdminForthStorageAdapterLocalFilesystem({
        fileSystemFolder: "./db/uploads/description_images", // folder where files will be stored on disk
        adminServeBaseUrl: "static/source", // the adapter not only stores files, but also serves them for HTTP requests
        mode: "public", // public if all files should be accessible from the web, private only if could be accesed by temporary presigned links
        signingSecret: process.env.ADMINFORTH_SECRET, // secret used to generate presigned URLs
      }),
  
      allowedFileExtensions: [
        "jpg",
        "jpeg",
        "png",
        "gif",
        "webm",
        "exe",
        "webp",
      ],
      maxFileSize: 1024 * 1024 * 20, // 20MB

      filePath: ({ originalFilename, originalExtension, contentType }) =>
        `description_images/${new Date().getFullYear()}/${randomUUID()}/${originalFilename}.${originalExtension}`,

    }),
  ],
} as AdminForthResourceInput;
```
Next, add new resource to `index.ts`:

```typescript title="./index.ts"
import descriptionImage from './resources/description_images.js';

...

  resources: [
    usersResource,
    apartments,
    // diff-add
    descriptionImage
  ],
```

Next, add attachments to RichEditor plugin:

```typescript title="./resources/apartments.ts"
import RichEditorPlugin from '@adminforth/rich-editor';

// ... existing resource configuration ...

new RichEditorPlugin({
  htmlFieldName: 'description',
  attachments: {
    attachmentResource: "description_images",
    attachmentFieldName: "image_path",
    attachmentRecordIdFieldName: "record_id",
    attachmentResourceIdFieldName: "resource_id",
  }
})
```

---

## Dashboard plugin

# Dashboard Plugin

The **Dashboard Plugin** adds dynamic, configurable dashboards to AdminForth. This page is a practical guide / reference demonstrating how to build and manage your dashboards using the **[Agent Plugin](/docs/tutorial/Plugins/agent)**.

While manual configuration is supported, the plugin is primarily designed to be managed via conversational prompts using the AI Agent. This is the fastest, easiest, and recommended way to create and modify your dashboards.

### Quick Start: Conversation Prompts
If you have the Agent Plugin active, you can interact with it right away using these prompts in the chat interface:
* *"Create a new dashboard named 'Sales Overview'"*
* *"Add a pie chart showing cars by body type to the Sales Overview dashboard"*
* *"Add a KPI card showing the average price of cars"*

---

## Using the Dashboard with the Agent

Once the Dashboard plugin is installed, the AI Agent has full capability to manage it. You do not need to construct YAML configurations yourself; the agent handles all database record updates and layout adjustments.

### End-to-End Prompt Examples
Here are interactive examples you can test immediately in the demo application generated via the AdminForth CLI:

#### 1. KPI Cards for Basic Metrics
* **Initial Prompt:**
  > *"Create a new dashboard group named 'Sales Stats' and add two KPI cards inside it: one for 'Total Cars' (count of all cars) and another for 'Average Price' (average car price)."*
* **Expected Result:**
  The agent creates a new group named "Sales Stats" containing two cards. One card displays the count of all records in the `cars` resource (e.g., `24`), and the second displays the average price formatted with a dollar sign (e.g., `$12,450`).
* **Follow-up Prompt:**
  > *"Change the background color of the Average Price card to blue and adjust its width to match the other card."*

#### 2. Visualizing Categories with a Bar Chart
* **Initial Prompt:**
  > *"Add a bar chart named 'Cars by Body Type' to the 'Sales Stats' group. Group it by body_type and sort by the number of cars from high to low."*
* **Expected Result:**
  A bar chart is created. It queries the `cars` resource, groups by `body_type`, and orders the bars so the body type with the most cars appears first.
* **Follow-up Prompt:**
  > *"Change the chart type to a pie chart and set its size to medium."*

#### 3. Data Table with Filters and Limits
* **Initial Prompt:**
  > *"Add a wide table widget named 'Top 5 Most Expensive Listed Cars' to my dashboard. Show the model, price, and production_year columns. Only include listed cars, and sort them by price descending."*
* **Expected Result:**
  A data table widget is added. It displays columns for model, price, and production year, filtered to only show cars where `listed` is true, limited to the top 5 most expensive.
* **Follow-up Prompt:**
  > *"Add the color column to this table, and rename the widget to 'Top 5 Premium Cars'."*

---

## Installation & Setup

Before using the dashboard, you need to perform the initial package installation and register the database tables:

### 1. Install Package

```bash
pnpm add @adminforth/dashboard --save
```

### 2. Create Dashboard Configs Table

The plugin needs one database resource to store dashboard definitions. For Prisma-based projects, add the table to your schema:

```prisma title="./schema.prisma"
model dashboard_configs {
  id        String @id
  slug      String @unique
  label     String
  revision  Int
  config    Json

  @@index([slug])
}
```

Create and apply a migration:

```bash
pnpm makemigration --name add-dashboard-configs
pnpm migrate:local
```

The generated SQL should be equivalent to:

```sql title="./migrations/.../migration.sql"
CREATE TABLE "dashboard_configs" (
  "id" TEXT NOT NULL PRIMARY KEY,
  "slug" TEXT NOT NULL,
  "label" TEXT NOT NULL,
  "revision" INTEGER NOT NULL,
  "config" JSON NOT NULL
);

CREATE UNIQUE INDEX "dashboard_configs_slug_key" ON "dashboard_configs"("slug");
CREATE INDEX "dashboard_configs_slug_idx" ON "dashboard_configs"("slug");
```

Use the JSON column type supported by your database connector. For example, PostgreSQL migrations might use `JSONB`, while SQLite migrations can use `JSON`.

### 3. Create Resource

Create a resource that points to the `dashboard_configs` table:

```ts title="./resources/dashboard_configs.ts"
import { randomUUID } from 'crypto';
import { AdminForthDataTypes } from 'adminforth';
import type { AdminForthResourceInput } from 'adminforth';

export default {
  dataSource: 'maindb',
  table: 'dashboard_configs',
  resourceId: 'dashboard_configs',
  label: 'Dashboard Configs',
  recordLabel: (record) => record.label,
  columns: [
    {
      name: 'id',
      primaryKey: true,
      type: AdminForthDataTypes.STRING,
      fillOnCreate: () => randomUUID(),
      showIn: {
        list: false,
        edit: false,
        create: false,
        show: true,
        filter: false,
      },
    },
    {
      name: 'slug',
      type: AdminForthDataTypes.STRING,
      label: 'Slug',
    },
    {
      name: 'label',
      type: AdminForthDataTypes.STRING,
      label: 'Label',
    },
    {
      name: 'revision',
      type: AdminForthDataTypes.INTEGER,
      label: 'Revision',
      fillOnCreate: () => 1,
      showIn: {
        edit: false,
        create: false,
      },
    },
    {
      name: 'config',
      type: AdminForthDataTypes.JSON,
      label: 'Config',
    },
  ],
} as AdminForthResourceInput;
```

Register this resource in your AdminForth app:

```ts title="./index.ts"
import dashboardConfigsResource from './resources/dashboard_configs.js';

export const admin = new AdminForth({
  // ...
  resources: [
    // ...
    dashboardConfigsResource,
  ],
});
```

### 4. Configure Plugin

Register the plugin in the application's `globalPlugins` array:

```ts title="./globalPlugins.ts"
import DashboardPlugin from '@adminforth/dashboard';

export const globalPlugins = [
  new DashboardPlugin({
    dashboardConfigsResourceId: 'dashboard_configs',
  }),
];
```

#### Control Dashboard Access and Editing Permissions

By default, only users with the `superadmin` role can access dashboards. Use the `editRoles` option to grant dashboard access and editing to other roles:

```ts title="./globalPlugins.ts"
new DashboardPlugin({
  dashboardConfigsResourceId: 'dashboard_configs',
  editRoles: ['superadmin', 'admin'], // allow 'admin' users to edit dashboards too
});
```

Users whose role is not listed in `editRoles` do not see the **Dashboards** sidebar group and receive a `403` response from dashboard configuration and widget-data endpoints. The same role check protects all dashboard mutations on the backend.

Dashboard widget queries also respect the target resource's list access rules. Before loading data, the plugin checks `allowedActions.list`, runs the resource's `list.beforeDatasourceRequest` hooks, and applies any filters added by those hooks. A widget cannot query a column that is `backendOnly` or hidden from the current user with `showIn.list`.

When a query omits `select`, it implicitly requests every column. If the resource contains restricted columns, specify an explicit `select` containing only columns the dashboard users may list. These checks also apply to fields used only for filters, grouping, ordering, buckets, or sparklines.

Then pass it to the AdminForth configuration:

```ts title="./index.ts"
import { globalPlugins } from './globalPlugins.js';

export const admin = new AdminForth({
  // ...
  globalPlugins,
});
```

After `admin.discoverDatabases()` runs, the plugin creates a default dashboard config if the table is empty:

```yaml
version: 1
groups:
  - id: default
    label: Default Group
    order: 1
widgets: []
```

---

## Manual Configuration

If you need to configure dashboards without using the AI Agent, you can do so manually via the AdminForth interface:

1. **Access Dashboards**: Open the **Dashboards** group in the sidebar and choose a dashboard page.
2. **Interactive UI Editor**: Users with a role listed in the plugin's `editRoles` option (defaults to `superadmin`) can add, rename, reorder, and remove groups or widgets directly from the user interface.
3. **YAML Configuration Editor**: The dashboard builder has built-in code editors. When editing a widget or a group manually, you write configurations using a YAML-based DSL.

### Editing dashboard settings

Click the tools icon in the dashboard header to edit the dashboard itself. The YAML editor accepts these fields:

```yaml
label: Sales Overview
slug: sales-overview
icon: flowbite:chart-pie-solid
```

- `label` is the page title and sidebar label.
- `slug` defines the URL at `/dashboard/<slug>`. It must contain only lowercase letters, numbers, and hyphens, and must be unique.
- `icon` is an optional [Iconify](https://icon-sets.iconify.design/) icon name used in the sidebar. Remove the field to use the default dashboard icon.

Saving a changed slug redirects the browser to the new dashboard URL.

For the complete schema specifications of queries, formulas, custom variables, layout fields, and advanced chart configurations, see the **[Dashboard Query Reference](/docs/tutorial/Plugins/dashboard-reference)**.

### Adding new dashboard pages manually

To create a new dashboard page manually, add a new record to your dashboard configs resource (e.g. `dashboard_configs` table in the database):

```yaml title="dashboard_configs.config"
version: 1
icon: flowbite:chart-pie-solid
groups:
  - id: sales
    label: Sales
    order: 1
widgets: []
```

Use a unique `slug`, for example `sales`. The plugin will expose it as `/dashboard/sales` and add it to the **Dashboards** sidebar group.

---

## Dashboard Query Reference


This reference guide details the YAML configuration syntax (DSL) used for widget queries, layout sizing, and calculations in the Dashboard plugin.

## Widget Queries

Widgets load data through `query`. The same query shape supports raw rows, grouped aggregate rows, per-measure filters, ordering, and calculated fields.

```yaml
query:
  resource: cars
  select:
    - field: body_type
      as: body_type
    - agg: count
      as: total_cars
    - agg: avg
      field: price
      as: avg_price
  group_by:
    - body_type
  order_by:
    - field: total_cars
      direction: desc
```

Step-based charts use a `steps` query when each step needs its own resource, measure, and filters. Funnel charts can also use this query shape; like every other chart, they accept a single-resource query as well.

Depending on the widget, `query` can also use `limit`, `offset`, `calcs`, `bucket`, and `formatting`.

Widget-scoped constants can be defined with `variables`. They are available inside `query.calcs` through `lookup($variables.path, field, default)`.

```yaml
label: Average Car Price by Database
target: chart
variables:
  price_multipliers:
    cars_sl: 0.84
    cars_mysql: 1.12
chart:
  type: bar
  x:
    field: name
  y:
    field: adjusted_value
query:
  source: steps
  steps:
    - name: SQLite
      resource: cars_sl
      select:
        - agg: avg
          field: price
          as: value
    - name: MySQL
      resource: cars_mysql
      select:
        - agg: avg
          field: price
          as: value
  calcs:
    - calc: value * lookup($variables.price_multipliers, resource, 1)
      as: adjusted_value
```

Define `variables` on each widget config. Dashboard root variables are not merged into widget data queries.

## Widget Examples

The examples below are widget configs as they appear in the dashboard widget editor. When you edit the whole `dashboard_configs.config` record directly, every widget also needs its persisted `id`, `group_id`, and `order` fields.

### Table

```yaml
label: Latest Cars
target: table
size: wide
height: 360
table:
  columns:
    - model
    - price
    - body_type
    - production_year
  page_size: 10
query:
  resource: cars
  select:
    - field: model
    - field: price
    - field: body_type
    - field: production_year
  order_by:
    - field: production_year
      direction: desc
```

Table widgets use pagination by default. Set `table.page_size` to choose how many rows each request loads, or `table.pagination` to `false` to request all rows at once.

### Pie Chart

```yaml
label: Cars by Body Type
target: chart
size: medium
height: 360
chart:
  type: pie
  label:
    field: body_type
  value:
    field: value
query:
  resource: cars
  select:
    - field: body_type
    - agg: count
      as: value
  group_by:
    - body_type
```

### Bar Chart

```yaml
label: Cars by Production Year
target: chart
size: wide
height: 360
chart:
  type: bar
  x:
    field: production_year
  y:
    field: value
query:
  resource: cars
  select:
    - field: production_year
    - agg: count
      as: value
  group_by:
    - production_year
```

### Chart With Multiple Sources

Use `query.source: steps` when chart data comes from different resources. Each step returns one row with `name`, `resource`, and the selected aggregate aliases.

```yaml
label: Sales Funnel
target: chart
size: large
height: 360
chart:
  type: funnel
  title: Sales funnel
query:
  source: steps
  steps:
    - name: Leads
      resource: leads
      select:
        - agg: count
          as: value
    - name: Qualified
      resource: leads
      select:
        - agg: count
          as: value
      filters:
        and:
          - field: status
            eq: qualified
    - name: Customers
      resource: orders
      select:
        - agg: count_distinct
          field: customer_id
          as: value
```

For the same numeric buckets across multiple resources, add `query.bucket` and render the result as a stacked bar chart. The dashboard runs every step once per bucket and returns rows with `label`, `name`, `resource`, and the aggregate aliases:

```yaml
label: Cars by Price Range and Database
target: chart
size: wide
height: 360
chart:
  type: stacked_bar
  x:
    field: label
  y:
    field: count
  series:
    field: name
query:
  source: steps
  bucket:
    field: price
    buckets:
      - label: Budget
        max: 3500
      - label: Mid-range
        min: 3500
        max: 7000
      - label: Premium
        min: 7000
  steps:
    - name: SQLite
      resource: cars_sl
      select:
        - agg: count
          as: count
    - name: MySQL
      resource: cars_mysql
      select:
        - agg: count
          as: count
```

### KPI Card

```yaml
label: Average Car Price
target: kpi_card
size: small
card:
  value:
    field: value
    prefix: $
query:
  resource: cars
  select:
    - agg: avg
      field: price
      as: value
```

### Gauge Card

```yaml
label: Average Car Price
target: gauge_card
size: small
card:
  value:
    field: value
    suffix: $
  target:
    field: max
  color: '#2563eb'
query:
  resource: cars
  select:
    - agg: avg
      field: price
      as: value
    - agg: max
      field: price
      as: max
```

### Pivot Table

```yaml
label: Cars Summary by Body Type
target: pivot_table
size: full
height: 420
pivot:
  rows:
    - body_type
  values:
    - field: total_cars
    - field: avg_price
query:
  resource: cars
  select:
    - field: body_type
    - agg: count
      as: total_cars
    - agg: avg
      field: price
      as: avg_price
  group_by:
    - body_type
```

Aggregation aliases such as `total_cars` and `avg_price` become table columns.

## Layout

Widgets support these layout fields:

```yaml
size: small
width: 320
height: 360
min_width: 240
max_width: 640
```

`size` can be `small`, `medium`, `large`, `wide`, or `full`. Explicit `width`, `height`, `min_width`, and `max_width` can be used when a widget needs more precise sizing.

---

## CRUD Approve Plugin


The CRUD Approve plugin adds a manual approval step for changes made from the AdminForth back-office. Instead of applying `create`, `edit`, or `delete` operations immediately, selected resources can send these operations to an approval queue. A reviewer can then inspect the JSON diff and either approve or reject the pending change.

This is useful when several administrators can modify important records, but final responsibility for applying changes should stay with a smaller group of trusted users.

The plugin stores approval requests in a separate resource. Each request contains the target resource id, target record id, action type, request status, user who initiated the change, optional responder, old/new record data, and extra request metadata.

[Getting Started](../001-gettingStarted.md) will be used as the base for this example. The protected resource example below extends the `aparts` resource created in the Getting Started tutorial.

## Installation

Install the plugin:

```bash
pnpm add @adminforth/crud-approve-plugin --save
```

To import:

```ts title="./resources/crud_manual_approve.ts"
import CRUDApprovePlugin from '@adminforth/crud-approve-plugin';
import { AdminForthDataTypes, type AdminForthResourceInput } from 'adminforth';
```

> **Note**: An early draft of this plugin documentation used `@adminforth/crud-approve`. The current package name is `@adminforth/crud-approve-plugin`, so the examples below use that package name.

## Create approval table

First, add a table for manual approval requests. If you use the Prisma setup from the Getting Started tutorial, add the model below to `schema.prisma`:

```prisma title="./schema.prisma"
model crud_manual_approve {
  id           String   @id
  record_id    String?
  resource_id  String
  action       String
  data         Json
  user_id      String
  responser_id String?
  status       Int      @default(1)
  created_at   DateTime @default(now())
  extra        Json?

  @@index([status, created_at])
  @@index([resource_id])
}
```

Then run a migration:

```bash
pnpm makemigration --name add-crud-manual-approve ; pnpm migrate:local
```

The `status` column uses numeric values:

- `1` — pending
- `2` — approved
- `3` — rejected

## Create approval resource

Create `crud_manual_approve.ts` in the `resources` folder:

```ts title="./resources/crud_manual_approve.ts"
import CRUDApprovePlugin from '@adminforth/crud-approve-plugin';
import { AdminForthDataTypes, type AdminForthResourceInput } from 'adminforth';

export const crudApprovePlugin = new CRUDApprovePlugin({
  resourceColumns: {
    idColumnName: 'id',
    recordIdColumnName: 'record_id',
    resourceIdColumnName: 'resource_id',
    actionColumnName: 'action',
    dataColumnName: 'data',
    userIdColumnName: 'user_id',
    responserIdColumnName: 'responser_id',
    statusColumnName: 'status',
    createdAtColumnName: 'created_at',
    extraColumnName: 'extra',
  },
});

export default {
  dataSource: 'maindb',
  table: 'crud_manual_approve',
  resourceId: 'crud_manual_approve',
  label: 'CRUD approvals',
  recordLabel: (record: any) => `${record.resource_id} / ${record.action}`,
  columns: [
    {
      name: 'id',
      primaryKey: true,
      showIn: { list: false, show: true, edit: false, create: false },
    },
    {
      name: 'record_id',
      label: 'Record ID',
      showIn: { all: true, edit: false, create: false },
    },
    {
      name: 'resource_id',
      label: 'Resource',
      showIn: { all: true, edit: false, create: false },
    },
    {
      name: 'action',
      enum: [
        { value: 'create', label: 'Create' },
        { value: 'edit', label: 'Edit' },
        { value: 'delete', label: 'Delete' },
      ],
      showIn: { all: true, edit: false, create: false },
    },
    {
      name: 'data',
      type: AdminForthDataTypes.JSON,
      sortable: false,
      showIn: { all: true, edit: false, create: false },
    },
    {
      name: 'user_id',
      label: 'Requested by',
      foreignResource: {
        resourceId: 'adminuser',
      },
      showIn: { all: true, edit: false, create: false },
    },
    {
      name: 'responser_id',
      label: 'Responded by',
      foreignResource: {
        resourceId: 'adminuser',
      },
      showIn: { all: true, edit: false, create: false },
    },
    {
      name: 'status',
      enum: [
        { value: 1, label: 'Pending' },
        { value: 2, label: 'Approved' },
        { value: 3, label: 'Rejected' },
      ],
      showIn: { all: true, edit: false, create: false },
    },
    {
      name: 'created_at',
      type: AdminForthDataTypes.DATETIME,
      allowMinMaxQuery: true,
      showIn: { all: true, edit: false, create: false },
    },
    {
      name: 'extra',
      type: AdminForthDataTypes.JSON,
      showIn: { all: false },
      backendOnly: true,
    },
  ],
  options: {
    listPageSize: 10,
    allowedActions: {
      create: false,
      edit: false,
      delete: false,
      show: async ({ adminUser }: any) => {
        return ['superadmin', 'reviewer'].includes(adminUser.dbUser.role);
      },
      filter: async ({ adminUser }: any) => {
        return ['superadmin', 'reviewer'].includes(adminUser.dbUser.role);
      },
    },
  },
  plugins: [crudApprovePlugin],
} as AdminForthResourceInput;
```

The plugin replaces the default rendering of the `data` column with a diff viewer on list and show pages. For pending requests, the viewer also renders **Approve** and **Reject** actions.

> **Note**: Do not attach the approval interception hook to the `crud_manual_approve` resource itself. This resource is the queue used by the plugin.

## Register approval resource

Import the approval resource in `index.ts` and add it to the AdminForth resource list and menu:

```ts title="./index.ts"
//diff-add
import crudManualApproveResource from './resources/crud_manual_approve.js';

export const admin = new AdminForth({
  ...
  resources: [
    ...
    //diff-add 
    crudManualApproveResource,
  ],
  menu: [
    ...
    //diff-add 
    {
    //diff-add
      label: 'Approvals',
    //diff-add
      icon: 'flowbite:clipboard-check-solid',
    //diff-add
      resourceId: 'crud_manual_approve',
    //diff-add
    },
  ],
});
```

## Send resource changes to approval

Now choose the resource whose changes should require review. The example below protects the `aparts` resource from the Getting Started tutorial. Users can submit changes, but these changes are stored as approval requests instead of being applied immediately.

Open `resources/apartments.ts` and add the helper and hooks below:

```ts title="./resources/apartments.ts"
import { AdminForthDataTypes, type AdminForthResourceInput } from 'adminforth';
//diff-add 
import { crudApprovePlugin } from './crud_manual_approve.js';

//diff-add 
async function sendChangeToApproval({
//diff-add 
  resource,
//diff-add 
  action,
//diff-add 
  record,
//diff-add 
  updates,
//diff-add 
  oldRecord,
//diff-add 
  recordId,
//diff-add 
  adminUser,
//diff-add 
  extra,
//diff-add 
}: any) {
//diff-add 
  // When the CRUD Approve plugin applies an already approved change,
//diff-add 
  // it marks the request with this flag. In that case we must not create
//diff-add 
  // another approval request, otherwise the operation would loop forever.
//diff-add 
  if (extra?.adminforth_plugin_crud_approve?.callingFromApprovalPlugin) {
//diff-add 
    return { ok: true };
//diff-add 
  }
//diff-add
//diff-add 
  const pkColumnName = resource.columns.find((column: any) => column.primaryKey)?.name || 'id';
//diff-add 
  const data = recordId ? { [pkColumnName]: recordId } : record;
//diff-add
//diff-add 
  const result = await crudApprovePlugin.createApprovalRequest({
//diff-add 
    resource,
//diff-add 
    action,
//diff-add 
    data,
//diff-add 
    user: adminUser,
//diff-add 
    record,
//diff-add 
    oldRecord,
//diff-add 
    updates,
//diff-add 
    extra,
//diff-add 
  });
//diff-add
//diff-add 
  if (result.error) {
//diff-add 
    return { ok: false, error: result.error };
//diff-add 
  }
//diff-add
//diff-add 
  // Stop the original mutation. The real create/edit/delete will be executed
//diff-add 
  // later only if a reviewer approves the request.
//diff-add 
  return { ok: true, error: "Action sent for manual approval" };
//diff-add
}

export default {
  dataSource: 'maindb',
  table: 'apartments',
  resourceId: 'aparts',
  label: 'Apartments',
  ...
  columns: [
    ...
  ],
  //diff-add
  hooks: {
  //diff-add
    create: {
  //diff-add
      beforeSave: async (args: any) => {
  //diff-add
        return sendChangeToApproval({ ...args, action: 'create' });
  //diff-add
      },
  //diff-add
    },
  //diff-add
    edit: {
  //diff-add
      beforeSave: async (args: any) => {
  //diff-add
        return sendChangeToApproval({ ...args, action: 'edit' });
  //diff-add
      },
  //diff-add
    },
  //diff-add
    delete: {
  //diff-add
      beforeSave: async (args: any) => {
  //diff-add
        return sendChangeToApproval({ ...args, action: 'delete' });
  //diff-add
      },
  //diff-add
    },
  //diff-add
  },
  options: {
    listPageSize: 10,
    allowedActions: {
      create: true,
      edit: true,
      delete: true,
      show: true,
      filter: true,
    },
  },
} as AdminForthResourceInput;
```

That is it. Now create, edit, and delete operations on `aparts` will create pending records in the `CRUD approvals` resource.

## How approval works

When a user changes a protected resource:

1. The resource `beforeSave` hook calls `crudApprovePlugin.createApprovalRequest(...)`.
2. The original mutation is stopped.
3. A pending approval request is stored in `crud_manual_approve`.
4. A reviewer opens the `Approvals` resource and reviews the diff.
5. If the reviewer rejects the request, only the request status changes to `Rejected`.
6. If the reviewer approves the request, the plugin applies the original create/edit/delete operation and changes the request status to `Approved`.

The plugin also calls the protected resource hooks while applying approved changes. Because of that, the `callingFromApprovalPlugin` guard in the example above is important.

## Protect reviewer access

Who may approve is decided by the `show` permission of the approval resource itself: the plugin resolves `options.allowedActions.show` of the approval resource on every approve and reject request, and rejects the request with `403` if the user is not allowed to see the queue. So the `allowedActions` below is not only a UI matter, it is the actual approval permission and it is enforced on the backend:

```ts title="./resources/crud_manual_approve.ts"
options: {
  allowedActions: {
    create: false,
    edit: false,
    delete: false,
    show: async ({ adminUser }: any) => {
      return ['superadmin', 'reviewer'].includes(adminUser.dbUser.role);
    },
    filter: async ({ adminUser }: any) => {
      return ['superadmin', 'reviewer'].includes(adminUser.dbUser.role);
    },
  },
},
```

You can also use a stricter policy and allow only `superadmin` users to open the approval queue.

The `show` callback receives the usual `{ adminUser, resource, meta, source, adminforth }` arguments, and for approve/reject calls `meta` contains the approval request being reviewed (`meta.record`) and its primary key (`meta.pk`). This allows granular policies, for example letting reviewers approve requests for some resources only:

```ts title="./resources/crud_manual_approve.ts"
show: async ({ adminUser, meta }: any) => {
  if (adminUser.dbUser.role === 'superadmin') {
    return true;
  }
  return adminUser.dbUser.role === 'reviewer' && meta?.record?.resource_id !== 'adminuser';
},
```

### Separation of duties

On top of the `show` check, the plugin does not allow a user to approve or reject a request he created himself, so the four-eyes principle holds even if requester and reviewer share the same role. If you really need to allow self-approval (for example in a single-admin development setup), pass `allowSelfApproval: true`:

```ts title="./resources/crud_manual_approve.ts"
export const crudApprovePlugin = new CRUDApprovePlugin({
  resourceColumns: { ... },
  // do not use in production: makes the four-eyes principle void
  allowSelfApproval: true,
});
```

## Optional: require 2FA before applying approved changes

If your application already uses the Two-Factor Authentication plugin, you can verify the confirmation result before the approved change is applied. Frontend confirmation alone is not a security boundary, so the backend must still verify the confirmation result in a protected resource hook.

The approval request handler passes approval request data through `extra.body`. If your approval UI sends a 2FA confirmation result in `meta.confirmationResult`, you can verify it before allowing the approved operation to continue.

```ts title="./resources/apartments.ts"
async function verifyApproval2FA({ adminUser, adminforth, extra }: any) {
  if (!extra?.adminforth_plugin_crud_approve?.callingFromApprovalPlugin) {
    return { ok: true };
  }

  const confirmationResult = extra?.body?.meta?.confirmationResult;
  if (!confirmationResult) {
    return { ok: false, error: 'Two-factor confirmation is required to approve this change' };
  }

  const t2fa = adminforth.getPluginByClassName('TwoFactorsAuthPlugin');
  if (!t2fa) {
    return { ok: false, error: 'TwoFactorsAuthPlugin is not configured' };
  }

  const verifyRes = await t2fa.verify(confirmationResult, {
    adminUser,
    userPk: adminUser.pk,
    extra,
  });

  if (!verifyRes?.ok) {
    return { ok: false, error: verifyRes?.error || 'Two-factor verification failed' };
  }

  return { ok: true };
}
```

Then call this check before `sendChangeToApproval` in the same protected resource hooks:

```ts title="./resources/apartments.ts"
hooks: {
  edit: {
    beforeSave: async (args: any) => {
      const twoFaResult = await verifyApproval2FA(args);
      if (twoFaResult.error) {
        return twoFaResult;
      }

      return sendChangeToApproval({ ...args, action: 'edit' });
    },
  },
},
```

For `create` and `delete`, use the same pattern and pass `action: 'create'` or `action: 'delete'`.

## Customizing approval data

The plugin stores `oldRecord` and `newRecord` in the `data` JSON column. This makes the pending request easy to inspect in the diff viewer.

You can pass additional metadata through `extra` when creating the approval request:

```ts title="./resources/apartments.ts"
const result = await crudApprovePlugin.createApprovalRequest({
  resource,
  action: 'edit',
  data: { id: recordId },
  user: adminUser,
  oldRecord,
  updates,
  extra: {
    ...extra,
    reason: 'Submitted from editorial workflow',
    source: 'admin-panel',
  },
});
```

This is useful when you want to keep extra audit context, for example request source, UI flow, or a business reason entered by the user.

## Using with several resources

The same approval queue can be reused for multiple resources. Add the `sendChangeToApproval` hook to every resource that must be reviewed:

```ts title="./resources/products.ts"
hooks: {
  create: {
    beforeSave: async (args: any) => sendChangeToApproval({ ...args, action: 'create' }),
  },
  edit: {
    beforeSave: async (args: any) => sendChangeToApproval({ ...args, action: 'edit' }),
  },
  delete: {
    beforeSave: async (args: any) => sendChangeToApproval({ ...args, action: 'delete' }),
  },
},
```

Each approval request stores its `resource_id`, so reviewers can see which resource the request belongs to.

## Troubleshooting

### The approval request is created, but the original change is also applied

Make sure your protected resource hook returns:

```ts
return { ok: false, error: null };
```

This stops the original mutation and leaves the change pending for review.

### Approved changes create another approval request

Make sure `sendChangeToApproval` starts with the guard below:

```ts
if (extra?.adminforth_plugin_crud_approve?.callingFromApprovalPlugin) {
  return { ok: true };
}
```

Without this guard, the approved operation can be intercepted again by the same hook.

### Diff viewer is not shown

Check that:

1. the plugin is installed on the approval resource;
2. `dataColumnName` points to a JSON column;
3. the `resourceColumns` mapping matches real column names in the approval table.

### Approve or reject button is not visible

Approve and reject controls are shown only for requests with `status = 1`.

### Approve or reject returns "You are not allowed to ..."

The reviewer did not pass the `canApprove` check, or he is the author of the request himself. Both checks run on the backend for every approve/reject call. See [Protect reviewer access](#protect-reviewer-access).

### Reviewers cannot open the approval resource

Check `options.allowedActions` on the approval resource. The examples above allow only users with `superadmin` or `reviewer` role to show and filter approval requests.

---

## JSON Form


The JSON Form plugin renders a rich, schema-driven form for a **JSON** column instead of the default raw text area. You describe the shape of the data with a JSON Schema (extended with a few `x-*` keywords for layout and validation messages) and the form is generated by [**jedison**](https://germanbisurgi.github.io/jedison-docs/), a JSON-Schema form generator, mounted inside the AdminForth create/edit views.

## Installation

```bash
pnpm add @adminforth/json-form --save
```

## Setting up

The plugin works **only with `json` columns**. If the target column is not of type `json`, the plugin throws during config validation.

First, update the schema:

```title="./schema.prisma"
model apartments {
      ...
  //diff-add
  config    Json? 
}
```
and make a migration:

```bash
pnpm makemigration --name add-apartment-config; pnpm migrate:local
```

Then make sure the target column is declared with the `json` datatype:

```ts title="./resources/apartments.ts"
import { AdminForthDataTypes } from 'adminforth';

export default {
  ...
  columns: [
    ...
//diff-add
    {
//diff-add
      name: 'config',
//diff-add
      type: AdminForthDataTypes.JSON,   // required: must be JSON
//diff-add
      label: 'Config',
//diff-add
    },
  ],
}
```

And finally import and attach the plugin, passing the field name and a schema:

```ts title="./resources/apartments.ts"
//diff-add
import JsonFormPlugin from '@adminforth/json-form';

export default {
  ...
  plugins: [
    ...
//diff-add
    new JsonFormPlugin({
//diff-add
      fieldName: 'config',
//diff-add
      schema: {
//diff-add
        title: 'RPG Character Creator',
//diff-add
        description: 'Create and customize your adventurer',
//diff-add
        type: 'object',
//diff-add
        'x-format': 'nav-vertical',
//diff-add
        properties: {
//diff-add
          identity: {
//diff-add
            title: 'Identity',
//diff-add
            type: 'object',
//diff-add
            'x-format': 'grid',
//diff-add
            required: ['name'],
//diff-add
            properties: {
//diff-add
              name: {
//diff-add
                title: 'Name',
//diff-add
                type: 'string',
//diff-add
                minLength: 2,
//diff-add
                'x-grid': { columns: 6 },
//diff-add
                'x-messages': { required: 'Every adventurer needs a name!' },
//diff-add
                default: 'Thalion Oakenshield',
//diff-add
              },
//diff-add
              // ...
//diff-add
            },
//diff-add
          },
//diff-add
          // ...
//diff-add
        },
//diff-add
      },
//diff-add
    }),
  ],
}
```

The same form is rendered in both the create and edit views for the `config` field.

## Key-value renderer

Since using JSON as key-value storage is a popular use case, the JSON Form plugin provides a custom key-value editor:

```js title="schema example"
schema: {
  "title": "Specifications",
  "type": "object",
  "additionalProperties": {
      "type": "string"
  }
}
```

![Key-value editor](json-form-key-value-editor.png)

Any object that declares no `properties` and does not set `additionalProperties: false` is rendered this way by default, so no extra keyword is needed to opt in. Rows are added inline, without a popup: the new key starts empty and gets the focus, the key itself is applied when the input loses focus or on `Enter`, and the trash button removes the entry right away. Renaming a key to one that already exists is refused with an inline message.

The value cell holds the regular editor for whatever `additionalProperties` describes, so values are not limited to strings — nested objects and arrays work too, and keep their own formatting and validation rules.

---

## Plugin development guide


Creating a plugin is a powerful way to extend AdminForth functionality.

## Concepts

Every plugin is installed to resource.

Every plugin simply does modification of AdminForth config which developer passed on AdminForth initialization. 

Plugin can modify both config of resource where it is installed or whole global config.

To perform modification plugin defines a method `modifyResourceConfig` which accepts `config` object. The `modifyResourceConfig` method called after first config validation and preprocessing. 

Also plugins can define custom components and custom APIs.

## Boilerplate

Let's create plugin which auto-completes text in strings

```bash
mkdir -p af-plugin-chatgpt
cd af-plugin-chatgpt
npx adminforth create-plugin
```

CLI options:

* **`--plugin-name`** - name for your plugin.

This command will:
1. Set up the TypeScript configuration
2. Create initial plugin files
3. Install required dependencies

The CLI will create the following files and directories:

```text
af-plugin-chatgpt/
├── custom
│   └── tsconfig.json     # TypeScript configuration for custom components
├── index.ts              # Main plugin file with boilerplate code
├── package.json          # Plugin package configuration
├── tsconfig.json         # TypeScript configuration
└── types.ts              # TypeScript types for your plugin

```

This is very important step! (otherwise some features like method redefinition might blindly fail).

## Creating plugin logic

In previous section we created boilerplate which is a must for every plugin. 
Now let's implement plugin logic. 

First of all we want one plugin installation to be able to set custom Vue component on create and edit pages.

In plugin options we will pass field name and `OPENAI_API_KEY`.

```ts title='./af-plugin-chatgpt/types.ts'
import  {type PluginsCommonOptions } from "adminforth";

export interface PluginOptions extends PluginsCommonOptions {

//diff-add
  /**
//diff-add
   * Field where plugin will auto-complete text. Should be string or text field.
//diff-add
   */
//diff-add
  fieldName: string;

//diff-add
  /**
//diff-add
   * OpenAI API key. Go to https://platform.openai.com/, go to Dashboard -> API keys -> Create new secret key
//diff-add
   * Paste value in your .env file OPENAI_API_KEY=your_key
//diff-add
   * Set openAiApiKey: process.env.OPENAI_API_KEY to access it
//diff-add
   */
//diff-add
  openAiApiKey: string;

//diff-add
  /**
//diff-add
   * Model name. Go to https://platform.openai.com/docs/models, select model and copy name.
//diff-add
   * Default is `gpt-5-nano`. Use e.g. more expensive `gpt-5.2` for more powerful model.
//diff-add
   */
//diff-add
  model?: string;

//diff-add
  /**
//diff-add
   * Expert settings
//diff-add
   */
//diff-add
  expert?: {

//diff-add
    /**
//diff-add
     * Number of tokens to generate. Default is 50. 1 token ~= ¾ words 
//diff-add
     */
//diff-add
    maxTokens?: number;
//diff-add
  }

}
```

We will use `vue-suggestion-input` package in our frontend component. 
To install package into frontend component, first of all we have to initialize npm package in custom folder:

```bash
cd af-plugin-chatgpt/custom
pnpm init -y
```

Now install our dependency:

```bash
pnpm i vue-suggestion-input -D
```

Create file `completionInput.vue`:

```html title='./af-plugin-chatgpt/custom/completionInput.vue'
<template>
  <SuggestionInput 
    class="bg-gray-50 border border-gray-300 text-gray-900 text-sm rounded-lg focus:ring-blue-500 
      focus:border-blue-500 block w-full p-2.5 dark:bg-gray-700 dark:border-gray-600 dark:placeholder-gray-400
      dark:text-white dark:focus:ring-blue-500 dark:focus:border-blue-500 whitespace-normal"
      v-model="currentValue"
      :type="column.type"
      :completionRequest="complete"
      :debounceTime="meta.debounceTime"
    />
</template>

<script setup lang="ts">
import { ref, onMounted, watch, Ref  } from 'vue';
import { callAdminForthApi } from '@/utils';
import type { AdminForthColumnCommon } from '@/types/Common';
import SuggestionInput from 'vue-suggestion-input';
import 'vue-suggestion-input/dist/style.css';

const props = defineProps<{
  column: AdminForthColumnCommon,
  record: any,
  meta: any,
}>();

const emit = defineEmits([
  'update:value',
]);

const currentValue: Ref<string> = ref('');

onMounted(() => {
  currentValue.value = props.record[props.column.name] || '';
});

watch(() => currentValue.value, (value) => {
  emit('update:value', value);
});

watch(() => props.record, (value) => {
  currentValue.value = value[props.column.name] || '';
});

async function complete(textBeforeCursor: string) {
  const res = await callAdminForthApi({
      path: `/plugin/${props.meta.pluginInstanceId}/doComplete`,
      method: 'POST',
      body: {
        record: {...props.record, [props.column.name]: textBeforeCursor},
      },
  });

  return res.completion;
}
</script>

```

As you can see we call API endpoint `/plugin/${props.meta.pluginInstanceId}/doComplete` to get completion. 

> For all your API calls from your own plugins we recommend to use same url format which includes pluginInstanceId. This way you can be sure that your API calls are unique for each plugin installation.

Let's define API endpoint in our plugin:

```ts title='./af-plugin-chatgpt/index.ts'
  setupEndpoints(server: IHttpServer) {
    server.endpoint({
      method: 'POST',
//diff-remove
      path: `/plugin/${this.pluginInstanceId}/example`,
//diff-add
      path: `/plugin/${this.pluginInstanceId}/doComplete`,
      handler: async ({ body }) => {
//diff-remove
        const { name } = body;
//diff-remove
        return { hey: `Hello ${name}` };
//diff-add
        const { record } = body;
//diff-add
        let currentVal = record[this.options.fieldName];
//diff-add
        const promptLimit = 500;
//diff-add
        if (currentVal && currentVal.length > promptLimit) {
//diff-add
          currentVal = currentVal.slice(-promptLimit);
//diff-add
        }
//diff-add
        const resLabel = this.resourceConfig.label;
//diff-add
        let content;
//diff-add
        if (currentVal) {
//diff-add
          content = `Continue writing for text/string field "${this.options.fieldName}" in the table "${resLabel}"\n` +
//diff-add
              `Current field value: ${currentVal}\n` +
//diff-add
              "Don't talk to me. Just write text. No quotes. Don't repeat current field value, just write completion\n";
//diff-add
        } else {
//diff-add
          content = `Fill text/string field "${this.options.fieldName}" in the table "${resLabel}"\n` +
//diff-add
              "Be short, clear and precise. No quotes. Don't talk to me. Just write text\n";
//diff-add
        }
//diff-add
        const resp = await fetch('https://api.openai.com/v1/chat/completions', {
//diff-add
          method: 'POST',
//diff-add
          headers: {
//diff-add
            'Content-Type': 'application/json',
//diff-add
            'Authorization': `Bearer ${this.options.openAiApiKey}`
//diff-add
          },
//diff-add
          body: JSON.stringify({
//diff-add
            model: this.options.model || 'gpt-5-nano',
//diff-add
            messages: [{ role: 'user', content, }],
//diff-add
            temperature: 0.7,
//diff-add
            max_tokens: this.options.expert?.maxTokens || 50,
//diff-add
            stop: ['.'],
//diff-add
          })
//diff-add
        });
//diff-add
        const data = await resp.json();
//diff-add
        if (!data.choices) {
//diff-add
              throw new Error(`Wrong response from OpenAI ${JSON.stringify(data)}`)
//diff-add
        }
//diff-add
        let suggestion = data.choices[0].message.content + (
//diff-add
          data.choices[0].finish_reason === 'stop' ? (
//diff-add
            this.columnType === AdminForthDataTypes.TEXT ? '. ' : ''
//diff-add
          ) : ''
//diff-add
        );
//diff-add
        if (suggestion.startsWith(currentVal)) {
//diff-add
          suggestion = suggestion.slice(currentVal.length);
//diff-add
        }
//diff-add
        if (suggestion.startsWith(currentVal)) {
//diff-add
          suggestion = suggestion.slice(currentVal.length);
//diff-add
        }
//diff-add
        const wordsList = suggestion.split(' ').map((w, i) => {
//diff-add
          return (i === suggestion.split(' ').length - 1) ? w : w + ' ';
//diff-add
        });
//diff-add
        return { completion: wordsList };
//diff-add
      }
      })
    }
```

Now we have to set custom input on create and edit pages for field which user defined in fieldName:

```ts title='./af-plugin-chatgpt/index.ts'

export default class ChatGptPlugin extends AdminForthPlugin {
  options: PluginOptions;

//diff-add
  resourceConfig!: AdminForthResource;
//diff-add
  columnType!: AdminForthDataTypes;

  ...

  async modifyResourceConfig(adminforth: IAdminForth, resourceConfig: AdminForthResource) {
    super.modifyResourceConfig(adminforth, resourceConfig);

//diff-add
    // ensure that column exists
//diff-add
    const column = resourceConfig.columns.find(f => f.name === this.options.fieldName);
//diff-add
    if (!column) {
//diff-add
      throw new Error(`Field ${this.options.fieldName} not found in resource ${resourceConfig.label}`);
//diff-add
    }
//diff-add
    if (!column.components) {
//diff-add
      column.components = {};
//diff-add
    }
//diff-add
    const filed = {
//diff-add
      file: this.componentPath('completionInput.vue'),
//diff-add
      meta: {
//diff-add
        pluginInstanceId: this.pluginInstanceId,
//diff-add
        fieldName: this.options.fieldName,
//diff-add
        debounceTime: 300,
//diff-add
      }
//diff-add
    }
//diff-add
    column.components.create = filed;
//diff-add
    column.components.edit = filed;
//diff-add
    this.columnType = column.type!;
  }

```

Additionally we should check that column type is string or text, otherwise our input will not work properly. 
From first sight we can make this validation in modifyResourceConfig method, but it is not good idea because we can't be sure that column type is
defined and known at this stage. If user defined it manually then it will be there, but if type is auto-discovered then it will be undefined at this stage.

That is why we will use `validateConfigAfterDiscover` method:

```ts title='./af-plugin-chatgpt/index.ts'
  validateConfigAfterDiscover(adminforth: IAdminForth, resourceConfig: AdminForthResource) {
//diff-add
    const column = this.resourceConfig.columns.find(f => f.name === this.options.fieldName);
//diff-add
    if (![AdminForthDataTypes.STRING, AdminForthDataTypes.TEXT].includes(column!.type!)) {
//diff-add
      throw new Error(`Field ${this.options.fieldName} should be string or text type, but it is ${column!.type}`);
//diff-add
    }
//diff-add
    // any validation better to do here e.g. because bundleNow might no have enough environment
//diff-add
    if (!this.options.openAiApiKey) {
//diff-add
      throw new Error('OPENAI_API_KEY is required');
//diff-add
    }
  }
```

Finally, since we want to support multiple installations on one resource (e.g. one plugin installation for `title` field and another for `description` field), we have to define plugin instance unique representation. Best idea in this case to use field name which will be different for each installation:

```ts title='./af-plugin-chatgpt/index.ts'
  instanceUniqueRepresentation(pluginOptions: any) : string {
//diff-add
    return `${pluginOptions.fieldName}`;
//diff-remove
    return `single`;
  }
```

To compile plugin run:

```bash
pnpm build
```

You can also publish your plugin to npm using `pnpm publish`.

## Installation of plugin

If you want to test your plugin locally before publishing, enter plugin dir and run:

```bash
cd af-plugin-chatgpt
pnpm link
```

Then enter your AdminForth project and run:

```bash
pnpm link af-plugin-chatgpt
```

Now  in your app `index.ts` file:

```ts title='./index.ts'

import ChatGptPlugin from 'af-plugin-chatgpt';

...

{
  resourceId: 'aparts',
  ...
  plugins: [
    ...
    new ChatGptPlugin({
      openAiApiKey: process.env.OPENAI_API_KEY as string,
      fieldName: 'title',
    }),
    new ChatGptPlugin({
      openAiApiKey: process.env.OPENAI_API_KEY as string,
      fieldName: 'description',
    }),
  ]
}

```

Go to https://platform.openai.com/, go to Dashboard -> API keys -> Create new secret key. Paste value in your `.env` file OPENAI_API_KEY=your_key

> ☝️ Using `pnpm link` approach still requires `pnpm build` in plugin dir after each change because plugin entry point is defined as `dist/index.js` in
> `package.json` file. To speed up plugin development you can also don't use `pnpm link` and just import plugin main file from your demo file:
> ```
> import ChatGptPlugin from '<path to af plugin>/af-plugin-chatgpt/index.js';
> ```

> 🎓 Homework 1: Extend `expert` settings section to include next parameters: `temperature`, `promptLimit`, `debounceTime`,

> 🎓 Homework 2: Plugin does not pass record other values to Chat GPT which can help to create better prompts with context understanding.
> Try to adjust prompt to include other record values. Keep in mind that longer prompts can be more expensive and slower, so should smartly limit prompt length.

## Configuring plugin activation order

By default all plugins are activated in random order. 

Rarely, it might happen that your plugin somehow depends on other plugins (e.g. default AdminForth rich text editor plugin depends on AdminForth upload file to support images in text).

To control plugin activation order you can set `activationOrder` property in plugin class:

```ts title='./af-plugin-chatgpt/index.ts'
export default class ChatGptPlugin extends AdminForthPlugin {
  options: PluginOptions;

  activationOrder = 100;

  ...
}
```

Default value of activationOrder for most plugins is `0`. Plugins with higher activationOrder will be activated later.

To ensure that plugin activates before some other plugins set `activationOrder` to negative value.

## Making plugin global

Each plugin should define a scope: resource-level or global level. 
* Resource-level plugins should be used when plugin instance works only with one resource config or it's fields. Instances of resource-scope plugins should be installed into "plugins' field of resource config. 
* All other plugins should be global-scoped. Such plugins are installed to `globalPlugins` of root adminforth config. They might modify configs of many resources like default AuditLog plugin or use several database resources to store data like default Agent plugin.

To make your plugin global, you need to use `pluginsScope: 'global'` and `modifyGlobalConfig` instead of `modifyResourceConfig`

```ts title="./your-global-plugin/index.ts"

  ...

  export default class YourPugin extends AdminForthPlugin {
    options: PluginOptions;
    //diff-add
    pluginsScope: 'global'

  ...

  //diff-remove
  async modifyResourceConfig(adminforth: IAdminForth, resourceConfig: AdminForthResource) {
    //diff-remove
    super.modifyResourceConfig(adminforth, resourceConfig);
  //diff-add
  modifyGlobalConfig(adminforth: IAdminForth) {
    //diff-add
    super.modifyGlobalConfig(adminforth);

  }

  ...
  
```

## Splitting frontend logic into multiple files

In case your plugin `.vue` files getting too big, you can split them into multiple files (components).

Just create a new file `subComponent.vue` in `custom` folder and add your code there. 

Then import it as a component:

```html title='./af-plugin-chatgpt/custom/completionInput.vue'
<template>
  ...
//diff-add
  <SubComponent />
  ...
</template>

<script setup lang="ts">
//diff-add
import SubComponent from './subComponent.vue';
</script>
```

## Using Adapters

There are couple of adapter interfaces in AdminForth like `EmailAdapter` for sending emails and `CompletionAdapter`.
Adapter is a way to provide same function from different vendors. For example plugin created in this guide uses exactly OpenAI API to get completion.
But in fact OpenAI is not only one API provider for completion, so `CompletionAdapter` interface is created to be easily extended. 
Here is code from AdminForth:

```ts
export interface CompletionAdapter {

  validate();

  complete(request: {
    content: string;
    maxTokens: number;
    outputSchema?: any;
    reasoningEffort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
    tools?: CompletionTool[];
    onChunk?: (
      chunk: string,
      event?: {
        type: 'output' | 'reasoning';
        delta: string;
        text: string;
        source?: 'summary' | 'text';
      },
    ) => void | Promise<void>;
  }): Promise<{
    content?: string;
    finishReason?: string;
    error?: string;
  }>;
}
```

To use adapter in plugin you should define it in plugin options:

```ts title='./af-plugin-any-complete/types.ts'

import { CompletionAdapter, type PluginsCommonOptions } from "adminforth";

export interface PluginOptions extends PluginsCommonOptions{
  ...

//diff-add
  /**
//diff-add
   * Adapter for completion
//diff-add
   */
//diff-add
  adapter: CompletionAdapter;
}
```

Then, in your plugin you should call `this.options.validate()`, this function will throw error if adminforth app developer did not pass
required parameter (e.g. API token for OpenAI). You can do it in `modifyResourceConfig` but, then it will be called at build time (e.g. in Dockerfile). However build time not always has access to all environment variables including `OPENAI_API_KEY`.

So we recommend calling validation in `validateConfigAfterDiscover` method because it called only in runtime on app start and not in build time.

```ts title='./af-plugin-any-complete/index.ts'
  validateConfigAfterDiscover(adminforth: IAdminForth, resourceConfig: AdminForthResource) {
//diff-add
    this.options.adapter.validate();

    ...
  }
```

If some issue with config will happen, validate method will throw error and instance will be crashed so AdminForth app developer will see error message in console and will have to fix it before starting app.

Now you can simply use adapter:

```ts title='./af-plugin-any-complete/index.ts'
handler: async (a) => {
  ...
  const resp = await this.options.adapter.complete({
    content,
    maxTokens: this.options.expert?.maxTokens || 50,
  });
  ...
}
``` 
## Providing a frontend API
If a plugin needs to provide an external frontend API so user code or other plugins can interact with it, you can create a .ts file or a global Pinia store (if you want to have some global variables or use plugin modals) and then re-use it in your frontend logic. For example:

1) Create new `./custom/useChatGptApi.ts` and `./custom/customModal` files
```text
af-plugin-chatgpt/
├── custom
│   └── tsconfig.json
|   └── completionInput.vue
//diff-add
|   └── useChatGptApi.ts
//diff-add
|   └── customModal.vue
├── index.ts
├── package.json
├── tsconfig.json
└── types.ts
```

2) Write your custom logic:

```ts title="./custom/useChatGptApi.ts"
import { ref } from 'vue';
import { callAdminForthApi } from '@/utils';
import { defineStore } from 'pinia'

export const useChatGptApi = defineStore('chatGptApi', () => {
  const isCustomModalOpened = ref(false);
  const customModalData = ref({})
  
  function openCustomModal(modalData) {
    customModalData.value = modalData;
    isCustomModalOpened.value = true;
  }

  function closeCustomModal() {
    isCustomModalOpened.value = false;
  }

  async function doComplete(pluginInstanceId, record, columnName, textBeforeCursor) {
    const res = await callAdminForthApi({
      path: `/plugin/${pluginInstanceId}/doComplete`,
      method: 'POST',
      body: {
        record: { ...record, [columnName]: textBeforeCursor },
      },
    });

    return res.completion;
  }

  return {
    isCustomModalOpened,
    customModalData,
    openCustomModal,
    closeCustomModal,
    doComplete
  }
```

3) If you want your plugin to have its own modal API, then first of all you'll need to inject this component somewhere so you can open it:

```ts title="./index.ts"

async modifyResourceConfig(adminforth: IAdminForth, resourceConfig: AdminForthResource) {

...

  // Global API injection: exposes openCustomModal(...) to open chatGptModal from anywhere
  (adminforth.config.customization.globalInjections.header).push({
    file: this.componentPath('customModal.vue'),
    meta: {
      pluginInstanceId: this.pluginInstanceId,
    }
  });

...

}

```

and:

```html title="customModal.vue"
<template>
  <!-- Hidden component that registers a global function to open job info modal -->
  <Modal 
    ref="dialogRef" 
    removeFromDomOnClose 
    class="p-4"
    :beforeCloseFunction="() => { chatGpt.closeCustomModal(); }"
  >
    
      ***Modal content***
      {{ chatGpt.customModalData }}
    
</template>

<script setup lang="ts">
  import { ref, onMounted, onBeforeUnmount, watch } from 'vue';
  import { Modal } from '@/afcl';
  import { useChatGptApi } from './useChatGptApi';

  const chatGpt = useChatGptApi();
  const dialogRef = ref<any>(null);

  const props = defineProps<{
    meta: {
      pluginInstanceId: string;
    }
  }>();

  watch(() => chatGpt.isCustomModalOpened, (newVal) => {
    if (newVal) {
      dialogRef.value?.open?.();
    } else {
      dialogRef.value?.close?.();
    }
  });
</script>

```

4) Re-use this api in your component:

```html
  <template>
    ...
  </template>

  <script setup>
    //diff-add
    import { useChatGptApi } from '@/custom/plugins/ChatGptPlugin/useChatGptApi';
    ...
  </script>
```

### How to get the plugin file path from a custom component

`ChatGptPlugin` is the class name that is defined inside `index.ts`.
So if we want to access plugin files from a custom component, we should use the path:
>`@/custom/plugins/*Plugin class name*/*File name*`

## How to add files to the public folder of spa

There might be cases, when you'll need to add some files, like icons or audio files to the public folder of spa.

To do so, you need in custom folder create `public` folder like:
`plugins/custom/public/...`

```text
plugin/
├── custom
│   ├── public/

```

And then, in bundled spa folder, files will be stored in path:

`spa/public/plugins/**your plugin class name**/`

---

## Working without direct database connection


Out of the box, AdminForth connects directly to your database using one of the supported drivers (PostgreSQL, MySQL, ClickHouse, MongoDB) and executes queries against it.

In some cases, you may not want to expose a direct database connection to AdminForth. Instead, you may prefer to allow AdminForth to access and modify data through your own APIs (for example, REST, GraphQL, or JSON-RPC).

With this approach, AdminForth never connects to the database and never even knows its URL. All read and write operations go through your API layer.

Why do this?

- Your API may enforce additional constraints or validation rules.

- You can precisely log all operations using your own logging or audit systems. (The built-in AuditLog tracks data modifications only and does not log read operations.)

- Your API may contain custom logic, such as distributed workflows or complex data-modification rules.

To implement this, you need to extend the data connector class and implement a small set of methods responsible for data access and mutations.

This example demonstrates how to do this using GraphQL, but the same approach can be adapted to REST or any other protocol. The code comments include detailed guidance for these cases.

Another reason to create a custom data source adapter is to support a database that AdminForth does not yet support. In that case, you are welcome to submit a pull request to AdminForth to add native support for that database.