/** * @fileoverview Manager for the Retention Policies Resource */// -----------------------------------------------------------------------------// Requirements// -----------------------------------------------------------------------------import BoxClient from '../box-client';import urlPath from '../util/url-path';import {UserMini} from "../schemas";// -----------------------------------------------------------------------------// Typedefs// -----------------------------------------------------------------------------/** * Enum of valid retention policy types, which specify how long the policy should * remain in effect. * @readonly * @enum {RetentionPolicyType} */enum RetentionPolicyType { FINITE = 'finite', INDEFINITE = 'indefinite',}/** * Enum of valid retention types. * @readonly * @enum {RetentionType} */enum RetentionType { /** * You can modify the retention policy. For example, you can add or remove folders, * shorten or lengthen the policy duration, or delete the assignment. * Use this type if your retention policy is not related to any regulatory purposes. */ MODIFIABLE = 'modifiable', /** * You can modify the retention policy only in a limited way: add a folder, lengthen the duration, * retire the policy, change the disposition action or notification settings. * You cannot perform other actions, such as deleting the assignment or shortening the policy duration. * Use this type to ensure compliance with regulatory retention policies. */ NON_MODIFIABLE = 'non_modifiable',}/** * Enum of valid retention policy disposition actions, which specify what should * be done when the retention period is over * @readonly * @enum {RetentionPolicyDispositionAction} */enum RetentionPolicyDispositionAction { PERMANENTLY_DELETE = 'permanently_delete', REMOVE_RETENTION = 'remove_retention',}/** * Enum of valid policy assignment types, which specify what object the policy applies to * @readonly * @enum {RetentionPolicyAssignmentType} */enum RetentionPolicyAssignmentType { FOLDER = 'folder', ENTERPRISE = 'enterprise', METADATA = 'metadata_template',}/** * Metadata template fields to filter on for assigning a retention policy * @typedef {Object} MetadataFilterField * @property {string} field The field to filter on * @property {string|int} value The value to filter against */type MetadataFilterField = { field: string; value: string | number;};// -----------------------------------------------------------------------------// Private// -----------------------------------------------------------------------------const BASE_PATH = '/retention_policies', ASSIGNMENTS_PATH = '/retention_policy_assignments', FILE_VERSION_RETENTIONS_PATH = '/file_version_retentions', ASSIGNMENTS_SUBRESOURCE = 'assignments', FILES_UNDER_RETENTION_SUBRESOURCE = 'files_under_retention', FILES_VERSIONS_UNDER_RETENTION_SUBRESOURCE = 'file_versions_under_retention';// -----------------------------------------------------------------------------// Public// -----------------------------------------------------------------------------/** * Simple manager for interacting with all Retention Policies endpoints and actions. * * @constructor * @param {BoxClient} client - The Box API Client that is responsible for making calls to the API * @returns {void} */class RetentionPolicies { client: BoxClient; policyTypes!: typeof RetentionPolicyType; dispositionActions!: typeof RetentionPolicyDispositionAction; assignmentTypes!: typeof RetentionPolicyAssignmentType; retentionTypes!: typeof RetentionType; constructor(client: BoxClient) { this.client = client; } /** * Used to create a single retention policy for an enterprise * * API Endpoint: '/retention_policies' * Method: POST * * @param {string} name - The name of the retention policy to be created * @param {RetentionPolicyType} type - The type of policy to create * @param {RetentionPolicyDispositionAction} action - The disposition action for the new policy * @param {Object} [options] - Additional parameters * @param {boolean} [options.are_owners_notified] - Whether or not owner and co-owners of a file are notified when the policy nears expiration * @param {boolean} [options.can_owner_extend_retention] - Whether or not the owner of a file will be allowed to extend the retention * @param {UserMini[]} [options.custom_notification_recipients] - A list of users notified when the retention policy duration is about to end * @param {string} [options.description] - The additional text description of the retention policy * @param {int} [options.retention_length] - For finite policies, the number of days to retain the content * @param {RetentionType} [options.retention_type] - The type of retention for the new policy * @param {Function} [callback] - Passed the new policy information if it was acquired successfully, error otherwise * @returns {Promise<Object>} A promise resolving to the new policy object */ create( name: string, type: RetentionPolicyType, action: RetentionPolicyDispositionAction, options?: { are_owners_notified? : boolean; can_owner_extend_retention?: boolean; custom_notification_recipients?: UserMini[]; description?: string; retention_length?: number; retention_type?: RetentionType; }, callback?: Function ) { var apiPath = urlPath(BASE_PATH), params = { body: { policy_name: name, policy_type: type, disposition_action: action, }, }; Object.assign(params.body, options); return this.client.wrapWithDefaultHandler(this.client.post)( apiPath, params, callback ); } /** * Fetches details about a specific retention policy * * API Endpoint: '/retention_policies/:policyID' * Method: GET * * @param {string} policyID - The Box ID of the retention policy being requested * @param {Object} [options] - Additional options for the request. Can be left null in most cases. * @param {Function} [callback] - Passed the policy information if it was acquired successfully, error otherwise * @returns {Promise<Object>} A promise resolving to the policy object */ get(policyID: string, options?: Record<string, any>, callback?: Function) { var apiPath = urlPath(BASE_PATH, policyID), params = { qs: options, }; return this.client.wrapWithDefaultHandler(this.client.get)( apiPath, params, callback ); } /** * Update or modify a retention policy. * * API Endpoint: '/retention_policies/:policyID' * Method: PUT * * @param {string} policyID - The Box ID of the retention policy to update * @param {Object} updates - The information to be updated * @param {string} [updates.policy_name] - The name of the retention policy * @param {RetentionPolicyDispositionAction} [updates.disposition_action] - The disposition action for the updated policy * @param {boolean} [updates.are_owners_notified] - Whether or not owner and co-owners of a file are notified when the policy nears expiration * @param {boolean} [updates.can_owner_extend_retention] - Whether or not the owner of a file will be allowed to extend the retention * @param {UserMini[]} [updates.custom_notification_recipients] - A list of users notified when the retention policy duration is about to end * @param {string} [updates.description] - The additional text description of the retention policy * @param {int} [updates.retention_length] - For finite policies, the number of days to retain the content * @param {RetentionType} [updates.retention_type] - The type of retention. The only possible value here is non_modifiable. You can convert a modifiable policy to non_modifiable, but not the other way around. * @param {string} [updates.status] - Used to retire a retention policy if status is set to retired * @param {Function} [callback] - Passed the updated policy information if it was acquired successfully, error otherwise * @returns {Promise<Object>} A promise resolving to the updated policy object */ update( policyID: string, updates: { policy_name?: string; disposition_action?: RetentionPolicyDispositionAction; are_owners_notified? : boolean; can_owner_extend_retention?: boolean; custom_notification_recipients?: UserMini[]; description?: string; retention_length?: number; retention_type?: RetentionType; status?: string; }, callback?: Function ) { var apiPath = urlPath(BASE_PATH, policyID), params = { body: updates, }; return this.client.wrapWithDefaultHandler(this.client.put)( apiPath, params, callback ); } /** * Fetches a list of retention policies for the enterprise * * API Endpoint: '/retention_policies * Method: GET * * @param {Object} [options] - Additional options for the request. Can be left null in most cases. * @param {string} [options.policy_name] - A full or partial name to filter the retention policies by * @param {RetentionPolicyType} [options.policy_type] - A policy type to filter the retention policies by * @param {string} [options.created_by_user_id] - A user id to filter the retention policies by * @param {Function} [callback] - Passed the policy objects if they were acquired successfully, error otherwise * @returns {Promise<Object>} A promise resolving to the collection of policies */ getAll( options?: { policy_name?: string; policy_type?: RetentionPolicyType; created_by_user_id?: string; }, callback?: Function ) { var apiPath = urlPath(BASE_PATH), params = { qs: options, }; return this.client.wrapWithDefaultHandler(this.client.get)( apiPath, params, callback ); } /** * Fetch a list of assignments for a given retention policy * * API Endpoint: '/retention_policies/:policyID/assignments' * Method: GET * * @param {string} policyID - The Box ID of the retention policy to get assignments for * @param {Object} [options] - Additional options for the request. Can be left null in most cases. * @param {RetentionPolicyAssignmentType} [options.type] - The type of the retention policy assignment to retrieve * @param {Function} [callback] - Passed the assignment objects if they were acquired successfully, error otherwise * @returns {Promise<Object>} A promise resolving to the collection of policy assignments */ getAssignments( policyID: string, options?: { type?: RetentionPolicyAssignmentType; }, callback?: Function ) { var apiPath = urlPath(BASE_PATH, policyID, ASSIGNMENTS_SUBRESOURCE), params = { qs: options, }; return this.client.wrapWithDefaultHandler(this.client.get)( apiPath, params, callback ); } /** * Assign a retention policy to a folder or the entire enterprise. * * API Endpoint: '/retention_policy_assignments * Method: POST * * @param {string} policyID - The ID of the policy to assign * @param {RetentionPolicyAssignmentType} assignType - The type of object the policy will be assigned to * @param {string} assignID - The Box ID of the object to assign the retention policy to * @param {Object} [options] - Optional parameters for the request * @param {MetadataFilterField[]} [options.filter_fields] - Metadata fields to filter against, if assigning to a metadata template * @param {string} [options.start_date_field] - Id of Metadata field which will be used to specify the start date for the retention policy, or set this to "upload_date" as value to use the date when the file was uploaded to Box * @param {Function} [callback] - Passed the new assignment object if successful, error otherwise * @returns {Promise<Object>} A promise resolving to the created assignment object */ assign( policyID: string, assignType: RetentionPolicyAssignmentType, assignID: string, options?: | { filter_fields?: MetadataFilterField[]; start_date_field?: string; } | Function | null, callback?: Function ) { // Shuffle optional arguments if (typeof options === 'function') { callback = options; options = null; } var apiPath = urlPath(ASSIGNMENTS_PATH), params = { body: { policy_id: policyID, assign_to: { type: assignType, id: assignID, }, }, }; Object.assign(params.body, options); return this.client.wrapWithDefaultHandler(this.client.post)( apiPath, params, callback ); } /** * Fetch a specific policy assignment * * API Endpoint: '/retention_policy_assignments/:assignmentID' * Method: GET * * @param {string} assignmentID - The Box ID of the policy assignment object to fetch * @param {Object} [options] - Additional options for the request. Can be left null in most cases. * @param {Function} [callback] - Passed the assignment object if it was acquired successfully, error otherwise * @returns {Promise<Object>} A promise resolving to the assignment object */ getAssignment( assignmentID: string, options?: Record<string, any>, callback?: Function ) { var apiPath = urlPath(ASSIGNMENTS_PATH, assignmentID), params = { qs: options, }; return this.client.wrapWithDefaultHandler(this.client.get)( apiPath, params, callback ); } /** * Delete a specific policy assignment. * * API Endpoint: '/retention_policy_assignments/:assignmentID' * Method: DELETE * * @param {string} assignmentID - The Box ID of the policy assignment object to delete * @param {Function} [callback] - Empty response body passed if successful. * @returns {Promise<void>} A promise resolving to nothing */ deleteAssignment(assignmentID: string, callback?: Function) { var apiPath = urlPath(ASSIGNMENTS_PATH, assignmentID) return this.client.wrapWithDefaultHandler(this.client.del)( apiPath, null, callback ); } /** * Get the specific retention record for a retained file version. To use this feature, * you must have the manage retention policies scope enabled for your API key * via your application management console. * * API Endpoint: '/file_version_retentions/:retentionID' * Method: GET * * @param {string} retentionID - The ID for the file retention record to retrieve * @param {Object} [options] - Additional options for the request. Can be left null in most cases. * @param {Function} [callback] - Pass the file version retention record if successful, error otherwise * @returns {Promise<Object>} A promise resolving to the retention record */ getFileVersionRetention( retentionID: string, options?: Record<string, any>, callback?: Function ) { var apiPath = urlPath(FILE_VERSION_RETENTIONS_PATH, retentionID), params = { qs: options, }; return this.client.wrapWithDefaultHandler(this.client.get)( apiPath, params, callback ); } /** * Get a list of retention records for a retained file versions in an enterprise. * To use this feature, you must have the manage retention policies scope enabled * for your API key via your application management console. * * API Endpoint: '/file_version_retentions' * Method: GET * * @param {Object} [options] - Additional options for the request. Can be left null in most cases. * @param {string} [options.file_id] - A file id to filter the file version retentions by * @param {string} [options.file_version_id] - A file version id to filter the file version retentions by * @param {string} [options.policy_id] - A policy id to filter the file version retentions by * @param {RetentionPolicyDispositionAction} [options.disposition_action] - The disposition action of the retention policy to filter by * @param {string} [options.disposition_before] - Filter by retention policies which will complete before a certain time * @param {string} [options.disposition_after] - Filter by retention policies which will complete after a certain time * @param {int} [options.limit] - The maximum number of items to return in a page * @param {string} [options.marker] - Paging marker, left blank to begin paging from the beginning * @param {Function} [callback] - Pass the file version retention record if successful, error otherwise * @returns {Promise<Object>} A promise resolving to the collection of retention records */ getAllFileVersionRetentions( options?: { file_id?: string; file_version_id?: string; policy_id?: string; disposition_action?: RetentionPolicyDispositionAction; disposition_before?: string; disposition_after?: string; limit?: number; marker?: string; }, callback?: Function ) { var apiPath = urlPath(FILE_VERSION_RETENTIONS_PATH), params = { qs: options, }; return this.client.wrapWithDefaultHandler(this.client.get)( apiPath, params, callback ); } /** * Get files under retention by each assignment * To use this feature, you must have the manage retention policies scope enabled * for your API key via your application management console. * * API Endpoint: '/retention_policy_assignments/:assignmentID/files_under_retention' * Method: GET * * @param {string} assignmentID - The Box ID of the policy assignment object to fetch * @param {Object} [options] - Additional options for the request. Can be left null in most cases. * @param {int} [options.limit] - The maximum number of items to return in a page * @param {string} [options.marker] - Paging marker, left blank to begin paging from the beginning * @param {Function} [callback] - Pass the file version retention record if successful, error otherwise * @returns {Promise<Object>} A promise resolving to the collection of retention records */ getFilesUnderRetentionForAssignment( assignmentID: string, options?: { limit?: number; marker?: string; }, callback?: Function ) { var apiPath = urlPath( ASSIGNMENTS_PATH, assignmentID, FILES_UNDER_RETENTION_SUBRESOURCE ), params = { qs: options, }; return this.client.wrapWithDefaultHandler(this.client.get)( apiPath, params, callback ); } /** * Get file versions under retention by each assignment * To use this feature, you must have the manage retention policies scope enabled * for your API key via your application management console. * * API Endpoint: '/retention_policy_assignments/:assignmentID/file_versions_under_retention' * Method: GET * * @param {string} assignmentID - The Box ID of the policy assignment object to fetch * @param {Object} [options] - Additional options for the request. Can be left null in most cases. * @param {int} [options.limit] - The maximum number of items to return in a page * @param {string} [options.marker] - Paging marker, left blank to begin paging from the beginning * @param {Function} [callback] - Pass the file version retention record if successful, error otherwise * @returns {Promise<Object>} A promise resolving to the collection of retention records */ getFileVersionsUnderRetentionForAssignment( assignmentID: string, options?: { limit?: number; market?: string; }, callback?: Function ) { var apiPath = urlPath( ASSIGNMENTS_PATH, assignmentID, FILES_VERSIONS_UNDER_RETENTION_SUBRESOURCE ), params = { qs: options, }; return this.client.wrapWithDefaultHandler(this.client.get)( apiPath, params, callback ); }}/** * Enum of valid retention policy types, which specify how long the policy should * remain in effect. * @readonly * @enum {RetentionPolicyType} */RetentionPolicies.prototype.policyTypes = RetentionPolicyType;/** * Enum of valid retention policy disposition actions, which specify what should * be done when the retention period is over * @readonly * @enum {RetentionPolicyDispositionAction} */RetentionPolicies.prototype.dispositionActions = RetentionPolicyDispositionAction;/** * Enum of valid policy assignment types, which specify what object the policy applies to * @readonly * @enum {RetentionPolicyAssignmentType} */RetentionPolicies.prototype.assignmentTypes = RetentionPolicyAssignmentType;/** * Enum of valid retention types. Could be either modifiable or non-modifiable. * @readonly * @enum {RetentionType} */RetentionPolicies.prototype.retentionTypes = RetentionType;export = RetentionPolicies;