roles

2026-02-17 21:53:14 -06:00
parent 6d951e426d
commit 987a1c8a6a
35 changed files with 1539 additions and 39 deletions
@@ -153,6 +153,52 @@ Update the currently authenticated user's information.

 ---

+### Check User Permissions
+
+**POST** `/user/@me/check-permission`
+
+Check if the currently authenticated user has specific permissions. Accepts an array of permission nodes and returns the status for each.
+
+**Authentication Required:** Yes
+
+**Required Scopes:** `user.read`
+
+**Request Body:**
+
+```json
+{
+  "permissions": ["user.read", "company.create", "credential.write"]
+}
+```
+
+**Response:**
+
+```json
+{
+  "status": 200,
+  "message": "Permission check completed.",
+  "data": {
+    "results": [
+      {
+        "permission": "user.read",
+        "hasPermission": true
+      },
+      {
+        "permission": "company.create",
+        "hasPermission": false
+      },
+      {
+        "permission": "credential.write",
+        "hasPermission": true
+      }
+    ]
+  },
+  "successful": true
+}
+```
+
+---
+
 ## Company Routes

 ### Get All Companies
@@ -203,17 +249,24 @@ Fetch a paginated list of all companies with optional search functionality.

 **GET** `/company/companies/:identifier`

-Fetch a single company by its ID.
+Fetch a single company by its ID. Automatically fetches fresh data from ConnectWise and returns it along with internal company data.

 **Authentication Required:** Yes

-**Required Permissions:** `company.fetch`
+**Required Permissions:**
+
+- `company.fetch` (base permission)
+- `company.fetch.address` (required when `includeAddress=true`)

 **URL Parameters:**

- `identifier` - Company ID
+- `identifier` - Company ID (internal database ID)

-**Response:**
+**Query Parameters:**
+
+- `includeAddress` (optional) - Set to "true" to include full address information. Requires `company.fetch.address` permission. (default: false)
+
+**Response (without includeAddress):**

 ```json
 {
@@ -223,7 +276,34 @@ Fetch a single company by its ID.
    "id": "ckx...",
    "name": "Acme Corp",
    "cw_CompanyId": 12345,
-    "cw_Identifier": "AcmeCorp"
+    "cw_Identifier": "AcmeCorp",
+    "cw_Data": {}
+  },
+  "successful": true
+}
+```
+
+**Response (with includeAddress=true):**
+
+```json
+{
+  "status": 200,
+  "message": "Company Fetched Successfully!",
+  "data": {
+    "id": "ckx...",
+    "name": "Acme Corp",
+    "cw_CompanyId": 12345,
+    "cw_Identifier": "AcmeCorp",
+    "cw_Data": {
+      "address": {
+        "line1": "123 Main St",
+        "line2": null,
+        "city": "Springfield",
+        "state": "IL",
+        "zip": "62701",
+        "country": "United States"
+      }
+    }
  },
  "successful": true
 }
@@ -861,6 +941,484 @@ Fetch all credentials that use a specific credential type.

 ---

+## Role Routes
+
+### Create Role
+
+**POST** `/role`
+
+Create a new role with a title, moniker, and optional permissions.
+
+**Authentication Required:** Yes
+
+**Required Permissions:** `role.create`
+
+**Request Body:**
+
+```json
+{
+  "title": "System Administrator",
+  "moniker": "system_admin",
+  "permissions": [
+    "user.read",
+    "user.write",
+    "company.fetch",
+    "credential.create"
+  ]
+}
+```
+
+**Response:**
+
+```json
+{
+  "status": 201,
+  "message": "Role Created Successfully!",
+  "data": {
+    "id": "ckx...",
+    "title": "System Administrator",
+    "moniker": "system_admin",
+    "permissions": [
+      "user.read",
+      "user.write",
+      "company.fetch",
+      "credential.create"
+    ],
+    "createdAt": "2026-02-17T00:00:00.000Z",
+    "updatedAt": "2026-02-17T00:00:00.000Z"
+  },
+  "successful": true
+}
+```
+
+---
+
+### Get Role by ID or Moniker
+
+**GET** `/role/:identifier`
+
+Fetch a single role by its ID or moniker.
+
+**Authentication Required:** Yes
+
+**Required Permissions:** `role.read`
+
+**URL Parameters:**
+
+- `identifier` - Role ID or moniker
+
+**Response:**
+
+```json
+{
+  "status": 200,
+  "message": "Role Fetched Successfully!",
+  "data": {
+    "id": "ckx...",
+    "title": "System Administrator",
+    "moniker": "system_admin",
+    "permissions": [
+      "user.read",
+      "user.write",
+      "company.fetch",
+      "credential.create"
+    ],
+    "createdAt": "2026-02-17T00:00:00.000Z",
+    "updatedAt": "2026-02-17T00:00:00.000Z"
+  },
+  "successful": true
+}
+```
+
+---
+
+### Get All Roles
+
+**GET** `/role`
+
+Fetch all roles in the system.
+
+**Authentication Required:** Yes
+
+**Required Permissions:** `role.read`, `role.list`
+
+**Response:**
+
+```json
+{
+  "status": 200,
+  "message": "Roles Fetched Successfully!",
+  "data": [
+    {
+      "id": "ckx...",
+      "title": "System Administrator",
+      "moniker": "system_admin",
+      "permissions": ["user.read", "user.write"],
+      "createdAt": "2026-02-17T00:00:00.000Z",
+      "updatedAt": "2026-02-17T00:00:00.000Z"
+    },
+    {
+      "id": "cky...",
+      "title": "Viewer",
+      "moniker": "viewer",
+      "permissions": ["user.read", "company.fetch"],
+      "createdAt": "2026-02-17T00:00:00.000Z",
+      "updatedAt": "2026-02-17T00:00:00.000Z"
+    }
+  ],
+  "successful": true
+}
+```
+
+---
+
+### Update Role
+
+**PATCH** `/role/:identifier`
+
+Update a role's title, moniker, or permissions.
+
+**Authentication Required:** Yes
+
+**Required Permissions:** `role.modify`
+
+**URL Parameters:**
+
+- `identifier` - Role ID or moniker
+
+**Request Body:**
+
+```json
+{
+  "title": "Super Administrator",
+  "moniker": "super_admin",
+  "permissions": ["*"]
+}
+```
+
+**Response:**
+
+```json
+{
+  "status": 200,
+  "message": "Role Updated Successfully!",
+  "data": {
+    "id": "ckx...",
+    "title": "Super Administrator",
+    "moniker": "super_admin",
+    "permissions": ["*"],
+    "createdAt": "2026-02-17T00:00:00.000Z",
+    "updatedAt": "2026-02-17T12:00:00.000Z"
+  },
+  "successful": true
+}
+```
+
+---
+
+### Delete Role
+
+**DELETE** `/role/:identifier`
+
+Delete a role. This will remove the role from all users that have it assigned.
+
+**Authentication Required:** Yes
+
+**Required Permissions:** `role.delete`
+
+**URL Parameters:**
+
+- `identifier` - Role ID or moniker
+
+**Response:**
+
+```json
+{
+  "status": 200,
+  "message": "Role Deleted Successfully!",
+  "data": {
+    "id": "ckx...",
+    "title": "System Administrator",
+    "moniker": "system_admin",
+    "createdAt": "2026-02-17T00:00:00.000Z",
+    "updatedAt": "2026-02-17T12:00:00.000Z"
+  },
+  "successful": true
+}
+```
+
+---
+
+### Add Permissions to Role
+
+**POST** `/role/:identifier/permissions`
+
+Add one or more permissions to an existing role. The new permissions will be merged with existing permissions.
+
+**Authentication Required:** Yes
+
+**Required Permissions:** `role.modify`
+
+**URL Parameters:**
+
+- `identifier` - Role ID or moniker
+
+**Request Body:**
+
+```json
+{
+  "permissions": ["credential.update", "credential.delete"]
+}
+```
+
+**Response:**
+
+```json
+{
+  "status": 200,
+  "message": "Permissions Added Successfully!",
+  "data": {
+    "id": "ckx...",
+    "title": "System Administrator",
+    "moniker": "system_admin",
+    "permissions": [
+      "user.read",
+      "user.write",
+      "company.fetch",
+      "credential.create",
+      "credential.update",
+      "credential.delete"
+    ],
+    "createdAt": "2026-02-17T00:00:00.000Z",
+    "updatedAt": "2026-02-17T12:30:00.000Z"
+  },
+  "successful": true
+}
+```
+
+---
+
+### Remove Permissions from Role
+
+**DELETE** `/role/:identifier/permissions`
+
+Remove one or more permissions from an existing role.
+
+**Authentication Required:** Yes
+
+**Required Permissions:** `role.modify`
+
+**URL Parameters:**
+
+- `identifier` - Role ID or moniker
+
+**Request Body:**
+
+```json
+{
+  "permissions": ["credential.delete"]
+}
+```
+
+**Response:**
+
+```json
+{
+  "status": 200,
+  "message": "Permissions Removed Successfully!",
+  "data": {
+    "id": "ckx...",
+    "title": "System Administrator",
+    "moniker": "system_admin",
+    "permissions": [
+      "user.read",
+      "user.write",
+      "company.fetch",
+      "credential.create",
+      "credential.update"
+    ],
+    "createdAt": "2026-02-17T00:00:00.000Z",
+    "updatedAt": "2026-02-17T12:45:00.000Z"
+  },
+  "successful": true
+}
+```
+
+---
+
+### Get Users with Role
+
+**GET** `/role/:identifier/users`
+
+Fetch all users that have been assigned a specific role.
+
+**Authentication Required:** Yes
+
+**Required Permissions:** `role.read`, `user.read`
+
+**URL Parameters:**
+
+- `identifier` - Role ID or moniker
+
+**Response:**
+
+```json
+{
+  "status": 200,
+  "message": "Users Fetched Successfully!",
+  "data": [
+    {
+      "id": "cku...",
+      "name": "John Doe",
+      "login": "john.doe",
+      "roles": ["ckx..."],
+      "createdAt": "2026-01-15T00:00:00.000Z",
+      "updatedAt": "2026-02-10T00:00:00.000Z"
+    },
+    {
+      "id": "ckv...",
+      "name": "Jane Smith",
+      "login": "jane.smith",
+      "roles": ["ckx...", "cky..."],
+      "createdAt": "2026-01-20T00:00:00.000Z",
+      "updatedAt": "2026-02-12T00:00:00.000Z"
+    }
+  ],
+  "successful": true
+}
+```
+
+---
+
+## Permission Routes
+
+### Get All Permission Nodes (Categorized)
+
+**GET** `/permissions`
+
+Fetch all permission nodes organized by category. Returns the full permission node definition object with categories as keys.
+
+**Authentication Required:** Yes
+
+**Required Permissions:** `role.read`
+
+**Response:**
+
+```json
+{
+  "status": 200,
+  "message": "Permission Nodes Fetched Successfully!",
+  "data": {
+    "global": {
+      "name": "Global Permissions",
+      "description": "Global wildcard permissions that grant access to all resources",
+      "permissions": [
+        {
+          "node": "*",
+          "description": "Full access to all resources and actions (administrator role)",
+          "usedIn": []
+        }
+      ]
+    },
+    "company": { "..." },
+    "credential": { "..." },
+    "...additional categories": { "..." }
+  },
+  "successful": true
+}
+```
+
+---
+
+### Get All Permission Nodes (Flat)
+
+**GET** `/permissions/nodes`
+
+Fetch a flat array of all permission nodes across all categories.
+
+**Authentication Required:** Yes
+
+**Required Permissions:** `role.read`
+
+**Response:**
+
+```json
+{
+  "status": 200,
+  "message": "All Permission Nodes Fetched Successfully!",
+  "data": [
+    {
+      "node": "*",
+      "description": "Full access to all resources and actions (administrator role)",
+      "usedIn": []
+    },
+    {
+      "node": "company.fetch",
+      "description": "Fetch a single company",
+      "usedIn": ["src/api/companies/[id]/fetch.ts"]
+    },
+    "...additional nodes"
+  ],
+  "successful": true
+}
+```
+
+---
+
+### Get Permission Nodes by Category
+
+**GET** `/permissions/:category`
+
+Fetch all permission nodes for a specific category.
+
+**Authentication Required:** Yes
+
+**Required Permissions:** `role.read`
+
+**Path Parameters:**
+
+- `category` - The category key (e.g., `global`, `company`, `credential`, `credentialType`, `role`, `user`, `permission`, `uiNavigation`, `adminUI`)
+
+**Response (Success):**
+
+```json
+{
+  "status": 200,
+  "message": "Permission Category Fetched Successfully!",
+  "data": {
+    "name": "Company Permissions",
+    "description": "Permissions for accessing and managing company resources",
+    "permissions": [
+      {
+        "node": "company.fetch",
+        "description": "Fetch a single company",
+        "usedIn": ["src/api/companies/[id]/fetch.ts"]
+      },
+      {
+        "node": "company.fetch.address",
+        "description": "View company address information",
+        "usedIn": ["src/api/companies/[id]/fetch.ts"],
+        "dependencies": ["company.fetch"]
+      }
+    ]
+  },
+  "successful": true
+}
+```
+
+**Response (Not Found):**
+
+```json
+{
+  "status": 404,
+  "message": "Permission category \"invalidCategory\" not found",
+  "error": "NotFound",
+  "successful": false
+}
+```
+
+---
+
 ## Utility Routes

 ### Teapot