@gzl10/baserow 1.2.0

package/src/ClientWithCredsWs.ts

@@ -0,0 +1,852 @@
+import { BaserowAdminConfig, LoginResponse, Workspace, BaserowConfigError } from './types'
+import { createHttpClient } from './utils/httpFactory'
+import { PerformanceManager } from './utils/performance'
+import { setupJwtTokens } from './utils/jwtTokens'
+import { validateRequired, validateString, validateUrl } from './utils/validation'
+import { AuthService } from './services/AuthService'
+import { DatabaseService } from './services/DatabaseService'
+import { DatabaseTokenService } from './services/DatabaseTokenService'
+import { TableService } from './services/TableService'
+import { FieldService } from './services/FieldService'
+import { RowService } from './services/RowService'
+import { WorkspaceService } from './services/WorkspaceService'
+import { DatabaseContext } from './contexts/DatabaseContext'
+import { DatabaseTokenContext } from './contexts/DatabaseTokenContext'
+import { BaseAuthClient } from './services/core/BaseAuthClient'
+
+/**
+ * Cliente administrativo restringido a workspace específico
+ *
+ * Proporciona acceso administrativo completo pero limitado a un workspace específico.
+ * API simplificada sin prefijo workspace, ideal para aplicaciones con scope limitado.
+ * Se autentica con JWT y auto-refresh, pero valida permisos solo para el workspace configurado.
+ *
+ * **Características:**
+ * - Autenticación JWT con auto-refresh automático
+ * - API simplificada: `admin.databases.create(name)` (workspace automático)
+ * - Acceso restringido al workspace especificado en configuración
+ * - Operaciones administrativas completas dentro del workspace
+ * - Resolución automática de nombres a IDs
+ * - Validación automática de permisos de workspace
+ *
+ * **API Simplificada:**
+ * - `admin.databases` → operaciones de databases del workspace
+ * - `admin.database(name)` → contexto de database específica
+ * - `admin.databaseToken` → gestión de Database Tokens del workspace
+ *
+ * @example
+ * ```typescript
+ * const admin = await BaserowWithCredentialsWorkspace.create({
+ *   url: 'https://baserow.example.com',
+ *   credentials: {
+ *     email: 'admin@example.com',
+ *     password: 'password123'
+ *   },
+ *   workspace: 'My Workspace'
+ * })
+ *
+ * // API simplificada sin prefijo workspace
+ * const databases = await admin.databases.findMany()
+ * const database = await admin.databases.create('My Database')
+ *
+ * // Acceso directo a operaciones de database
+ * const table = await admin.database('My Database')
+ *   .table('Users')
+ *   .create({
+ *     data: [['Name', 'Email'], ['John', 'john@example.com']],
+ *     first_row_header: true
+ *   })
+ *
+ * // Gestión de Database Tokens del workspace
+ * const token = await admin.databaseToken.createFullAccess('app-token')
+ * ```
+ *
+ * @since 1.0.0
+ */
+export class ClientWithCredsWs extends BaseAuthClient<BaserowAdminConfig, 'credentials'> {
+  private defaultWorkspace: Workspace
+
+  // Servicios que tienen sentido a nivel workspace
+  public databases: DatabaseService
+
+  // Servicios internos (no públicos)
+  private workspaceService: WorkspaceService
+  private databaseTokenService: DatabaseTokenService
+
+  private constructor(config: BaserowAdminConfig, loginResponse: LoginResponse, workspace: Workspace) {
+    // Procesar performance con defaults antes de guardar
+    const processedConfig = {
+      ...config,
+      performance: PerformanceManager.merge(config.performance)
+    }
+
+    // Inicializar HttpClient con JWT token
+    const http = createHttpClient({
+      url: processedConfig.url,
+      token: loginResponse.access_token,
+      logger: processedConfig.logger,
+      performance: processedConfig.performance
+    })
+
+    // Inicializar AuthService
+    const auth = new AuthService(http, processedConfig.logger)
+
+    super(processedConfig, http, auth, processedConfig.logger)
+    this.defaultWorkspace = workspace
+
+    // Transferir tokens al AuthService ANTES de configurar auto-refresh
+    setupJwtTokens(this.auth, loginResponse)
+
+    // Configurar auto-refresh de tokens (ahora tiene los tokens almacenados)
+    this.auth.setupAutoRefresh()
+
+    // Iniciar keep-alive si está habilitado
+    if (processedConfig.keepAlive?.enabled) {
+      const intervalMinutes = processedConfig.keepAlive.intervalMinutes ?? 7200
+      this.auth.startKeepAlive(intervalMinutes)
+    }
+
+    // Inicializar servicios
+    this.workspaceService = new WorkspaceService(this.http, this.logger)
+    this.databaseTokenService = new DatabaseTokenService(this.http, this.logger)
+    this.databases = new DatabaseService(this.http, this.logger, workspace.id)
+
+    if (this.logger) {
+      this.logger.info(
+        `BaserowWithCredentialsWorkspace initialized with JWT authentication (workspace-restricted to "${workspace.name}")`
+      )
+    }
+  }
+
+  /**
+   * Campos que deben excluirse por defecto para cliente con credenciales workspace
+   * Excluye credentials por seguridad
+   */
+  protected getDefaultExcludeKeys(): string[] {
+    return ['credentials']
+  }
+
+  /**
+   * Crear instancia de BaserowWithCredentialsWorkspace con auto-login y validación de workspace
+   *
+   * Factory method que maneja la autenticación automáticamente y valida/crea el workspace.
+   * Retorna una instancia lista para usar con JWT token válido y workspace configurado.
+   *
+   * **Keep-Alive opcional** para backends 24/7:
+   * - Habilitar con `keepAlive: { enabled: true }` para evitar expiración de refresh token
+   * - Default: re-login cada 5 días (7200 min), margen de seguridad de 2 días
+   * - ⚠️ Almacena credenciales en memoria (solo para backends confiables)
+   *
+   * @param config - Configuración del cliente administrativo
+   * @param config.url - URL del servidor Baserow
+   * @param config.credentials - Credenciales de usuario (email/password)
+   * @param config.workspace - Nombre del workspace a usar (se crea si no existe)
+   * @param config.keepAlive - Opcional: configuración keep-alive para backends 24/7
+   * @param config.logger - Logger opcional para debugging
+   * @returns Promise que resuelve a instancia autenticada de BaserowWithCredentialsWorkspace
+   *
+   * @throws {BaserowConfigError} Si la configuración es inválida o falta workspace
+   * @throws {BaserowAuthError} Si las credenciales son incorrectas
+   *
+   * @example
+   * ```typescript
+   * // Cliente básico sin keep-alive
+   * const admin = await BaserowWithCredentialsWorkspace.create({
+   *   url: 'https://baserow.example.com',
+   *   credentials: {
+   *     email: 'admin@example.com',
+   *     password: 'secure-password'
+   *   },
+   *   workspace: 'My Company Workspace'
+   * })
+   *
+   * // Cliente con keep-alive para backend 24/7 (re-login cada 5 días)
+   * const adminBackend = await BaserowWithCredentialsWorkspace.create({
+   *   url: 'https://baserow.example.com',
+   *   credentials: {
+   *     email: 'admin@example.com',
+   *     password: 'secure-password'
+   *   },
+   *   workspace: 'My Company Workspace',
+   *   keepAlive: { enabled: true }
+   * })
+   *
+   * // Cliente listo para usar (restringido al workspace)
+   * const databases = await admin.databases.list()
+   * const stats = await admin.getUsageStats() // Solo del workspace configurado
+   * ```
+   *
+   * @since 1.0.0
+   */
+  static async create(config: BaserowAdminConfig): Promise<ClientWithCredsWs> {
+    validateRequired(config, 'config')
+    validateString(config.url, 'url')
+    validateRequired(config.credentials, 'credentials')
+    validateString(config.credentials.email, 'email')
+    validateString(config.credentials.password, 'password')
+
+    if (!config.workspace) {
+      throw new BaserowConfigError('workspace is required for BaserowWithCredentialsWorkspace', 'workspace')
+    }
+
+    if (!validateUrl(config.url)) {
+      throw new BaserowConfigError('Invalid URL format', 'url')
+    }
+
+    // Crear HttpClient temporal para login
+    const tempHttp = createHttpClient({
+      url: config.url,
+      token: '', // Sin token inicial
+      logger: config.logger,
+      performance: config.performance
+    })
+
+    // Crear AuthService temporal
+    const tempAuth = new AuthService(tempHttp, config.logger)
+
+    // Realizar login
+    const loginResponse = await tempAuth.login(config.credentials)
+
+    if (config.logger) {
+      config.logger.info(`BaserowWithCredentialsWorkspace: Logged in as ${loginResponse.user.username}`)
+    }
+
+    // Resolver workspace por nombre
+    const tempWorkspaceService = new WorkspaceService(tempHttp, config.logger)
+    let workspace = await tempWorkspaceService.findUnique(config.workspace)
+
+    // Si no existe, crearlo
+    if (!workspace) {
+      if (config.logger) {
+        config.logger.info(`BaserowWithCredentialsWorkspace: Creating workspace "${config.workspace}"`)
+      }
+      workspace = await tempWorkspaceService.create({ name: config.workspace })
+    }
+
+    // Crear instancia con token válido y workspace resuelto
+    // Los tokens son transferidos dentro del constructor
+    const admin = new ClientWithCredsWs(config, loginResponse, workspace)
+
+    return admin
+  }
+
+  /**
+   * Verificar estado de salud del servidor Baserow
+   *
+   * Realiza un health check del servidor sin requerir autenticación.
+   * Útil para verificar conectividad antes de realizar operaciones.
+   *
+   * @returns Promise que resuelve a `true` si el servidor está saludable, `false` en caso contrario
+   *
+   * @example
+   * ```typescript
+   * const isHealthy = await admin.health()
+   * if (!isHealthy) {
+   *   console.log('Servidor Baserow no disponible')
+   *   return
+   * }
+   *
+   * // Proceder con operaciones del workspace
+   * const databases = await admin.databases.list()
+   * ```
+   *
+   * @since 1.0.0
+   */
+  async health(): Promise<boolean> {
+    try {
+      // Usar endpoint de salud oficial (no requiere autenticación)
+      const healthUrl = `${this.config.url.replace(/\/$/, '')}/api/_health/`
+      const response = await fetch(healthUrl, {
+        method: 'GET',
+        headers: { 'Content-Type': 'application/json' }
+      })
+
+      return response.ok
+    } catch (error) {
+      if (this.logger) {
+        this.logger.error('BaserowWithCredentialsWorkspace health check failed:', error)
+      }
+      return false
+    }
+  }
+
+  /**
+   * Obtener la configuración actual del cliente (sin exponer credenciales)
+   *
+   * Retorna una copia de solo lectura de la configuración, excluyendo las credenciales
+   * por seguridad. Incluye el workspace configurado.
+   *
+   * @returns Configuración actual sin credenciales (solo lectura)
+   *
+   * @example
+   * ```typescript
+   * const config = admin.getConfig()
+   * console.log('URL servidor:', config.url)
+   * console.log('Workspace:', config.workspace)
+   * // Las credenciales no están incluidas por seguridad
+   * ```
+   *
+   * @since 1.0.0
+   */
+  getConfig(): Readonly<Omit<BaserowAdminConfig, 'credentials'>> {
+    return this.getConfigBase()
+  }
+
+  /**
+   * Verificar si el cliente está autenticado
+   *
+   * Comprueba si hay un token JWT válido y no expirado.
+   * Si el token está próximo a expirar, el auto-refresh se encargará de renovarlo.
+   *
+   * @returns `true` si está autenticado con token válido, `false` en caso contrario
+   *
+   * @example
+   * ```typescript
+   * if (admin.isAuthenticated()) {
+   *   const databases = await admin.databases.list()
+   * } else {
+   *   console.log('Sesión expirada, necesario re-login')
+   * }
+   * ```
+   *
+   * @since 1.0.0
+   */
+  isAuthenticated(): boolean {
+    return this.auth.isAuthenticated()
+  }
+
+  /**
+   * Obtener el token JWT actual
+   *
+   * Retorna el token de acceso actual si está disponible.
+   * Útil para debugging o integración con otros sistemas.
+   *
+   * @returns Token JWT actual o `undefined` si no está autenticado
+   *
+   * @example
+   * ```typescript
+   * const token = admin.getCurrentToken()
+   * if (token) {
+   *   console.log('Token disponible:', token.substring(0, 20) + '...')
+   * }
+   * ```
+   *
+   * @since 1.0.0
+   */
+  getCurrentToken(): string | undefined {
+    return this.auth.getCurrentToken()
+  }
+
+  /**
+   * Renovar el token de acceso manualmente
+   *
+   * Fuerza la renovación del token JWT usando el refresh token.
+   * Normalmente no es necesario llamar esto manualmente ya que el auto-refresh
+   * se encarga automáticamente.
+   *
+   * @returns Promise que resuelve al nuevo token de acceso
+   *
+   * @throws {BaserowReLoginRequiredError} Si el refresh token ha expirado (~7 días)
+   * @throws {BaserowAuthTokenInvalidError} Si el refresh token es inválido
+   *
+   * @example
+   * ```typescript
+   * try {
+   *   const newToken = await admin.refreshToken()
+   *   console.log('Token renovado exitosamente')
+   * } catch (error) {
+   *   if (error instanceof BaserowReLoginRequiredError) {
+   *     console.log('Sesión expirada, necesario re-login con credenciales')
+   *     // Redirigir a login o solicitar credenciales nuevamente
+   *   }
+   * }
+   * ```
+   *
+   * @since 1.0.0
+   */
+  async refreshToken(): Promise<string> {
+    return await this.auth.refreshAccessToken()
+  }
+
+  /**
+   * Verificar si el cliente necesita re-autenticación
+   *
+   * Útil para detectar si los tokens se han perdido o el refresh token expiró,
+   * permitiendo manejar proactivamente la re-autenticación antes de hacer requests.
+   *
+   * @aiUsage
+   * **✅ Usar cuando:**
+   * - Antes de operaciones críticas (validación proactiva de sesión)
+   * - Después de períodos largos de inactividad (>6 horas)
+   * - Al iniciar aplicación (verificar si sesión previa sigue válida)
+   * - Después de errores 401 (distinguir si es recoverable con refresh)
+   * - En background jobs/cron tasks (sesiones de larga duración)
+   *
+   * **❌ NO usar cuando:**
+   * - Ya tienes try/catch con BaserowReLoginRequiredError (manejo reactivo suficiente)
+   * - Llamando cada request (overhead innecesario, auto-refresh ya maneja)
+   * - Solo para logging (usar `getAuthStatus()` que da más info)
+   *
+   * @aiPattern
+   * ## 🎯 Patrón: Wrapper con Auto-Relogin
+   *
+   * Crea una función wrapper que automáticamente reautentica si la sesión expiró:
+   *
+   * ```typescript
+   * async function withAutoRelogin<T>(
+   *   admin: ClientWithCredsWs,
+   *   credentials: { email: string; password: string },
+   *   operation: (client: ClientWithCredsWs) => Promise<T>
+   * ): Promise<T> {
+   *   // 1. Verificar proactivamente si necesita re-login
+   *   if (admin.needsReLogin()) {
+   *     console.log('🔄 Sesión expirada, reautenticando...')
+   *
+   *     admin = await ClientWithCredsWs.create({
+   *       url: admin.getConfig().url,
+   *       credentials,
+   *       workspace: admin.getConfig().workspace!
+   *     })
+   *
+   *     console.log('✅ Re-autenticación exitosa')
+   *   }
+   *
+   *   // 2. Ejecutar operación con manejo de errores
+   *   try {
+   *     return await operation(admin)
+   *   } catch (error) {
+   *     // 3. Si falla con re-login required, reintentar UNA vez
+   *     if (error instanceof BaserowReLoginRequiredError) {
+   *       console.log('🔄 Token refresh falló, reautenticando...')
+   *
+   *       admin = await ClientWithCredsWs.create({
+   *         url: admin.getConfig().url,
+   *         credentials,
+   *         workspace: admin.getConfig().workspace!
+   *       })
+   *
+   *       return await operation(admin)
+   *     }
+   *     throw error
+   *   }
+   * }
+   *
+   * // Uso del wrapper
+   * const result = await withAutoRelogin(
+   *   admin,
+   *   { email: 'user@example.com', password: 'secret' },
+   *   async (client) => {
+   *     const databases = await client.databases.findMany()
+   *     return databases
+   *   }
+   * )
+   * ```
+   *
+   * @aiPattern
+   * ## 🔄 Patrón: Session Manager con Polling
+   *
+   * Para aplicaciones de larga duración, monitorea la sesión periódicamente:
+   *
+   * ```typescript
+   * class SessionManager {
+   *   private checkInterval: NodeJS.Timeout | null = null
+   *
+   *   constructor(
+   *     private admin: ClientWithCredsWs,
+   *     private credentials: { email: string; password: string }
+   *   ) {}
+   *
+   *   // Monitorear sesión cada N minutos
+   *   startMonitoring(intervalMinutes: number = 30) {
+   *     this.checkInterval = setInterval(async () => {
+   *       if (this.admin.needsReLogin()) {
+   *         console.warn('⚠️  Sesión expirada detectada, reautenticando...')
+   *
+   *         try {
+   *           this.admin = await ClientWithCredsWs.create({
+   *             url: this.admin.getConfig().url,
+   *             credentials: this.credentials,
+   *             workspace: this.admin.getConfig().workspace!
+   *           })
+   *
+   *           console.log('✅ Sesión renovada automáticamente')
+   *         } catch (error) {
+   *           console.error('❌ Error renovando sesión:', error)
+   *           // Notificar al usuario o detener el servicio
+   *         }
+   *       }
+   *     }, intervalMinutes * 60 * 1000)
+   *   }
+   *
+   *   stopMonitoring() {
+   *     if (this.checkInterval) {
+   *       clearInterval(this.checkInterval)
+   *     }
+   *   }
+   *
+   *   getClient(): ClientWithCredsWs {
+   *     return this.admin
+   *   }
+   * }
+   *
+   * // Uso
+   * const sessionManager = new SessionManager(admin, credentials)
+   * sessionManager.startMonitoring(30) // Check cada 30 min
+   *
+   * // Usar cliente desde manager
+   * const client = sessionManager.getClient()
+   * const data = await client.databases.findMany()
+   * ```
+   *
+   * @aiErrorHandling
+   * ## ⚠️ Casos de Re-Login Necesario
+   *
+   * **Caso 1: Tokens perdidos (reinicio de proceso)**
+   * ```typescript
+   * // Al iniciar aplicación, verificar sesión previa
+   * if (admin.needsReLogin()) {
+   *   console.log('Tokens perdidos (reinicio), necesario login')
+   *   // needsReLogin() = true porque no hay tokens en memoria
+   * }
+   * ```
+   *
+   * **Caso 2: Refresh token expirado (~7 días inactividad)**
+   * ```typescript
+   * // Después de 7+ días sin uso
+   * if (admin.needsReLogin()) {
+   *   console.log('Refresh token expirado, necesario login')
+   *   // Access token expirado + no refresh token disponible
+   * }
+   * ```
+   *
+   * **Caso 3: Sesión válida (NO necesita re-login)**
+   * ```typescript
+   * if (!admin.needsReLogin()) {
+   *   // Access token válido O refresh token disponible para renovar
+   *   const data = await admin.databases.findMany()
+   *   // Auto-refresh manejará la renovación si access token expira
+   * }
+   * ```
+   *
+   * @aiWarning
+   * **⚠️ Limitaciones:**
+   * - No detecta refresh token inválido (solo detecta ausencia o access token expirado)
+   * - Si refresh token está corrupto, `needsReLogin()` retorna `false` pero el refresh fallará
+   * - Para validación completa, usar try/catch con `BaserowReLoginRequiredError`
+   *
+   * **⚠️ Credenciales en Memoria:**
+   * - El wrapper `withAutoRelogin()` requiere credenciales en memoria
+   * - Evalúa riesgos de seguridad vs conveniencia
+   * - Alternativa: solicitar credenciales al usuario cuando `needsReLogin()` = true
+   *
+   * @returns `true` si necesita re-login, `false` si la sesión es válida
+   *
+   * @example
+   * ```typescript
+   * // Validación proactiva simple
+   * if (admin.needsReLogin()) {
+   *   console.log('Sesión expirada, solicitando credenciales...')
+   *   // Mostrar formulario de login o solicitar credenciales
+   *   const newAdmin = await ClientWithCredsWs.create({
+   *     url: config.url,
+   *     credentials: { email, password },
+   *     workspace: config.workspace
+   *   })
+   * } else {
+   *   // Sesión válida, continuar normalmente
+   *   const databases = await admin.databases.findMany()
+   * }
+   *
+   * // Con wrapper de auto-relogin
+   * const databases = await withAutoRelogin(
+   *   admin,
+   *   credentials,
+   *   async (client) => client.databases.findMany()
+   * )
+   * ```
+   *
+   * @since 1.0.4
+   */
+  needsReLogin(): boolean {
+    // No hay tokens = necesita login
+    if (!this.auth.getCurrentToken() || !this.auth['refreshToken']) {
+      return true
+    }
+
+    // Si el access token está expirado y no tenemos refresh token, necesita login
+    if (this.auth.isTokenExpired() && !this.auth['refreshToken']) {
+      return true
+    }
+
+    return false
+  }
+
+  /**
+   * Obtener estado detallado de autenticación
+   *
+   * Proporciona información completa sobre el estado actual de la sesión,
+   * útil para debugging y monitoreo de sesiones.
+   *
+   * @returns Objeto con información detallada del estado de autenticación
+   *
+   * @example
+   * ```typescript
+   * const status = admin.getAuthStatus()
+   * console.log('Autenticado:', status.isAuthenticated)
+   * console.log('Token expira:', status.tokenExpiry)
+   * console.log('Tiene refresh token:', status.hasRefreshToken)
+   * console.log('Necesita re-login:', status.needsReLogin)
+   * ```
+   *
+   * @since 1.0.4
+   */
+  getAuthStatus(): {
+    isAuthenticated: boolean
+    hasAccessToken: boolean
+    hasRefreshToken: boolean
+    tokenExpiry?: Date
+    isTokenExpired: boolean
+    needsReLogin: boolean
+  } {
+    const hasAccessToken = !!this.auth.getCurrentToken()
+    const hasRefreshToken = !!this.auth['refreshToken']
+    const tokenExpiry = this.auth['tokenExpiry'] as Date | undefined
+    const isTokenExpired = this.auth.isTokenExpired()
+
+    return {
+      isAuthenticated: this.auth.isAuthenticated(),
+      hasAccessToken,
+      hasRefreshToken,
+      tokenExpiry,
+      isTokenExpired,
+      needsReLogin: this.needsReLogin()
+    }
+  }
+
+  /**
+   * Cerrar sesión y limpiar tokens
+   *
+   * Invalida los tokens JWT, detiene el keep-alive y limpia el estado de autenticación.
+   * Después de llamar este método, el cliente necesitará volver a autenticarse.
+   *
+   * @example
+   * ```typescript
+   * // Al final de la aplicación o cambio de usuario
+   * admin.logout()
+   *
+   * // El cliente ya no está autenticado
+   * console.log(admin.isAuthenticated()) // false
+   * ```
+   *
+   * @since 1.0.0
+   */
+  logout(): void {
+    this.auth.logout() // Esto internamente llama stopKeepAlive()
+    if (this.logger) {
+      this.logger.info('BaserowWithCredentialsWorkspace: Logged out')
+    }
+  }
+
+  /**
+   * Obtener el workspace configurado
+   *
+   * Retorna la información completa del workspace al que está restringido este cliente.
+   * Útil para obtener ID, nombre y metadatos del workspace actual.
+   *
+   * @returns Información completa del workspace configurado
+   *
+   * @example
+   * ```typescript
+   * const workspace = admin.getDefaultWorkspace()
+   * console.log(`Workspace actual: ${workspace.name} (ID: ${workspace.id})`)
+   * ```
+   *
+   * @since 1.0.0
+   */
+  getDefaultWorkspace(): Workspace {
+    return this.defaultWorkspace
+  }
+
+  /**
+   * Obtener ID del workspace configurado
+   *
+   * Retorna únicamente el ID numérico del workspace al que está restringido este cliente.
+   * Método de conveniencia para obtener solo el ID sin metadatos adicionales.
+   *
+   * @returns ID numérico del workspace configurado
+   *
+   * @example
+   * ```typescript
+   * const workspaceId = admin.getWorkspaceId()
+   * console.log(`Operando en workspace ID: ${workspaceId}`)
+   * ```
+   *
+   * @since 1.0.0
+   */
+  getWorkspaceId(): number {
+    return this.defaultWorkspace.id
+  }
+
+  // ============================================================================
+  // API DIRECTO - SIN WORKSPACE PREFIX
+  // ============================================================================
+
+  /**
+   * Acceder a una database específica del workspace configurado (API simplificada)
+   *
+   * Crea un contexto de database que permite operaciones en tablas y filas.
+   * Solo puede acceder a databases del workspace configurado.
+   * Acepta tanto nombres de database como IDs numéricos.
+   *
+   * @param databaseIdentifier - Nombre de la database o ID numérico
+   * @returns Contexto de database con acceso a tablas y operaciones
+   *
+   * @example
+   * ```typescript
+   * // Usando nombre de la database
+   * const tables = await admin.database('My Database').tables.findMany()
+   * const table = await admin.database('My Database').table('Users').create()
+   *
+   * // Usando ID numérico
+   * const rows = await admin.database(123).table('Users').rows.list()
+   *
+   * // API simplificada completa
+   * const newTable = await admin.database('CRM')
+   *   .table('Customers')
+   *   .create({
+   *     data: [['Name', 'Email'], ['John', 'john@example.com']],
+   *     first_row_header: true
+   *   })
+   *
+   * // Gestión de campos
+   * const field = await admin.database('CRM')
+   *   .table('Customers')
+   *   .field.createText('Company', undefined, 'Nombre de la empresa')
+   * ```
+   *
+   * @since 1.0.0
+   */
+  database(databaseIdentifier: string | number): DatabaseContext {
+    // Crear instancias de servicios según se necesiten para el contexto
+    const tableService = new TableService(this.http, this.logger)
+    const fieldService = new FieldService(this.http, this.logger)
+    const rowService = new RowService(this.http, this.logger)
+
+    return new DatabaseContext(
+      this.workspaceService,
+      this.defaultWorkspace.id,
+      databaseIdentifier,
+      this.databases,
+      tableService,
+      fieldService,
+      rowService,
+      this.logger
+    )
+  }
+
+  /**
+   * Acceder a gestión de Database Tokens del workspace configurado
+   *
+   * Proporciona operaciones completas de Database Tokens limitadas al workspace actual.
+   * Los Database Tokens creados solo tendrán acceso a databases de este workspace.
+   *
+   * @returns Contexto de Database Token con operaciones CRUD
+   *
+   * @example
+   * ```typescript
+   * // Crear token con acceso completo al workspace
+   * const fullToken = await admin.databaseToken.createFullAccess('app-token')
+   *
+   * // Crear token con permisos específicos
+   * const readOnlyToken = await admin.databaseToken.create('readonly-token', {
+   *   databases: [{ database_id: 123, permissions: 'read' }]
+   * })
+   *
+   * // Listar todos los tokens del workspace
+   * const tokens = await admin.databaseToken.list()
+   *
+   * // Gestionar token específico
+   * await admin.databaseToken.update(tokenId, { name: 'New Name' })
+   * await admin.databaseToken.delete(tokenId)
+   * ```
+   *
+   * @since 1.0.0
+   */
+  get databaseToken(): DatabaseTokenContext {
+    return new DatabaseTokenContext(
+      this.workspaceService,
+      this.defaultWorkspace.id,
+      this.databaseTokenService,
+      this.logger
+    )
+  }
+
+  /**
+   * Obtener estadísticas de uso del workspace configurado
+   *
+   * Recopila información sobre recursos y estado del workspace al que está
+   * restringido este cliente. Útil para dashboards y monitoreo.
+   *
+   * @returns Promise con estadísticas completas del workspace
+   *
+   * @example
+   * ```typescript
+   * const stats = await admin.getUsageStats()
+   * console.log(`Workspace: ${stats.workspace.name}`)
+   * console.log(`Databases: ${stats.totalDatabases}`)
+   * console.log(`Tables: ${stats.totalTables}`)
+   * console.log(`Autenticado: ${stats.isAuthenticated}`)
+   * console.log(`Token válido: ${stats.tokenValid}`)
+   * console.log(`Modo: ${stats.mode}`) // 'workspace-restricted'
+   * ```
+   *
+   * @since 1.0.0
+   */
+  async getUsageStats(): Promise<{
+    totalDatabases: number
+    totalTables: number
+    isAuthenticated: boolean
+    tokenValid: boolean
+    workspace: { id: number; name: string }
+    mode: 'workspace-restricted'
+  }> {
+    // Filtrar databases del workspace configurado
+    const allDatabases = await this.databases.findMany()
+    const databases = allDatabases.filter(db => db.workspace?.id === this.defaultWorkspace.id)
+
+    // Usar las tablas que ya vienen en el objeto Database (más eficiente)
+    const totalTables = databases.reduce((sum, db) => sum + (db.tables?.length || 0), 0)
+
+    return {
+      totalDatabases: databases.length,
+      totalTables,
+      isAuthenticated: this.isAuthenticated(),
+      tokenValid: !this.auth.isTokenExpired(),
+      mode: 'workspace-restricted',
+      workspace: {
+        id: this.defaultWorkspace.id,
+        name: this.defaultWorkspace.name
+      }
+    }
+  }
+
+  /**
+   * Cerrar conexiones HTTP y limpiar recursos
+   *
+   * Detiene el keep-alive, libera recursos del cliente HTTP y cierra conexiones pendientes.
+   * Debe llamarse cuando el cliente ya no se necesite para evitar memory leaks.
+   *
+   * @example
+   * ```typescript
+   * // Al final de la aplicación o cuando ya no se necesite el cliente
+   * admin.destroy()
+   * ```
+   *
+   * @since 1.0.0
+   */
+  destroy(): void {
+    this.logger?.debug?.('Destroying BaserowWithCredentialsWorkspace')
+    this.auth.stopKeepAlive()
+    this.http.destroy()
+  }
+}