identity-admin 1.28.28 → 1.28.29

package/skills/identity-admin/SKILL.md

@@ -0,0 +1,272 @@
+---
+name: identity-admin
+description: Use when setting up or configuring the identity-admin dashboard, creating or editing resource files, troubleshooting admin dashboard behavior, or integrating identity-admin plugins
+---
+
+<SUBAGENT-STOP>
+If you were dispatched as a subagent to execute a specific task, skip this skill.
+</SUBAGENT-STOP>
+
+# identity-admin
+
+## Overview
+
+`identity-admin` is an Express + Mongoose package that auto-generates a full admin dashboard (REST API + React Material UI frontend) from simple resource file definitions. You define the models and field configurations, and the dashboard handles CRUD, filters, permissions, notifications, reports, and imports.
+
+## When to Use
+
+- Installing `identity-admin` in a new or existing Express + Mongoose project
+- Creating or editing **resource files** (`IResourceFile`) that describe how a Mongoose model appears in the dashboard
+- Configuring dashboard authentication (session-based with cookies)
+- Adding custom CRUD hooks (before/after handlers)
+- Defining custom actions, filter scopes, or field overrides
+- Setting up the permissions plugin or admin notifications plugin
+- Troubleshooting missing resources, auth failures, or incorrect field display
+
+## Installation
+
+```bash
+npm i identity-admin
+```
+
+Requires `mongoose`, `express`, and `inversify` (with `inversify-express-utils`) in your project.
+
+## Quick Start — Unauthenticated Dashboard
+
+```typescript
+import Dashboard from 'identity-admin';
+import { IResourceFile } from 'identity-admin/lib/types/IResourceFile';
+import MyModel from './models/MyModel';
+
+const myResource: IResourceFile = {
+  properties: {
+    resource: MyModel,
+    modelName: 'mymodel',
+    name: 'My Model',
+    title: 'name',
+  },
+  listProperties: ['name', 'createdAt'],
+  formProperties: ['name', 'description'],
+};
+
+const dashboard = new Dashboard({ resources: [myResource] });
+
+// After mongoose.connect(...)
+dashboard.build(app);
+```
+
+The dashboard is now available at `/dashboard`.
+
+## Dashboard Configuration (`DashboardConfig`)
+
+```typescript
+interface DashboardConfig {
+  resources: IResourceFile[];       // required — array of resource definitions
+  rootPath?: string;                // default "/dashboard"
+  configurations?: IConfiguartionFile;
+  localesOptions?: i18n.ConfigurationOptions;
+  cookiesConfiguration?: CookieConfiguration;
+  authenticate?: AuthenticateMiddleWare;
+}
+```
+
+## Resource Files — Quick Reference
+
+A resource file (`IResourceFile`) tells the dashboard how to handle a Mongoose model. The two required properties are:
+
+```typescript
+properties: {
+  resource: Model<any, any>;   // the Mongoose model
+  modelName: string;           // collection name in the database
+}
+```
+
+Common optional properties:
+
+| Property | Purpose |
+|----------|---------|
+| `properties.name` | Display name in the nav bar (defaults to `modelName`) |
+| `properties.title` | Field used as the record link and search target (defaults to `name`, `title`, or `email`; falls back to `_id`) |
+| `properties.parent` | Nav group: `{ name: string, icon: string }` (MUI icon names) |
+| `properties.isAllowed` | `(currentUser) => boolean` — permission gate |
+| `properties.isVisible` | `(currentUser) => boolean` — nav bar visibility |
+| `properties.hiddenProperties` | Array of field names to hide entirely |
+| `properties.defaultOrderBy` / `defaultOrder` | Sort field and direction |
+| `properties.defaultrowsPerPage` | Pagination size (default 10) |
+
+**Display arrays** control which fields appear on each page:
+
+- `listProperties` — table columns in the list view
+- `showProperties` — read-only detail view
+- `formProperties` — create/edit form fields
+- `filterProperties` — advanced filter fields
+- `quickFilterProperties` — quick filter chips
+
+> **For the complete resource file interface reference — all field overrides, virtuals, actions, filters, CRUD hooks, population, and localization options — read `resource-file.md`.**
+
+## Authenticated Dashboard
+
+Add session-based authentication with cookies:
+
+```typescript
+const dashboard = new Dashboard({
+  resources: [myResource],
+  cookiesConfiguration: {
+    cookiesSecret: "your-secret",
+    cookieName: "connect.sid"
+  },
+  authenticate: async (credentials: AdminCredentials) => {
+    const user = await Admin.findOne({ email: credentials.email });
+    if (user) {
+      const matched = await bcrypt.compare(credentials.password, user.encryptedPassword);
+      if (matched) return user;
+    }
+    return false;
+  }
+});
+```
+
+## App Configuration (`IConfiguartionFile`)
+
+```typescript
+interface IConfiguartionFile {
+  textFieldSize?: 'small' | 'medium';
+  defaultRowsPerPage?: number;
+  themeLayout?: 'mini' | 'vertical' | 'horizontal';
+  themeStretch?: boolean;
+  showMainActions?: boolean;
+  adminNotifications?: boolean;
+  baseApiUrl?: string;
+  enableLocalization?: boolean;
+  disableDuplicateAction?: boolean;
+  enablePermissions?: boolean;
+}
+```
+
+Pass it via `configurations` in `DashboardConfig`.
+
+## Custom Actions
+
+Add extra record or resource actions:
+
+```typescript
+actions: {
+  extras: [{
+    key: 'approve',
+    name: 'Approve',
+    icon: 'CheckCircle',
+    actionType: 'record',           // 'record' | 'resource'
+    handler: async (req, res, data) => {
+      data.record.status = 'approved';
+      await data.record.save();
+      return { action: 'LIST', path: data.resource.path };
+    },
+  }],
+},
+```
+
+## CRUD Hooks
+
+Intercept CRUD operations with before/after handlers:
+
+```typescript
+crudOperations: {
+  create: {
+    before: async (req, params, currentUser) => {
+      params.createdBy = currentUser._id;
+      return params;
+    },
+  },
+  index: {
+    before: async (req, filter, currentUser) => {
+      filter.isActive = true;
+      return filter;
+    },
+  },
+},
+```
+
+## Filter Scopes
+
+Add auto or manual scope filters:
+
+```typescript
+filters: {
+  scopes: {
+    isAccessible: true,
+    auto: {
+      key: 'status',
+      options: ['active', 'inactive', 'pending'],
+    },
+  },
+},
+```
+
+## Plugins
+
+- **Permissions** — role-based access control. See [`docs/permissions.md`](../../docs/permissions.md)
+- **Admin Notifications** — in-app notification system. See [`docs/adminNotifications.md`](../../docs/adminNotifications.md)
+
+## Custom Routes
+
+For full control (you provide your own React app), extend the built-in controllers:
+
+```typescript
+import DashboardController from 'identity-admin/lib/controllers/DashboardController';
+import ResourceController from 'identity-admin/lib/controllers/ResourceController';
+import ActionController from 'identity-admin/lib/controllers/ActionController';
+```
+
+See the README for detailed examples.
+
+## Common Patterns
+
+**Override a field type:**
+```typescript
+properties: {
+  model: {
+    avatar: { type: 'image' as FieldTypes, mediaUploader: true },
+    description: { type: 'HTML' as FieldTypes },
+    phone: { type: 'phoneNumber' as FieldTypes, countryCodes: ['sa', 'eg'] },
+  },
+},
+```
+
+**Add a virtual password field:**
+```typescript
+model: {
+  virtuals: {
+    password: {
+      type: 'password',
+      showIn: Virtuals.FORM,
+      required: true,
+    },
+  },
+},
+```
+
+**Disable delete, enable bulk delete:**
+```typescript
+actions: {
+  delete: { isAccessible: false },
+  bulkDelete: { isAccessible: true },
+},
+```
+
+## Red Flags
+
+- Forgetting to add the resource to the `resources` array — the file alone isn't enough
+- Mismatch between `modelName` and the actual Mongoose collection name
+- Field name typos in `listProperties` / `formProperties` — they're silently ignored
+- Missing Inversify container bindings when using the permissions plugin
+- `authenticate` returns `false` for valid credentials — check bcrypt comparison
+- `cookiesSecret` is required for authenticated dashboards, even in development
+
+## Verification Checklist
+
+- [ ] Mongoose model is connected and compiled before `dashboard.build(app)`
+- [ ] Resource file has at minimum `properties.resource` and `properties.modelName`
+- [ ] For authenticated dashboard: `cookiesConfiguration` is set and `authenticate` returns the user object
+- [ ] Custom actions return a valid `IActionHandlerResponse`
+- [ ] Plugin resources are added to the main `resources` array
+- [ ] Before/after handlers always return the expected type (params, filter, or document)