@gzl10/baserow 1.2.0

package/src/services/WorkspaceService.ts

@@ -0,0 +1,113 @@
+import { HttpService } from './core/HttpService'
+import { Workspace, BaserowResponse, BaserowNotFoundError, BaserowError } from '../types'
+import { validateRequired, validatePositiveNumber, validateString } from '../utils/validation'
+
+export interface CreateWorkspaceRequest {
+  name: string
+}
+
+export interface UpdateWorkspaceRequest {
+  name?: string
+}
+
+export class WorkspaceService extends HttpService {
+  // ===== PUBLIC API (Prisma-style) =====
+
+  /**
+   * Listar todos los workspaces del usuario
+   */
+  async findMany(): Promise<Workspace[]> {
+    const response = await this.http.get<BaserowResponse<Workspace> | Workspace[]>('/workspaces/')
+    return Array.isArray(response) ? response : response.results
+  }
+
+  /**
+   * Buscar workspace por ID o nombre
+   */
+  async findUnique(identifier: string | number): Promise<Workspace | null> {
+    if (typeof identifier === 'number') {
+      // Buscar por ID
+      const workspaces = await this.findMany()
+      return workspaces.find(ws => ws.id === identifier) || null
+    } else {
+      // Buscar por nombre
+      validateRequired(identifier, 'workspace identifier')
+      const workspaces = await this.findMany()
+      return workspaces.find(ws => ws.name === identifier) || null
+    }
+  }
+
+  /**
+   * Crear workspace - API pública
+   */
+  async create(data: CreateWorkspaceRequest): Promise<Workspace> {
+    return this.createWorkspaceInternal(data)
+  }
+
+  // ===== INTERNAL METHODS (Private) =====
+
+  /**
+   * Crear nuevo workspace (método interno)
+   * @private - Solo para uso interno del servicio
+   */
+  private async createWorkspaceInternal(data: CreateWorkspaceRequest): Promise<Workspace> {
+    validateString(data.name, 'name')
+
+    return await this.http.post<Workspace>('/workspaces/', {
+      name: data.name
+    })
+  }
+
+  /**
+   * Actualizar workspace (método interno)
+   * @private - Solo para uso por WorkspaceContext
+   */
+  private async updateWorkspaceInternal(workspaceId: number, data: UpdateWorkspaceRequest): Promise<Workspace> {
+    validatePositiveNumber(workspaceId, 'workspaceId')
+
+    if (data.name !== undefined) {
+      validateString(data.name, 'name')
+    }
+
+    try {
+      return await this.http.patch<Workspace>(`/workspaces/${workspaceId}/`, data)
+    } catch (error) {
+      if (error instanceof BaserowError && error.status === 404) {
+        throw new BaserowNotFoundError('Workspace', workspaceId)
+      }
+      throw error
+    }
+  }
+
+  /**
+   * Eliminar workspace (método interno)
+   * @private - Solo para uso por WorkspaceContext
+   */
+  private async deleteWorkspaceInternal(workspaceId: number): Promise<void> {
+    validatePositiveNumber(workspaceId, 'workspaceId')
+
+    try {
+      await this.http.delete(`/workspaces/${workspaceId}/`)
+    } catch (error) {
+      if (error instanceof BaserowError && error.status === 404) {
+        throw new BaserowNotFoundError('Workspace', workspaceId)
+      }
+      throw error
+    }
+  }
+
+  // ===== FRIEND ACCESS PATTERN FOR WORKSPACE CONTEXT =====
+  // Symbol-based access que no aparece en la API pública pero permite acceso interno
+
+  /**
+   * Friend access para WorkspaceContext
+   * No aparece en intellisense normal ni en la API pública
+   * @internal
+   */
+  get [Symbol.for('workspaceContext')]() {
+    return {
+      updateWorkspace: this.updateWorkspaceInternal.bind(this),
+      deleteWorkspace: this.deleteWorkspaceInternal.bind(this)
+    }
+  }
+}

package/src/services/core/BaseAuthClient.ts

@@ -0,0 +1,111 @@
+/**
+ * Clase base abstracta para clientes con autenticación JWT
+ * Extiende BaseClient agregando funcionalidades de autenticación
+ */
+
+import { BaseClient } from './BaseClient'
+import { HttpClient } from '../../utils/axios'
+import { Logger } from '../../types/index'
+import { AuthService } from '../AuthService'
+
+export abstract class BaseAuthClient<TConfig = any, TExcludeKeys extends keyof TConfig = never> extends BaseClient<
+  TConfig,
+  TExcludeKeys
+> {
+  protected auth: AuthService
+
+  constructor(config: TConfig, http: HttpClient, auth: AuthService, logger?: Logger) {
+    super(config, http, logger)
+    this.auth = auth
+  }
+
+  /**
+   * 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()) {
+   *   console.log('Cliente autenticado correctamente')
+   *   // Proceder con operaciones que requieren autenticación
+   * } else {
+   *   console.log('Cliente no autenticado')
+   * }
+   * ```
+   *
+   * @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 para usar el token en otras APIs.
+   *
+   * @returns Token JWT actual o undefined si no está autenticado
+   *
+   * @example
+   * ```typescript
+   * const token = admin.getCurrentToken()
+   * if (token) {
+   *   console.log('Token actual:', token.substring(0, 10) + '...')
+   * }
+   * ```
+   *
+   * @since 1.0.0
+   */
+  getCurrentToken(): string | undefined {
+    return this.auth.getCurrentToken()
+  }
+
+  /**
+   * Refrescar el token JWT manualmente
+   *
+   * Normalmente el auto-refresh maneja esto automáticamente, pero este método
+   * permite forzar un refresh del token antes de que expire.
+   *
+   * @returns Promise que resuelve al nuevo token de acceso
+   * @throws {BaserowAuthError} Si el refresh falla (refresh token expirado/inválido)
+   *
+   * @example
+   * ```typescript
+   * try {
+   *   const newToken = await admin.refreshToken()
+   *   console.log('Token refrescado exitosamente')
+   * } catch (error) {
+   *   console.error('Error refrescando token:', error.message)
+   *   // Re-autenticar usuario
+   * }
+   * ```
+   *
+   * @since 1.0.0
+   */
+  async refreshToken(): Promise<string> {
+    return await this.auth.refreshAccessToken()
+  }
+
+  /**
+   * Cerrar sesión y limpiar tokens
+   *
+   * Invalida el token JWT actual y limpia toda la información de autenticación.
+   * Después de logout() el cliente no podrá realizar operaciones autenticadas.
+   *
+   * @example
+   * ```typescript
+   * admin.logout()
+   * console.log(admin.isAuthenticated()) // false
+   * ```
+   *
+   * @since 1.0.0
+   */
+  logout(): void {
+    this.auth.logout()
+  }
+}

package/src/services/core/BaseClient.ts

@@ -0,0 +1,107 @@
+/**
+ * Clase base abstracta para todos los clientes de Baserow
+ * Proporciona funcionalidades comunes como getConfig() unificado
+ */
+
+import { BaseService } from './BaseService'
+import { HttpClient } from '../../utils/axios'
+import { Logger } from '../../types/index'
+
+export abstract class BaseClient<TConfig = any, TExcludeKeys extends keyof TConfig = never> extends BaseService {
+  protected config: TConfig
+
+  constructor(config: TConfig, http: HttpClient, logger?: Logger) {
+    super(http, logger)
+    this.config = config
+  }
+
+  /**
+   * Obtener configuración del cliente sin campos sensibles
+   *
+   * Implementación unificada que excluye automáticamente campos sensibles
+   * como credenciales, manteniendo consistencia entre todos los clientes.
+   *
+   * @param excludeKeys - Campos adicionales a excluir de la configuración
+   * @returns Configuración del cliente sin campos sensibles
+   *
+   * @example
+   * ```typescript
+   * const config = client.getConfig()
+   * console.log('URL:', config.url)
+   * console.log('Performance:', config.performance)
+   * // credentials no aparece en el resultado
+   * ```
+   */
+  protected getConfigBase<K extends keyof TConfig = TExcludeKeys>(
+    excludeKeys: K[] = [] as K[]
+  ): Readonly<Omit<TConfig, K | TExcludeKeys>> {
+    const result = { ...this.config } as any
+
+    // Excluir campos predefinidos para este tipo de cliente
+    const defaultExcludes = this.getDefaultExcludeKeys()
+    const allExcludes = [...defaultExcludes, ...excludeKeys]
+
+    allExcludes.forEach(key => delete result[key])
+
+    return result
+  }
+
+  /**
+   * Campos que deben excluirse por defecto para este tipo de cliente
+   * Subclases pueden sobrescribir este método para definir exclusiones específicas
+   */
+  protected abstract getDefaultExcludeKeys(): string[]
+
+  /**
+   * Verificar si el servidor Baserow está disponible (health check)
+   *
+   * Realiza una verificación de conectividad básica al servidor Baserow
+   * sin requerir autenticación. Útil para verificar disponibilidad del servicio.
+   *
+   * @returns Promise que resuelve a true si el servidor está disponible
+   *
+   * @example
+   * ```typescript
+   * const isHealthy = await client.health()
+   * if (!isHealthy) {
+   *   console.log('Servidor Baserow no disponible')
+   * }
+   * ```
+   *
+   * @since 1.0.0
+   */
+  async health(): Promise<boolean> {
+    try {
+      // Usar endpoint de salud oficial (no requiere autenticación)
+      const healthUrl = `${(this.config as any).url.replace(/\/$/, '')}/api/_health/`
+      const response = await fetch(healthUrl, {
+        method: 'GET',
+        headers: { 'Content-Type': 'application/json' }
+      })
+
+      return response.ok
+    } catch (error) {
+      this.logError('Health check failed', error)
+      return false
+    }
+  }
+
+  /**
+   * Destruir cliente y liberar recursos
+   *
+   * Limpia todas las conexiones HTTP, timers y recursos del cliente.
+   * Debe llamarse cuando el cliente ya no se va a usar para evitar memory leaks.
+   *
+   * @example
+   * ```typescript
+   * // Al final de la aplicación o cuando ya no se necesite el cliente
+   * client.destroy()
+   * ```
+   *
+   * @since 1.0.0
+   */
+  destroy(): void {
+    this.logDebug(`Destroying ${this.constructor.name}`)
+    this.http.destroy()
+  }
+}

package/src/services/core/BaseService.ts

@@ -0,0 +1,71 @@
+/**
+ * Clase base para todos los servicios de Baserow
+ * Proporciona funcionalidades comunes como HTTP client, logging y validación
+ */
+
+import { HttpClient } from '../../utils/axios'
+import { Logger } from '../../types/index'
+
+export abstract class BaseService {
+  protected logger?: Logger
+
+  constructor(
+    protected http: HttpClient,
+    logger?: Logger
+  ) {
+    this.logger = logger
+  }
+
+  /**
+   * Log de información
+   */
+  protected logInfo(message: string, ...params: any[]): void {
+    this.logger?.info?.(`[${this.constructor.name}] ${message}`, ...params)
+  }
+
+  /**
+   * Log de warnings
+   */
+  protected logWarn(message: string, ...params: any[]): void {
+    this.logger?.warn?.(`[${this.constructor.name}] ${message}`, ...params)
+  }
+
+  /**
+   * Log de errores
+   */
+  protected logError(message: string, error?: any, ...params: any[]): void {
+    this.logger?.error?.(`[${this.constructor.name}] ${message}`, error, ...params)
+  }
+
+  /**
+   * Log de debug
+   */
+  protected logDebug(message: string, ...params: any[]): void {
+    this.logger?.debug?.(`[${this.constructor.name}] ${message}`, ...params)
+  }
+
+  /**
+   * Método helper para construir URLs de endpoints
+   */
+  protected buildEndpoint(...segments: (string | number)[]): string {
+    const cleanedSegments = segments.map(segment => String(segment).replace(/^\/|\/$/g, ''))
+    return cleanedSegments.join('/') + '/'
+  }
+
+  /**
+   * Método helper para manejar errores HTTP de forma consistente
+   */
+  protected handleHttpError(error: any, operation: string, resourceId?: number | string): never {
+    const context = resourceId ? `${operation} for resource ${resourceId}` : operation
+    this.logError(`HTTP error during ${context}`, error)
+    throw error
+  }
+
+  /**
+   * Log de operación exitosa
+   */
+  protected logSuccess(operation: string, resourceId?: number | string, details?: any): void {
+    const context = resourceId ? `${operation} for resource ${resourceId}` : operation
+    this.logInfo(`✅ ${context} completed successfully`, details)
+  }
+}

package/src/services/core/HttpService.ts

@@ -0,0 +1,115 @@
+/**
+ * Servicio HTTP especializado para operaciones CRUD comunes
+ * Elimina duplicación de código HTTP entre servicios
+ */
+
+import { BaseService } from './BaseService'
+import { BaserowResponse, BaserowNotFoundError } from '../../types/index'
+
+export abstract class HttpService extends BaseService {
+  /**
+   * GET genérico para listar recursos
+   */
+  protected async getList<T>(endpoint: string, params?: Record<string, any>): Promise<T[]> {
+    try {
+      this.logDebug(`Fetching list from ${endpoint}`, params)
+      const response = await this.http.get<BaserowResponse<T>>(endpoint, { params })
+      this.logSuccess(`list operation`, undefined, { count: response.count })
+      return response.results
+    } catch (error) {
+      this.handleHttpError(error, 'list operation')
+    }
+  }
+
+  /**
+   * GET genérico para obtener un recurso por ID
+   */
+  protected async getById<T>(endpoint: string, id: number): Promise<T> {
+    try {
+      this.logDebug(`Fetching resource ${id} from ${endpoint}`)
+      const response = await this.http.get<T>(this.buildEndpoint(endpoint, id))
+      this.logSuccess('get operation', id)
+      return response
+    } catch (error) {
+      if ((error as any).status === 404) {
+        const resourceName = endpoint.split('/').pop() || 'resource'
+        throw new BaserowNotFoundError(resourceName, id)
+      }
+      this.handleHttpError(error, 'get operation', id)
+    }
+  }
+
+  /**
+   * POST genérico para crear recursos
+   */
+  protected async createResource<T, C = any>(endpoint: string, data: C): Promise<T> {
+    try {
+      this.logDebug(`Creating resource at ${endpoint}`, data)
+      const response = await this.http.post<T>(endpoint, data)
+      this.logSuccess('create operation', (response as any).id || 'new')
+      return response
+    } catch (error) {
+      this.handleHttpError(error, 'create operation')
+    }
+  }
+
+  /**
+   * PATCH genérico para actualizar recursos
+   */
+  protected async updateResource<T, U = any>(endpoint: string, id: number, data: U): Promise<T> {
+    try {
+      this.logDebug(`Updating resource ${id} at ${endpoint}`, data)
+      const response = await this.http.patch<T>(this.buildEndpoint(endpoint, id), data)
+      this.logSuccess('update operation', id)
+      return response
+    } catch (error) {
+      if ((error as any).status === 404) {
+        const resourceName = endpoint.split('/').pop() || 'resource'
+        throw new BaserowNotFoundError(resourceName, id)
+      }
+      this.handleHttpError(error, 'update operation', id)
+    }
+  }
+
+  /**
+   * DELETE genérico para eliminar recursos
+   */
+  protected async deleteById(endpoint: string, id: number): Promise<void> {
+    try {
+      this.logDebug(`Deleting resource ${id} from ${endpoint}`)
+      await this.http.delete(this.buildEndpoint(endpoint, id))
+      this.logSuccess('delete operation', id)
+    } catch (error) {
+      if ((error as any).status === 404) {
+        const resourceName = endpoint.split('/').pop() || 'resource'
+        throw new BaserowNotFoundError(resourceName, id)
+      }
+      this.handleHttpError(error, 'delete operation', id)
+    }
+  }
+
+  /**
+   * Método helper para buscar recursos por nombre
+   */
+  protected async findResourceByName<T extends { id: number; name: string }>(
+    endpoint: string,
+    name: string,
+    listParams?: Record<string, any>
+  ): Promise<T | null> {
+    try {
+      this.logDebug(`Searching for resource with name "${name}" in ${endpoint}`)
+      const items = await this.getList<T>(endpoint, listParams)
+      const found = items.find(item => item.name === name) || null
+
+      if (found) {
+        this.logSuccess(`find by name "${name}"`, found.id)
+      } else {
+        this.logDebug(`No resource found with name "${name}"`)
+      }
+
+      return found
+    } catch (error) {
+      this.handleHttpError(error, `find by name "${name}"`)
+    }
+  }
+}

package/src/services/core/ValidationService.ts

@@ -0,0 +1,149 @@
+/**
+ * Servicio de validación centralizado
+ * Elimina duplicación de validaciones entre servicios
+ */
+
+import { BaseService } from './BaseService'
+import { BaserowConfigError, BaserowValidationError } from '../../types/index'
+import { validateRequired, validatePositiveNumber, validateString, validateUrl } from '../../utils/validation'
+
+export class ValidationService extends BaseService {
+  /**
+   * Valida configuración básica de Baserow
+   */
+  validateBaserowConfig(url: string, token?: string): void {
+    try {
+      validateRequired(url, 'url')
+      validateUrl(url, 'url')
+
+      if (token) {
+        validateRequired(token, 'token')
+        validateString(token, 'token')
+      }
+    } catch (error) {
+      throw new BaserowConfigError(`Invalid configuration: ${(error as Error).message}`)
+    }
+  }
+
+  /**
+   * Valida credenciales de usuario
+   */
+  validateCredentials(email: string, password: string): void {
+    try {
+      validateRequired(email, 'email')
+      validateString(email, 'email')
+      validateRequired(password, 'password')
+      validateString(password, 'password')
+
+      // Validación básica de email
+      if (!email.includes('@')) {
+        throw new Error('Invalid email format')
+      }
+    } catch (error) {
+      throw new BaserowValidationError(`Invalid credentials: ${(error as Error).message}`, {
+        email: email ? [] : ['Email is required'],
+        password: password ? [] : ['Password is required']
+      })
+    }
+  }
+
+  /**
+   * Valida IDs numéricos
+   */
+  validateId(id: number, fieldName: string): void {
+    try {
+      validateRequired(id, fieldName)
+      validatePositiveNumber(id, fieldName)
+    } catch (error) {
+      throw new BaserowValidationError(`Invalid ${fieldName}: ${(error as Error).message}`, {
+        [fieldName]: [(error as Error).message]
+      })
+    }
+  }
+
+  /**
+   * Valida nombres de recursos
+   */
+  validateResourceName(name: string, resourceType: string): void {
+    try {
+      validateRequired(name, 'name')
+      validateString(name, 'name')
+
+      if (name.trim() !== name) {
+        throw new Error('Name cannot start or end with whitespace')
+      }
+
+      if (name.length > 255) {
+        throw new Error('Name cannot exceed 255 characters')
+      }
+    } catch (error) {
+      throw new BaserowValidationError(`Invalid ${resourceType} name: ${(error as Error).message}`, {
+        name: [(error as Error).message]
+      })
+    }
+  }
+
+  /**
+   * Valida datos de tabla de creación
+   */
+  validateTableData(data: Array<Array<string>>): void {
+    if (!Array.isArray(data)) {
+      throw new BaserowValidationError('Table data must be an array', {
+        data: ['Must be an array of arrays']
+      })
+    }
+
+    if (data.length === 0) {
+      throw new BaserowValidationError('Table data cannot be empty', {
+        data: ['At least one row is required']
+      })
+    }
+
+    const firstRowLength = data[0]?.length || 0
+    if (firstRowLength === 0) {
+      throw new BaserowValidationError('First row cannot be empty', {
+        data: ['First row must have at least one column']
+      })
+    }
+
+    // Verificar que todas las filas tengan la misma longitud
+    for (let i = 0; i < data.length; i++) {
+      if (!Array.isArray(data[i])) {
+        throw new BaserowValidationError(`Row ${i} must be an array`, {
+          data: [`Row ${i} is not an array`]
+        })
+      }
+
+      if (data[i].length !== firstRowLength) {
+        throw new BaserowValidationError(`All rows must have the same number of columns`, {
+          data: [`Row ${i} has ${data[i].length} columns, expected ${firstRowLength}`]
+        })
+      }
+    }
+  }
+
+  /**
+   * Combina múltiples validaciones en una sola llamada
+   */
+  validateMultiple(validations: Array<() => void>): void {
+    const errors: string[] = []
+
+    for (const validation of validations) {
+      try {
+        validation()
+      } catch (error) {
+        if (error instanceof BaserowValidationError) {
+          errors.push(error.message)
+        } else {
+          errors.push((error as Error).message || 'Unknown validation error')
+        }
+      }
+    }
+
+    if (errors.length > 0) {
+      throw new BaserowValidationError(`Multiple validation errors: ${errors.join(', ')}`, {
+        multiple: errors
+      })
+    }
+  }
+}