SuiteCoffee/docs/ak.md

# Documentación detallada de funciones: `ak.js`

Este documento fue generado automáticamente a partir del archivo `ak.js` proporcionado. Incluye una sección por función detectada, con firma, ubicación, descripción, parámetros, valores de retorno, posibles errores y un ejemplo de uso.

> **Nota:** Las descripciones y tipos se infieren heurísticamente a partir de los nombres, comentarios y cuerpo de cada función. Revise y ajuste donde corresponda.

---

### `getConfig`

**Firma:** `function getConfig()`  
**Ubicación:** línea 28

**Comentario previo en el código:**
```js
// ------------------------------------------------------------
// Cliente para la API Admin de Authentik (v3)
// - Sin dependencias externas (usa fetch nativo de Node >=18)
// - ESM compatible
// - Timeouts, reintentos opcionales y mensajes de error claros
// - Compatible con services/auth/src/index.js actual
// ------------------------------------------------------------

// Utiliza AUTHENTIK_BASE_URL y AUTHENTIK_TOKEN para validar y devuelve la configuración (base URL y token) desde variables de entorno.
// Devuelve la URL base y el Token que se leyó desde .env 

/**
 * @typedef {Object} AkCfg
 * @property {string} BASE   // p.ej. "https://idp.example.com"
 * @property {string} TOKEN  // bearer
 */

/**
 * @typedef {Object} AkOpts
 * @property {Record<string, string|number|boolean|Array<string|number|boolean>>} [qs]
 * @property {any} [body]
 * @property {number} [timeoutMs=10000]
 * @property {number} [retries=0]
 * @property {Record<string,string>} [headers]
 */
```
**Descripción:** Obtiene Config.

**Parámetros:** *(sin parámetros)*

**Retorna (aprox.):** `{ BASE, TOKEN }`

**Errores/excepciones:**
- Puede lanzar `Error('[AK_CONFIG] Falta variable AUTHENTIK_BASE_URL')`.
- Puede lanzar `Error('[AK_CONFIG] Falta variable AUTHENTIK_TOKEN')`.

**Ejemplo de uso:**
```js
const result = getConfig();
console.log(result);
```

---
### `akListGroups`

**Firma:** `export async function akListGroups(search = "")`  
**Ubicación:** línea 60

**Comentario previo en el código:**
```js
// Listar grupos con búsqueda por nombre/slug
```
**Descripción:** Función `akListGroups`. Interactúa con una API HTTP.

**Parámetros:**
- `search` (opcional, por defecto = `""`): descripción.

**Retorna (aprox.):** `[]`

**Ejemplo de uso:**
```js
const result = await akListGroups(search);
console.log(result);
```

---
### `akPatchUserAttributes`

**Firma:** `export async function akPatchUserAttributes(userPk, partialAttrs = {})`  
**Ubicación:** línea 73

**Descripción:** Función `akPatchUserAttributes`.

**Parámetros:**
- `userPk`: descripción.
- `partialAttrs` (opcional, por defecto = `{}`): descripción.

**Retorna:** Puede no retornar valor explícito (`void`) o retorna según la rama de ejecución.

**Ejemplo de uso:**
```js
const result = await akPatchUserAttributes(userPk, partialAttrs);
console.log(result);
```

---
### `akEnsureGroupForTenant`

**Firma:** `export async function akEnsureGroupForTenant(tenantHex)`  
**Ubicación:** línea 97

**Descripción:** Función `akEnsureGroupForTenant`. Interactúa con una API HTTP. Maneja errores con bloques try/catch.

**Parámetros:**
- `tenantHex`: descripción.

**Retorna (aprox.):** `found.pk ?? found.id`

**Errores/excepciones:**
- Puede lanzar `TypeError("akEnsureGroupForTenant: `tenantHex` is required")`.

**Ejemplo de uso:**
```js
const result = await akEnsureGroupForTenant(tenantHex);
console.log(result);
```

---
### `akAddUserToGroup`

**Firma:** `export async function akAddUserToGroup(userPk, groupPk)`  
**Ubicación:** línea 130

**Descripción:** Función `akAddUserToGroup`. Interactúa con una API HTTP. Maneja errores con bloques try/catch.

**Parámetros:**
- `userPk`: descripción.
- `groupPk`: descripción.

**Retorna (aprox.):** `await akPOST("/core/group_memberships/", { body: { user, group } })`

**Errores/excepciones:**
- Puede lanzar `TypeError("akAddUserToGroup: `userPk` is required")`.
- Puede lanzar `TypeError("akAddUserToGroup: `groupPk` is required")`.

**Ejemplo de uso:**
```js
const result = await akAddUserToGroup(userPk, groupPk);
console.log(result);
```

---
### `request`

**Firma:** `export async function request(method, path, opts = {}, cfg)`  
**Ubicación:** línea 167

**Comentario previo en el código:**
```js
/**
 * Llamada HTTP genérica con fetch + timeout + manejo de errores.
 * @param {'GET'|'POST'|'PUT'|'PATCH'|'DELETE'} method
 * @param {string} path   Ruta relativa (ej. "/core/users/") o absoluta; si es relativa se antepone "/api/v3".
 * @param {AkOpts} [opts]
 * @param {AkCfg}  [cfg]  Config inyectada; si se omite se usa getConfig()
 * @returns {Promise<any|null>}
 */
```
**Descripción:** Función `request`.

**Parámetros:**
- `method`: descripción.
- `path`: descripción.
- `opts` (opcional, por defecto = `{}`): descripción.
- `cfg`: descripción.

**Retorna:** Puede no retornar valor explícito (`void`) o retorna según la rama de ejecución.

**Ejemplo de uso:**
```js
const result = await request(method, path, opts, cfg);
console.log(result);
```

---
### `akFindUserByEmail`

**Firma:** `export async function akFindUserByEmail(email)`  
**Ubicación:** línea 262

**Comentario previo en el código:**
```js
// ------------------------------------------------------------
// Funciones públicas
// ------------------------------------------------------------
```
**Descripción:** Función `akFindUserByEmail`. Interactúa con una API HTTP.

**Parámetros:**
- `email`: descripción.

**Retorna (aprox.):** `null`

**Errores/excepciones:**
- Puede lanzar `TypeError("akFindUserByEmail: `email` is required")`.

**Ejemplo de uso:**
```js
const result = await akFindUserByEmail(email);
console.log(result);
```

---
### `akCreateUser`

**Firma:** `export async function akCreateUser(p = {})`  
**Ubicación:** línea 298

**Descripción:** Función `akCreateUser`.

**Parámetros:**
- `p` (opcional, por defecto = `{}`): descripción.

**Retorna:** Puede no retornar valor explícito (`void`) o retorna según la rama de ejecución.

**Ejemplo de uso:**
```js
const result = await akCreateUser(p);
console.log(result);
```

---
### `akSetPassword`

**Firma:** `export async function akSetPassword(userPk, password, requireChange = true)`  
**Ubicación:** línea 349

**Descripción:** Función `akSetPassword`. Interactúa con una API HTTP. Maneja errores con bloques try/catch.

**Parámetros:**
- `userPk`: descripción.
- `password`: descripción.
- `requireChange` (opcional, por defecto = `true`): descripción.

**Retorna (aprox.):** `true`

**Errores/excepciones:**
- Puede lanzar `TypeError("akSetPassword: `userPk` is required")`.
- Puede lanzar `TypeError("akSetPassword: `password` is required")`.

**Ejemplo de uso:**
```js
const result = await akSetPassword(userPk, password, requireChange);
console.log(result);
```

---
### `akResolveGroupIdByName`

**Firma:** `export async function akResolveGroupIdByName(name)`  
**Ubicación:** línea 373

**Descripción:** Función `akResolveGroupIdByName`.

**Parámetros:**
- `name`: descripción.

**Retorna (aprox.):** `byName?.pk ?? byName?.id ?? null`

**Errores/excepciones:**
- Puede lanzar `TypeError("akResolveGroupIdByName: `name` is required")`.

**Ejemplo de uso:**
```js
const result = await akResolveGroupIdByName(name);
console.log(result);
```

---
### `akResolveGroupId`

**Firma:** `export async function akResolveGroupId({ id, pk, uuid, name, slug } = {})`  
**Ubicación:** línea 389

**Descripción:** Función `akResolveGroupId`.

**Parámetros:**
- `{ id`: descripción.
- `pk`: descripción.
- `uuid`: descripción.
- `name`: descripción.
- `slug }` (opcional, por defecto = `{}`): descripción.

**Retorna:** Puede no retornar valor explícito (`void`) o retorna según la rama de ejecución.

**Ejemplo de uso:**
```js
const result = await akResolveGroupId({ id, pk, uuid, name, slug });
console.log(result);
```

---
### `toPk`

**Firma:** `const => toPk(v)`  
**Ubicación:** línea 390

**Descripción:** Función `toPk`.

**Parámetros:**
- `v`: descripción.

**Retorna (aprox.):** `Number.isFinite(n) ? n : String(v)`

**Ejemplo de uso:**
```js
const result = toPk(v);
console.log(result);
```

---