@gzl10/baserow 1.2.0

package/src/types/schema.ts

@@ -0,0 +1,446 @@
+import type { Table } from './core'
+
+/**
+ * Tipos TypeScript para el sistema de definición declarativa de schemas
+ *
+ * Permite definir esquemas de base de datos completos usando un formato
+ * JSON/TypeScript que luego puede ser aplicado usando database().loadSchema()
+ *
+ * @example
+ * ```typescript
+ * const ecommerceSchema: DatabaseSchema = {
+ *   version: "1.0.0",
+ *   tables: [
+ *     {
+ *       name: "clientes",
+ *       fields: [
+ *         { name: "nombre", type: "text" },
+ *         { name: "email", type: "email" },
+ *         {
+ *           name: "categoria",
+ *           type: "single_select",
+ *           config: {
+ *             options: [
+ *               { value: "Premium", color: "blue" }
+ *             ]
+ *           }
+ *         }
+ *       ]
+ *     }
+ *   ],
+ *   relationships: [
+ *     {
+ *       name: "cliente",
+ *       sourceTable: "pedidos",
+ *       targetTable: "clientes"
+ *     }
+ *   ]
+ * }
+ * ```
+ *
+ */
+
+/**
+ * Schema completo de una base de datos
+ */
+export interface DatabaseSchema {
+  /** Versión del schema para control de cambios */
+  version?: string
+  /** Descripción del propósito de la base de datos */
+  description?: string
+  /** Definición de todas las tablas */
+  tables: TableSchema[]
+  /** Relaciones entre tablas (se crean después de las tablas) */
+  relationships?: RelationshipSchema[]
+}
+
+/**
+ * Schema de una tabla individual
+ */
+export interface TableSchema {
+  /** Nombre de la tabla */
+  name: string
+  /** Descripción opcional de la tabla */
+  description?: string
+  /** Definición de todos los campos de la tabla */
+  fields: FieldSchema[]
+}
+
+/**
+ * Schema de un campo individual
+ */
+export interface FieldSchema {
+  /** Nombre del campo */
+  name: string
+  /** Tipo de campo de Baserow */
+  type: FieldType
+  /** Descripción opcional del campo */
+  description?: string
+  /** Configuración específica según el tipo de campo */
+  config?: FieldConfig
+}
+
+/**
+ * Schema de una relación entre tablas
+ */
+export interface RelationshipSchema {
+  /** Nombre del campo de relación */
+  name: string
+  /** Tabla que contiene la relación (tabla origen) */
+  sourceTable: string
+  /** Tabla objetivo de la relación */
+  targetTable: string
+  /** Descripción opcional de la relación */
+  description?: string
+}
+
+/**
+ * Tipos de campos soportados por Baserow
+ */
+export type FieldType =
+  // Campos de texto
+  | 'text'
+  | 'long_text'
+  | 'url'
+  | 'email'
+  | 'phone_number'
+
+  // Campos numéricos
+  | 'number'
+  | 'rating'
+
+  // Campos de fecha
+  | 'date'
+  | 'last_modified'
+  | 'created_on'
+  | 'last_modified_by'
+  | 'created_by'
+
+  // Campos de selección
+  | 'single_select'
+  | 'multiple_select'
+
+  // Campos booleanos
+  | 'boolean'
+
+  // Campos de relación
+  | 'link_row'
+  | 'formula'
+
+  // Campos avanzados
+  | 'file'
+  | 'autonumber'
+  | 'count'
+  | 'rollup'
+  | 'lookup'
+
+/**
+ * Configuración específica por tipo de campo
+ */
+export type FieldConfig =
+  | TextFieldConfig
+  | NumberFieldConfig
+  | DateFieldConfig
+  | SelectFieldConfig
+  | MultiSelectFieldConfig
+  | BooleanFieldConfig
+  | LinkRowFieldConfig
+  | FormulaFieldConfig
+  | FileFieldConfig
+  | CountFieldConfig
+  | RollupFieldConfig
+  | LookupFieldConfig
+
+/**
+ * Configuración para campos de texto
+ */
+export interface TextFieldConfig {
+  /** Valor por defecto */
+  default?: string
+  /** Texto de placeholder */
+  placeholder?: string
+}
+
+/**
+ * Configuración para campos numéricos
+ */
+export interface NumberFieldConfig {
+  /** Número de decimales (0 para enteros) */
+  decimals?: number
+  /** Valor mínimo permitido */
+  min?: number
+  /** Valor máximo permitido */
+  max?: number
+  /** Valor por defecto */
+  default?: number
+  /** Prefijo (ej: "$") */
+  prefix?: string
+  /** Sufijo (ej: " €") */
+  suffix?: string
+  /** Formato de separadores */
+  separators?: 'COMMA_PERIOD' | 'PERIOD_COMMA'
+}
+
+/**
+ * Configuración para campos de fecha
+ */
+export interface DateFieldConfig {
+  /** Incluir tiempo además de fecha */
+  includeTime?: boolean
+  /** Formato de fecha */
+  format?: 'ISO' | 'US' | 'EU'
+  /** Formato de hora */
+  timeFormat?: '24' | '12'
+  /** Valor por defecto */
+  default?: string
+  /** Zona horaria */
+  timezone?: string
+}
+
+/**
+ * Configuración para campos single_select
+ */
+export interface SelectFieldConfig {
+  /** Opciones disponibles */
+  options: SelectOption[]
+}
+
+/**
+ * Configuración para campos multiple_select
+ */
+export interface MultiSelectFieldConfig {
+  /** Opciones disponibles */
+  options: SelectOption[]
+}
+
+/**
+ * Opción para campos de selección
+ */
+export interface SelectOption {
+  /** Valor de la opción */
+  value: string
+  /** Color de la opción */
+  color: SelectOptionColor
+}
+
+/**
+ * Colores disponibles para opciones de select
+ */
+export type SelectOptionColor =
+  | 'blue'
+  | 'green'
+  | 'red'
+  | 'yellow'
+  | 'orange'
+  | 'purple'
+  | 'pink'
+  | 'brown'
+  | 'gray'
+  | 'dark_blue'
+  | 'dark_green'
+  | 'dark_red'
+  | 'dark_yellow'
+  | 'dark_orange'
+  | 'dark_purple'
+  | 'dark_pink'
+  | 'dark_brown'
+  | 'dark_gray'
+
+/**
+ * Configuración para campos boolean
+ */
+export interface BooleanFieldConfig {
+  /** Valor por defecto */
+  default?: boolean
+}
+
+/**
+ * Configuración para campos link_row (relaciones)
+ */
+export interface LinkRowFieldConfig {
+  /** ID de la tabla objetivo */
+  targetTableId?: number
+  /** Nombre de la tabla objetivo (se resuelve en runtime) */
+  targetTableName?: string
+}
+
+/**
+ * Configuración para campos de fórmula
+ */
+export interface FormulaFieldConfig {
+  /** Fórmula a ejecutar */
+  formula: string
+}
+
+/**
+ * Configuración para campos de archivo
+ */
+export interface FileFieldConfig {
+  /** Tipos de archivo permitidos */
+  allowedFileTypes?: string[]
+  /** Tamaño máximo en bytes */
+  maxFileSize?: number
+}
+
+/**
+ * Configuración para campos count
+ */
+export interface CountFieldConfig {
+  /** ID de la tabla a contar */
+  targetTableId?: number
+  /** Nombre de la tabla a contar (se resuelve en runtime) */
+  targetTableName?: string
+}
+
+/**
+ * Configuración para campos rollup
+ */
+export interface RollupFieldConfig {
+  /** ID de la tabla objetivo */
+  targetTableId?: number
+  /** Nombre de la tabla objetivo */
+  targetTableName?: string
+  /** ID del campo objetivo */
+  targetFieldId?: number
+  /** Nombre del campo objetivo */
+  targetFieldName?: string
+  /** Función de agregación */
+  aggregation: 'sum' | 'avg' | 'min' | 'max' | 'count'
+}
+
+/**
+ * Configuración para campos lookup
+ */
+export interface LookupFieldConfig {
+  /** ID de la tabla objetivo */
+  targetTableId?: number
+  /** Nombre de la tabla objetivo */
+  targetTableName?: string
+  /** ID del campo objetivo */
+  targetFieldId?: number
+  /** Nombre del campo objetivo */
+  targetFieldName?: string
+}
+
+/**
+ * Opciones para cargar un schema
+ */
+export interface LoadSchemaOptions {
+  /** Modo de carga */
+  mode?: LoadSchemaMode
+  /** Versión del schema (para tracking) */
+  version?: string
+  /** Forzar carga aunque no haya cambios */
+  force?: boolean
+  /** Limpiar tablas que no estén en el schema */
+  cleanup?: boolean
+}
+
+/**
+ * Modos de carga de schema
+ */
+export type LoadSchemaMode =
+  /** Solo crear, no actualizar existentes */
+  | 'create-only'
+  /** Crear y actualizar campos existentes */
+  | 'update'
+  /** Recrear todo desde cero */
+  | 'recreate'
+
+/**
+ * Resultado de cargar un schema
+ */
+export interface LoadSchemaResult {
+  /** Tablas creadas/actualizadas */
+  tables: Table[]
+  /** Tablas indexadas por nombre para fácil acceso */
+  tablesByName: Record<string, Table>
+  /** Información de control del schema */
+  schemaControl: SchemaControl
+  /** Lista de cambios aplicados */
+  changes: SchemaChange[]
+  /** Estadísticas de la operación */
+  stats: LoadSchemaStats
+}
+
+/**
+ * Información de control del schema cargado
+ */
+export interface SchemaControl {
+  /** ID único del control */
+  id: string
+  /** Versión del schema */
+  version: string
+  /** Hash del schema para detectar cambios */
+  schemaHash: string
+  /** Fecha de carga */
+  loadedAt: Date
+  /** Nombres de tablas creadas por este schema */
+  tablesCreated: string[]
+  /** Estado del schema */
+  status: SchemaControlStatus
+  /** Opciones usadas para la carga */
+  loadOptions: LoadSchemaOptions
+}
+
+/**
+ * Estados del control de schema
+ */
+export type SchemaControlStatus =
+  /** Schema activo y actualizado */
+  | 'active'
+  /** Schema desactualizado */
+  | 'outdated'
+  /** Error en la carga */
+  | 'error'
+  /** Carga en progreso */
+  | 'loading'
+
+/**
+ * Tipos de cambios aplicados durante la carga
+ */
+export interface SchemaChange {
+  /** Tipo de cambio */
+  type: SchemaChangeType
+  /** Elemento afectado */
+  target: string
+  /** Descripción del cambio */
+  description: string
+  /** Detalles adicionales */
+  details?: any
+}
+
+/**
+ * Tipos de cambios de schema
+ */
+export type SchemaChangeType =
+  | 'table_created'
+  | 'table_updated'
+  | 'table_deleted'
+  | 'field_created'
+  | 'field_updated'
+  | 'field_deleted'
+  | 'relationship_created'
+  | 'relationship_updated'
+  | 'relationship_deleted'
+
+/**
+ * Estadísticas de la operación de carga
+ */
+export interface LoadSchemaStats {
+  /** Tiempo total de ejecución en ms */
+  duration: number
+  /** Número de tablas procesadas */
+  tablesProcessed: number
+  /** Número de campos procesados */
+  fieldsProcessed: number
+  /** Número de relaciones procesadas */
+  relationshipsProcessed: number
+  /** Número de errores encontrados */
+  errors: number
+  /** Número de warnings */
+  warnings: number
+}
+
+// Re-export tipos necesarios de otros archivos
+export type { Table, Field, Row } from './index'

package/src/types/tokens.ts

@@ -0,0 +1,36 @@
+/**
+ * Tipos relacionados con Database Tokens de Baserow
+ */
+
+/**
+ * Prefijo único para identificar tokens creados por la librería
+ * vs tokens creados manualmente por usuarios
+ */
+export const LIBRARY_TOKEN_PREFIX = 'br-lib:'
+
+export interface DatabaseTokenPermissions {
+  create: boolean
+  read: boolean
+  update: boolean
+  delete: boolean
+}
+
+export interface DatabaseToken {
+  id: number
+  name: string
+  token: string
+  workspace: number
+  permissions: DatabaseTokenPermissions
+  created_on: string
+}
+
+export interface CreateDatabaseTokenRequest {
+  name: string
+  permissions: DatabaseTokenPermissions
+}
+
+export interface UpdateDatabaseTokenRequest {
+  name?: string
+  permissions?: DatabaseTokenPermissions
+  rotate_token?: boolean
+}

package/src/types.ts

@@ -0,0 +1,11 @@
+/**
+ * Tipos TypeScript para Baserow API
+ *
+ * DEPRECATED: Este archivo mantiene compatibilidad hacia atrás.
+ * Usa imports específicos desde src/types/ para mejor tree-shaking.
+ *
+ * @deprecated Use imports from './types/index.js' instead
+ */
+
+// Re-export todo desde el nuevo index modular
+export * from './types/index'

package/src/utils/auth.ts

@@ -0,0 +1,174 @@
+import { HttpClient } from './axios'
+import { BaserowCredentials, BaserowError, LoginResponse, Logger } from '../types'
+import { validateRequired, validateString, validateUrl } from './validation'
+
+/**
+ * Opciones para la verificación de login
+ */
+export interface VerifyLoginOptions {
+  /** Timeout en milisegundos (default: 10000) */
+  timeout?: number
+  /** Logger para debug (opcional) */
+  logger?: Logger
+}
+
+/**
+ * Verificar si las credenciales de Baserow son válidas sin crear cliente
+ *
+ * Esta función es útil para:
+ * - Validar credenciales en formularios de login
+ * - Health checks de credenciales
+ * - Verificación de configuración antes de inicializar la aplicación
+ *
+ * @param url URL base de Baserow (ej: 'https://baserow.gzl10.com')
+ * @param credentials Credenciales de usuario (email y password)
+ * @param options Opciones adicionales (timeout, logger)
+ * @returns Promise<boolean> - true si las credenciales son válidas
+ *
+ * @example
+ * ```typescript
+ * import { verifyLogin } from '@gzl10/baserow'
+ *
+ * const isValid = await verifyLogin('https://baserow.gzl10.com', {
+ *   email: 'user@example.com',
+ *   password: 'password123'
+ * })
+ *
+ * if (isValid) {
+ *   // Proceder a crear BaserowAdmin
+ *   const admin = await BaserowAdmin.create({ ... })
+ * } else {
+ *   // Mostrar error en UI
+ *   console.error('Credenciales inválidas')
+ * }
+ * ```
+ */
+export async function verifyLogin(
+  url: string,
+  credentials: BaserowCredentials,
+  options: VerifyLoginOptions = {}
+): Promise<boolean> {
+  // Validación de parámetros
+  validateRequired(url, 'url')
+  validateRequired(credentials, 'credentials')
+  validateString(credentials.email, 'email')
+  validateString(credentials.password, 'password')
+
+  if (!validateUrl(url)) {
+    throw new Error('url must be a valid URL')
+  }
+
+  const { timeout = 10000, logger } = options
+
+  // Crear HttpClient temporal (sin almacenar estado)
+  let tempHttp: HttpClient | undefined
+
+  try {
+    tempHttp = new HttpClient({
+      baseURL: `${url.replace(/\/$/, '')}/api`,
+      token: '', // Sin token inicial
+      timeout,
+      logger
+    })
+
+    logger?.info?.('BaserowAuth: Verifying credentials...')
+
+    // Intentar login con las credenciales proporcionadas
+    const loginData = {
+      username: credentials.email,
+      password: credentials.password
+    }
+
+    const response = await tempHttp.post<LoginResponse>('/user/token-auth/', loginData)
+
+    // Si llegamos aquí, el login fue exitoso
+    logger?.info?.(`BaserowAuth: Credentials valid for user ${response.user.username}`)
+    return true
+  } catch (error) {
+    // Manejar diferentes tipos de errores
+    if (error instanceof BaserowError) {
+      switch (error.status) {
+        case 401:
+          // Credenciales inválidas
+          logger?.warn?.('BaserowAuth: Invalid credentials provided')
+          return false
+
+        case 400:
+          // Bad request (formato incorrecto)
+          logger?.warn?.('BaserowAuth: Bad request - invalid data format')
+          return false
+
+        case 403:
+          // Usuario bloqueado o sin permisos
+          logger?.warn?.('BaserowAuth: User forbidden or blocked')
+          return false
+
+        case 429:
+          // Rate limit - técnicamente las credenciales podrían ser válidas
+          logger?.warn?.('BaserowAuth: Rate limited - cannot verify at this time')
+          return false
+
+        case 500:
+        case 502:
+        case 503:
+        case 504:
+          // Errores del servidor
+          logger?.error?.('BaserowAuth: Server error during login verification')
+          return false
+
+        default:
+          // Otros errores HTTP
+          logger?.error?.(`BaserowAuth: HTTP error ${error.status}: ${error.message}`)
+          return false
+      }
+    }
+
+    // Errores de red, timeout, etc.
+    logger?.error?.('BaserowAuth: Network or connection error:', error)
+    return false
+  } finally {
+    // Limpieza: el HttpClient temporal se garbage-collectea automáticamente
+    // No necesitamos limpiar tokens porque no los almacenamos
+    tempHttp = undefined
+  }
+}
+
+/**
+ * Verificar si una URL de Baserow es accesible (health check básico)
+ *
+ * @param url URL base de Baserow
+ * @param options Opciones de verificación
+ * @returns Promise<boolean> - true si el servidor es accesible
+ */
+export async function verifyBaserowHealth(
+  url: string,
+  options: Pick<VerifyLoginOptions, 'timeout' | 'logger'> = {}
+): Promise<boolean> {
+  validateRequired(url, 'url')
+
+  if (!validateUrl(url)) {
+    throw new Error('url must be a valid URL')
+  }
+
+  const { timeout = 5000, logger } = options
+
+  try {
+    logger?.info?.('BaserowAuth: Checking Baserow health...')
+
+    // Usar endpoint público de health que no requiere autenticación
+    const healthUrl = `${url.replace(/\/$/, '')}/api/_health/`
+    const response = await fetch(healthUrl, {
+      method: 'GET',
+      headers: { 'Content-Type': 'application/json' },
+      signal: AbortSignal.timeout(timeout)
+    })
+
+    const isHealthy = response.ok
+    logger?.info?.(`BaserowAuth: Baserow health check ${isHealthy ? 'passed' : 'failed'}`)
+
+    return isHealthy
+  } catch (error) {
+    logger?.error?.('BaserowAuth: Health check failed:', error)
+    return false
+  }
+}