@gzl10/baserow 1.2.0

package/src/ClientWithCreds.ts

@@ -0,0 +1,545 @@
+import { BaserowAdminConfig, LoginResponse, 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 { WorkspaceService } from './services/WorkspaceService'
+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 { WorkspaceContext } from './contexts/WorkspaceContext'
+import { BaseAuthClient } from './services/core/BaseAuthClient'
+
+/**
+ * Cliente administrativo con acceso global a todos los workspaces
+ *
+ * Proporciona acceso completo de administración usando JWT authentication con auto-refresh.
+ * API jerárquica que siempre comienza por workspace para mantener contexto claro.
+ * Ideal para scripts de administración y operaciones multi-workspace.
+ *
+ * **Características:**
+ * - Autenticación JWT con auto-refresh automático
+ * - API jerárquica: siempre `admin.workspace(name).database(name)`
+ * - Acceso global a todos los workspaces del usuario
+ * - Operaciones administrativas completas: crear/modificar estructura
+ * - Resolución automática de nombres a IDs
+ * - Validación de permisos y contextos
+ *
+ * **API Jerárquica:**
+ * - `admin.workspaces` → operaciones masivas de workspaces
+ * - `admin.workspace(name)` → contexto de workspace específico
+ * - `admin.workspace(name).databases` → operaciones masivas de databases
+ * - `admin.workspace(name).database(name)` → contexto de database específica
+ *
+ * @example
+ * ```typescript
+ * // Crear cliente admin global usando la API unificada
+ * const admin = await BaserowClient.create({
+ *   url: 'https://baserow.example.com',
+ *   credentials: {
+ *     email: 'admin@example.com',
+ *     password: 'password123'
+ *   }
+ * })
+ *
+ * // API jerárquica que siempre comienza por workspace
+ * const workspaces = await admin.workspaces.findMany()
+ * const workspace = await admin.workspaces.create({ name: 'New Workspace' })
+ *
+ * // Gestión completa de workspaces con API jerárquica
+ * const updatedWS = await admin.workspace('Company').update({ name: 'New Company' })
+ * await admin.workspace('Old Company').delete()
+ *
+ * // Operaciones específicas con contexto jerárquico
+ * const database = await admin.workspace('Company')
+ *   .database('CRM')
+ *   .create()
+ *
+ * const table = await admin.workspace('Company')
+ *   .database('CRM')
+ *   .table('Customers')
+ *   .create({
+ *     data: [['Name', 'Email'], ['Alice', 'alice@example.com']],
+ *     first_row_header: true
+ *   })
+ * ```
+ *
+ * @since 1.0.0
+ */
+export class ClientWithCreds extends BaseAuthClient<BaserowAdminConfig, 'credentials'> {
+  // Servicios para operaciones globales
+  public readonly workspaces: WorkspaceService
+  private readonly databaseService: DatabaseService
+  private readonly databaseTokenService: DatabaseTokenService
+  private readonly tableService: TableService
+  private readonly fieldService: FieldService
+  private readonly rowService: RowService
+
+  private constructor(config: BaserowAdminConfig, loginResponse: LoginResponse) {
+    // 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)
+
+    // 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.workspaces = new WorkspaceService(this.http, this.logger)
+    this.databaseService = new DatabaseService(this.http, this.logger)
+    this.databaseTokenService = new DatabaseTokenService(this.http, this.logger)
+    this.tableService = new TableService(this.http, this.logger)
+    this.fieldService = new FieldService(this.http, this.logger)
+    this.rowService = new RowService(this.http, this.logger)
+
+    if (this.logger) {
+      this.logger.info('ClientWithCreds initialized with JWT authentication (global mode)')
+    }
+  }
+
+  /**
+   * Campos que deben excluirse por defecto para cliente con credenciales
+   * Excluye credentials por seguridad
+   */
+  protected getDefaultExcludeKeys(): string[] {
+    return ['credentials']
+  }
+
+  /**
+   * Crear instancia de ClientWithCreds con auto-login
+   *
+   * Factory method que maneja la autenticación automáticamente y retorna una instancia
+   * lista para usar con JWT token válido y auto-refresh 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.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 ClientWithCreds
+   *
+   * @throws {BaserowConfigError} Si la configuración es inválida
+   * @throws {BaserowAuthError} Si las credenciales son incorrectas
+   *
+   * @example
+   * ```typescript
+   * // Cliente básico sin keep-alive
+   * const admin = await BaserowClient.create({
+   *   url: 'https://baserow.example.com',
+   *   credentials: {
+   *     email: 'admin@example.com',
+   *     password: 'secure-password'
+   *   }
+   * })
+   *
+   * // Cliente con keep-alive para backend 24/7 (re-login cada 5 días)
+   * const adminBackend = await BaserowClient.create({
+   *   url: 'https://baserow.example.com',
+   *   credentials: {
+   *     email: 'admin@example.com',
+   *     password: 'secure-password'
+   *   },
+   *   keepAlive: { enabled: true }
+   * })
+   *
+   * // Cliente listo para usar
+   * const workspaces = await admin.workspaces.findMany()
+   * ```
+   *
+   * @since 1.0.0
+   */
+  static async create(config: BaserowAdminConfig): Promise<ClientWithCreds> {
+    validateRequired(config, 'config')
+    validateString(config.url, 'url')
+    validateRequired(config.credentials, 'credentials')
+    validateString(config.credentials.email, 'email')
+    validateString(config.credentials.password, 'password')
+
+    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(`ClientWithCreds: Logged in as ${loginResponse.user.username}`)
+    }
+
+    // Crear instancia con token válido
+    // Los tokens son transferidos dentro del constructor
+    const admin = new ClientWithCreds(config, loginResponse)
+
+    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
+   * const workspaces = await admin.workspaces.findMany()
+   * ```
+   *
+   * @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('ClientWithCreds 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. Útil para debugging y logging.
+   *
+   * @returns Configuración actual sin credenciales (solo lectura)
+   *
+   * @example
+   * ```typescript
+   * const config = admin.getConfig()
+   * console.log('URL servidor:', config.url)
+   * // 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 workspaces = await admin.workspaces.findMany()
+   * } 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 {BaserowAuthError} Si el refresh token es inválido o expirado
+   *
+   * @example
+   * ```typescript
+   * try {
+   *   const newToken = await admin.refreshToken()
+   *   console.log('Token renovado exitosamente')
+   * } catch (error) {
+   *   console.log('Error renovando token, necesario re-login')
+   * }
+   * ```
+   *
+   * @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.
+   *
+   * @returns `true` si necesita re-login, `false` si la sesión es válida
+   *
+   * @example
+   * ```typescript
+   * if (admin.needsReLogin()) {
+   *   console.log('Sesión expirada, solicitando credenciales...')
+   *   const newAdmin = await ClientWithCreds.create({
+   *     url: config.url,
+   *     credentials: { email, password }
+   *   })
+   * } else {
+   *   const workspaces = await admin.workspaces.findMany()
+   * }
+   * ```
+   *
+   * @since 1.0.4
+   */
+  needsReLogin(): boolean {
+    if (!this.auth.getCurrentToken() || !this.auth['refreshToken']) {
+      return true
+    }
+
+    if (this.auth.isTokenExpired() && !this.auth['refreshToken']) {
+      return true
+    }
+
+    return false
+  }
+
+  /**
+   * Obtener estado detallado de autenticación
+   *
+   * @returns Objeto con información detallada del estado de autenticación
+   *
+   * @example
+   * ```typescript
+   * const status = admin.getAuthStatus()
+   * console.log('Autenticado:', status.isAuthenticated)
+   * 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('ClientWithCreds: Logged out')
+    }
+  }
+
+  // ============================================================================
+  // API JERÁRQUICA - SIEMPRE COMIENZA POR WORKSPACE
+  // ============================================================================
+
+  /**
+   * Acceder a un workspace específico (API jerárquica)
+   *
+   * Crea un contexto de workspace que permite operaciones en databases y recursos anidados.
+   * Acepta tanto nombres de workspace como IDs numéricos.
+   *
+   * @param workspaceIdentifier - Nombre del workspace o ID numérico
+   * @returns Contexto de workspace con acceso a databases y operaciones
+   *
+   * @example
+   * ```typescript
+   * // Usando nombre del workspace
+   * const databases = await admin.workspace('My Workspace').databases.list()
+   * const database = await admin.workspace('My Workspace').databases.create({
+   *   name: 'New Database'
+   * })
+   *
+   * // Usando ID numérico
+   * const tables = await admin.workspace(123).database('My DB').tables.findMany()
+   *
+   * // API jerárquica completa
+   * const table = await admin.workspace('Company')
+   *   .database('CRM')
+   *   .table('Customers')
+   *   .create({
+   *     data: [['Name', 'Email'], ['John', 'john@example.com']],
+   *     first_row_header: true
+   *   })
+   * ```
+   *
+   * @since 1.0.0
+   */
+  workspace(workspaceIdentifier: string | number): WorkspaceContext {
+    return new WorkspaceContext(
+      this.workspaces,
+      this.databaseService,
+      this.databaseTokenService,
+      this.tableService,
+      this.fieldService,
+      this.rowService,
+      workspaceIdentifier,
+      this.logger
+    )
+  }
+
+  /**
+   * Obtener estadísticas de uso global
+   */
+  async getUsageStats(): Promise<{
+    totalWorkspaces: number
+    totalDatabases: number
+    totalTables: number
+    isAuthenticated: boolean
+    tokenValid: boolean
+    mode: 'global'
+  }> {
+    const workspaces = await this.workspaces.findMany()
+
+    // Contar databases y tables de todos los workspaces
+    let totalDatabases = 0
+    let totalTables = 0
+
+    for (const workspace of workspaces) {
+      const databases = await this.databaseService.findMany()
+      const workspaceDatabases = databases.filter(db => db.workspace?.id === workspace.id)
+      totalDatabases += workspaceDatabases.length
+
+      // Usar las tablas que ya vienen en el objeto Database (más eficiente)
+      totalTables += workspaceDatabases.reduce((sum, db) => sum + (db.tables?.length || 0), 0)
+    }
+
+    return {
+      totalWorkspaces: workspaces.length,
+      totalDatabases,
+      totalTables,
+      isAuthenticated: this.isAuthenticated(),
+      tokenValid: !this.auth.isTokenExpired(),
+      mode: 'global'
+    }
+  }
+
+  /**
+   * Cerrar conexiones HTTP y limpiar recursos
+   *
+   * Detiene el keep-alive y libera recursos del cliente HTTP.
+   * Debe llamarse cuando el cliente ya no se necesite.
+   *
+   * @since 1.0.0
+   */
+  destroy(): void {
+    this.logger?.debug?.('Destroying ClientWithCreds')
+    this.auth.stopKeepAlive()
+    this.http.destroy()
+  }
+}