@gzl10/baserow 1.2.0

package/src/contexts/DatabaseTokenContext.ts

@@ -0,0 +1,331 @@
+import {
+  Logger,
+  DatabaseToken,
+  CreateDatabaseTokenRequest,
+  UpdateDatabaseTokenRequest,
+  DatabaseTokenPermissions,
+  LIBRARY_TOKEN_PREFIX
+} from '../types'
+import { DatabaseTokenService } from '../services/DatabaseTokenService'
+import { WorkspaceService } from '../services/WorkspaceService'
+
+/**
+ * Context para operaciones de database tokens en un workspace específico
+ *
+ * Proporciona una API completa para gestionar database tokens que permiten
+ * acceso limitado a databases y tablas específicas. Los tokens pueden
+ * configurarse con diferentes niveles de permisos y scope.
+ *
+ * **Características principales:**
+ * - Gestión completa de database tokens (CRUD)
+ * - Control granular de permisos (create, read, update, delete)
+ * - Sistema de prefijos para tokens de librería ('br-lib:')
+ * - Métodos de conveniencia para casos comunes
+ * - Limpieza automática de tokens de test
+ * - Resolución automática de workspace por nombre o ID
+ * - Validación de existencia y búsqueda por nombre o valor
+ *
+ * **Nomenclatura de Tokens:**
+ * - `create()`: Control total del nombre (para uso directo del usuario)
+ * - `createLibraryToken()`: Agrega prefijo 'br-lib:' automáticamente
+ * - `createFullAccess()/createReadOnly()`: Métodos de conveniencia con prefijo 'br-lib:'
+ *
+ * **Tipos de Permisos:**
+ * - **create**: Permite crear nuevas filas
+ * - **read**: Permite leer datos existentes
+ * - **update**: Permite modificar filas existentes
+ * - **delete**: Permite eliminar filas
+ *
+ * @example
+ * ```typescript
+ * // Métodos de conveniencia
+ * const fullToken = await workspace.databaseToken.createFullAccess('api-client')
+ * const readToken = await workspace.databaseToken.createReadOnly('dashboard')
+ *
+ * // Control granular de permisos
+ * const customToken = await workspace.databaseToken.create('custom', {
+ *   create: true,
+ *   read: true,
+ *   update: false,
+ *   delete: false
+ * })
+ *
+ * // Gestión de tokens
+ * const tokens = await workspace.databaseToken.list()
+ * const token = await workspace.databaseToken.findByName('br-lib:api-client')
+ * await workspace.databaseToken.update(token.id, { name: 'nuevo-nombre' })
+ *
+ * // Limpieza de tokens de test
+ * const cleanup = await workspace.databaseToken.cleanupLibraryTokens()
+ * console.log(`Eliminados: ${cleanup.deleted}, Errores: ${cleanup.errors}`)
+ * ```
+ *
+ * @since 1.0.0
+ */
+export class DatabaseTokenContext {
+  private workspaceIdentifier: string | number
+  private resolvedWorkspaceId?: number
+  private logger?: Logger
+
+  /**
+   * Crea un nuevo context de database tokens
+   *
+   * @param workspaceService - Servicio para operaciones de workspace
+   * @param workspaceIdentifier - Nombre o ID del workspace donde gestionar tokens
+   * @param databaseTokenService - Servicio para operaciones de database tokens
+   * @param logger - Logger opcional para debug y trazabilidad
+   *
+   * @since 1.0.0
+   */
+  constructor(
+    private workspaceService: WorkspaceService,
+    workspaceIdentifier: string | number,
+    private databaseTokenService: DatabaseTokenService,
+    logger?: Logger
+  ) {
+    this.workspaceIdentifier = workspaceIdentifier
+    this.logger = logger
+  }
+
+  /**
+   * Listar todos los database tokens del workspace
+   * @returns Promise<DatabaseToken[]> Lista de todos los database tokens
+   * @throws {BaserowError} Si el workspace no existe o hay error de red
+   */
+  async list(): Promise<DatabaseToken[]> {
+    const workspaceId = await this.resolveWorkspaceId()
+    return await this.databaseTokenService.list(workspaceId)
+  }
+
+  /**
+   * Obtener database token por ID
+   * @param tokenId - ID numérico del database token
+   * @returns Promise<DatabaseToken> Database token encontrado
+   * @throws {BaserowNotFoundError} Si el token no existe
+   * @throws {BaserowError} Si hay error de red o validación
+   */
+  async get(tokenId: number): Promise<DatabaseToken> {
+    return await this.databaseTokenService.get(tokenId)
+  }
+
+  /**
+   * Obtener database token por su valor (key)
+   * Busca en la lista de tokens del workspace
+   * @param tokenValue - Valor string del token (ej: "abc123def456...")
+   * @returns Promise<DatabaseToken> Database token encontrado
+   * @throws {Error} Si el token no se encuentra en el workspace
+   * @throws {BaserowError} Si hay error de red
+   */
+  async getToken(tokenValue: string): Promise<DatabaseToken> {
+    const workspaceId = await this.resolveWorkspaceId()
+    const tokens = await this.databaseTokenService.list(workspaceId)
+    const found = tokens.find(token => token.token === tokenValue)
+
+    if (!found) {
+      throw new Error(`Database token with value ${tokenValue.substring(0, 8)}... not found in workspace`)
+    }
+
+    return found
+  }
+
+  /**
+   * Crear nuevo database token con control total del nombre
+   * Para tokens de librería, usar createLibraryToken() o métodos de conveniencia
+   * @param name - Nombre del token (sin modificar)
+   * @param permissions - Permisos del token (create, read, update, delete)
+   * @returns Promise<DatabaseToken> Database token creado
+   * @throws {BaserowValidationError} Si el nombre o permisos son inválidos
+   * @throws {BaserowError} Si hay error de red
+   */
+  async create(name: string, permissions: DatabaseTokenPermissions): Promise<DatabaseToken> {
+    const workspaceId = await this.resolveWorkspaceId()
+    const request: CreateDatabaseTokenRequest = {
+      name,
+      permissions
+    }
+    return await this.databaseTokenService.createToken(workspaceId, request)
+  }
+
+  /**
+   * Crear database token con prefijo de librería para identificación
+   * Equivalente a create() pero agrega automáticamente el prefijo 'br-lib:'
+   * @param name - Nombre base del token (se le agregará 'br-lib:' automáticamente)
+   * @param permissions - Permisos del token (create, read, update, delete)
+   * @returns Promise<DatabaseToken> Database token creado con prefijo 'br-lib:'
+   * @throws {BaserowValidationError} Si el nombre o permisos son inválidos
+   * @throws {BaserowError} Si hay error de red
+   */
+  async createLibraryToken(name: string, permissions: DatabaseTokenPermissions): Promise<DatabaseToken> {
+    const prefixedName = `${LIBRARY_TOKEN_PREFIX}${name}`
+    return await this.create(prefixedName, permissions)
+  }
+
+  /**
+   * Crear database token con permisos completos (CRUD)
+   * Automáticamente agrega prefijo 'br-lib:' para identificación de librería
+   * Equivalente a: createLibraryToken(name, {create: true, read: true, update: true, delete: true})
+   * @param name - Nombre base del token (se le agregará 'br-lib:' automáticamente)
+   * @returns Promise<DatabaseToken> Database token con permisos completos y prefijo 'br-lib:'
+   * @throws {BaserowValidationError} Si el nombre es inválido
+   * @throws {BaserowError} Si hay error de red
+   */
+  async createFullAccess(name: string): Promise<DatabaseToken> {
+    const prefixedName = `${LIBRARY_TOKEN_PREFIX}${name}`
+    return await this.create(prefixedName, {
+      create: true,
+      read: true,
+      update: true,
+      delete: true
+    })
+  }
+
+  /**
+   * Crear database token de solo lectura
+   * Automáticamente agrega prefijo 'br-lib:' para identificación de librería
+   * Equivalente a: createLibraryToken(name, {create: false, read: true, update: false, delete: false})
+   * @param name - Nombre base del token (se le agregará 'br-lib:' automáticamente)
+   * @returns Promise<DatabaseToken> Database token de solo lectura con prefijo 'br-lib:'
+   * @throws {BaserowValidationError} Si el nombre es inválido
+   * @throws {BaserowError} Si hay error de red
+   */
+  async createReadOnly(name: string): Promise<DatabaseToken> {
+    const prefixedName = `${LIBRARY_TOKEN_PREFIX}${name}`
+    return await this.create(prefixedName, {
+      create: false,
+      read: true,
+      update: false,
+      delete: false
+    })
+  }
+
+  /**
+   * Actualizar database token
+   * @param tokenId - ID numérico del database token
+   * @param data - Datos a actualizar (nombre y/o permisos)
+   * @returns Promise<DatabaseToken> Database token actualizado
+   * @throws {BaserowNotFoundError} Si el token no existe
+   * @throws {BaserowValidationError} Si los datos son inválidos
+   * @throws {BaserowError} Si hay error de red
+   */
+  async update(tokenId: number, data: UpdateDatabaseTokenRequest): Promise<DatabaseToken> {
+    return await this.databaseTokenService.updateToken(tokenId, data)
+  }
+
+  /**
+   * Eliminar database token
+   * @param tokenId - ID numérico del database token a eliminar
+   * @returns Promise<void>
+   * @throws {BaserowNotFoundError} Si el token no existe
+   * @throws {BaserowError} Si hay error de red
+   */
+  async delete(tokenId: number): Promise<void> {
+    return await this.databaseTokenService.delete(tokenId)
+  }
+
+  /**
+   * Verificar si un database token existe
+   * @param tokenId - ID numérico del database token
+   * @returns Promise<boolean> true si existe, false si no existe
+   * @throws {BaserowError} Si hay error de red
+   */
+  async exists(tokenId: number): Promise<boolean> {
+    return await this.databaseTokenService.exists(tokenId)
+  }
+
+  /**
+   * Buscar database token por nombre
+   * @param name - Nombre exacto del database token a buscar
+   * @returns Promise<DatabaseToken | null> Token encontrado o null si no existe
+   * @throws {BaserowError} Si hay error de red
+   */
+  async findByName(name: string): Promise<DatabaseToken | null> {
+    const workspaceId = await this.resolveWorkspaceId()
+    return await this.databaseTokenService.findByName(workspaceId, name)
+  }
+
+  /**
+   * Listar solo tokens creados por la librería (con prefijo br-lib:)
+   * @returns Promise<DatabaseToken[]> Lista de tokens que empiezan con 'br-lib:'
+   * @throws {BaserowError} Si hay error de red
+   */
+  async listLibraryTokens(): Promise<DatabaseToken[]> {
+    const allTokens = await this.list()
+    return allTokens.filter(token => token.name.startsWith(LIBRARY_TOKEN_PREFIX))
+  }
+
+  /**
+   * Verificar si un token fue creado por la librería
+   * @param token - Database token a verificar
+   * @returns boolean true si el token tiene prefijo 'br-lib:', false si no
+   */
+  isLibraryToken(token: DatabaseToken): boolean {
+    return token.name.startsWith(LIBRARY_TOKEN_PREFIX)
+  }
+
+  /**
+   * Limpiar todos los tokens creados por la librería en el workspace
+   * Elimina solo tokens que empiecen con 'br-lib:'
+   * @returns Promise<{deleted: number, errors: number}> Resumen de tokens eliminados y errores
+   * @throws {BaserowError} Si hay error crítico de red
+   */
+  async cleanupLibraryTokens(): Promise<{ deleted: number; errors: number }> {
+    const libraryTokens = await this.listLibraryTokens()
+    let deleted = 0
+    let errors = 0
+
+    for (const token of libraryTokens) {
+      try {
+        await this.delete(token.id)
+        deleted++
+        if (this.logger) {
+          this.logger.info(`Deleted library token: "${token.name}" (ID: ${token.id})`)
+        }
+      } catch (error) {
+        errors++
+        if (this.logger) {
+          this.logger.error(`Error deleting library token "${token.name}":`, error)
+        }
+      }
+    }
+
+    return { deleted, errors }
+  }
+
+  /**
+   * Resolver workspace ID (lazy loading)
+   * Convierte nombre de workspace a ID numérico si es necesario
+   * @returns Promise<number> ID numérico del workspace
+   * @throws {BaserowNotFoundError} Si el workspace no existe
+   * @throws {BaserowError} Si hay error de red
+   * @private
+   */
+  private async resolveWorkspaceId(): Promise<number> {
+    // Si ya tenemos un ID resuelto Y es un nombre string, podemos usar el cache
+    if (this.resolvedWorkspaceId && typeof this.workspaceIdentifier === 'string') {
+      return this.resolvedWorkspaceId
+    }
+
+    let workspace
+    if (typeof this.workspaceIdentifier === 'number') {
+      // Es un ID numérico - retornar directamente sin verificación adicional
+      // La verificación se asume hecha por el caller (BaserowAdminWorkspace)
+      if (this.logger?.debug) {
+        this.logger.debug(`Using workspace ID for database tokens: ${this.workspaceIdentifier}`)
+      }
+      return this.workspaceIdentifier
+    } else {
+      // Es un nombre string - se puede cachear
+      workspace = await this.workspaceService.findUnique(this.workspaceIdentifier)
+      if (!workspace) {
+        throw new Error(`Workspace "${this.workspaceIdentifier}" not found`)
+      }
+      this.resolvedWorkspaceId = workspace.id
+
+      if (this.logger) {
+        this.logger.info(`Resolved workspace for database tokens: "${workspace.name}" (ID: ${workspace.id})`)
+      }
+
+      return this.resolvedWorkspaceId!
+    }
+  }
+}