@adatechnology/keycloak-admin 1.0.0-rc.1 → 1.0.0-rc.3

package/README.md

@@ -32,9 +32,23 @@ const { id } = await keycloak.createUser({
 })
 ```
 
-Operações: `createUser`, `findUserByEmail`, `listUsers`, `updateUser`, `setEnabled`,
+Operações de usuário: `createUser`, `findUserByEmail`, `listUsers`, `updateUser`, `setEnabled`,
 `updateAttributes`, `deleteUser`, `setPassword`, `setTemporaryPassword`.
 
+Foto de perfil: `setProfilePicture({ userId, pictureUrl })`. O atributo é `picture`, o nome que o
+OIDC reserva — com um mapeador no realm ele chega ao token, e a tela desenha o avatar sem uma
+consulta por pessoa.
+
+⚠️ O Keycloak **não hospeda imagem**: o valor é uma URL e o arquivo é do produto. Base64 no atributo
+cresce o token até ele parar de caber no cabeçalho, e o sintoma aparece longe — login que funciona
+no navegador e falha no `curl`. A operação lê os atributos antes de gravar, porque o Admin API
+substitui o conjunto: mandar só a foto apagaria `company_id` e o resto.
+
+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.

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;
 };
@@ -109,6 +113,20 @@ type SetEnabledParams = {
     readonly enabled: boolean;
     readonly userId: string;
 };
+/**
+ * O atributo padrão da foto. `picture` é o nome que o OIDC já reserva para isso, e usá-lo é o que
+ * permite a foto chegar ao token por um mapeador do realm em vez de uma consulta extra por tela.
+ *
+ * ⚠️ O Keycloak **não hospeda imagem**: o valor é uma URL, e quem guarda o arquivo é o produto. Um
+ * atributo com base64 dentro cresce o token até ele parar de caber no cabeçalho, e aí o sintoma é
+ * login que funciona no navegador e falha no `curl`.
+ */
+declare const PROFILE_PICTURE_ATTRIBUTE = "picture";
+type SetProfilePictureParams = {
+    /** URL da imagem, ou `undefined` para tirar a foto sem mexer nos outros atributos. */
+    readonly pictureUrl: string | undefined;
+    readonly userId: string;
+};
 type UpdateAttributesParams = {
     readonly attributes: KeycloakUserAttributes;
     readonly userId: string;
@@ -125,12 +143,57 @@ 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>;
+    setProfilePicture(params: SetProfilePictureParams): Promise<void>;
     setPassword(params: SetPasswordParams): Promise<void>;
     setTemporaryPassword(params: SetTemporaryPasswordParams): Promise<void>;
     updateAttributes(params: UpdateAttributesParams): Promise<void>;
@@ -155,4 +218,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 ListUsersParams, type ListUsersResult, 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, PROFILE_PICTURE_ATTRIBUTE, type SerializedKeycloakAdminError, type SetEnabledParams, type SetPasswordParams, type SetProfilePictureParams, 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
   };
@@ -182,6 +187,9 @@ function createKeycloakTokenProvider({
   };
 }
 
+// src/keycloak-admin.types.ts
+var PROFILE_PICTURE_ATTRIBUTE = "picture";
+
 // src/keycloak-admin.client.ts
 var HTTP_CONFLICT = 409;
 var HTTP_NOT_FOUND = 404;
@@ -195,7 +203,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 +290,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) });
@@ -297,6 +305,41 @@ function createKeycloakAdminClient({
      * 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);
@@ -304,6 +347,26 @@ function createKeycloakAdminClient({
       const found = await response.json();
       return { hasMore: found.length > limit, users: found.slice(0, limit) };
     },
+    /**
+     * A foto é atributo, e o Admin API **substitui o conjunto** quando recebe `attributes`. Por isso
+     * esta operação lê o usuário antes: mandar só a foto apagaria `company_id`, `tax_id` e qualquer
+     * outro atributo do produto — e o sintoma seria login entrando sem empresa, longe daqui.
+     */
+    async setProfilePicture({ pictureUrl, userId }) {
+      const response = await adminRequest({ method: "GET", url: endpoints.user(userId) });
+      const current = await response.json();
+      const attributes = { ...current.attributes ?? {} };
+      if (pictureUrl === void 0 || pictureUrl === "") {
+        delete attributes[PROFILE_PICTURE_ATTRIBUTE];
+      } else {
+        attributes[PROFILE_PICTURE_ATTRIBUTE] = pictureUrl;
+      }
+      await adminRequest({
+        body: { attributes: normalizeAttributes(attributes) },
+        method: "PUT",
+        url: endpoints.user(userId)
+      });
+    },
     async setEnabled({ enabled, userId }) {
       await adminRequest({ body: { enabled }, method: "PUT", url: endpoints.user(userId) });
     },
@@ -327,6 +390,7 @@ export {
   KEYCLOAK_ADMIN_ERROR_CODE,
   KEYCLOAK_ADMIN_TOKEN_RENEWAL_SKEW_MS,
   KeycloakAdminError,
+  PROFILE_PICTURE_ATTRIBUTE,
   buildKeycloakAdminEndpoints,
   createKeycloakAdminClient,
   isKeycloakAdminError,

package/package.json

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