roboto-js 1.7.4 → 1.8.1

package/src/rbt_object.js

@@ -307,6 +307,351 @@ export default class RbtObject{
     }
   }
 
+  /**
+   * Grants access to this object for specific users and/or user groups.
+   * Updates the IAC (Identity and Access Control) permissions.
+   * 
+   * @param {Object} options - Access grant options
+   * @param {string[]} [options.userIds=[]] - Array of user IDs to grant read access
+   * @param {string[]} [options.groupIds=[]] - Array of user group IDs to grant read access
+   * @param {boolean} [options.write=false] - If true, grants write access instead of read access
+   * @param {boolean} [options.replace=false] - If true, replaces existing grants; if false, merges with existing
+   * @param {boolean} [options.save=true] - If true, automatically saves the object after updating permissions
+   * @returns {Promise<RbtObject>} - Returns this object (saved if options.save is true)
+   * 
+   * @example
+   * // Grant read access to specific users
+   * await myObject.grantAccess({ 
+   *   userIds: ['user123', 'user456'] 
+   * });
+   * 
+   * @example
+   * // Grant read access to user groups
+   * await myObject.grantAccess({ 
+   *   groupIds: ['grpRngAccount', 'grpAdmins'] 
+   * });
+   * 
+   * @example
+   * // Grant write access to users and groups
+   * await myObject.grantAccess({ 
+   *   userIds: ['user123'],
+   *   groupIds: ['grpAdmins'],
+   *   write: true 
+   * });
+   * 
+   * @example
+   * // Replace existing permissions instead of merging
+   * await myObject.grantAccess({ 
+   *   userIds: ['user123'],
+   *   replace: true 
+   * });
+   * 
+   * @example
+   * // Update permissions without auto-saving
+   * await myObject.grantAccess({ 
+   *   userIds: ['user123'],
+   *   save: false 
+   * });
+   * // ... make other changes ...
+   * await myObject.save();
+   */
+  async grantAccess(options = {}) {
+    const {
+      userIds = [],
+      groupIds = [],
+      write = false,
+      replace = false,
+      save = true
+    } = options;
+
+    // Validate inputs
+    if (!Array.isArray(userIds)) {
+      throw new Error('userIds must be an array');
+    }
+    if (!Array.isArray(groupIds)) {
+      throw new Error('groupIds must be an array');
+    }
+
+    // Get current IAC settings
+    const iac = this.get('iac') || {};
+
+    // Determine which grant type to update (read or write)
+    const grantType = write ? 'writeGrants' : 'readGrants';
+
+    // Initialize grants if they don't exist
+    if (!iac[grantType]) {
+      iac[grantType] = {};
+    }
+
+    // Handle users
+    if (userIds.length > 0) {
+      if (replace) {
+        // Replace existing users
+        iac[grantType].users = [...userIds];
+      } else {
+        // Merge with existing users (avoiding duplicates)
+        const existingUsers = iac[grantType].users || [];
+        const mergedUsers = [...new Set([...existingUsers, ...userIds])];
+        iac[grantType].users = mergedUsers;
+      }
+    }
+
+    // Handle user groups
+    if (groupIds.length > 0) {
+      if (replace) {
+        // Replace existing groups
+        iac[grantType].userGroups = [...groupIds];
+      } else {
+        // Merge with existing groups (avoiding duplicates)
+        const existingGroups = iac[grantType].userGroups || [];
+        const mergedGroups = [...new Set([...existingGroups, ...groupIds])];
+        iac[grantType].userGroups = mergedGroups;
+      }
+    }
+
+    // Update the object
+    this.set('iac', iac);
+
+    // Save if requested
+    if (save) {
+      return await this.save();
+    }
+
+    return this;
+  }
+
+  /**
+   * Publishes this object to make it publicly accessible (or unpublishes it).
+   * Adds or removes 'public_user' from the IAC read permissions.
+   * 
+   * @param {Object} options - Publishing options
+   * @param {boolean} [options.publish=true] - If true, publishes the object; if false, unpublishes it
+   * @param {boolean} [options.save=true] - If true, automatically saves the object after updating permissions
+   * @returns {Promise<RbtObject>} - Returns this object (saved if options.save is true)
+   * 
+   * @example
+   * // Publish an object (make it public)
+   * await myObject.publishObject();
+   * 
+   * @example
+   * // Unpublish an object (make it private)
+   * await myObject.publishObject({ publish: false });
+   * 
+   * @example
+   * // Publish without auto-saving
+   * await myObject.publishObject({ save: false });
+   * // ... make other changes ...
+   * await myObject.save();
+   */
+  async publishObject(options = {}) {
+    const {
+      publish = true,
+      save = true
+    } = options;
+
+    // Get current IAC settings
+    const iac = this.get('iac') || {};
+
+    // Initialize readGrants if it doesn't exist
+    if (!iac.readGrants) {
+      iac.readGrants = {};
+    }
+
+    // Initialize users array if it doesn't exist
+    if (!Array.isArray(iac.readGrants.users)) {
+      iac.readGrants.users = [];
+    }
+
+    if (publish) {
+      // Add public_user if not already present
+      if (!iac.readGrants.users.includes('public_user')) {
+        iac.readGrants.users.push('public_user');
+      }
+    } else {
+      // Remove public_user
+      iac.readGrants.users = iac.readGrants.users.filter(userId => userId !== 'public_user');
+    }
+
+    // Update the object
+    this.set('iac', iac);
+
+    // Save if requested
+    if (save) {
+      return await this.save();
+    }
+
+    return this;
+  }
+
+  /**
+   * Unpublishes this object to remove public access.
+   * Removes 'public_user' from the IAC read permissions.
+   * This is an alias for publishObject({ publish: false }) for better code clarity.
+   * 
+   * @param {Object} options - Unpublishing options
+   * @param {boolean} [options.save=true] - If true, automatically saves the object after updating permissions
+   * @returns {Promise<RbtObject>} - Returns this object (saved if options.save is true)
+   * 
+   * @example
+   * // Unpublish an object (remove public access)
+   * await myObject.unpublishObject();
+   * 
+   * @example
+   * // Unpublish without auto-saving
+   * await myObject.unpublishObject({ save: false });
+   * // ... make other changes ...
+   * await myObject.save();
+   */
+  async unpublishObject(options = {}) {
+    return await this.publishObject({ 
+      publish: false, 
+      save: options.save !== undefined ? options.save : true 
+    });
+  }
+
+  /**
+   * Revokes access from specific users and/or user groups.
+   * 
+   * @param {Object} options - Access revocation options
+   * @param {string[]} [options.userIds=[]] - Array of user IDs to remove from read or write access
+   * @param {string[]} [options.groupIds=[]] - Array of group IDs to remove from read or write access
+   * @param {boolean} [options.write=false] - If true, removes write access; if false, removes read access
+   * @param {boolean} [options.save=true] - If true, automatically saves the object after updating permissions
+   * @returns {Promise<RbtObject>} - Returns this object (saved if options.save is true)
+   * 
+   * @example
+   * // Revoke read access from specific users
+   * await myObject.revokeAccess({ 
+   *   userIds: ['user_123', 'user_456'] 
+   * });
+   * 
+   * @example
+   * // Revoke write access from specific groups
+   * await myObject.revokeAccess({ 
+   *   groupIds: ['grpEditors'],
+   *   write: true 
+   * });
+   * 
+   * @example
+   * // Revoke access from users and groups
+   * await myObject.revokeAccess({ 
+   *   userIds: ['user_123'],
+   *   groupIds: ['grpViewers']
+   * });
+   * 
+   * @example
+   * // Revoke without auto-saving
+   * await myObject.revokeAccess({ 
+   *   userIds: ['user_123'],
+   *   save: false 
+   * });
+   */
+  async revokeAccess(options = {}) {
+    const {
+      userIds = [],
+      groupIds = [],
+      write = false,
+      save = true
+    } = options;
+
+    // Validate inputs
+    if (!Array.isArray(userIds)) {
+      throw new Error('userIds must be an array');
+    }
+    if (!Array.isArray(groupIds)) {
+      throw new Error('groupIds must be an array');
+    }
+
+    // Get current IAC settings
+    const iac = this.get('iac') || {};
+
+    // Determine which grant type to update (read or write)
+    const grantType = write ? 'writeGrants' : 'readGrants';
+
+    // Initialize grants if they don't exist
+    if (!iac[grantType]) {
+      iac[grantType] = {};
+    }
+
+    // Remove specified users
+    if (userIds.length > 0 && Array.isArray(iac[grantType].users)) {
+      iac[grantType].users = iac[grantType].users.filter(
+        userId => !userIds.includes(userId)
+      );
+    }
+
+    // Remove specified groups
+    if (groupIds.length > 0 && Array.isArray(iac[grantType].userGroups)) {
+      iac[grantType].userGroups = iac[grantType].userGroups.filter(
+        groupId => !groupIds.includes(groupId)
+      );
+    }
+
+    // Update the object
+    this.set('iac', iac);
+
+    // Save if requested
+    if (save) {
+      return await this.save();
+    }
+
+    return this;
+  }
+
+  /**
+   * Checks if this object is currently published (publicly accessible).
+   * 
+   * @returns {boolean} - True if 'public_user' is in the read grants, false otherwise
+   * 
+   * @example
+   * if (myObject.isPublished()) {
+   *   console.log('Object is public');
+   * }
+   */
+  isPublished() {
+    const iac = this.get('iac');
+    if (!iac || !iac.readGrants || !Array.isArray(iac.readGrants.users)) {
+      return false;
+    }
+    return iac.readGrants.users.includes('public_user');
+  }
+
+  /**
+   * Gets the current sharing permissions for this object.
+   * 
+   * @returns {Object} - Object containing read and write grants
+   * @returns {Object} returns.readGrants - Read access grants
+   * @returns {string[]} returns.readGrants.users - Array of user IDs with read access
+   * @returns {string[]} returns.readGrants.userGroups - Array of group IDs with read access
+   * @returns {string[]} returns.readGrants.organizations - Array of organization IDs with read access
+   * @returns {Object} returns.writeGrants - Write access grants
+   * @returns {string[]} returns.writeGrants.users - Array of user IDs with write access
+   * @returns {string[]} returns.writeGrants.userGroups - Array of group IDs with write access
+   * @returns {string[]} returns.writeGrants.organizations - Array of organization IDs with write access
+   * 
+   * @example
+   * const permissions = myObject.getSharing();
+   * console.log('Read users:', permissions.readGrants.users);
+   * console.log('Read groups:', permissions.readGrants.userGroups);
+   */
+  getSharing() {
+    const iac = this.get('iac') || {};
+    return {
+      readGrants: {
+        users: iac.readGrants?.users || [],
+        userGroups: iac.readGrants?.userGroups || [],
+        organizations: iac.readGrants?.organizations || [],
+        userSegments: iac.readGrants?.userSegments || []
+      },
+      writeGrants: {
+        users: iac.writeGrants?.users || [],
+        userGroups: iac.writeGrants?.userGroups || [],
+        organizations: iac.writeGrants?.organizations || [],
+        userSegments: iac.writeGrants?.userSegments || []
+      }
+    };
+  }
+
   async delete() {
     if (!this._internalData.type) {
       throw new Error('Cannot delete object without type');