rbac-manager 0.0.0-stage → 1.0.0

package/.github/workflows/publish.yml

@@ -0,0 +1,29 @@
+name: Publish to npm
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          registry-url: https://registry.npmjs.org
+
+      # npm's trusted publishing requires a recent npm CLI.
+      - run: npm install --global npm@latest
+
+      - run: npm ci
+      - run: npm run typecheck
+      - run: npm run build
+      - run: npm publish --access public --provenance

package/README.md

@@ -1,3 +1,318 @@
-# Temporary Holding Version
+# Universal Enterprise RBAC & Masters Template
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A production-ready, highly modular, frontend-only RBAC (Role-Based Access Control) and Masters framework built for React and Next.js. Engineered to connect directly to any backend REST API with **zero hardcoded keys**, **dynamic permission naming & aliases**, **pluggable API adapters**, **granular action toggles**, **dynamic table schemas**, and **built-in solutions for all enterprise integration roadblocks**.
+
+---
+
+## 🌟 Core Highlights
+
+- **Frontend-Only**: No database or backend code required. Directly interfaces with backend API endpoints.
+- **Universal Framework Routing**: Native adapters for Next.js App Router (`useRouter`), React Router (`useNavigate`, `Link`), TanStack Router, and Remix—eliminating full-page browser reloads.
+- **Zero FOUC (Flash of Unauthorized Content)**: Full SSR session hydration support (`initialUser`, `initialPermissions`) prevents permission flashing on server-rendered pages.
+- **Silent Token Refresh & Request Replay**: Transparently catches 401s, calls your refresh token API, and replays failed requests without logging the user out.
+- **Multi-Tenancy & Workspace Switching**: Built-in `activeTenantId` and `setTenantId()` automatically injects `X-Tenant-Id` headers and re-fetches permissions on the fly.
+- **Flexible Pagination Engine**: Seamlessly adapts to 0-based (`page=0`), 1-based (`page=1`), or SQL offset/limit (`offset=0&limit=10`) backend contracts.
+- **Cascading Form Dropdowns**: Dynamic select options that filter automatically based on parent fields (e.g. Department list dynamically filtered by selected Entity).
+- **Zero Hardcoded Permission Strings**: All permission names are isolated in module-level constants (`src/constants/permissions/`).
+- **Supports Any Permission Naming Convention**: Whether your backend sends `roles.add`, `roles.addition`, `roles:create`, or `ROLE_ADD`, it matches automatically via the dynamic permission resolver and alias map.
+- **100% Complete Style & ClassName Overrides**: Strip default styles with `unstyled={true}` or inject custom Tailwind/CSS classes into any sub-element.
+- **Dual ESM & CommonJS**: Ships with first-class ES modules (`dist/esm`) and CommonJS (`dist/cjs`) bundles with full TypeScript `.d.ts` declarations.
+
+---
+
+## 🛠️ Solutions for Enterprise Integration Roadblocks
+
+### 1. Framework Routing (Next.js & React Router)
+Avoid full-page reloads by passing your framework's native router:
+
+```tsx
+// Next.js App Router:
+import { useRouter } from 'next/navigation';
+import Link from 'next/link';
+import { createNextRouterAdapter, createRBACConfig } from '@custom/rbac-template';
+
+const rbacConfig = createRBACConfig({
+  apiBaseUrl: 'https://api.example.com',
+  router: createNextRouterAdapter(useRouter(), Link),
+});
+
+// React Router (Vite / CRA):
+import { useNavigate, Link } from 'react-router-dom';
+import { createReactRouterAdapter } from '@custom/rbac-template';
+
+const rbacConfig = createRBACConfig({
+  router: createReactRouterAdapter(useNavigate(), Link),
+});
+```
+
+---
+
+### 2. Eliminating SSR Flashing (Zero FOUC)
+In Next.js, read your session on the server and pass it directly to `PermissionProvider`. The page renders with full permissions immediately upon hydration:
+
+```tsx
+// app/layout.tsx (Server Component)
+import { getServerSession } from '@/lib/auth';
+import { ClientProviders } from './providers';
+
+export default async function RootLayout({ children }) {
+  const session = await getServerSession();
+
+  return (
+    <html>
+      <body>
+        <ClientProviders
+          initialUser={session?.user}
+          initialPermissions={session?.permissions}
+          initialNavigation={session?.navigation}
+        >
+          {children}
+        </ClientProviders>
+      </body>
+    </html>
+  );
+}
+```
+
+---
+
+### 3. Silent Token Refresh (401 Interception)
+Prevent users from losing form progress due to expired access tokens:
+
+```typescript
+const rbacConfig = createRBACConfig({
+  apiBaseUrl: 'https://api.example.com',
+  getToken: () => localStorage.getItem('accessToken'),
+  // Catches 401s, refreshes token, and replays failed requests transparently:
+  refreshToken: async () => {
+    const res = await fetch('/api/auth/refresh', { method: 'POST' });
+    const data = await res.json();
+    localStorage.setItem('accessToken', data.accessToken);
+    return data.accessToken;
+  },
+  onUnauthorized: () => {
+    window.location.href = '/login';
+  },
+});
+```
+
+---
+
+### 4. Multi-Tenancy & Entity Switching
+Switch active company/branch workspaces and automatically update permissions:
+
+```tsx
+import { usePermission } from '@custom/rbac-template';
+
+export function TenantSwitcher({ entities }) {
+  const { activeTenantId, setTenantId } = usePermission();
+
+  return (
+    <select
+      value={activeTenantId || ''}
+      onChange={(e) => setTenantId(e.target.value)} // Automatically refetches /auth/me & adds X-Tenant-Id header
+    >
+      {entities.map((e) => (
+        <option key={e.id} value={e.id}>
+          {e.name}
+        </option>
+      ))}
+    </select>
+  );
+}
+```
+
+---
+
+### 5. Backend Pagination Contract Adaptation
+Configure 0-based vs 1-based indexing or offset/limit mode in 1 line:
+
+```typescript
+const rbacConfig = createRBACConfig({
+  pagination: {
+    pageIndexOffset: 0,      // For Spring Boot (0-based indexing: page=0)
+    pageParamName: 'pageIndex',
+    limitParamName: 'pageSize',
+    // Or for SQL offset/limit:
+    // useOffsetLimit: true,
+    // offsetParamName: 'offset',
+  },
+});
+```
+
+---
+
+### 6. Cascading / Dependent Form Dropdowns
+Configure form fields to dynamically filter based on parent selections:
+
+```tsx
+<EmployeeMasterView
+  formFields={[
+    { name: 'firstName', label: 'First Name', required: true },
+    {
+      name: 'entityId',
+      label: 'Entity',
+      type: 'select',
+      options: entities.map((e) => ({ label: e.name, value: e.id })),
+    },
+    {
+      name: 'departmentId',
+      label: 'Department',
+      type: 'select',
+      dependsOn: ['entityId'], // Re-evaluates when entityId changes
+      options: (formData) =>
+        departments
+          .filter((d) => !formData.entityId || d.entityId === formData.entityId)
+          .map((d) => ({ label: d.name, value: d.id })),
+      disabled: (formData) => !formData.entityId, // Disabled until entity is chosen
+    },
+  ]}
+/>
+```
+
+---
+
+### 7. Dynamic Permission Names & Aliases (`roles.add` vs `roles.addition`)
+
+```typescript
+const rbacConfig = createRBACConfig({
+  permissionAliases: {
+    'roles.add': 'roles.addition',          // Maps 'roles.add' -> 'roles.addition'
+    'roles.edit': 'roles:modify',           // Colon notation support
+    'department_master.add': 'dept.create', // Custom department create slug
+  },
+  // Or global format resolver:
+  // permissionResolver: (module, action) => `${module}:${action}`,
+});
+```
+
+---
+
+### 8. Field-Level Validation Error Mapping
+When your backend validation fails (e.g. HTTP 400 or 422 with `{ errors: { name: "Name is already taken" } }` or `{ errors: [{ field: "code", message: "Duplicate" }] }`), `HttpClient` and `MasterDataTable` automatically normalize and highlight each field directly under its input element.
+
+---
+
+### 9. Toast & Notification Library Callbacks
+Connect any UI toast library (Sonner, react-toastify, AntD, Chakra) with zero vendor lock-in:
+
+```typescript
+import { toast } from 'sonner';
+
+const rbacConfig = createRBACConfig({
+  onNotification: ({ type, title, message }) => {
+    if (type === 'success') toast.success(message);
+    else if (type === 'error') toast.error(message);
+    else toast(message);
+  },
+});
+```
+
+---
+
+### 10. URL Query State Synchronization (Deep Linking)
+Keep table filters, search keywords, page index, and sort order in sync with browser query params so users can bookmark and share URLs:
+
+```tsx
+<DepartmentMasterView syncWithUrl={true} defaultSortBy="name" defaultSortOrder="asc" />
+```
+
+---
+
+### 11. Column Sorting (Ascending / Descending)
+Mark any column as sortable with custom backend keys and direction toggle indicators:
+
+```tsx
+<Table
+  columns={[
+    { key: 'name', header: 'Department Name', sortable: true, sortKey: 'dept_name' },
+    { key: 'createdAt', header: 'Created At', sortable: true },
+  ]}
+  sortBy={sortBy}
+  sortOrder={sortOrder}
+  onSortChange={(colKey, direction) => handleSort(colKey, direction)}
+/>
+```
+
+---
+
+### 12. Bulk Row Selection & Batch Actions
+Opt-in multi-row select checkboxes with floating batch action toolbars:
+
+```tsx
+<DepartmentMasterView
+  selectable={true}
+  batchActions={[
+    {
+      key: 'export',
+      label: 'Export Selected',
+      onClick: (selectedIds, selectedItems) => exportToCsv(selectedItems),
+    },
+    {
+      key: 'archive',
+      label: 'Archive',
+      variant: 'danger',
+      onClick: (selectedIds) => archiveDepartments(selectedIds),
+    },
+  ]}
+/>
+```
+
+---
+
+### 13. Multi-Language i18n Localization
+Translate or customize all table buttons, modals, badges, and counters:
+
+```typescript
+const rbacConfig = createRBACConfig({
+  i18n: {
+    addNew: '+ Añadir',
+    saveChanges: 'Guardar cambios',
+    cancel: 'Cancelar',
+    delete: 'Eliminar',
+    searchPlaceholder: 'Buscar...',
+    showingEntries: (from, to, total) => `Mostrando ${from} a ${to} de ${total} registros`,
+  },
+});
+```
+
+---
+
+### 14. File & Multipart Uploads (`FormData`)
+`HttpClient` automatically detects `FormData` instances, omitting default JSON headers so the browser dynamically injects the appropriate `multipart/form-data; boundary=...`:
+
+```typescript
+const formData = new FormData();
+formData.append('file', file);
+await http.upload('/masters/departments/import', formData);
+```
+
+---
+
+## 🎨 Complete Style & ClassName Overrides
+
+Pass custom CSS / Tailwind classes directly to any element of the module:
+```tsx
+<DepartmentMasterView
+  classNames={{
+    root: 'p-6 bg-slate-900 text-white rounded-2xl',
+    header: {
+      title: 'text-2xl font-bold text-amber-400',
+      addButton: 'bg-amber-500 hover:bg-amber-600 text-black',
+    },
+    table: {
+      thead: 'bg-slate-800 text-slate-300 font-semibold',
+      th: 'px-6 py-4 uppercase tracking-wider text-xs',
+      tr: 'hover:bg-slate-800/50 border-b border-slate-800',
+      td: 'px-6 py-4 text-slate-300',
+    },
+  }}
+/>
+```
+
+Or pass `unstyled={true}` to strip all default styling when using **shadcn/ui**, **MUI**, or **Bootstrap**.
+
+---
+
+## 📄 License
+MIT

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "rbac-manager",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Enterprise-grade, highly customizable, frontend-only RBAC and Masters template with pluggable API adapters",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    },
+    "./styles.css": "./src/styles/standalone.css"
+  },
+  "scripts": {
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build": "npm run build:esm && npm run build:cjs && node scripts/postbuild.js",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "rbac",
+    "permission",
+    "roles",
+    "masters",
+    "access-control",
+    "react",
+    "frontend-template"
+  ],
+  "author": "",
+  "license": "MIT",
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "@types/react": "^18.3.31",
+    "@types/react-dom": "^18.3.7",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "clsx": "^2.1.0",
+    "tailwind-merge": "^2.2.0"
+  }
+}

package/scripts/postbuild.js

@@ -0,0 +1,17 @@
+const fs = require('fs');
+const path = require('path');
+
+const cjsPackageJson = path.join(__dirname, '..', 'dist', 'cjs', 'package.json');
+const esmPackageJson = path.join(__dirname, '..', 'dist', 'esm', 'package.json');
+
+// Ensure dist/cjs exists
+if (fs.existsSync(path.dirname(cjsPackageJson))) {
+  fs.writeFileSync(cjsPackageJson, JSON.stringify({ type: 'commonjs' }, null, 2));
+}
+
+// Ensure dist/esm exists
+if (fs.existsSync(path.dirname(esmPackageJson))) {
+  fs.writeFileSync(esmPackageJson, JSON.stringify({ type: 'module' }, null, 2));
+}
+
+console.log('Postbuild: Successfully generated CJS and ESM package.json manifests.');

package/src/config/rbac.config.ts

@@ -0,0 +1,206 @@
+import { RBACAdapters } from '../core/types/adapter.types';
+import { DEFAULT_ADAPTERS } from '../core/adapters';
+import { RBAC_CONSTANTS, configureRBACConstants, RBACLocaleStrings } from '../constants';
+import { configurePermissionKeys } from '../constants/permissions';
+import { RBACTheme, defaultRBACTheme, mergeThemes } from '../theme';
+import { PermissionKeyResolverFn, defaultPermissionResolver } from '../core/utils/permissionResolver';
+import { RouterAdapter } from '../core/types/router.types';
+import { PaginationConfig, defaultPaginationConfig } from '../core/types/pagination.types';
+
+export interface RBACNotification {
+  type: 'success' | 'error' | 'info' | 'warning';
+  title?: string;
+  message: string;
+}
+
+export type RBACNotificationHandler = (notification: RBACNotification) => void;
+
+export interface ModuleFeatureConfig {
+  enabled?: boolean;
+  allowAdd?: boolean;
+  allowEdit?: boolean;
+  allowDelete?: boolean;
+  allowView?: boolean;
+}
+
+export type FeatureToggle = boolean | ModuleFeatureConfig;
+
+export interface RBACFeaturesConfig {
+  masters: {
+    entity: FeatureToggle;
+    department: FeatureToggle;
+    designation: FeatureToggle;
+    employee: FeatureToggle;
+    moduleMaster: FeatureToggle;
+    subModuleMaster: FeatureToggle;
+    [customMaster: string]: FeatureToggle | undefined;
+  };
+  rolesAndPermissions: {
+    roleCrud: FeatureToggle;
+    permissionAssignmentMatrix: boolean;
+    permissionRegistry: boolean;
+  };
+}
+
+export interface RBACConfig {
+  apiBaseUrl: string;
+  features: RBACFeaturesConfig;
+  endpoints: typeof RBAC_CONSTANTS.endpoints;
+  adapters: RBACAdapters;
+  theme: RBACTheme;
+  router?: RouterAdapter;
+  pagination: PaginationConfig;
+  permissionResolver: PermissionKeyResolverFn;
+  permissionAliases: Record<string, string>;
+  i18n?: Partial<RBACLocaleStrings>;
+  onNotification?: RBACNotificationHandler;
+  getToken?: () => string | null | undefined;
+  getTenantId?: () => string | number | null | undefined;
+  getCustomHeaders?: () => Record<string, string>;
+  refreshToken?: () => Promise<string | null | undefined>;
+  onUnauthorized?: () => void;
+}
+
+export const defaultRBACConfig: RBACConfig = {
+  apiBaseUrl: 'https://api.example.com',
+  features: {
+    masters: {
+      entity: { enabled: true, allowAdd: true, allowEdit: true, allowDelete: true },
+      department: { enabled: true, allowAdd: true, allowEdit: true, allowDelete: true },
+      designation: { enabled: true, allowAdd: true, allowEdit: true, allowDelete: true },
+      employee: { enabled: true, allowAdd: true, allowEdit: true, allowDelete: true },
+      moduleMaster: { enabled: true, allowAdd: true, allowEdit: true, allowDelete: true },
+      subModuleMaster: { enabled: true, allowAdd: true, allowEdit: true, allowDelete: true },
+    },
+    rolesAndPermissions: {
+      roleCrud: { enabled: true, allowAdd: true, allowEdit: true, allowDelete: true },
+      permissionAssignmentMatrix: true,
+      permissionRegistry: true,
+    },
+  },
+  endpoints: { ...RBAC_CONSTANTS.endpoints },
+  adapters: { ...DEFAULT_ADAPTERS },
+  theme: defaultRBACTheme,
+  pagination: defaultPaginationConfig,
+  permissionResolver: defaultPermissionResolver,
+  permissionAliases: {},
+  getToken: () => {
+    if (typeof window !== 'undefined') {
+      return localStorage.getItem('token') || undefined;
+    }
+    return undefined;
+  },
+};
+
+/**
+ * Check if a specific CRUD action is allowed for a given feature toggle
+ */
+export function isActionAllowed(
+  configValue: FeatureToggle | undefined,
+  action: 'add' | 'edit' | 'delete' | 'view'
+): boolean {
+  if (configValue === undefined || configValue === false) return false;
+  if (configValue === true) return true;
+  if (configValue.enabled === false) return false;
+  if (action === 'add') return configValue.allowAdd ?? true;
+  if (action === 'edit') return configValue.allowEdit ?? true;
+  if (action === 'delete') return configValue.allowDelete ?? true;
+  if (action === 'view') return configValue.allowView ?? true;
+  return true;
+}
+
+/**
+ * Deep merge helper to create full config with user overrides
+ */
+export function createRBACConfig(custom: Partial<{
+  apiBaseUrl: string;
+  features: Partial<{
+    masters: Partial<Record<string, FeatureToggle>>;
+    rolesAndPermissions: Partial<{
+      roleCrud: FeatureToggle;
+      permissionAssignmentMatrix: boolean;
+      permissionRegistry: boolean;
+    }>;
+  }>;
+  endpoints: Partial<typeof RBAC_CONSTANTS.endpoints>;
+  adapters: Partial<{
+    auth: Partial<RBACAdapters['auth']>;
+    roles: Partial<RBACAdapters['roles']>;
+    permissions: Partial<RBACAdapters['permissions']>;
+    masters: Partial<RBACAdapters['masters']>;
+  }>;
+  theme: Partial<RBACTheme>;
+  router: RouterAdapter;
+  pagination: Partial<PaginationConfig>;
+  permissionResolver: PermissionKeyResolverFn;
+  permissionAliases: Record<string, string>;
+  permissionKeys: Parameters<typeof configurePermissionKeys>[0];
+  constants: Parameters<typeof configureRBACConstants>[0];
+  i18n: Partial<RBACLocaleStrings>;
+  onNotification: RBACNotificationHandler;
+  getToken: () => string | null | undefined;
+  getTenantId: () => string | number | null | undefined;
+  getCustomHeaders: () => Record<string, string>;
+  refreshToken: () => Promise<string | null | undefined>;
+  onUnauthorized: () => void;
+}> = {}): RBACConfig {
+  if (custom.constants) {
+    configureRBACConstants(custom.constants);
+  }
+
+  if (custom.permissionKeys) {
+    configurePermissionKeys(custom.permissionKeys);
+  }
+
+  if (custom.i18n) {
+    configureRBACConstants({ i18n: custom.i18n });
+  }
+
+  const features: RBACFeaturesConfig = {
+    masters: {
+      ...defaultRBACConfig.features.masters,
+      ...(custom.features?.masters || {}),
+    },
+    rolesAndPermissions: {
+      ...defaultRBACConfig.features.rolesAndPermissions,
+      ...(custom.features?.rolesAndPermissions || {}),
+    },
+  };
+
+  const endpoints = {
+    ...defaultRBACConfig.endpoints,
+    ...(custom.endpoints || {}),
+  };
+
+  const adapters: RBACAdapters = {
+    auth: { ...defaultRBACConfig.adapters.auth, ...(custom.adapters?.auth || {}) },
+    roles: { ...defaultRBACConfig.adapters.roles, ...(custom.adapters?.roles || {}) },
+    permissions: { ...defaultRBACConfig.adapters.permissions, ...(custom.adapters?.permissions || {}) },
+    masters: { ...defaultRBACConfig.adapters.masters, ...(custom.adapters?.masters || {}) },
+  };
+
+  const theme = mergeThemes(defaultRBACTheme, custom.theme);
+  const pagination = { ...defaultPaginationConfig, ...(custom.pagination || {}) };
+
+  return {
+    apiBaseUrl: custom.apiBaseUrl || defaultRBACConfig.apiBaseUrl,
+    features,
+    endpoints,
+    adapters,
+    theme,
+    router: custom.router || defaultRBACConfig.router,
+    pagination,
+    permissionResolver: custom.permissionResolver || defaultRBACConfig.permissionResolver,
+    permissionAliases: {
+      ...defaultRBACConfig.permissionAliases,
+      ...(custom.permissionAliases || {}),
+    },
+    i18n: custom.i18n,
+    onNotification: custom.onNotification,
+    getToken: custom.getToken || defaultRBACConfig.getToken,
+    getTenantId: custom.getTenantId || defaultRBACConfig.getTenantId,
+    getCustomHeaders: custom.getCustomHeaders || defaultRBACConfig.getCustomHeaders,
+    refreshToken: custom.refreshToken || defaultRBACConfig.refreshToken,
+    onUnauthorized: custom.onUnauthorized || defaultRBACConfig.onUnauthorized,
+  };
+}

package/src/constants/actions.constants.ts

@@ -0,0 +1,21 @@
+/**
+ * Action keys, IDs, and human-readable labels.
+ * Used for the Permission Matrix and Permission Gates.
+ */
+export const DEFAULT_ACTION_KEYS = {
+  VIEW: 'view',
+  ADD: 'add',
+  EDIT: 'edit',
+  DELETE: 'delete',
+  ASSIGN: 'assign',
+} as const;
+
+export const DEFAULT_ACTION_CONFIGS = [
+  { actionId: 1, action_key: DEFAULT_ACTION_KEYS.VIEW, action_name: 'View', sort_order: 1 },
+  { actionId: 2, action_key: DEFAULT_ACTION_KEYS.ADD, action_name: 'Add (Create)', sort_order: 2 },
+  { actionId: 3, action_key: DEFAULT_ACTION_KEYS.EDIT, action_name: 'Edit', sort_order: 3 },
+  { actionId: 4, action_key: DEFAULT_ACTION_KEYS.DELETE, action_name: 'Delete', sort_order: 4 },
+  { actionId: 5, action_key: DEFAULT_ACTION_KEYS.ASSIGN, action_name: 'Assign', sort_order: 5 },
+] as const;
+
+export type ActionKey = (typeof DEFAULT_ACTION_KEYS)[keyof typeof DEFAULT_ACTION_KEYS] | string;

package/src/constants/apiKeys.constants.ts

@@ -0,0 +1,25 @@
+/**
+ * Global API response and pagination field keys.
+ * If your backend wraps responses in different keys (e.g. `items` instead of `list`),
+ * change it here or pass overrides via RBACConfig.
+ */
+export const DEFAULT_API_RESPONSE_KEYS = {
+  SUCCESS: 'success',
+  STATUS_CODE: 'statusCode',
+  MESSAGE: 'message',
+  DATA: 'data',
+  ERROR: 'error',
+  ERRORS: 'errors',
+} as const;
+
+export const DEFAULT_PAGINATION_KEYS = {
+  PAGE: 'page',
+  LIMIT: 'limit',
+  TOTAL: 'total',
+  TOTAL_PAGES: 'totalPages',
+  HAS_NEXT: 'hasNext',
+  ITEMS: 'list', // container API returns `list` or direct array
+} as const;
+
+export type ApiResponseKeys = typeof DEFAULT_API_RESPONSE_KEYS;
+export type PaginationKeys = typeof DEFAULT_PAGINATION_KEYS;