// @ts-check
/**
* @import {ExpressRequestAuthorized, ExpressResponse} from '../types.js'
*/
/**
* List Share Router - List and Dynamic List Sharing Management
*
* This module provides comprehensive sharing functionality for both static lists and dynamic lists,
* enabling controlled access and collaboration across different user groups and permission levels.
*
* Key Features:
* - Share lists with groups or other lists as sources
* - Granular permission control (visible vs changeable access)
* - Admin-controlled sharing with hierarchical permissions
* - Real-time synchronization of shared list changes
* - Comprehensive share management and monitoring
* - Integration with visibility and access control systems
*
* Share Types:
* - visible: Read-only access to list contents
* - changeable: Read-write access to list contents
*
* Business Logic:
* - Only list administrators can create or remove shares
* - Shares are based on source objects (groups or lists)
* - Shared access respects the hierarchical permission structure
* - Changes to shared lists are synchronized in real-time
* - Share relationships are tracked and auditable
*/
import { checkAdmin, checkVisible } from '../utils/authChecks.js';
import { requestUpdateLogger } from '../utils/requestLogger.js';
import * as listShareController from './listShare/controller.js';
export const putShare = listShareController.putShare;
export const deleteShare = listShareController.deleteShare;
export const getSharesAll = listShareController.getSharesAll;
export const getShares = listShareController.getShares;
export const getShared = listShareController.getShared;
export const getShare = listShareController.getShare;
/**
* @param {import('express').Router} list
* @param {import('express').Router} dlist
*/
const listShares=(list,dlist)=>
{
/**
* Create a share filter for a static list
*
* Creates a new share relationship that grants access to a static list based on a source
* object (group or list). The share can be read-only or allow modifications based on
* the permission level specified.
*
* @route PUT /list/share/:UIDsource/:UIDlist
* @param {string} UIDsource - Unique identifier of the source object (group or list)
* @param {string} UIDlist - Unique identifier of the static list to share
* @param {Object} request.body - Share configuration
* @param {string} request.body.type - Type of share filter
* @param {boolean} [request.body.readOnly=false] - Whether share is read-only (visible) or modifiable (changeable)
* @param {Object} [request.body] - Additional filter configuration
* @example
* PUT /list/share/group-123/project-team-456
* {
* "type": "group_members",
* "readOnly": false
* }
* Response: {
* "success": true,
* "result": {
* "UID": "share-789",
* "type": "group_members",
* "readOnly": false
* }
* }
* @returns {Object} Response object
* @property {boolean} .success - True if share was created successfully
* @property {Object} [result] - Created share information
* @property {string} result.UID - Unique identifier of the created share filter
* @property {Object} result - Additional share configuration data
*/
// @ts-ignore
list.put('/share/:UIDsource/:UIDlist', requestUpdateLogger, listShareController.putListShareController)
/**
* Create a share filter for a dynamic list
*
* Creates a new share relationship that grants access to a dynamic list based on a source
* object (group or list). The share can be read-only or allow modifications based on
* the permission level specified.
*
* @route PUT /dlist/share/:UIDsource/:UIDlist
* @param {string} UIDsource - Unique identifier of the source object (group or list)
* @param {string} UIDlist - Unique identifier of the dynamic list to share
* @param {Object} request.body - Share configuration
* @param {string} request.body.type - Type of share filter
* @param {boolean} [request.body.readOnly=false] - Whether share is read-only (visible) or modifiable (changeable)
* @param {Object} [request.body] - Additional filter configuration
* @example
* PUT /dlist/share/dept-123/active-devs-456
* {
* "type": "department_filter",
* "readOnly": true
* }
* Response: {
* "success": true,
* "result": {
* "UID": "share-789",
* "type": "department_filter",
* "readOnly": true
* }
* }
* @returns {Object} Response object
* @property {boolean} .success - True if share was created successfully
* @property {Object} [result] - Created share information
* @property {string} result.UID - Unique identifier of the created share filter
* @property {Object} result - Additional share configuration data
*/
// @ts-ignore
dlist.put('/share/:UIDsource/:UIDlist', requestUpdateLogger, listShareController.putDlistShareController)
/**
* Remove a share filter from a static list
*
* Removes an existing share relationship from a static list, revoking access
* for the associated source object. Requires admin permissions for the list.
*
* @route DELETE /list/share/:UIDshare
* @param {string} UIDshare - Unique identifier of the share filter to remove
* @example
* DELETE /list/share/share-789
* Response: { "success": true }
* @returns {Object} Response object
* @property {boolean} .success - True if share was removed successfully
* @property {string} [message] - Error message if removal failed
*/
// @ts-ignore
list.delete('/share/:UIDshare', requestUpdateLogger, listShareController.deleteListShareController)
/**
* Remove a share filter from a dynamic list
*
* Removes an existing share relationship from a dynamic list, revoking access
* for the associated source object. Requires admin permissions for the list.
*
* @route DELETE /dlist/share/:UIDshare
* @param {string} UIDshare - Unique identifier of the share filter to remove
* @example
* DELETE /dlist/share/share-789
* Response: { "success": true }
* @returns {Object} Response object
* @property {boolean} .success - True if share was removed successfully
* @property {string} [message] - Error message if removal failed
*/
// @ts-ignore
dlist.delete('/share/:UIDshare', requestUpdateLogger, listShareController.deleteDlistShareController)
// get all share filters in the system (only for admins)
/**
* Get all share filters in the system (Admin only)
*
* Retrieves a comprehensive list of all share filters across the system.
* This endpoint is restricted to administrators for system-wide monitoring
* and management of sharing relationships.
*
* @route GET /list/shares/all
* @example
* GET /list/shares/all
* Response: {
* "success": true,
* "result": [
* {
* "UID": "share-123",
* "Data": { "type": "group_members", "readOnly": false },
* "Title": "IT Department",
* "Display": "IT Department Members",
* "UIDBelongsTo": "group-456",
* "UIDTarget": "list-789"
* }
* ]
* }
* @returns {Object} Response object
* @property {boolean} .success - True if query was successful
* @property {Array} .result - Array of all share filters
* @property {string} .result[].UID - Share filter unique identifier
* @property {Object} .result[].Data - Share filter configuration
* @property {string} .result[].Title - Source object title
* @property {string} .result[].Display - Source object display name
* @property {string} .result[].UIDBelongsTo - Source object UID
* @property {string} .result[].UIDTarget - Target list UID
*/
// @ts-ignore
list.get('/shares/all',checkAdmin,(req,res)=>getSharesAll(req,res,'list'))
/**
* Get all share filters for dynamic lists in the system (Admin only)
*
* Retrieves a comprehensive list of all share filters for dynamic lists across the system.
* This endpoint is restricted to administrators for system-wide monitoring.
*
* @route GET /dlist/shares/all
* @example
* GET /dlist/shares/all
* Response: {
* "success": true,
* "result": [
* {
* "UID": "share-456",
* "Data": { "type": "department_filter", "readOnly": true },
* "Title": "Engineering Dept",
* "Display": "Engineering Department",
* "UIDBelongsTo": "group-789",
* "UIDTarget": "dlist-101"
* }
* ]
* }
* @returns {Object} Response object
* @property {boolean} .success - True if query was successful
* @property {Array} .result - Array of all dynamic list share filters
* @property {string} .result[].UID - Share filter unique identifier
* @property {Object} .result[].Data - Share filter configuration
* @property {string} .result[].Title - Source object title
* @property {string} .result[].Display - Source object display name
* @property {string} .result[].UIDBelongsTo - Source object UID
* @property {string} .result[].UIDTarget - Target dynamic list UID
*/
// @ts-ignore
dlist.get('/shares/all',checkAdmin,(req,res)=>getSharesAll(req,res,'dlist'))
// get all share filters for a list/dlist
/**
* Get all share filters for a specific static list
*
* Retrieves all share filters associated with a specific static list,
* showing which sources have access and their permission levels.
*
* @route GET /list/shares/:UIDlist
* @param {string} UIDlist - Unique identifier of the static list
* @example
* GET /list/shares/project-team-123
* Response: {
* "success": true,
* "result": [
* {
* "UID": "share-789",
* "Type": "changeable",
* "Data": { "type": "group_members" },
* "Title": "IT Department",
* "Display": "IT Department Members",
* "UIDBelongsTo": "group-456",
* "SourceType": "group"
* }
* ]
* }
* @returns {Object} Response object
* @property {boolean} .success - True if query was successful
* @property {Array} .result - Array of share filters for this list
* @property {string} .result[].UID - Share filter unique identifier
* @property {string} .result[].Type - Share type (visible/changeable)
* @property {Object} .result[].Data - Share filter configuration
* @property {string} .result[].Title - Source object title
* @property {string} .result[].Display - Source object display name
* @property {string} .result[].UIDBelongsTo - Source object UID
* @property {string} .result[].SourceType - Type of source object
*/
// @ts-ignore
list.get('/shares/:UIDlist',checkVisible,(req,res)=>getShares(req,res,'list'))
/**
* Get all share filters for a specific dynamic list
*
* Retrieves all share filters associated with a specific dynamic list,
* showing which sources have access and their permission levels.
*
* @route GET /dlist/shares/:UIDlist
* @param {string} UIDlist - Unique identifier of the dynamic list
* @example
* GET /dlist/shares/active-devs-123
* Response: {
* "success": true,
* "result": [
* {
* "UID": "share-101",
* "Type": "visible",
* "Data": { "type": "department_filter" },
* "Title": "Engineering Dept",
* "Display": "Engineering Department",
* "UIDBelongsTo": "group-789",
* "SourceType": "group"
* }
* ]
* }
* @returns {Object} Response object
* @property {boolean} .success - True if query was successful
* @property {Array} .result - Array of share filters for this list
* @property {string} .result[].UID - Share filter unique identifier
* @property {string} .result[].Type - Share type (visible/changeable)
* @property {Object} .result[].Data - Share filter configuration
* @property {string} .result[].Title - Source object title
* @property {string} .result[].Display - Source object display name
* @property {string} .result[].UIDBelongsTo - Source object UID
* @property {string} .result[].SourceType - Type of source object
*/
// @ts-ignore
dlist.get('/shares/:UIDlist',checkVisible,(req,res)=>getShares(req,res,'dlist'))
// get individual share
/**
* Get detailed information about a specific share filter
*
* Retrieves comprehensive information about a specific share filter,
* including its configuration, source, and target relationships.
*
* @route GET /list/share/:UID
* @param {string} UID - Unique identifier of the share filter
* @example
* GET /list/share/share-789
* Response: {
* "success": true,
* "result": {
* "UID": "share-789",
* "UIDBelongsTo": "group-456",
* "Data": { "type": "group_members", "readOnly": false },
* "Type": "changeable",
* "UIDTarget": "list-123",
* "SourceType": "group"
* }
* }
* @returns {Object} Response object
* @property {boolean} .success - True if share was found
* @property {Object} [result] - Share filter information
* @property {string} result.UID - Share filter unique identifier
* @property {string} result.UIDBelongsTo - Source object UID
* @property {Object} result.Data - Share filter configuration
* @property {string} result.Type - Share type (visible/changeable)
* @property {string} result.UIDTarget - Target list UID
* @property {string} result.SourceType - Type of source object
*/
// @ts-ignore
list.get('/share/:UID',getShare)
/**
* Get detailed information about a specific dynamic list share filter
*
* Retrieves comprehensive information about a specific share filter for dynamic lists,
* including its configuration, source, and target relationships.
*
* @route GET /dlist/share/:UID
* @param {string} UID - Unique identifier of the share filter
* @example
* GET /dlist/share/share-101
* Response: {
* "success": true,
* "result": {
* "UID": "share-101",
* "UIDBelongsTo": "group-789",
* "Data": { "type": "department_filter", "readOnly": true },
* "Type": "visible",
* "UIDTarget": "dlist-456",
* "SourceType": "group"
* }
* }
* @returns {Object} Response object
* @property {boolean} .success - True if share was found
* @property {Object} [result] - Share filter information
* @property {string} result.UID - Share filter unique identifier
* @property {string} result.UIDBelongsTo - Source object UID
* @property {Object} result.Data - Share filter configuration
* @property {string} result.Type - Share type (visible/changeable)
* @property {string} result.UIDTarget - Target dynamic list UID
* @property {string} result.SourceType - Type of source object
*/
// @ts-ignore
dlist.get('/share/:UID',getShare)
// GET actually shared
/**
* Get paginated list of members shared with a static list
*
* Retrieves a paginated list of all members who have access to a static list
* through share relationships, including their permission levels and details.
*
* @route GET /list/shared/:UIDlist
* @param {string} UIDlist - Unique identifier of the static list
* @param {number} [query.__page] - Page number for pagination
* @param {number} [query.limit] - Number of results per page
* @example
* GET /list/shared/project-team-123?__page=1
* Response: {
* "success": true,
* "result": [
* {
* "Type": "person",
* "UID": "person-456",
* "Data": { "name": "John Doe", "email": "john@example.com" },
* "ExtraData": { "department": "IT" },
* "Title": "John Doe",
* "Display": "John Doe",
* "readOnly": 0,
* "admin": 0
* }
* ]
* }
* @returns {Object} Response object
* @property {boolean} .success - True if query was successful
* @property {Array} .result - Array of shared members
* @property {string} .result[].Type - Object type (person/group)
* @property {string} .result[].UID - Member unique identifier
* @property {Object} .result[].Data - Member data
* @property {Object} .result[].ExtraData - Additional member data
* @property {string} .result[].Title - Member title
* @property {string} .result[].Display - Member display name
* @property {number} .result[].readOnly - Whether access is read-only (1) or modifiable (0)
* @property {number} .result[].admin - Whether user has admin access (1) or not (0)
*/
// @ts-ignore
list.get('/shared/:UIDlist', checkVisible, listShareController.getListSharedController)
/**
* Get paginated list of members shared with a dynamic list
*
* Retrieves a paginated list of all members who have access to a dynamic list
* through share relationships, including their permission levels and details.
*
* @route GET /dlist/shared/:UIDlist
* @param {string} UIDlist - Unique identifier of the dynamic list
* @param {number} [query.__page] - Page number for pagination
* @param {number} [query.limit] - Number of results per page
* @example
* GET /dlist/shared/active-devs-123?__page=1
* Response: {
* "success": true,
* "result": [
* {
* "Type": "person",
* "UID": "person-789",
* "Data": { "name": "Jane Smith", "skills": ["JavaScript", "React"] },
* "ExtraData": { "experience": "5 years" },
* "Title": "Jane Smith",
* "Display": "Jane Smith - Senior Developer",
* "readOnly": 1,
* "admin": 0
* }
* ]
* }
* @returns {Object} Response object
* @property {boolean} .success - True if query was successful
* @property {Array} .result - Array of shared members
* @property {string} .result[].Type - Object type (person/group)
* @property {string} .result[].UID - Member unique identifier
* @property {Object} .result[].Data - Member data
* @property {Object} .result[].ExtraData - Additional member data
* @property {string} .result[].Title - Member title
* @property {string} .result[].Display - Member display name
* @property {number} .result[].readOnly - Whether access is read-only (1) or modifiable (0)
* @property {number} .result[].admin - Whether user has admin access (1) or not (0)
*/
// @ts-ignore
dlist.get('/shared/:UIDlist', checkVisible, listShareController.getDlistSharedController)
}
export default listShares