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:

// ------------------------------------------------------------
// 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:

const result = getConfig();
console.log(result);

---

akListGroups

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

Comentario previo en el código:

// 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:

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:

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:

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:

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:

/**
 * 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:

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:

// ------------------------------------------------------------
// 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:

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:

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:

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:

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:

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:

const result = toPk(v);
console.log(result);

---