Zumri-Backend/Documentation/Permission-API.md

# Permission API

## Authentication
All endpoints require authentication token. Include in header:
```
Authorization: Bearer <token>
```

---

## Permission Endpoints

### Create Permission

**Endpoint**
```
POST: http://localhost:3070/api/permission
```

**Authorization**: Admin only

**Request Body**
```json
{
  "permissionName": "Create Inquiry",
  "permissionDescription": "Permission to create new inquiries",
  "page": "inquiry",
  "module": "inquiry_management",
  "action": "create"
}
```

**Response (201)**
```json
{
  "success": true,
  "data": {
    "permission_id": "inquiry_management.inquiry.create",
    "permissionName": "Create Inquiry",
    "permissionDescription": "Permission to create new inquiries",
    "page": "inquiry",
    "module": "inquiry_management",
    "action": "create",
    "createdAt": "2026-05-15T10:30:00Z",
    "updatedAt": "2026-05-15T10:30:00Z"
  }
}
```

---

### Bulk Create Permissions

**Endpoint**
```
POST: http://localhost:3070/api/permission/bulk
```

**Authorization**: Admin only

**Request Body**
```json
{
  "permissions": [
    {
      "permissionName": "Create Inquiry",
      "permissionDescription": "Permission to create new inquiries",
      "page": "inquiry",
      "module": "inquiry_management",
      "action": "create"
    },
    {
      "permissionName": "View Inquiry",
      "permissionDescription": "Permission to view inquiries",
      "page": "inquiry",
      "module": "inquiry_management",
      "action": "view"
    },
    {
      "permissionName": "Edit Inquiry",
      "permissionDescription": "Permission to edit inquiries",
      "page": "inquiry",
      "module": "inquiry_management",
      "action": "edit"
    }
  ]
}
```

**Response (201)**
```json
{
  "success": true,
  "data": {
    "created": [
      {
        "permission_id": "inquiry_management.inquiry.create",
        "permissionName": "Create Inquiry",
        "permissionDescription": "Permission to create new inquiries",
        "page": "inquiry",
        "module": "inquiry_management",
        "action": "create"
      },
      {
        "permission_id": "inquiry_management.inquiry.view",
        "permissionName": "View Inquiry",
        "permissionDescription": "Permission to view inquiries",
        "page": "inquiry",
        "module": "inquiry_management",
        "action": "view"
      },
      {
        "permission_id": "inquiry_management.inquiry.edit",
        "permissionName": "Edit Inquiry",
        "permissionDescription": "Permission to edit inquiries",
        "page": "inquiry",
        "module": "inquiry_management",
        "action": "edit"
      }
    ],
    "failed": []
  }
}
```

---

### Get All Permissions

**Endpoint**
```
GET: http://localhost:3070/api/permission
```

**Response (200)**
```json
{
  "success": true,
  "data": [
    {
      "permission_id": "inquiry_management.inquiry.create",
      "permissionName": "Create Inquiry",
      "permissionDescription": "Permission to create new inquiries",
      "page": "inquiry",
      "module": "inquiry_management",
      "action": "create"
    },
    {
      "permission_id": "inquiry_management.inquiry.view",
      "permissionName": "View Inquiry",
      "permissionDescription": "Permission to view inquiries",
      "page": "inquiry",
      "module": "inquiry_management",
      "action": "view"
    }
  ]
}
```

---

### Get Permission by ID

**Endpoint**
```
GET: http://localhost:3070/api/permission/:permissionId
```

**Example**
```
GET: http://localhost:3070/api/permission/inquiry_management.inquiry.create
```

**Response (200)**
```json
{
  "success": true,
  "data": {
    "permission_id": "inquiry_management.inquiry.create",
    "permissionName": "Create Inquiry",
    "permissionDescription": "Permission to create new inquiries",
    "page": "inquiry",
    "module": "inquiry_management",
    "action": "create"
  }
}
```

---

### Update Permission

**Endpoint**
```
PUT: http://localhost:3070/api/permission/:permissionId
```

**Authorization**: Admin only

**Request Body**
```json
{
  "permissionName": "Create New Inquiry",
  "permissionDescription": "Updated permission to create new inquiries"
}
```

**Response (200)**
```json
{
  "success": true,
  "data": {
    "permission_id": "inquiry_management.inquiry.create",
    "permissionName": "Create New Inquiry",
    "permissionDescription": "Updated permission to create new inquiries",
    "page": "inquiry",
    "module": "inquiry_management",
    "action": "create"
  },
  "message": "Permission updated successfully"
}
```

---

### Delete Permission

**Endpoint**
```
DELETE: http://localhost:3070/api/permission/:permissionId
```

**Authorization**: Admin only

**Response (200)**
```json
{
  "success": true,
  "message": "Permission deleted successfully"
}
```

---

## Role Endpoints

### Create Role

**Endpoint**
```
POST: http://localhost:3070/api/permission/roles
```

**Authorization**: Admin only

**Request Body**
```json
{
  "roleName": "Inquiry Manager",
  "roleDescription": "Role for managing inquiries"
}
```

**Response (201)**
```json
{
  "success": true,
  "data": {
    "role_id": "role_1715843400000",
    "roleName": "Inquiry Manager",
    "roleDescription": "Role for managing inquiries",
    "createdAt": "2026-05-15T10:30:00Z",
    "updatedAt": "2026-05-15T10:30:00Z"
  }
}
```

---

### Get All Roles

**Endpoint**
```
GET: http://localhost:3070/api/permission/roles
```

**Response (200)**
```json
{
  "success": true,
  "data": [
    {
      "role_id": "role_1715843400000",
      "roleName": "Inquiry Manager",
      "roleDescription": "Role for managing inquiries",
      "rolePermissions": [
        {
          "rp_id": "rp_1715843500000",
          "role_id": "role_1715843400000",
          "permission_id": "inquiry_management.inquiry.create",
          "permission": {
            "permission_id": "inquiry_management.inquiry.create",
            "permissionName": "Create Inquiry",
            "page": "inquiry",
            "module": "inquiry_management",
            "action": "create"
          }
        }
      ]
    }
  ]
}
```

---

### Get Role by ID

**Endpoint**
```
GET: http://localhost:3070/api/permission/roles/:roleId
```

**Example**
```
GET: http://localhost:3070/api/permission/roles/role_1715843400000
```

**Response (200)**
```json
{
  "success": true,
  "data": {
    "role_id": "role_1715843400000",
    "roleName": "Inquiry Manager",
    "roleDescription": "Role for managing inquiries",
    "rolePermissions": [
      {
        "rp_id": "rp_1715843500000",
        "role_id": "role_1715843400000",
        "permission_id": "inquiry_management.inquiry.create",
        "permission": {
          "permission_id": "inquiry_management.inquiry.create",
          "permissionName": "Create Inquiry",
          "page": "inquiry",
          "module": "inquiry_management",
          "action": "create"
        }
      }
    ]
  }
}
```

---

### Update Role

**Endpoint**
```
PUT: http://localhost:3070/api/permission/roles/:roleId
```

**Authorization**: Admin only

**Request Body**
```json
{
  "roleName": "Senior Inquiry Manager",
  "roleDescription": "Updated role for managing inquiries"
}
```

**Response (200)**
```json
{
  "success": true,
  "data": {
    "role_id": "role_1715843400000",
    "roleName": "Senior Inquiry Manager",
    "roleDescription": "Updated role for managing inquiries"
  },
  "message": "Role updated successfully"
}
```

---

### Delete Role

**Endpoint**
```
DELETE: http://localhost:3070/api/permission/roles/:roleId
```

**Authorization**: Admin only

**Response (200)**
```json
{
  "success": true,
  "message": "Role deleted successfully"
}
```

---

## Role-Permission Assignment Endpoints

### Assign Permission to Role

**Endpoint**
```
POST: http://localhost:3070/api/permission/roles/:roleId/permissions
```

**Authorization**: Admin only

**Request Body**
```json
{
  "role_id": "role_1715843400000",
  "permission_id": "inquiry_management.inquiry.create"
}
```

**Response (201)**
```json
{
  "success": true,
  "data": {
    "rp_id": "rp_1715843500000",
    "role_id": "role_1715843400000",
    "permission_id": "inquiry_management.inquiry.create",
    "createdAt": "2026-05-15T10:30:00Z",
    "updatedAt": "2026-05-15T10:30:00Z"
  }
}
```

---

### Bulk Assign Permissions to Role

**Endpoint**
```
POST: http://localhost:3070/api/permission/roles/permissions/bulk
```

**Authorization**: Admin only

**Request Body**
```json
{
  "role_id": "role_1715843400000",
  "permission_ids": [
    "inquiry_management.inquiry.create",
    "inquiry_management.inquiry.view",
    "inquiry_management.inquiry.edit",
    "vendor_management.vendor.view"
  ]
}
```

**Response (201)**
```json
{
  "success": true,
  "data": {
    "created": [
      {
        "rp_id": "rp_1715843500001",
        "role_id": "role_1715843400000",
        "permission_id": "inquiry_management.inquiry.create"
      },
      {
        "rp_id": "rp_1715843500002",
        "role_id": "role_1715843400000",
        "permission_id": "inquiry_management.inquiry.view"
      },
      {
        "rp_id": "rp_1715843500003",
        "role_id": "role_1715843400000",
        "permission_id": "inquiry_management.inquiry.edit"
      },
      {
        "rp_id": "rp_1715843500004",
        "role_id": "role_1715843400000",
        "permission_id": "vendor_management.vendor.view"
      }
    ],
    "failed": []
  }
}
```

**Response with Failures (201)**
```json
{
  "success": false,
  "data": {
    "created": [
      {
        "rp_id": "rp_1715843500001",
        "role_id": "role_1715843400000",
        "permission_id": "inquiry_management.inquiry.create"
      }
    ],
    "failed": [
      {
        "role_id": "role_1715843400000",
        "permission_id": "inquiry_management.inquiry.view",
        "error": "Role permission already exists"
      },
      {
        "role_id": "role_1715843400000",
        "permission_id": "nonexistent_permission",
        "error": "Permission not found"
      }
    ]
  }
}
```

---

## User Permission Endpoints

### Get User Permissions

**Endpoint**
```
GET: http://localhost:3070/api/permission/users/:userId/permissions
```

**Example**
```
GET: http://localhost:3070/api/permission/users/usr_5ff8afec-5ddc-47d9-a63f-b43df0d8c3b4/permissions
```

**Response (200)**
```json
{
  "success": true,
  "data": [
    {
      "up_id": 1,
      "user_id": "usr_5ff8afec-5ddc-47d9-a63f-b43df0d8c3b4",
      "permission_id": "inquiry_management.inquiry.create",
      "permission": {
        "permission_id": "inquiry_management.inquiry.create",
        "permissionName": "Create Inquiry",
        "page": "inquiry",
        "module": "inquiry_management",
        "action": "create"
      }
    }
  ]
}
```

---

### Create User Permission

**Endpoint**
```
POST: http://localhost:3070/api/permission/users/permissions
```

**Authorization**: Admin only

**Request Body**
```json
{
  "user_id": "usr_5ff8afec-5ddc-47d9-a63f-b43df0d8c3b4",
  "permission_id": "inquiry_management.inquiry.create"
}
```

**Response (201)**
```json
{
  "success": true,
  "data": {
    "up_id": 1,
    "user_id": "usr_5ff8afec-5ddc-47d9-a63f-b43df0d8c3b4",
    "permission_id": "inquiry_management.inquiry.create",
    "createdAt": "2026-05-15T10:30:00Z",
    "updatedAt": "2026-05-15T10:30:00Z"
  }
}
```

---

### Bulk Create User Permissions

**Endpoint**
```
POST: http://localhost:3070/api/permission/users/permissions/bulk
```

**Authorization**: Admin only

**Request Body**
```json
{
  "user_id": "usr_5ff8afec-5ddc-47d9-a63f-b43df0d8c3b4",
  "permission_ids": [
    "inquiry_management.inquiry.create",
    "inquiry_management.inquiry.view",
    "inquiry_management.inquiry.edit",
    "vendor_management.vendor.view"
  ]
}
```

**Response (201)**
```json
{
  "success": true,
  "data": {
    "created": [
      {
        "up_id": 1,
        "user_id": "usr_5ff8afec-5ddc-47d9-a63f-b43df0d8c3b4",
        "permission_id": "inquiry_management.inquiry.create"
      },
      {
        "up_id": 2,
        "user_id": "usr_5ff8afec-5ddc-47d9-a63f-b43df0d8c3b4",
        "permission_id": "inquiry_management.inquiry.view"
      },
      {
        "up_id": 3,
        "user_id": "usr_5ff8afec-5ddc-47d9-a63f-b43df0d8c3b4",
        "permission_id": "inquiry_management.inquiry.edit"
      },
      {
        "up_id": 4,
        "user_id": "usr_5ff8afec-5ddc-47d9-a63f-b43df0d8c3b4",
        "permission_id": "vendor_management.vendor.view"
      }
    ],
    "failed": []
  }
}
```

**Response with Failures (201)**
```json
{
  "success": false,
  "data": {
    "created": [
      {
        "up_id": 1,
        "user_id": "usr_5ff8afec-5ddc-47d9-a63f-b43df0d8c3b4",
        "permission_id": "inquiry_management.inquiry.create"
      }
    ],
    "failed": [
      {
        "user_id": "usr_5ff8afec-5ddc-47d9-a63f-b43df0d8c3b4",
        "permission_id": "inquiry_management.inquiry.view",
        "error": "User permission already exists"
      },
      {
        "user_id": "usr_5ff8afec-5ddc-47d9-a63f-b43df0d8c3b4",
        "permission_id": "nonexistent_permission",
        "error": "Permission not found"
      }
    ]
  }
}
```

---

### Update User Permission

**Endpoint**
```
PUT: http://localhost:3070/api/permission/users/permissions/:upId
```

**Authorization**: Admin only

**Request Body**
```json
{
  "permission_id": "inquiry_management.inquiry.edit"
}
```

**Response (200)**
```json
{
  "success": true,
  "data": {
    "up_id": 1,
    "user_id": "usr_5ff8afec-5ddc-47d9-a63f-b43df0d8c3b4",
    "permission_id": "inquiry_management.inquiry.edit"
  },
  "message": "User permission updated successfully"
}
```

---

### Delete User Permission

**Endpoint**
```
DELETE: http://localhost:3070/api/permission/users/permissions/:upId
```

**Authorization**: Admin only

**Response (200)**
```json
{
  "success": true,
  "message": "User permission deleted successfully"
}
```

---

## Error Responses

### Bad Request (400)
```json
{
  "success": false,
  "message": "Permission name, page, module, and action are required"
}
```

### Not Found (404)
```json
{
  "success": false,
  "message": "Permission not found"
}
```

### Internal Server Error (500)
```json
{
  "success": false,
  "message": "An error occurred while fetching permissions."
}
```