add role api

API_DOCUMENTATION.md

@@ -38,6 +38,7 @@ Errors: `404` unknown function, `400` (`KeyNotFoundException`/`InvalidOperationE
 | `/api/loginUser` | POST | UserManager | forced `loginUser` |
 | `/api/forgotPassword` | POST | RecoveryManager | forced `forgotPassword` |
 | `/api/alt` | POST | AltOptionManager | from body |
+| `/api/role` | POST | RoleManager | from body |
 
 ### GET /api/status
 Response:
@@ -63,9 +64,12 @@ Payload:
   "roleId": "guid (required)",
   "userTypeId": "guid (required)",
   "chkUser": "bool? (if true, checks for existing conflicting user)",
-  "password": "string? (auto-generated if empty)"
+  "password": "string? (auto-generated if empty)",
+  "sendCredentialsEmail": "bool? (default true; emails `email` the username + password when set)"
 }
 ```
+The generated/supplied password is now persisted (hashed) against the user record (previously a bug left it unset). When `email` is present and `sendCredentialsEmail` is not `false`, an email with the username and password is sent best-effort after the user is committed (failures do not roll back registration).
+
 Data:
 ```json
 {
@@ -129,6 +133,13 @@ Data:
 }
 ```
 
+### listUserTypes
+No payload.
+Data: array of
+```json
+{ "userTypeId": "guid", "code": "", "description": "" }
+```
+
 ### getUserSessions
 _Requires auth (userId from claims). No payload needed._
 Data: array of
@@ -323,8 +334,52 @@ Data:
 
 ---
 
+## /api/role — RoleManager functions
+
+> **Null-tolerant fields (fixed 2026-07-18):** `isSystemRole` is read via `data["isSystemRole"].ValueKind != JsonValueKind.Null`
+> before calling `GetBoolean()` in both `createRole` and `updateRole` — an explicit JSON `null` (as opposed to the key being
+> absent) previously threw an unhandled `InvalidOperationException`, surfaced to ERPCore callers as a generic `500`/`AUTH_UPSTREAM_ERROR`.
+
+### createRole
+Payload:
+```json
+{ "code": "string (required)", "name": "string? (defaults to code)", "isSystemRole": "bool? (default false)" }
+```
+Data:
+```json
+{ "roleId": "guid", "code": "", "name": "", "isSystemRole": false, "createdAt": "" }
+```
+
+### getRole
+Payload:
+```json
+{ "roleId": "guid (required)" }
+```
+Data: same shape as `createRole`.
+
+### listRoles
+No payload.
+Data: array of `createRole`-shaped objects.
+
+### updateRole
+Payload (all fields optional except `roleId`):
+```json
+{ "roleId": "guid (required)", "code": "string?", "name": "string?", "isSystemRole": "bool?" }
+```
+Data: same shape as `createRole`.
+
+### deleteRole
+Payload:
+```json
+{ "roleId": "guid (required)" }
+```
+Blocked with a `400` (`"ROLE_IN_USE: role is assigned to one or more users"`) if any `User.RoleId` references it (FK is `Restrict`).
+Data: `{ "message": "Role deleted successfully" }`
+
+---
+
 ## Notes
 - All timestamps are UTC.
 - `deviceName`, `Browser`, `OS`, `IPAddress` are captured per session from request headers for session tracking (`getUserSessions`).
-- Password login validation (`PasswordHasher.Verify`) is currently commented out in `loginUser` — passwords are not checked on login as of this version.
+- Password login validation (`PasswordHasher.Verify`) is performed in `loginUser` — invalid/missing password hashes are rejected.
 - JWT access tokens issued with `expiresIn: 3600` (1 hour); refresh tokens/sessions expire after 30 days.