@adatechnology/keycloak-admin 1.0.0-rc.0 → 1.0.0-rc.2

package/README.md

@@ -32,8 +32,17 @@ const { id } = await keycloak.createUser({
 })
 ```
 
-Operações: `createUser`, `findUserByEmail`, `updateUser`, `setEnabled`, `updateAttributes`,
-`deleteUser`, `setPassword`, `setTemporaryPassword`.
+Operações de usuário: `createUser`, `findUserByEmail`, `listUsers`, `updateUser`, `setEnabled`,
+`updateAttributes`, `deleteUser`, `setPassword`, `setTemporaryPassword`.
+
+Operações de grupo: `createGroup`, `updateGroup`, `deleteGroup`, `listGroups`, `addUserToGroup`,
+`removeUserFromGroup`. Só o **primeiro nível** — grupo aninhado muda o significado de "pertencer",
+porque quem está no filho herda o pai, e um produto que não modela hierarquia não deve criá-la por
+acidente. A filiação é endereçada pelo **usuário** (`/users/{id}/groups/{id}`), não pelo grupo.
+
+`listUsers({ first, limit, search })` devolve `{ users, hasMore }`. O realm não informa total, então
+a página pede um registro a mais que o limite e descarta-o: é assim que `hasMore` sai sem uma
+segunda chamada.
 
 ## Token
 

package/dist/index.d.ts

@@ -16,8 +16,12 @@ type BuildKeycloakAdminEndpointsParams = {
     readonly realm: string;
 };
 declare function buildKeycloakAdminEndpoints({ baseUrl, realm }: BuildKeycloakAdminEndpointsParams): {
+    readonly group: (groupId: string) => string;
+    readonly groups: string;
     readonly token: `${string}/realms/${string}/protocol/openid-connect/token`;
     readonly user: (userId: string) => string;
+    /** O Admin API endereça a filiação pelo usuário, não pelo grupo: é `PUT` para entrar, `DELETE` para sair. */
+    readonly userGroup: (userId: string, groupId: string) => string;
     readonly userPassword: (userId: string) => string;
     readonly users: string;
 };
@@ -88,6 +92,19 @@ type CreateUserResult = {
 type FindUserByEmailParams = {
     readonly email: string;
 };
+/**
+ * O realm não devolve página infinita: `first`/`max` são o recorte que o Keycloak entende, e quem
+ * chama precisa saber se ainda há mais — daí `hasMore`, derivado de pedir um a mais que o limite.
+ */
+type ListUsersParams = {
+    readonly first?: number;
+    readonly limit?: number;
+    readonly search?: string;
+};
+type ListUsersResult = {
+    readonly hasMore: boolean;
+    readonly users: readonly KeycloakUser[];
+};
 type UpdateUserParams = {
     readonly user: Readonly<Partial<Pick<KeycloakUser, 'email' | 'emailVerified' | 'firstName' | 'lastName' | 'username'>>>;
     readonly userId: string;
@@ -112,10 +129,55 @@ type SetTemporaryPasswordParams = {
     readonly password: string;
     readonly userId: string;
 };
+/**
+ * O grupo do realm. O Keycloak aceita hierarquia (`subGroups`), e este cliente trata só o primeiro
+ * nível de propósito: grupo aninhado muda o significado de "pertencer" — quem está no filho herda o
+ * pai —, e um produto que não modela hierarquia não deve criá-la por acidente.
+ */
+type KeycloakGroup = {
+    readonly attributes?: KeycloakUserAttributes;
+    readonly id: string;
+    readonly name: string;
+    readonly path?: string;
+};
+type CreateGroupParams = {
+    readonly attributes?: KeycloakUserAttributes;
+    readonly name: string;
+};
+type CreateGroupResult = {
+    readonly id: string;
+};
+type UpdateGroupParams = {
+    readonly groupId: string;
+    readonly group: Readonly<Partial<Pick<KeycloakGroup, 'attributes' | 'name'>>>;
+};
+type DeleteGroupParams = {
+    readonly groupId: string;
+};
+type ListGroupsParams = {
+    readonly first?: number;
+    readonly limit?: number;
+    readonly search?: string;
+};
+type ListGroupsResult = {
+    readonly groups: readonly KeycloakGroup[];
+    readonly hasMore: boolean;
+};
+type GroupMembershipParams = {
+    readonly groupId: string;
+    readonly userId: string;
+};
 type KeycloakAdminClient = {
+    addUserToGroup(params: GroupMembershipParams): Promise<void>;
+    createGroup(params: CreateGroupParams): Promise<CreateGroupResult>;
+    deleteGroup(params: DeleteGroupParams): Promise<void>;
+    listGroups(params?: ListGroupsParams): Promise<ListGroupsResult>;
+    removeUserFromGroup(params: GroupMembershipParams): Promise<void>;
+    updateGroup(params: UpdateGroupParams): Promise<void>;
     createUser(params: CreateUserParams): Promise<CreateUserResult>;
     deleteUser(params: DeleteUserParams): Promise<void>;
     findUserByEmail(params: FindUserByEmailParams): Promise<KeycloakUser | undefined>;
+    listUsers(params?: ListUsersParams): Promise<ListUsersResult>;
     setEnabled(params: SetEnabledParams): Promise<void>;
     setPassword(params: SetPasswordParams): Promise<void>;
     setTemporaryPassword(params: SetTemporaryPasswordParams): Promise<void>;
@@ -141,4 +203,4 @@ declare function parseKeycloakAdminConfig(value: unknown): KeycloakAdminConfig;
 
 declare function createKeycloakAdminClient({ config: rawConfig, fetch: injectedFetch, now, }: CreateKeycloakAdminClientParams): KeycloakAdminClient;
 
-export { type CreateKeycloakAdminClientParams, type CreateUserParams, type CreateUserResult, type DeleteUserParams, type FetchLike, type FindUserByEmailParams, KEYCLOAK_ADMIN_ERROR_CODE, KEYCLOAK_ADMIN_TOKEN_RENEWAL_SKEW_MS, type KeycloakAdminClient, type KeycloakAdminConfig, type KeycloakAdminEndpoints, KeycloakAdminError, type KeycloakAdminErrorCode, type KeycloakAdminErrorContext, type KeycloakAdminErrorParams, type KeycloakPassword, type KeycloakUser, type KeycloakUserAttributes, type SerializedKeycloakAdminError, type SetEnabledParams, type SetPasswordParams, type SetTemporaryPasswordParams, type UpdateAttributesParams, type UpdateUserParams, buildKeycloakAdminEndpoints, createKeycloakAdminClient, isKeycloakAdminError, keycloakAdminConfigSchema, parseKeycloakAdminConfig };
+export { type CreateGroupParams, type CreateGroupResult, type CreateKeycloakAdminClientParams, type CreateUserParams, type CreateUserResult, type DeleteGroupParams, type DeleteUserParams, type FetchLike, type FindUserByEmailParams, type GroupMembershipParams, KEYCLOAK_ADMIN_ERROR_CODE, KEYCLOAK_ADMIN_TOKEN_RENEWAL_SKEW_MS, type KeycloakAdminClient, type KeycloakAdminConfig, type KeycloakAdminEndpoints, KeycloakAdminError, type KeycloakAdminErrorCode, type KeycloakAdminErrorContext, type KeycloakAdminErrorParams, type KeycloakGroup, type KeycloakPassword, type KeycloakUser, type KeycloakUserAttributes, type ListGroupsParams, type ListGroupsResult, type ListUsersParams, type ListUsersResult, type SerializedKeycloakAdminError, type SetEnabledParams, type SetPasswordParams, type SetTemporaryPasswordParams, type UpdateAttributesParams, type UpdateGroupParams, type UpdateUserParams, buildKeycloakAdminEndpoints, createKeycloakAdminClient, isKeycloakAdminError, keycloakAdminConfigSchema, parseKeycloakAdminConfig };

package/dist/index.js

@@ -17,9 +17,14 @@ function buildKeycloakAdminEndpoints({ baseUrl, realm }) {
   const origin = baseUrl.replace(/\/+$/, "");
   const encodedRealm = encodeURIComponent(realm);
   const users = `${origin}/admin/realms/${encodedRealm}/users`;
+  const groups = `${origin}/admin/realms/${encodedRealm}/groups`;
   return {
+    group: (groupId) => `${groups}/${encodeURIComponent(groupId)}`,
+    groups,
     token: `${origin}/realms/${encodedRealm}/protocol/openid-connect/token`,
     user: (userId) => `${users}/${encodeURIComponent(userId)}`,
+    /** O Admin API endereça a filiação pelo usuário, não pelo grupo: é `PUT` para entrar, `DELETE` para sair. */
+    userGroup: (userId, groupId) => `${users}/${encodeURIComponent(userId)}/groups/${encodeURIComponent(groupId)}`,
     userPassword: (userId) => `${users}/${encodeURIComponent(userId)}/reset-password`,
     users
   };
@@ -195,7 +200,7 @@ function normalizeAttributes(attributes) {
     Object.entries(attributes).map(([key, value]) => [key, typeof value === "string" ? [value] : [...value]])
   );
 }
-function userIdFromLocation(response) {
+function idFromLocation(response) {
   const location = response.headers.get("location");
   const id = location?.split("/").filter(Boolean).at(-1);
   if (id === void 0 || id === "") {
@@ -282,7 +287,7 @@ function createKeycloakAdminClient({
         secrets: [password?.value],
         url: endpoints.users
       });
-      return { id: userIdFromLocation(response) };
+      return { id: idFromLocation(response) };
     },
     async deleteUser({ userId }) {
       await adminRequest({ method: "DELETE", url: endpoints.user(userId) });
@@ -293,6 +298,52 @@ function createKeycloakAdminClient({
       const found = await response.json();
       return found.at(0);
     },
+    /**
+     * Pede um a mais que o limite para saber se há próxima página sem uma segunda chamada — o
+     * Keycloak não devolve total, e contar o realm inteiro só para desenhar um botão é caro.
+     */
+    async addUserToGroup({ groupId, userId }) {
+      await adminRequest({ method: "PUT", url: endpoints.userGroup(userId, groupId) });
+    },
+    async createGroup({ attributes, name }) {
+      const response = await adminRequest({
+        body: { ...attributes === void 0 ? {} : { attributes: normalizeAttributes(attributes) }, name },
+        method: "POST",
+        url: endpoints.groups
+      });
+      return { id: idFromLocation(response) };
+    },
+    async deleteGroup({ groupId }) {
+      await adminRequest({ method: "DELETE", url: endpoints.group(groupId) });
+    },
+    /** Mesmo recorte de `listUsers`: pede um a mais que o limite para saber se há próxima página. */
+    async listGroups({ first = 0, limit = 100, search } = {}) {
+      const query = new URLSearchParams({ first: String(first), max: String(limit + 1) });
+      if (search !== void 0 && search !== "") query.set("search", search);
+      const response = await adminRequest({ method: "GET", url: `${endpoints.groups}?${query}` });
+      const found = await response.json();
+      return { groups: found.slice(0, limit), hasMore: found.length > limit };
+    },
+    async removeUserFromGroup({ groupId, userId }) {
+      await adminRequest({ method: "DELETE", url: endpoints.userGroup(userId, groupId) });
+    },
+    async updateGroup({ group, groupId }) {
+      await adminRequest({
+        body: {
+          ...group.attributes === void 0 ? {} : { attributes: normalizeAttributes(group.attributes) },
+          ...group.name === void 0 ? {} : { name: group.name }
+        },
+        method: "PUT",
+        url: endpoints.group(groupId)
+      });
+    },
+    async listUsers({ first = 0, limit = 100, search } = {}) {
+      const query = new URLSearchParams({ first: String(first), max: String(limit + 1) });
+      if (search !== void 0 && search !== "") query.set("search", search);
+      const response = await adminRequest({ method: "GET", url: `${endpoints.users}?${query}` });
+      const found = await response.json();
+      return { hasMore: found.length > limit, users: found.slice(0, limit) };
+    },
     async setEnabled({ enabled, userId }) {
       await adminRequest({ body: { enabled }, method: "PUT", url: endpoints.user(userId) });
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adatechnology/keycloak-admin",
-  "version": "1.0.0-rc.0",
+  "version": "1.0.0-rc.2",
   "description": "Agnostic Keycloak Admin API client authenticated as a service account (client_credentials)",
   "type": "module",
   "main": "dist/index.js",