Source: Router/admins.js

// @ts-check
/**
 * @import {ExpressRequestAuthorized, ExpressResponse} from '../types.js'
 */
/**
 * Admins Router
 * 
 * This router manages the admin list for an organization. It provides endpoints to:
 * - Get the current admin list UID for the organization
 * - Set/update the admin list for the organization
 * 
 * The admin functionality works by linking a specific list (which contains admin users)
 * to the organization via a 'admin' type link in the Links table.
 * 
 * All endpoints require admin rights to access.
 * 
 * @module AdminsRouter
 */
import express from 'express';
import {UUID2hex,HEX2uuid,query} from '@commtool/sql-query'
import { checkAdmin } from '../utils/authChecks.js';
import {requestUpdateLogger, errorLoggerRead,errorLoggerUpdate} from '../utils/requestLogger.js'

const api = express();

/**
 * GET /
 * Retrieves the admin list UID for the current organization
 * 
 * This endpoint looks up which list is currently configured as the admin list
 * for the organization by finding a link with type 'admin' pointing to the
 * organization's root UID.
 * 
 * Access: Requires admin rights
 * 




  * @returns {Object} Response object
 * @property {boolean} response.success - Whether the operation was successful
 * @property {string} [response.result] - UID of the admin list (if found)
 * @property {string} [response.message] - Error message (if no admin list defined)
 */

/**
 * @param {import('../types.js').ExpressRequestAuthorized} req
 * @param {import('../types.js').ExpressResponse} res
 */
const getAdminList = async (req, res) => {
    try {
        // Query the Links table to find the admin list for this organization
        // The admin list is linked to the organization root with type 'admin'
        const admins=await query(`SELECT UID FROM Links WHERE UIDTarget = ? AND Type='admin' `,[UUID2hex(req.session.root)])
        
        if(admins.length===1)
            // Admin list found - return its UID
            res.json({success:true,result:HEX2uuid(admins[0].UID)})
        else
            // No admin list configured yet
            res.json({success:false,message:'no admin list defined yet'})
    }
    catch(e)
    {
        // Log any database or other errors
        errorLoggerRead(e)
        res.status(500).json({success:false,message:'Internal server error'})
    }
}

// @ts-ignore
api.get('/', checkAdmin, getAdminList)


/**
 * PUT /:UIDlist
 * Sets or updates the admin list for the current organization
 * 
 * This endpoint configures which list should be used as the admin list for
 * the organization. It first removes any existing admin list link, then
 * creates a new link between the specified list and the organization.
 * 
 * The admin list contains the users who have administrative privileges
 * for the organization.
 * 
 * Access: Requires admin rights
 * 
 * @param {string} UIDlist - UUID of the list to set as admin list


  * @returns {Object} Response object
 * @property {boolean} response.success - Whether the operation was successful
 */

/**
 * @param {import('../types.js').ExpressRequestAuthorized} req
 * @param {import('../types.js').ExpressResponse} res
 */
const setAdminList = async (req, res) => {
    try {
        // First, remove any existing admin list link for this organization
        // This ensures there's only one admin list per organization
        await query(`DELETE FROM Links WHERE UIDTarget = ? AND Type='admin' `,[UUID2hex(req.session.root)])
        
        // Create a new link between the specified list and the organization
        // This establishes the list as the new admin list
        await query(`INSERT INTO Links (UID,Type,UIDTarget) VALUES(?,'admin',?)`, 
            [UUID2hex(req.params.UIDlist),UUID2hex(req.session.root)])
        
        res.json({success:true})
    }
    catch(e)
    {
        // Log any database or other errors
        errorLoggerUpdate(e)
        res.status(500).json({success:false,message:'Internal server error'})
    }
}

// @ts-ignore
api.put('/:UIDlist', requestUpdateLogger, checkAdmin, setAdminList)

/**
 * Export the admin router
 * 
 * This router provides a simple but essential functionality for managing
 * organizational administration. The admin list system works as follows:
 * 
 * 1. Each organization can have one admin list
 * 2. The admin list is a regular list object that contains admin users
 * 3. The connection between organization and admin list is stored in the Links table
 * 4. Link type 'admin' identifies admin list relationships
 * 
 * Database Schema:
 * - Links.UID: Points to the admin list UID
 * - Links.UIDTarget: Points to the organization root UID  
 * - Links.Type: Set to 'admin' to identify admin relationships
 * 
 * Security:
 * - All endpoints require existing admin rights (checkAdmin middleware)
 * - This prevents unauthorized users from viewing or modifying admin lists
 * - Request logging ensures admin list changes are tracked
 */
export default api