// @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
*/
/**
* @swagger
* components:
* schemas:
* ShareFilter:
* type: object
* properties:
* UID:
* type: string
* format: uuid
* description: Share filter unique identifier
* Type:
* type: string
* enum: [visible, changeable]
* description: Permission level of the share
* Data:
* type: object
* description: Share filter configuration data
* Title:
* type: string
* description: Source object title
* Display:
* type: string
* description: Source object display name
* UIDBelongsTo:
* type: string
* format: uuid
* description: UID of the source object
* UIDTarget:
* type: string
* format: uuid
* description: UID of the target list
* SourceType:
* type: string
* enum: [group, list]
* description: Type of the source object
*/
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)=>
{
/**
* @swagger
* /api/list/share/{UIDsource}/{UIDlist}:
* put:
* summary: Create a share filter for a static list
* description: Creates a new share relationship granting access to a static list based on a source object (group or list). Requires admin rights on the list and visibility rights on the source.
* tags: [Lists]
* security:
* - bearerAuth: []
* parameters:
* - in: path
* name: UIDsource
* required: true
* schema:
* type: string
* format: uuid
* description: UID of the source object (group or list)
* - in: path
* name: UIDlist
* required: true
* schema:
* type: string
* format: uuid
* description: UID of the static list to share
* requestBody:
* required: true
* content:
* application/json:
* schema:
* type: object
* required:
* - type
* properties:
* type:
* type: string
* description: Filter type
* responses:
* 200:
* description: Share filter created successfully
* content:
* application/json:
* schema:
* type: object
* properties:
* success:
* type: boolean
* result:
* $ref: '#/components/schemas/ShareFilter'
*/
// @ts-ignore
list.put('/share/:UIDsource/:UIDlist', requestUpdateLogger, listShareController.putListShareController)
/**
* @swagger
* /api/dlist/share/{UIDsource}/{UIDlist}:
* put:
* summary: Create a share filter for a dynamic list
* description: Creates a new share relationship granting access to a dynamic list based on a source object (group or list). Requires admin rights on the dynamic list and visibility rights on the source.
* tags: [Lists]
* security:
* - bearerAuth: []
* parameters:
* - in: path
* name: UIDsource
* required: true
* schema:
* type: string
* format: uuid
* description: UID of the source object (group or list)
* - in: path
* name: UIDlist
* required: true
* schema:
* type: string
* format: uuid
* description: UID of the dynamic list to share
* requestBody:
* required: true
* content:
* application/json:
* schema:
* type: object
* required:
* - type
* properties:
* type:
* type: string
* description: Filter type
* responses:
* 200:
* description: Share filter created successfully
* content:
* application/json:
* schema:
* type: object
* properties:
* success:
* type: boolean
* result:
* $ref: '#/components/schemas/ShareFilter'
*/
// @ts-ignore
dlist.put('/share/:UIDsource/:UIDlist', requestUpdateLogger, listShareController.putDlistShareController)
/**
* @swagger
* /api/list/share/{UIDshare}:
* delete:
* summary: Remove a share filter from a static list
* description: Removes an existing share relationship from a static list, revoking access for the associated source object. Requires admin rights on the list.
* tags: [Lists]
* security:
* - bearerAuth: []
* parameters:
* - in: path
* name: UIDshare
* required: true
* schema:
* type: string
* format: uuid
* description: UID of the share filter to remove
* responses:
* 200:
* description: Share filter removed successfully
* content:
* application/json:
* schema:
* type: object
* properties:
* success:
* type: boolean
* message:
* type: string
*/
// @ts-ignore
list.delete('/share/:UIDshare', requestUpdateLogger, listShareController.deleteListShareController)
/**
* @swagger
* /api/dlist/share/{UIDshare}:
* delete:
* summary: Remove a share filter from a dynamic list
* description: Removes an existing share relationship from a dynamic list, revoking access for the associated source object. Requires admin rights on the dynamic list.
* tags: [Lists]
* security:
* - bearerAuth: []
* parameters:
* - in: path
* name: UIDshare
* required: true
* schema:
* type: string
* format: uuid
* description: UID of the share filter to remove
* responses:
* 200:
* description: Share filter removed successfully
* content:
* application/json:
* schema:
* type: object
* properties:
* success:
* type: boolean
* message:
* type: string
*/
// @ts-ignore
dlist.delete('/share/:UIDshare', requestUpdateLogger, listShareController.deleteDlistShareController)
/**
* @swagger
* /api/list/shares/all:
* get:
* summary: Get all static list share filters (Admin only)
* description: Retrieves all share filters for static lists across the system. Restricted to administrators.
* tags: [Lists]
* security:
* - bearerAuth: []
* responses:
* 200:
* description: List of all share filters
* content:
* application/json:
* schema:
* type: object
* properties:
* success:
* type: boolean
* result:
* type: array
* items:
* $ref: '#/components/schemas/ShareFilter'
*/
// @ts-ignore
list.get('/shares/all',checkAdmin,(req,res)=>getSharesAll(req,res,'list'))
/**
* @swagger
* /api/dlist/shares/all:
* get:
* summary: Get all dynamic list share filters (Admin only)
* description: Retrieves all share filters for dynamic lists across the system. Restricted to administrators.
* tags: [Lists]
* security:
* - bearerAuth: []
* responses:
* 200:
* description: List of all dynamic list share filters
* content:
* application/json:
* schema:
* type: object
* properties:
* success:
* type: boolean
* result:
* type: array
* items:
* $ref: '#/components/schemas/ShareFilter'
*/
// @ts-ignore
dlist.get('/shares/all',checkAdmin,(req,res)=>getSharesAll(req,res,'dlist'))
/**
* @swagger
* /api/list/shares/{UIDlist}:
* get:
* summary: Get all share filters for a static list
* description: Retrieves all share filters associated with a specific static list, showing which sources have access and their permission levels.
* tags: [Lists]
* security:
* - bearerAuth: []
* parameters:
* - in: path
* name: UIDlist
* required: true
* schema:
* type: string
* format: uuid
* description: UID of the static list
* responses:
* 200:
* description: Share filters for the list
* content:
* application/json:
* schema:
* type: object
* properties:
* success:
* type: boolean
* result:
* type: array
* items:
* $ref: '#/components/schemas/ShareFilter'
*/
// @ts-ignore
list.get('/shares/:UIDlist',checkVisible,(req,res)=>getShares(req,res,'list'))
/**
* @swagger
* /api/dlist/shares/{UIDlist}:
* get:
* summary: Get all share filters for a dynamic list
* description: Retrieves all share filters associated with a specific dynamic list, showing which sources have access and their permission levels.
* tags: [Lists]
* security:
* - bearerAuth: []
* parameters:
* - in: path
* name: UIDlist
* required: true
* schema:
* type: string
* format: uuid
* description: UID of the dynamic list
* responses:
* 200:
* description: Share filters for the dynamic list
* content:
* application/json:
* schema:
* type: object
* properties:
* success:
* type: boolean
* result:
* type: array
* items:
* $ref: '#/components/schemas/ShareFilter'
*/
// @ts-ignore
dlist.get('/shares/:UIDlist',checkVisible,(req,res)=>getShares(req,res,'dlist'))
/**
* @swagger
* /api/list/share/{UID}:
* get:
* summary: Get a specific static list share filter
* description: Retrieves detailed information about a specific share filter for a static list.
* tags: [Lists]
* security:
* - bearerAuth: []
* parameters:
* - in: path
* name: UID
* required: true
* schema:
* type: string
* format: uuid
* description: UID of the share filter
* responses:
* 200:
* description: Share filter details
* content:
* application/json:
* schema:
* type: object
* properties:
* success:
* type: boolean
* result:
* $ref: '#/components/schemas/ShareFilter'
*/
// @ts-ignore
list.get('/share/:UID',getShare)
/**
* @swagger
* /api/dlist/share/{UID}:
* get:
* summary: Get a specific dynamic list share filter
* description: Retrieves detailed information about a specific share filter for a dynamic list.
* tags: [Lists]
* security:
* - bearerAuth: []
* parameters:
* - in: path
* name: UID
* required: true
* schema:
* type: string
* format: uuid
* description: UID of the share filter
* responses:
* 200:
* description: Share filter details
* content:
* application/json:
* schema:
* type: object
* properties:
* success:
* type: boolean
* result:
* $ref: '#/components/schemas/ShareFilter'
*/
// @ts-ignore
dlist.get('/share/:UID',getShare)
/**
* @swagger
* /api/list/shared/{UIDlist}:
* get:
* summary: Get paginated members shared with a static list
* description: Retrieves a paginated list of all members who have access to a static list through share relationships.
* tags: [Lists]
* security:
* - bearerAuth: []
* parameters:
* - in: path
* name: UIDlist
* required: true
* schema:
* type: string
* format: uuid
* description: UID of the static list
* - in: query
* name: __page
* schema:
* type: integer
* description: Page number for pagination
* responses:
* 200:
* description: Paginated list of shared members
* content:
* application/json:
* schema:
* type: object
* properties:
* success:
* type: boolean
* result:
* type: array
* items:
* type: object
* properties:
* Type:
* type: string
* description: Object type (person/group)
* UID:
* type: string
* format: uuid
* Data:
* type: object
* ExtraData:
* type: object
* Title:
* type: string
* Display:
* type: string
* readOnly:
* type: integer
* description: 1 = read-only, 0 = modifiable
* admin:
* type: integer
* description: 1 = admin access, 0 = no admin
*/
// @ts-ignore
list.get('/shared/:UIDlist', checkVisible, listShareController.getListSharedController)
/**
* @swagger
* /api/dlist/shared/{UIDlist}:
* get:
* summary: Get paginated members shared with a dynamic list
* description: Retrieves a paginated list of all members who have access to a dynamic list through share relationships.
* tags: [Lists]
* security:
* - bearerAuth: []
* parameters:
* - in: path
* name: UIDlist
* required: true
* schema:
* type: string
* format: uuid
* description: UID of the dynamic list
* - in: query
* name: __page
* schema:
* type: integer
* description: Page number for pagination
* responses:
* 200:
* description: Paginated list of shared members
* content:
* application/json:
* schema:
* type: object
* properties:
* success:
* type: boolean
* result:
* type: array
* items:
* type: object
* properties:
* Type:
* type: string
* description: Object type (person/group)
* UID:
* type: string
* format: uuid
* Data:
* type: object
* ExtraData:
* type: object
* Title:
* type: string
* Display:
* type: string
* readOnly:
* type: integer
* description: 1 = read-only, 0 = modifiable
* admin:
* type: integer
* description: 1 = admin access, 0 = no admin
*/
// @ts-ignore
dlist.get('/shared/:UIDlist', checkVisible, listShareController.getDlistSharedController)
}
export default listShares