User Groups

/**
 * Create a User Group
 * @param options - User group configuration parameters
 * @returns Promise resolving to created user group details
 */
usergroups.create(options: UsergroupsCreateArguments): Promise<UsergroupsCreateResponse>;

interface UsergroupsCreateArguments extends TokenOverridable, OptionalTeamAssignable, UsergroupsIncludeCount {
  /** A name for the User Group (must be unique among User Groups) */
  name: string;
  /** Comma-separated string of encoded channel IDs for default channels */
  channels?: string;
  /** Short description of the User Group */
  description?: string;
  /** Mention handle (must be unique among channels, users and User Groups) */
  handle?: string;
}

interface UsergroupsIncludeCount {
  /** Include the number of users in each User Group */
  include_count?: boolean;
}

interface UsergroupsCreateResponse extends WebAPICallResult {
  /** The created user group object */
  usergroup?: Usergroup;
}

import { WebClient } from "@slack/web-api";

const web = new WebClient(process.env.SLACK_BOT_TOKEN);

// Create a basic user group
const usergroup = await web.usergroups.create({
  name: "Engineering Team",
  handle: "engineering",
  description: "All engineering team members",
  include_count: true
});

// Create user group with default channels
await web.usergroups.create({
  name: "Marketing Team",
  handle: "marketing", 
  description: "Marketing department members",
  channels: "C1234567890,C0987654321" // Channel IDs
});

/**
 * List all User Groups for a team
 * @param options - Optional filtering parameters
 * @returns Promise resolving to list of user groups
 */
usergroups.list(options?: UsergroupsListArguments): Promise<UsergroupsListResponse>;

type UsergroupsListArguments = OptionalArgument<
  TokenOverridable &
  OptionalTeamAssignable &
  UsergroupsIncludeCount & {
    /** Include disabled User Groups */
    include_disabled?: boolean;
    /** Include the list of users for each User Group */
    include_users?: boolean;
  }
>;

interface UsergroupsListResponse extends WebAPICallResult {
  /** Array of user groups */
  usergroups?: Usergroup[];
}

// Get all active user groups
const activeGroups = await web.usergroups.list({
  include_count: true
});

// Get all user groups including disabled ones
const allGroups = await web.usergroups.list({
  include_disabled: true,
  include_users: true,
  include_count: true
});

console.log(`Found ${allGroups.usergroups?.length} user groups`);

/**
 * Update an existing User Group
 * @param options - User group update parameters
 * @returns Promise resolving to updated user group details
 */
usergroups.update(options: UsergroupsUpdateArguments): Promise<UsergroupsUpdateResponse>;

interface UsergroupsUpdateArguments extends TokenOverridable, OptionalTeamAssignable, Partial<UsergroupsCreateArguments> {
  /** The encoded ID of the User Group to update */
  usergroup: string;
}

interface UsergroupsUpdateResponse extends WebAPICallResult {
  /** The updated user group object */
  usergroup?: Usergroup;
}

/**
 * Enable an existing User Group
 * @param options - User group enable parameters
 * @returns Promise resolving to enabled user group details
 */
usergroups.enable(options: UsergroupsEnableArguments): Promise<UsergroupsEnableResponse>;

interface UsergroupsEnableArguments extends TokenOverridable, OptionalTeamAssignable, UsergroupsIncludeCount {
  /** The encoded ID of the User Group to enable */
  usergroup: string;
}

interface UsergroupsEnableResponse extends WebAPICallResult {
  /** The enabled user group object */
  usergroup?: Usergroup;
}

/**
 * Disable an existing User Group
 * @param options - User group disable parameters
 * @returns Promise resolving to disabled user group details
 */
usergroups.disable(options: UsergroupsDisableArguments): Promise<UsergroupsDisableResponse>;

interface UsergroupsDisableArguments extends TokenOverridable, OptionalTeamAssignable, UsergroupsIncludeCount {
  /** The encoded ID of the User Group to disable */
  usergroup: string;
}

interface UsergroupsDisableResponse extends WebAPICallResult {
  /** The disabled user group object */
  usergroup?: Usergroup;
}

/**
 * List all users in a User Group
 * @param options - User group parameters
 * @returns Promise resolving to list of user IDs
 */
usergroups.users.list(options: UsergroupsUsersListArguments): Promise<UsergroupsUsersListResponse>;

interface UsergroupsUsersListArguments extends TokenOverridable, OptionalTeamAssignable {
  /** The encoded ID of the User Group to list users for */
  usergroup: string;
  /** Include disabled users */
  include_disabled?: boolean;
}

interface UsergroupsUsersListResponse extends WebAPICallResult {
  /** Array of user IDs in the group */
  users?: string[];
}

/**
 * Update the list of users in a User Group
 * @param options - User group user update parameters
 * @returns Promise resolving to updated user group details
 */
usergroups.users.update(options: UsergroupsUsersUpdateArguments): Promise<UsergroupsUsersUpdateResponse>;

interface UsergroupsUsersUpdateArguments extends TokenOverridable, OptionalTeamAssignable, UsergroupsIncludeCount {
  /** The encoded ID of the User Group to update users for */
  usergroup: string;
  /** Comma-separated string of encoded user IDs */
  users: string;
}

interface UsergroupsUsersUpdateResponse extends WebAPICallResult {
  /** The updated user group object */
  usergroup?: Usergroup;
}

// Update user group properties
await web.usergroups.update({
  usergroup: "S1234567890",
  name: "Senior Engineering Team",
  description: "Senior engineering team members",
  handle: "senior-eng"
});

// Enable/disable user groups
await web.usergroups.disable({
  usergroup: "S1234567890",
  include_count: true
});

await web.usergroups.enable({
  usergroup: "S1234567890", 
  include_count: true
});

// Manage user group membership
const currentUsers = await web.usergroups.users.list({
  usergroup: "S1234567890"
});

// Add new users to the group
await web.usergroups.users.update({
  usergroup: "S1234567890",
  users: "U1111111111,U2222222222,U3333333333"
});

const addUsersToGroup = async (usergroupId: string, newUserIds: string[]) => {
  // Get current users
  const currentUsers = await web.usergroups.users.list({
    usergroup: usergroupId
  });
  
  // Combine current and new users
  const allUsers = [...(currentUsers.users || []), ...newUserIds];
  const uniqueUsers = [...new Set(allUsers)];
  
  // Update the group
  await web.usergroups.users.update({
    usergroup: usergroupId,
    users: uniqueUsers.join(',')
  });
};

const removeUsersFromGroup = async (usergroupId: string, removeUserIds: string[]) => {
  const currentUsers = await web.usergroups.users.list({
    usergroup: usergroupId
  });
  
  const remainingUsers = (currentUsers.users || [])
    .filter(userId => !removeUserIds.includes(userId));
  
  await web.usergroups.users.update({
    usergroup: usergroupId,
    users: remainingUsers.join(',')
  });
};

const createManagedUserGroup = async (groupConfig: {
  name: string;
  handle: string; 
  description: string;
  initialUsers: string[];
  defaultChannels: string[];
}) => {
  // Create user group
  const result = await web.usergroups.create({
    name: groupConfig.name,
    handle: groupConfig.handle,
    description: groupConfig.description,
    channels: groupConfig.defaultChannels.join(','),
    include_count: true
  });
  
  const usergroupId = result.usergroup?.id;
  if (!usergroupId) throw new Error('Failed to create user group');
  
  // Add initial users
  if (groupConfig.initialUsers.length > 0) {
    await web.usergroups.users.update({
      usergroup: usergroupId,
      users: groupConfig.initialUsers.join(',')
    });
  }
  
  return result.usergroup;
};

interface Usergroup {
  /** User group ID */
  id?: string;
  /** Team ID that owns the user group */
  team_id?: string;
  /** Whether the user group is active */
  is_external?: boolean;
  /** Timestamp when user group was created */
  date_create?: number;
  /** Timestamp when user group was last updated */
  date_update?: number;
  /** User ID who created the user group */
  created_by?: string;
  /** User ID who last updated the user group */
  updated_by?: string;
  /** User group name */
  name?: string;
  /** User group description */
  description?: string;
  /** User group handle (for mentions) */
  handle?: string;
  /** Whether user group is active */
  is_usergroup?: boolean;
  /** Whether user group can be mentioned */
  is_subteam?: boolean;
  /** Auto-provision settings */
  auto_provision?: boolean;
  /** Enterprise grid settings */
  enterprise_subteam_id?: string;
  /** Number of users in the group */
  user_count?: number;
  /** Array of user IDs in the group */
  users?: string[];
  /** Preferences object */
  prefs?: UsergroupPrefs;
}

interface UsergroupPrefs {
  /** Array of default channel IDs */
  channels?: string[];
  /** Array of default group IDs */
  groups?: string[];
}

interface OptionalTeamAssignable {
  /** Team ID for Enterprise Grid workspaces */
  team_id?: string;
}

interface TokenOverridable {
  /** Override the default token for this request */
  token?: string;
}