Group Management

/**
 * Find groups with optional search and pagination
 * @param query - Optional search and pagination parameters
 * @returns Array of group representations
 */
find(query?: GroupQuery): Promise<GroupRepresentation[]>;

/**
 * Create a new group
 * @param group - Group configuration
 * @returns Object with created group ID
 */
create(group: GroupRepresentation): Promise<{ id: string }>;

/**
 * Find a specific group by ID
 * @param params - Group identifier
 * @returns Group representation or undefined if not found
 */
findOne(params: { id: string }): Promise<GroupRepresentation | undefined>;

/**
 * Update an existing group
 * @param query - Group identifier
 * @param group - Updated group configuration
 */
update(query: { id: string }, group: GroupRepresentation): Promise<void>;

/**
 * Delete a group
 * @param params - Group identifier
 */
del(params: { id: string }): Promise<void>;

/**
 * Count groups with optional search criteria
 * @param query - Optional search parameters
 * @returns Object with count
 */
count(query?: GroupCountQuery): Promise<{ count: number }>;

// Find all groups
const groups = await kcAdminClient.groups.find();
console.log("Available groups:", groups.map(g => g.name));

// Search groups with pagination
const searchResult = await kcAdminClient.groups.find({
  search: "admin",
  first: 0,
  max: 10,
  briefRepresentation: true,
});

// Create new group
const { id } = await kcAdminClient.groups.create({
  name: "developers",
  attributes: {
    department: ["engineering"],
    location: ["remote"],
  },
});

// Update group
await kcAdminClient.groups.update(
  { id },
  {
    name: "senior-developers",
    attributes: {
      department: ["engineering"],
      level: ["senior"],
    },
  }
);

// Get group count
const { count } = await kcAdminClient.groups.count({
  search: "dev",
});
console.log("Groups containing 'dev':", count);

/**
 * List subgroups of a parent group
 * @param query - Parent group ID and optional pagination
 * @returns Array of subgroup representations
 */
listSubGroups(query: SubGroupQuery): Promise<GroupRepresentation[]>;

/**
 * Create or update a child group under a parent
 * @param query - Parent group identifier
 * @param group - Child group configuration
 * @returns Object with created/updated group ID
 */
setOrCreateChild(query: { id: string }, group: GroupRepresentation): Promise<{ id: string }>;

// List subgroups
const subgroups = await kcAdminClient.groups.listSubGroups({
  parentId: parentGroupId,
  first: 0,
  max: 20,
});

console.log("Subgroups:", subgroups.map(g => g.name));

// Create child group
const { id: childId } = await kcAdminClient.groups.setOrCreateChild(
  { id: parentGroupId },
  {
    name: "frontend-team",
    attributes: {
      specialty: ["react", "typescript"],
    },
  }
);

// Create nested hierarchy
const { id: grandparentId } = await kcAdminClient.groups.create({
  name: "engineering",
});

const { id: parentId } = await kcAdminClient.groups.setOrCreateChild(
  { id: grandparentId },
  { name: "development" }
);

await kcAdminClient.groups.setOrCreateChild(
  { id: parentId },
  { name: "backend-team" }
);

/**
 * List members of a group
 * @param params - Group identifier and pagination options
 * @returns Array of user representations
 */
listMembers(params: { id: string } & PaginatedQuery): Promise<UserRepresentation[]>;

// Get all group members
const members = await kcAdminClient.groups.listMembers({
  id: groupId,
});

console.log("Group members:", members.map(u => u.username));

// Get group members with pagination
const memberPage = await kcAdminClient.groups.listMembers({
  id: groupId,
  first: 0,
  max: 50,
});

// Count group members
const allMembers = await kcAdminClient.groups.listMembers({ id: groupId });
console.log("Total members:", allMembers.length);

/**
 * List all role mappings for a group
 * @param params - Group identifier
 * @returns Complete role mappings (realm and client roles)
 */
listRoleMappings(params: { id: string }): Promise<MappingsRepresentation>;

/**
 * Add realm roles to a group
 * @param params - Group identifier and roles to add
 */
addRealmRoleMappings(params: { id: string; roles: RoleMappingPayload[] }): Promise<void>;

/**
 * List current realm role mappings for a group
 * @param params - Group identifier
 * @returns Array of assigned realm roles
 */
listRealmRoleMappings(params: { id: string }): Promise<RoleRepresentation[]>;

/**
 * Remove realm roles from a group
 * @param params - Group identifier and roles to remove
 */
delRealmRoleMappings(params: { id: string; roles: RoleMappingPayload[] }): Promise<void>;

/**
 * List available realm roles that can be assigned to the group
 * @param params - Group identifier
 * @returns Array of available realm roles
 */
listAvailableRealmRoleMappings(params: { id: string }): Promise<RoleRepresentation[]>;

/**
 * List effective realm roles (including composite roles)
 * @param params - Group identifier
 * @returns Array of effective realm roles
 */
listCompositeRealmRoleMappings(params: { id: string }): Promise<RoleRepresentation[]>;

/**
 * Add client roles to a group
 * @param params - Group ID, client ID, and roles to add
 */
addClientRoleMappings(params: {
  id: string;
  clientUniqueId: string;
  roles: RoleMappingPayload[];
}): Promise<void>;

/**
 * List current client role mappings for a group
 * @param params - Group and client identifiers
 * @returns Array of assigned client roles
 */
listClientRoleMappings(params: {
  id: string;
  clientUniqueId: string;
}): Promise<RoleRepresentation[]>;

// Get all role mappings for a group
const roleMappings = await kcAdminClient.groups.listRoleMappings({
  id: groupId,
});

console.log("Realm roles:", roleMappings.realmMappings?.map(r => r.name));
console.log("Client roles:", Object.keys(roleMappings.clientMappings || {}));

// Add realm roles to group
await kcAdminClient.groups.addRealmRoleMappings({
  id: groupId,
  roles: [
    { id: "role-id-1", name: "developer" },
    { id: "role-id-2", name: "user" },
  ],
});

// Add client roles to group
await kcAdminClient.groups.addClientRoleMappings({
  id: groupId,
  clientUniqueId: clientId,
  roles: [
    { id: "client-role-id", name: "app-admin" },
  ],
});

// Remove roles from group
await kcAdminClient.groups.delRealmRoleMappings({
  id: groupId,
  roles: [{ id: "role-id-1", name: "developer" }],
});

/**
 * Group search and pagination query parameters
 */
interface GroupQuery extends PaginatedQuery, SummarizedQuery {
  /** Search term for group name */
  search?: string;
  /** Exact match for search term */
  exact?: boolean;
  /** Additional query parameters */
  [key: string]: string | number | undefined | boolean;
}

/**
 * Subgroup query parameters
 */
interface SubGroupQuery extends PaginatedQuery, SummarizedQuery {
  /** Parent group ID */
  parentId: string;
  /** Search term for subgroup name */
  search?: string;
}

/**
 * Group count query parameters
 */
interface GroupCountQuery {
  /** Search term */
  search?: string;
  /** Count only top-level groups */
  top?: boolean;
}

/**
 * Pagination query parameters
 */
interface PaginatedQuery {
  /** Number of results to skip */
  first?: number;
  /** Maximum number of results to return */
  max?: number;
}

/**
 * Brief representation option
 */
interface SummarizedQuery {
  /** Return brief representation (fewer fields) */
  briefRepresentation?: boolean;
}

/**
 * Role mapping payload for assignments
 */
interface RoleMappingPayload {
  /** Role ID */
  id?: string;
  /** Role name */
  name?: string;
}

/**
 * Complete role mappings structure
 */
interface MappingsRepresentation {
  /** Realm role mappings */
  realmMappings?: RoleRepresentation[];
  /** Client role mappings by client ID */
  clientMappings?: Record<string, RoleRepresentation[]>;
}

/**
 * Group representation with hierarchy and attributes
 */
interface GroupRepresentation {
  /** Group unique identifier */
  id?: string;
  /** Group name */
  name?: string;
  /** Full path in group hierarchy */
  path?: string;
  /** Custom attributes */
  attributes?: Record<string, string[]>;
  /** Assigned realm roles */
  realmRoles?: string[];
  /** Assigned client roles by client ID */
  clientRoles?: Record<string, string[]>;
  /** Child groups */
  subGroups?: GroupRepresentation[];
  /** Parent group ID */
  parentId?: string;
  /** Number of subgroups */
  subGroupCount?: number;
}