@gzl10/baserow 1.2.0

package/src/utils/field-cache.ts

@@ -0,0 +1,164 @@
+import { FieldService } from '../services/FieldService'
+import { Field, Logger } from '../types'
+
+/**
+ * Metadata de campos con tipos y opciones select
+ */
+export interface FieldMetadata {
+  /** Mapa de nombre de campo → tipo de campo */
+  types: Record<string, string>
+  /** Mapa de nombre de campo → {valor: id} para campos select */
+  selectOptions: Record<string, Record<string, number>>
+}
+
+/**
+ * Cache centralizado para metadata de campos de tablas
+ *
+ * Proporciona un sistema de cache eficiente para tipos de campo y opciones
+ * de campos select/multiselect, permitiendo resolver automáticamente
+ * valores de texto a IDs de opción para filtros de Baserow.
+ *
+ * **Características:**
+ * - Cache por tabla (tableId) para evitar conflictos
+ * - Mapeo automático value → ID para campos select
+ * - Invalidación granular por tabla o completa
+ * - Logging opcional para debugging
+ * - Performance optimizada con Map interna
+ *
+ * @example
+ * ```typescript
+ * const cache = new FieldCache(logger)
+ * const metadata = await cache.getFieldMetadata(fieldService, 123)
+ *
+ * // Tipos de campo: metadata.types['categoria'] // 'single_select'
+ * // Opciones select: metadata.selectOptions['categoria']['Premium'] // 45
+ * ```
+ *
+ * @since 1.2.0
+ */
+export class FieldCache {
+  private cache = new Map<number, FieldMetadata>()
+  private logger?: Logger
+
+  /**
+   * Crear nueva instancia de FieldCache
+   *
+   * @param logger - Logger opcional para debugging y trazabilidad
+   */
+  constructor(logger?: Logger) {
+    this.logger = logger
+  }
+
+  /**
+   * Obtener metadata completa de campos para una tabla
+   *
+   * Retorna tipos de campo y opciones de select con cache automático.
+   * Si los datos no están en cache, hace fetch automático y los almacena.
+   *
+   * @param fieldService - Servicio de campos para hacer fetch si necesario
+   * @param tableId - ID numérico de la tabla
+   * @returns Promise con metadata completa de campos
+   *
+   * @example
+   * ```typescript
+   * const metadata = await cache.getFieldMetadata(fieldService, 123)
+   *
+   * // Usar tipos
+   * const fieldType = metadata.types['categoria'] // 'single_select'
+   *
+   * // Resolver valor a ID
+   * const optionId = metadata.selectOptions['categoria']['Premium'] // 45
+   * ```
+   */
+  async getFieldMetadata(fieldService: FieldService, tableId: number): Promise<FieldMetadata> {
+    if (!this.cache.has(tableId)) {
+      const fields = await fieldService.findMany(tableId)
+      const metadata = this.buildMetadata(fields, tableId)
+      this.cache.set(tableId, metadata)
+    }
+    return this.cache.get(tableId)!
+  }
+
+  /**
+   * Construir metadata a partir de array de campos
+   *
+   * @private
+   * @param fields - Array de campos de la tabla
+   * @param tableId - ID de la tabla (para logging)
+   * @returns Metadata construida
+   */
+  private buildMetadata(fields: Field[], tableId: number): FieldMetadata {
+    const types: Record<string, string> = {}
+    const selectOptions: Record<string, Record<string, number>> = {}
+
+    for (const field of fields) {
+      // Mapear nombre → tipo
+      types[field.name] = field.type
+
+      // Para campos select, construir mapeo value → id
+      if (['single_select', 'multiple_select'].includes(field.type) && field.select_options) {
+        selectOptions[field.name] = Object.fromEntries(
+          field.select_options.map(option => [option.value, option.id]).filter(([, id]) => id !== undefined)
+        )
+      }
+    }
+
+    // Logging detallado para debugging
+    this.logger?.debug?.(`Field metadata cached for table ${tableId}`, {
+      fieldCount: fields.length,
+      selectFieldCount: Object.keys(selectOptions).length,
+      typeDistribution: Object.values(types).reduce(
+        (acc, type) => {
+          acc[type] = (acc[type] || 0) + 1
+          return acc
+        },
+        {} as Record<string, number>
+      ),
+      selectFields: Object.keys(selectOptions)
+    })
+
+    return { types, selectOptions }
+  }
+
+  /**
+   * Invalidar cache para una tabla específica o completo
+   *
+   * Útil cuando se sabe que los campos de una tabla han cambiado
+   * (campos agregados, eliminados, o opciones select modificadas).
+   *
+   * @param tableId - ID de tabla específica a invalidar. Si no se proporciona, limpia todo el cache
+   *
+   * @example
+   * ```typescript
+   * // Invalidar tabla específica
+   * cache.clearCache(123)
+   *
+   * // Limpiar todo el cache
+   * cache.clearCache()
+   * ```
+   */
+  clearCache(tableId?: number): void {
+    if (tableId !== undefined) {
+      const wasDeleted = this.cache.delete(tableId)
+      this.logger?.debug?.(`Cache cleared for table ${tableId}`, { wasDeleted })
+    } else {
+      const cacheSize = this.cache.size
+      this.cache.clear()
+      this.logger?.debug?.(`Full cache cleared`, { clearedTables: cacheSize })
+    }
+  }
+
+  /**
+   * Obtener estadísticas del cache
+   *
+   * Útil para debugging y monitoreo de performance.
+   *
+   * @returns Estadísticas del cache
+   */
+  getCacheStats(): { cachedTables: number; tableIds: number[] } {
+    return {
+      cachedTables: this.cache.size,
+      tableIds: Array.from(this.cache.keys())
+    }
+  }
+}

package/src/utils/httpFactory.ts

@@ -0,0 +1,66 @@
+/**
+ * Factory centralizado para creación de HttpClient
+ *
+ * Elimina duplicación de código en la inicialización de HttpClient
+ * proporcionando una fuente única de verdad para la configuración.
+ *
+ * @internal
+ * @since 1.0.0
+ */
+
+import { HttpClient } from './axios'
+import { PerformanceManager } from './performance'
+import type { Logger, BaserowPerformanceOptions } from '../types'
+
+/**
+ * Configuración para crear HttpClient
+ */
+export interface HttpClientFactoryConfig {
+  /** URL base de Baserow (ej: 'https://baserow.com') */
+  url: string
+  /** Token de autenticación (Database Token o JWT) */
+  token: string
+  /** Logger opcional para debug */
+  logger?: Logger
+  /** Configuración de performance opcional */
+  performance?: Partial<BaserowPerformanceOptions>
+}
+
+/**
+ * Crea una instancia de HttpClient con configuración estandarizada
+ *
+ * Centraliza la lógica de:
+ * - Sanitización de URL base
+ * - Configuración de performance (merge con defaults globales)
+ * - Configuración de token y logger
+ *
+ * @param config - Configuración del cliente HTTP
+ * @returns Instancia configurada de HttpClient
+ *
+ * @example
+ * ```typescript
+ * // Para Database Token
+ * const client = createHttpClient({
+ *   url: 'https://baserow.com',
+ *   token: 'db_token_123',
+ *   logger: console
+ * })
+ *
+ * // Para JWT (durante login)
+ * const tempClient = createHttpClient({
+ *   url: 'https://baserow.com',
+ *   token: '', // Sin token inicial
+ *   logger: console,
+ *   performance: { timeout: 15000 }
+ * })
+ * ```
+ */
+export function createHttpClient(config: HttpClientFactoryConfig): HttpClient {
+  return new HttpClient({
+    baseURL: `${config.url.replace(/\/$/, '')}/api`,
+    token: config.token,
+    logger: config.logger,
+    // Combinar defaults globales con configuración específica de instancia
+    ...PerformanceManager.merge(config.performance)
+  })
+}

package/src/utils/jwt-decoder.ts

@@ -0,0 +1,188 @@
+/**
+ * Utilidades para decodificar JWT tokens sin dependencias externas
+ *
+ * Proporciona funciones para extraer información de JWT tokens usando
+ * solo decodificación Base64 nativa de Node.js/Browser.
+ *
+ * **Características:**
+ * - Sin dependencias externas
+ * - Manejo robusto de errores
+ * - Compatible con Node.js y navegadores
+ * - Extrae claim `exp` (expiration) del payload
+ *
+ * @example
+ * ```typescript
+ * const token = 'eyJhbGc...'
+ * const expiry = decodeJwtExpiry(token)
+ * if (expiry) {
+ *   console.log('Token expira en:', expiry)
+ * }
+ * ```
+ *
+ * @since 1.0.0
+ */
+
+import { Logger } from '../types'
+
+/**
+ * Decodifica el claim `exp` (expiration) de un JWT token
+ *
+ * Lee el payload del JWT token y extrae el timestamp de expiración
+ * sin validar la firma (solo para leer metadatos del token).
+ *
+ * **JWT Structure:**
+ * - JWT = `header.payload.signature` (3 partes separadas por `.`)
+ * - `payload` está en Base64URL encoding
+ * - `exp` claim es Unix timestamp en **segundos** (no milisegundos)
+ *
+ * **Implementación:**
+ * 1. Split token por `.`
+ * 2. Decodificar parte [1] (payload) desde Base64
+ * 3. Parsear JSON del payload
+ * 4. Extraer `exp` y convertir a Date (multiplicar por 1000 para ms)
+ *
+ * @param token - JWT token completo en formato string
+ * @param logger - Logger opcional para debugging
+ * @returns Date de expiración o undefined si no se puede decodificar
+ *
+ * @example
+ * ```typescript
+ * // Token válido
+ * const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MDkzOTY4MDB9.sig'
+ * const expiry = decodeJwtExpiry(token)
+ * // expiry = Date(2024-03-02T12:00:00.000Z)
+ *
+ * // Token sin exp claim
+ * const tokenNoExp = 'eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjoiYWRtaW4ifQ.sig'
+ * const expiry2 = decodeJwtExpiry(tokenNoExp)
+ * // expiry2 = undefined
+ *
+ * // Token malformado
+ * const badToken = 'invalid-token'
+ * const expiry3 = decodeJwtExpiry(badToken)
+ * // expiry3 = undefined
+ * ```
+ *
+ * @since 1.0.0
+ */
+export function decodeJwtExpiry(token: string, logger?: Logger): Date | undefined {
+  try {
+    // Validar que el token tenga formato JWT (3 partes separadas por puntos)
+    const parts = token.split('.')
+    if (parts.length !== 3) {
+      logger?.warn?.(`❌ JWT malformado: esperaba 3 partes, recibió ${parts.length}`)
+      return undefined
+    }
+
+    // Decodificar payload (parte [1]) desde Base64
+    // atob() es global en navegadores y Node.js 16+
+    // Para Node.js < 16, usar Buffer.from(parts[1], 'base64').toString()
+    const payload = JSON.parse(
+      typeof atob !== 'undefined'
+        ? atob(parts[1]) // Browser / Node.js 16+
+        : Buffer.from(parts[1], 'base64').toString() // Node.js < 16
+    )
+
+    // Extraer claim 'exp' (expiration time)
+    // exp está en formato Unix timestamp (segundos desde epoch)
+    if (payload.exp === undefined || payload.exp === null || typeof payload.exp !== 'number') {
+      logger?.warn?.('❌ JWT sin claim exp válido')
+      return undefined
+    }
+
+    // Convertir Unix timestamp (segundos) a Date (milisegundos)
+    const expiryDate = new Date(payload.exp * 1000)
+
+    // Validar que la fecha sea válida
+    if (isNaN(expiryDate.getTime())) {
+      logger?.warn?.(`❌ Claim exp inválido: ${payload.exp}`)
+      return undefined
+    }
+
+    logger?.debug?.(`✅ JWT exp decodificado: ${expiryDate.toISOString()}`)
+    return expiryDate
+  } catch (error) {
+    logger?.warn?.('❌ Error decodificando JWT exp:', error)
+    return undefined
+  }
+}
+
+/**
+ * Decodifica el payload completo de un JWT token
+ *
+ * Útil para debugging o para acceder a otros claims del token
+ * además de `exp`.
+ *
+ * @param token - JWT token completo en formato string
+ * @param logger - Logger opcional para debugging
+ * @returns Payload del JWT o undefined si no se puede decodificar
+ *
+ * @example
+ * ```typescript
+ * const token = 'eyJhbGc...'
+ * const payload = decodeJwtPayload(token)
+ * console.log(payload)
+ * // { user_id: 123, exp: 1709396800, iat: 1709393200 }
+ * ```
+ *
+ * @since 1.0.0
+ */
+export function decodeJwtPayload(token: string, logger?: Logger): Record<string, any> | undefined {
+  try {
+    const parts = token.split('.')
+    if (parts.length !== 3) {
+      logger?.warn?.(`❌ JWT malformado: esperaba 3 partes, recibió ${parts.length}`)
+      return undefined
+    }
+
+    const payload = JSON.parse(
+      typeof atob !== 'undefined' ? atob(parts[1]) : Buffer.from(parts[1], 'base64').toString()
+    )
+
+    return payload
+  } catch (error) {
+    logger?.warn?.('❌ Error decodificando JWT payload:', error)
+    return undefined
+  }
+}
+
+/**
+ * Verifica si un JWT token está expirado
+ *
+ * Compara el claim `exp` del token con el tiempo actual.
+ * Útil para validaciones rápidas sin decodificar manualmente.
+ *
+ * @param token - JWT token completo en formato string
+ * @param bufferMs - Buffer de tiempo en ms para considerar "casi expirado" (default: 0)
+ * @param logger - Logger opcional para debugging
+ * @returns true si está expirado, false si es válido, undefined si no se puede decodificar
+ *
+ * @example
+ * ```typescript
+ * const token = 'eyJhbGc...'
+ *
+ * // Verificar si está expirado ahora
+ * if (isJwtExpired(token)) {
+ *   console.log('Token expirado')
+ * }
+ *
+ * // Verificar si expira en los próximos 5 minutos
+ * const fiveMinutes = 5 * 60 * 1000
+ * if (isJwtExpired(token, fiveMinutes)) {
+ *   console.log('Token expira pronto, renovar')
+ * }
+ * ```
+ *
+ * @since 1.0.0
+ */
+export function isJwtExpired(token: string, bufferMs: number = 0, logger?: Logger): boolean | undefined {
+  const expiry = decodeJwtExpiry(token, logger)
+  if (!expiry) {
+    return undefined // No se pudo decodificar
+  }
+
+  const now = Date.now()
+  const expiryWithBuffer = expiry.getTime() - bufferMs
+
+  return now >= expiryWithBuffer
+}

package/src/utils/jwtTokens.ts

@@ -0,0 +1,50 @@
+/**
+ * Utilidades centralizadas para manejo de JWT tokens
+ *
+ * Elimina duplicación de lógica de configuración de tokens JWT
+ * entre ClientWithCreds y ClientWithCredsWs.
+ *
+ * @internal
+ * @since 1.0.0
+ */
+
+import type { LoginResponse } from '../types'
+import type { AuthService } from '../services/AuthService'
+import { decodeJwtExpiry } from './jwt-decoder'
+
+/**
+ * Configura los tokens JWT en un AuthService existente
+ *
+ * Centraliza la lógica de transferencia de tokens desde LoginResponse
+ * al AuthService interno, eliminando duplicación entre clientes.
+ *
+ * **Importante:** La expiración se decodifica del claim `exp` del JWT,
+ * no se asume un TTL hardcoded.
+ *
+ * @param authService - Instancia de AuthService donde configurar tokens
+ * @param loginResponse - Respuesta del login con tokens JWT
+ *
+ * @example
+ * ```typescript
+ * // En ClientWithCreds.create()
+ * const admin = new ClientWithCreds(config, loginResponse)
+ * setupJwtTokens(admin.auth, loginResponse)
+ * ```
+ */
+export function setupJwtTokens(authService: AuthService, loginResponse: LoginResponse): void {
+  // Acceder a propiedades privadas del AuthService
+  // Esto es necesario para transferir tokens del login temporal al AuthService final
+  const authServiceAny = authService as any
+
+  authServiceAny['accessToken'] = loginResponse.access_token
+  authServiceAny['refreshToken'] = loginResponse.refresh_token
+
+  // Decodificar expiración desde el claim 'exp' del JWT (estándar)
+  const expiry = decodeJwtExpiry(loginResponse.access_token)
+  if (!expiry) {
+    // Fallback conservador si no se puede decodificar
+    authServiceAny['tokenExpiry'] = new Date(Date.now() + 10 * 60 * 1000) // 10 min
+  } else {
+    authServiceAny['tokenExpiry'] = expiry
+  }
+}

package/src/utils/performance.ts

@@ -0,0 +1,105 @@
+import type { BaserowPerformanceOptions } from '../types'
+
+/**
+ * Defaults centralizados de performance para toda la librería
+ *
+ * Fuente única de verdad para valores por defecto de configuración de performance.
+ * Usado por PerformanceManager y HttpClient para evitar duplicación.
+ */
+export const PERFORMANCE_DEFAULTS: BaserowPerformanceOptions = {
+  timeout: 30000,
+  retries: 3,
+  maxRequestsPerSecond: 10,
+  enableRateLimiting: true
+} as const
+
+/**
+ * Gestor centralizado de configuración de performance para toda la librería Baserow
+ *
+ * Proporciona una API unificada para gestionar la configuración global de performance
+ * que se aplicará a todas las instancias de clientes Baserow.
+ *
+ * @internal
+ * @since 1.0.0
+ */
+export class PerformanceManager {
+  /**
+   * Configuración global por defecto de performance
+   */
+  private static globalDefaults: BaserowPerformanceOptions = { ...PERFORMANCE_DEFAULTS }
+
+  /**
+   * Establece la configuración global de performance
+   *
+   * @param defaults - Configuración parcial para sobrescribir defaults
+   *
+   * @example
+   * ```typescript
+   * PerformanceManager.setGlobal({
+   *   timeout: 60000,
+   *   retries: 5
+   * })
+   * ```
+   */
+  static setGlobal(defaults: Partial<BaserowPerformanceOptions>): void {
+    PerformanceManager.globalDefaults = {
+      ...PerformanceManager.globalDefaults,
+      ...defaults
+    }
+  }
+
+  /**
+   * Obtiene la configuración global actual de performance
+   *
+   * @returns Copia de la configuración global actual
+   *
+   * @example
+   * ```typescript
+   * const current = PerformanceManager.getGlobal()
+   * console.log('Timeout global:', current.timeout)
+   * ```
+   */
+  static getGlobal(): BaserowPerformanceOptions {
+    return { ...PerformanceManager.globalDefaults }
+  }
+
+  /**
+   * Resetea la configuración global a los valores por defecto de la librería
+   *
+   * @example
+   * ```typescript
+   * PerformanceManager.reset()
+   * ```
+   */
+  static reset(): void {
+    PerformanceManager.globalDefaults = { ...PERFORMANCE_DEFAULTS }
+  }
+
+  /**
+   * Combina la configuración global con la configuración específica de instancia
+   *
+   * La configuración de instancia tiene prioridad sobre la global.
+   *
+   * @param instanceConfig - Configuración específica de la instancia (opcional)
+   * @returns Configuración final combinada
+   *
+   * @example
+   * ```typescript
+   * // Solo configuración global
+   * const config1 = PerformanceManager.merge()
+   *
+   * // Configuración global + override de instancia
+   * const config2 = PerformanceManager.merge({
+   *   retries: 1,  // Override
+   *   timeout: 5000  // Override
+   *   // maxRequestsPerSecond y enableRateLimiting vienen de global
+   * })
+   * ```
+   */
+  static merge(instanceConfig?: Partial<BaserowPerformanceOptions>): BaserowPerformanceOptions {
+    return {
+      ...PerformanceManager.globalDefaults,
+      ...instanceConfig
+    }
+  }
+}