@gzl10/baserow 1.2.0

package/README.md

@@ -0,0 +1,847 @@
+# @gzl10/baserow
+
+Cliente TypeScript moderno para Baserow API v1.35+ (2025) con **arquitectura de tres clientes**, **PrismaBaserowMapper**, **21/22 tipos de campos** y **gestión automática de JWT con refresh tokens**.
+
+## ✨ Características Principales
+
+- 🎯 **Arquitectura de 3 Clientes**: Token, Admin Global y Admin Workspace
+- 🔐 **Auto-Refresh JWT**: Gestión automática de access y refresh tokens con renovación inteligente
+- 🗺️ **PrismaBaserowMapper**: Sintaxis familiar estilo Prisma para consultas (35+ tests)
+- 📋 **21/22 Tipos de Campos**: Cobertura completa incluyendo file, autonumber, count, rollup, lookup
+- 🚀 **HTTP Optimizado**: axios-retry + axios-rate-limit oficiales (36% menos código)
+- 🔄 **API Jerárquica**: Navegación intuitiva workspace → database → table → fields/rows
+- ⚡ **Operaciones Bulk**: Procesamiento batch optimizado con retry logic
+- 🧪 **Testing Robusto**: 60+ tests (35+ integración + 34 error handling), 42% cobertura error handling
+
+## 📚 Documentación
+
+Esta es una guía de inicio rápido. **[Ver índice completo de documentación →](docs/README.md)**
+
+### 📖 Guías de Usuario
+
+- **[Filtros y Ordenaciones](docs/FILTERS_AND_SORTING.md)** - Guía completa de búsquedas, filtros y ordenaciones
+- **[API Reference](docs/BASEROW_API_REFERENCE.md)** - Referencia completa de la API
+- **[Keep-Alive](docs/KEEP_ALIVE.md)** - Configuración de keep-alive para backends 24/7
+- **[Migración](docs/MIGRATION.md)** - Guía de migración desde versiones anteriores
+
+### 🔧 Documentación Técnica
+
+- **[Testing](docs/TESTING.md)** - Guía de tests y cobertura
+- **[Debugging](docs/DEBUGGING.md)** - Solución de problemas comunes
+- **[Roadmap](docs/ROADMAP.md)** - Plan de evolución de la librería
+
+### 📊 Análisis y Referencia
+
+- **[Baserow 1.35.3 Impact](docs/BASEROW_1.35.3_IMPACT_ANALYSIS.md)** - Análisis de compatibilidad con Baserow 1.35.3
+- **[Endpoint Validation](docs/ENDPOINT_VALIDATION_RESULTS.md)** - Validación de endpoints de API
+
+---
+
+## 🎯 Arquitectura
+
+### Cliente Principal Unificado
+
+```typescript
+import { BaserowClient } from '@gzl10/baserow'
+
+// 1. Cliente con Database Token (solo lectura de datos)
+const client = await BaserowClient.create({
+  url: 'https://baserow.example.com',
+  token: 'db_token_123'
+})
+
+// 2. Cliente Admin Global (acceso multi-workspace)
+const adminGlobal = await BaserowClient.create({
+  url: 'https://baserow.example.com',
+  credentials: { email: 'admin@example.com', password: 'password' }
+})
+
+// 3. Cliente Admin Workspace (scope específico)
+const adminWorkspace = await BaserowClient.create({
+  url: 'https://baserow.example.com',
+  credentials: { email: 'admin@example.com', password: 'password' },
+  workspace: 'Mi Workspace'
+})
+```
+
+### Tres Arquitecturas Especializadas
+
+| Cliente            | Autenticación       | Capacidades                                       | Casos de Uso                                      |
+| ------------------ | ------------------- | ------------------------------------------------- | ------------------------------------------------- |
+| **BaserowClient**  | Database Token      | CRUD de datos, operaciones bulk                   | Apps cliente, integración de datos, APIs públicas |
+| **AdminGlobal**    | JWT Multi-workspace | Gestión completa de workspaces, databases, tables | Scripts administrativos, herramientas DevOps      |
+| **AdminWorkspace** | JWT Scope limitado  | Operaciones dentro de un workspace específico     | Apps empresariales, dashboards especializados     |
+
+## 🚀 Instalación
+
+```bash
+pnpm install @gzl10/baserow
+```
+
+## 🔍 PrismaBaserowMapper - Sintaxis Familiar
+
+Sintaxis estilo Prisma.js para consultas Baserow con **35+ tests** de validación:
+
+```typescript
+import { BaserowClient } from '@gzl10/baserow'
+
+const client = await BaserowClient.create({ url, token })
+
+// Sintaxis Prisma familiar
+const employees = await client
+  .database(123)
+  .table(456)
+  .rows.findMany({
+    where: {
+      AND: [{ status: 'active' }, { age: { gte: 18, lt: 65 } }, { email: { contains: '@company.com' } }]
+    },
+    orderBy: [{ created_at: 'desc' }, { name: 'asc' }],
+    take: 20,
+    skip: 40,
+    select: { id: true, name: true, email: true }
+  })
+```
+
+**Operadores soportados:**
+
+- **Comparación**: `equals`, `not`, `contains`, `startsWith`, `endsWith`, `gt`, `gte`, `lt`, `lte`
+- **Lógicos**: `AND`, `OR` (flat), `NOT`
+- **Estado**: `isEmpty`, `isNotEmpty`
+- **Fechas**: Conversión automática a ISO strings
+
+**📖 Ver guía completa:** [Filtros y Ordenaciones](docs/FILTERS_AND_SORTING.md)
+
+## 📖 Uso Básico
+
+### Tipos de Configuración (Aliases DX-friendly)
+
+Para facilitar el desarrollo, la librería exporta aliases descriptivos:
+
+```typescript
+// Tipos de configuración (aliases cortos)
+import type { TokenConfig, CredentialsConfig, CredentialsWorkspaceConfig } from '@gzl10/baserow'
+
+// Clases de cliente (para tipado avanzado)
+import type { ClientWithToken, ClientWithCreds, ClientWithCredsWs } from '@gzl10/baserow'
+
+// Equivalencias:
+// - TokenConfig = BaserowTokenConfig
+// - CredentialsConfig = BaserowCredentialsConfig
+// - CredentialsWorkspaceConfig = BaserowCredentialsWorkspaceConfig
+```
+
+### 1. Cliente con Database Token (Solo datos)
+
+```typescript
+import { BaserowClient } from '@gzl10/baserow'
+import type { TokenConfig } from '@gzl10/baserow'
+
+const config: TokenConfig = {
+  url: 'https://baserow.example.com',
+  token: 'your_database_token'
+}
+
+const client = await BaserowClient.create(config)
+
+// API jerárquica simple
+const rows = await client.database(123).table(456).rows.list()
+const newRow = await client.database(123).table(456).rows.create({
+  name: 'John Doe',
+  email: 'john@example.com'
+})
+
+// Operaciones bulk optimizadas
+const bulkRows = await client
+  .database(123)
+  .table(456)
+  .rows.createBulk(
+    [
+      { name: 'Alice', email: 'alice@example.com' },
+      { name: 'Bob', email: 'bob@example.com' }
+    ],
+    { batchSize: 100 }
+  )
+```
+
+### 2. Cliente Admin Global (Multi-workspace)
+
+```typescript
+import type { CredentialsConfig } from '@gzl10/baserow'
+
+const config: CredentialsConfig = {
+  url: 'https://baserow.example.com',
+  credentials: {
+    email: 'admin@example.com',
+    password: 'your_password'
+  }
+}
+
+const admin = await BaserowClient.create(config)
+
+// Gestión completa de workspaces
+const workspaces = await admin.workspaces.list()
+const newWS = await admin.workspaces.create({ name: 'Nueva Empresa' })
+const updatedWS = await admin.workspace('Company').update({ name: 'New Company' })
+await admin.workspace('Old Company').delete()
+
+// Creación jerárquica de recursos
+const database = await admin.workspace('Company').databases.create('CRM')
+const table = await admin
+  .workspace('Company')
+  .database('CRM')
+  .tables.create({
+    name: 'Customers',
+    data: [
+      ['Name', 'Email'],
+      ['Alice', 'alice@example.com']
+    ],
+    first_row_header: true
+  })
+```
+
+### 3. Cliente Admin Workspace (Scope limitado)
+
+```typescript
+import type { CredentialsWorkspaceConfig } from '@gzl10/baserow'
+
+const config: CredentialsWorkspaceConfig = {
+  url: 'https://baserow.example.com',
+  credentials: {
+    email: 'admin@example.com',
+    password: 'your_password'
+  },
+  workspace: 'Company'
+}
+
+const adminWS = await BaserowClient.create(config)
+
+// API simplificada sin prefijo workspace
+const databases = await adminWS.databases.list()
+const table = await adminWS.database('CRM').tables.create({ name: 'Products' })
+```
+
+## 📋 Cobertura Completa de Campos (21/22 tipos)
+
+La librería soporta **prácticamente todos los tipos de campos** de Baserow v1.35+ incluyendo los nuevos campos avanzados:
+
+### ✅ Campos Implementados por Categoría
+
+#### Texto y Comunicación (5 tipos)
+
+```typescript
+const nameField = await table.field.createText('full_name')
+const descField = await table.field.createLongText('description')
+const websiteField = await table.field.createUrl('website')
+const emailField = await table.field.createEmail('contact_email')
+const phoneField = await table.field.createPhoneNumber('phone')
+```
+
+#### Numéricos y Lógicos (3 tipos)
+
+```typescript
+const priceField = await table.field.createNumber('price', 2) // 2 decimales
+const activeField = await table.field.createBoolean('is_active')
+const ratingField = await table.field.createRating('rating', 5) // máx 5 estrellas
+```
+
+#### Fecha y Auditoría (5 tipos)
+
+```typescript
+const birthdateField = await table.field.createDate('birthdate')
+const lastModField = await table.field.createLastModified('updated_at')
+const lastUserField = await table.field.createLastModifiedBy('updated_by')
+const createdField = await table.field.createCreatedOn('created_at')
+const creatorField = await table.field.createCreatedBy('created_by')
+```
+
+#### Selección y Opciones (2 tipos)
+
+```typescript
+const statusField = await table.field.createSingleSelect('status', [
+  { value: 'active', color: 'green' },
+  { value: 'inactive', color: 'red' }
+])
+const tagsField = await table.field.createMultipleSelect('tags', [
+  { value: 'urgent', color: 'red' },
+  { value: 'important', color: 'orange' }
+])
+```
+
+#### Relacionales (2 tipos)
+
+```typescript
+const linkField = await table.field.createLinkRow('related_items', targetTableId)
+const formulaField = await table.field.createFormula('total_price', 'field("quantity") * field("price")')
+```
+
+#### 🆕 Campos Avanzados (5 tipos) - ¡Nuevos en v1.1.0+!
+
+```typescript
+// Archivos adjuntos
+const docsField = await table.field.createFile('documents')
+
+// Numeración automática
+const ticketField = await table.field.createAutonumber('ticket_id')
+
+// Conteo de relaciones
+const itemsCountField = await table.field.createCount('items_count', targetTableId)
+
+// Agregación desde tabla relacionada
+const totalField = await table.field.createRollup('total_amount', tableId, fieldId, 'sum')
+
+// Búsqueda desde tabla relacionada
+const namesField = await table.field.createLookup('item_names', tableId, fieldId)
+```
+
+### API Fluida Consistente
+
+Todos los tipos de campos siguen el mismo patrón de API para máxima consistencia:
+
+```typescript
+// Patrón: table.field.create[TipoCampo](nombre, ...parametrosEspecificos)
+const field = await table.field.createText('campo_nombre')
+
+// Operaciones CRUD disponibles para todos los tipos
+const updatedField = await table.field.update(fieldId, { name: 'nuevo_nombre' })
+await table.field.delete(fieldId)
+const allFields = await table.field.list()
+```
+
+## 🔧 Utilidades Express (Opcionales)
+
+La librería incluye utilidades opcionales para integración con Express **sin crear dependencias**.
+
+### Configuración Básica
+
+```typescript
+import express from 'express'
+import { BaserowClient, express as baserowExpress } from '@gzl10/baserow'
+
+const app = express()
+const client = await BaserowClient.create({ url, token })
+
+// Middlewares
+app.use('/api', baserowExpress.baserowContext(client))
+app.use('/api', baserowExpress.requireAuth())
+
+// Routes con cliente automático
+app.get('/api/tables/:tableId/rows', async (req, res, next) => {
+  try {
+    const rows = await req.baserow!.database(123).table(parseInt(req.params.tableId)).rows.list()
+    res.json(baserowExpress.serializePaginated(rows))
+  } catch (error) {
+    next(error)
+  }
+})
+
+// Error handler
+app.use(baserowExpress.errorHandler())
+```
+
+### Middlewares Disponibles
+
+```typescript
+// Auto-crear cliente por request
+app.use(
+  '/api',
+  baserowExpress.baserowAuth({
+    url: process.env.BASEROW_URL!,
+    token: process.env.BASEROW_TOKEN!
+  })
+)
+
+// Validar autenticación
+app.use('/api', baserowExpress.requireAuth())
+
+// Cleanup automático de recursos
+app.use('/api', baserowExpress.baserowCleanup())
+```
+
+### Serializadores
+
+```typescript
+// Paginated responses
+const paginatedRows = baserowExpress.serializePaginated(result)
+
+// Response con metadatos
+const rowsWithMeta = baserowExpress.serializeRowsWithMeta(rows, table, fields)
+
+// Clean entities
+const cleanTable = baserowExpress.serializeTable(table, true)
+```
+
+### Error Handling
+
+```typescript
+// Error handler con logging
+app.use(
+  baserowExpress.errorHandler({
+    includeStack: process.env.NODE_ENV === 'development',
+    logger: console
+  })
+)
+
+// Handler simplificado
+app.use(baserowExpress.simpleErrorHandler())
+```
+
+## ⚡ Características Técnicas
+
+- ✅ **TypeScript**: Tipado fuerte con inferencia automática de tipos
+- ✅ **ESM Moderno**: Compilación optimizada con tsup (5-10x más rápido que tsc)
+- ✅ **HTTP Simplificado**: 36% menos código usando axios-retry + axios-rate-limit oficiales
+- ✅ **Connection Pooling**: Node.js 20+ keepAlive nativo (eliminado agentkeepalive)
+- ✅ **PrismaMapper**: Sintaxis familiar Prisma con 35+ tests de transformaciones
+- ✅ **21/22 Campos**: Cobertura prácticamente completa incluyendo campos avanzados
+- ✅ **API Jerárquica**: workspace → database → table → fields/rows navegación intuitiva
+- ✅ **Retry Logic**: Manejo robusto de rate limiting y timeouts configurable
+- ✅ **Error Handling**: Errores tipados (BaserowError, ValidationError, etc.) + 34 tests de validación (v1.0.2)
+- ✅ **Express Ready**: Utilidades opcionales sin dependencias obligatorias
+- ✅ **Testing Robusto**: 60+ tests (35+ integración + 34 error handling), 42% cobertura
+
+## 🔧 Configuración Avanzada
+
+### 🔐 Autenticación y Refresh Tokens
+
+La librería gestiona automáticamente **JWT access tokens** y **refresh tokens** con renovación automática:
+
+#### Persistencia de Tokens (Por Instancia)
+
+```typescript
+const adminClient = await BaserowClient.create({
+  url: 'https://baserow.example.com',
+  credentials: { email: 'admin@example.com', password: 'password' }
+})
+
+// ✅ Tokens almacenados en memoria de la instancia
+// ✅ TTL leído automáticamente del claim 'exp' del JWT (~10 min en Baserow)
+// ✅ Auto-refresh cuando el access token expira
+// ✅ Thread-safe: cada instancia tiene sus propios tokens
+// ❌ No persistidos en disco: re-login necesario después de reinicio
+
+// Verificar estado de autenticación
+console.log(adminClient.isAuthenticated()) // true
+console.log(adminClient.getCurrentToken()) // 'eyJhbGc...'
+
+// Renovar manualmente si es necesario
+const newToken = await adminClient.refreshToken()
+```
+
+**Nota sobre expiración de tokens:**
+La librería usa **decodificación estándar JWT** para leer el claim `exp` del token, no asume ningún TTL hardcoded. Esto garantiza:
+
+- ✅ **Precisión perfecta**: usa el tiempo real del servidor Baserow
+- ✅ **Adaptabilidad**: funciona si Baserow cambia la configuración de TTL
+- ✅ **Estándar JWT**: sigue las mejores prácticas de la industria
+
+#### Auto-Refresh en Errores 401
+
+```typescript
+// El cliente configura automáticamente un interceptor
+// que renueva el token en caso de 401 Unauthorized
+adminClient.setupAutoRefresh() // Opcional, ya configurado internamente
+
+// Cualquier request que falle con 401 intentará:
+// 1. Renovar el access token con el refresh token
+// 2. Reintentar la request original con el nuevo token
+// 3. Si el refresh falla, limpiar tokens y lanzar error
+```
+
+#### Manejo de Errores de Autenticación
+
+```typescript
+import { BaserowAuthTokenExpiredError, BaserowAuthTokenInvalidError } from '@gzl10/baserow'
+
+try {
+  await adminClient.refreshToken()
+} catch (error) {
+  if (error instanceof BaserowAuthTokenExpiredError) {
+    // Refresh token expirado - re-login necesario
+    console.error('❌ Refresh token expired - please login again')
+    // Redirigir a login o solicitar nuevas credenciales
+  } else if (error instanceof BaserowAuthTokenInvalidError) {
+    // Refresh token inválido o corrupto
+    console.error('❌ Invalid refresh token - check credentials')
+  }
+}
+```
+
+#### Códigos de Error Específicos
+
+| Error                          | Código                | Descripción                     | Acción Recomendada                     |
+| ------------------------------ | --------------------- | ------------------------------- | -------------------------------------- |
+| `BaserowAuthTokenExpiredError` | `AUTH_TOKEN_EXPIRED`  | Access o refresh token expirado | Re-login con credenciales              |
+| `BaserowAuthTokenInvalidError` | `AUTH_TOKEN_INVALID`  | Token inválido o corrupto       | Verificar credenciales y configuración |
+| `BaserowError`                 | `NO_REFRESH_TOKEN`    | No hay refresh token disponible | Hacer login primero                    |
+| `BaserowError`                 | `INVALID_CREDENTIALS` | Credenciales incorrectas        | Verificar email y password             |
+
+#### Keep-Alive para Backends 24/7 (v1.3.0+)
+
+⚠️ **Limitación de Baserow**: El refresh token expira **7 días después del login** (fijo, NO se renueva al hacer refresh).
+
+**Solución**: Keep-alive ejecuta **re-login automático** cada 5 días para obtener tokens frescos, previniendo la expiración.
+
+```typescript
+// Backend de larga duración con keep-alive
+const backendClient = await BaserowClient.create({
+  url: 'https://baserow.example.com',
+  credentials: { email: 'backend@example.com', password: 'password' },
+  keepAlive: {
+    enabled: true,
+    intervalMinutes: 7200 // Default: 7200 (5 días)
+  }
+})
+
+// ✅ Re-login automático cada 5 días → tokens siempre frescos
+// ✅ Backend funciona indefinidamente sin intervención manual
+// ✅ Se detiene automáticamente en logout() o destroy()
+// ⚠️ Credenciales almacenadas en memoria (solo backends confiables)
+```
+
+**Recomendaciones de intervalo:**
+
+| Tipo de Backend     | Intervalo         | Motivo                                               |
+| ------------------- | ----------------- | ---------------------------------------------------- |
+| **Producción 24/7** | 7200 min (5 días) | Balance óptimo: margen de 2 días antes de expiración |
+| **Crítico**         | 4320 min (3 días) | Extra conservador: margen de 4 días                  |
+| **Desarrollo**      | 1440 min (1 día)  | Testing frecuente, detección rápida de problemas     |
+
+**Ejemplo completo backend Express:**
+
+```typescript
+import { BaserowClient } from '@gzl10/baserow'
+
+// Inicializar cliente con keep-alive al arrancar servidor
+const client = await BaserowClient.create({
+  url: process.env.BASEROW_URL!,
+  credentials: {
+    email: process.env.BASEROW_EMAIL!,
+    password: process.env.BASEROW_PASSWORD!
+  },
+  keepAlive: { enabled: true }, // Default: 5 días
+  workspace: 'Production'
+})
+
+// Usar cliente en rutas Express
+app.get('/api/data', async (req, res) => {
+  const databases = await client.databases.findMany()
+  res.json(databases)
+})
+
+// Limpiar al cerrar servidor
+process.on('SIGTERM', () => {
+  client.destroy() // Detiene keep-alive y limpia credenciales
+  process.exit(0)
+})
+```
+
+**⚠️ Seguridad**:
+
+- Credenciales se almacenan en memoria del proceso
+- Solo usar en backends propios/confiables
+- NO usar en frontends o aplicaciones compartidas
+- Se limpian automáticamente en `logout()`/`destroy()`
+
+### Performance con Presets Predefinidos
+
+La librería incluye **presets de performance optimizados** para diferentes entornos:
+
+```typescript
+import { BaserowClient, PERFORMANCE_PRESETS } from '@gzl10/baserow'
+
+// Producción (balanceado): 30s timeout, 3 retries, 10 req/s
+const prodClient = await BaserowClient.create({
+  url: 'https://baserow.example.com',
+  token: 'your_token',
+  performance: PERFORMANCE_PRESETS.production
+})
+
+// Desarrollo (relajado): 60s timeout, 2 retries, 5 req/s
+const devClient = await BaserowClient.create({
+  url: 'http://localhost:3000',
+  credentials: { email: 'dev@example.com', password: 'password' },
+  performance: PERFORMANCE_PRESETS.development
+})
+
+// Testing (conservador): 45s timeout, 2 retries, 5 req/s
+const testClient = await BaserowClient.create({
+  url: 'https://test.baserow.com',
+  token: 'test_token',
+  performance: PERFORMANCE_PRESETS.testing
+})
+```
+
+#### Presets Disponibles
+
+| Preset         | Timeout | Retries | Rate (req/s) | Uso Ideal             |
+| -------------- | ------- | ------- | ------------ | --------------------- |
+| `production`   | 30s     | 3       | 10           | Producción balanceada |
+| `development`  | 60s     | 2       | 5            | Desarrollo local      |
+| `testing`      | 45s     | 2       | 5            | Tests automatizados   |
+| `aggressive`   | 15s     | 5       | 20           | Servidores robustos   |
+| `conservative` | 60s     | 1       | 2            | Recursos limitados    |
+
+```typescript
+// Helper function para obtener presets dinámicamente
+import { getPerformancePreset } from '@gzl10/baserow'
+
+const preset = getPerformancePreset('production')
+// Equivalente a: PERFORMANCE_PRESETS.production
+```
+
+### Performance Global
+
+```typescript
+import { PerformanceManager } from '@gzl10/baserow'
+
+// Configurar defaults globales
+PerformanceManager.setGlobal({
+  timeout: 45000,
+  retries: 5,
+  maxRequestsPerSecond: 20,
+  enableRateLimiting: true
+})
+
+// Ver configuración actual
+const currentDefaults = PerformanceManager.getGlobal()
+```
+
+### Por Instancia (Custom)
+
+```typescript
+const client = await BaserowClient.create({
+  url: 'https://baserow.example.com',
+  token: 'your_token',
+  performance: {
+    timeout: 60000,
+    retries: 3,
+    maxRequestsPerSecond: 10
+  }
+})
+```
+
+## 🗂️ Operaciones Avanzadas
+
+### API Jerárquica CRUD Completa
+
+La librería proporciona una API jerárquica consistente para operaciones CRUD en todos los niveles:
+
+```typescript
+// ✅ Gestión de Workspaces
+const workspaces = await admin.workspaces.list()
+const newWS = await admin.workspaces.create({ name: 'Nueva Empresa' })
+const updatedWS = await admin.workspace('Mi Empresa').update({ name: 'Empresa Actualizada' })
+await admin.workspace('Empresa Vieja').delete()
+
+// ✅ Gestión de Databases (dentro de workspace)
+const databases = await admin.workspace('Mi Empresa').databases.list()
+const newDB = await admin.workspace('Mi Empresa').databases.create('Nueva Database')
+const updatedDB = await admin.workspace('Mi Empresa').database('CRM').update({ name: 'CRM v2' })
+await admin.workspace('Mi Empresa').database('CRM Viejo').delete()
+
+// ✅ Gestión de Tables (dentro de database)
+const tables = await admin.workspace('Mi Empresa').database('CRM').tables.list()
+const newTable = await admin
+  .workspace('Mi Empresa')
+  .database('CRM')
+  .tables.create({
+    name: 'Customers',
+    data: [
+      ['Name', 'Email'],
+      ['Alice', 'alice@example.com']
+    ],
+    first_row_header: true
+  })
+const updatedTable = await admin.workspace('Mi Empresa').database('CRM').table('Customers').update({ name: 'Clients' })
+await admin.workspace('Mi Empresa').database('CRM').table('Old Table').delete()
+```
+
+### Operaciones Bulk
+
+```typescript
+// Crear múltiples filas
+const newRows = await client
+  .database(123)
+  .table(456)
+  .rows.createBulk(
+    [
+      { name: 'Alice', email: 'alice@example.com' },
+      { name: 'Bob', email: 'bob@example.com' }
+    ],
+    { batchSize: 100 }
+  )
+
+// Descargar tabla completa
+const allRows = await client.database(123).table(456).rows.listAll()
+```
+
+### Gestión de Campos
+
+```typescript
+// Crear campos de todos los tipos
+const textField = await admin.workspace('Company').database('CRM').table('Customers').field.createText('company_name')
+
+const emailField = await admin
+  .workspace('Company')
+  .database('CRM')
+  .table('Customers')
+  .field.createEmail('contact_email')
+
+const selectField = await admin
+  .workspace('Company')
+  .database('CRM')
+  .table('Customers')
+  .field.createSingleSelect('status', [
+    { value: 'active', color: 'green' },
+    { value: 'inactive', color: 'red' }
+  ])
+```
+
+### Database Tokens
+
+```typescript
+// Crear tokens con permisos específicos
+const token = await admin
+  .workspace('Company')
+  .database('CRM')
+  .tokens.create({
+    name: 'API Integration Token',
+    permissions: {
+      create: true,
+      read: true,
+      update: true,
+      delete: false
+    }
+  })
+```
+
+## 🧪 Testing Comprehensivo
+
+La librería incluye **60+ tests** de integración con **cobertura de error handling del 42%**:
+
+### Suite de Tests Disponibles
+
+```bash
+# Todos los tests (rápido)
+pnpm test
+
+# Tests en modo watch
+pnpm test:watch
+
+# Solo tests de smoke (CI/CD)
+pnpm test:smoke
+
+# Tests específicos de error handling
+pnpm test admin-database.test.ts admin-table.test.ts admin-field-basic.test.ts admin-field-advanced.test.ts
+```
+
+### 📊 Cobertura de Testing
+
+- **✅ 60+ Tests Totales**: 35+ integración + 34 error handling (v1.0.2)
+- **✅ Tests de Campos**: 8 archivos especializados por tipo de campo
+- **✅ PrismaMapper**: 35+ tests de transformaciones complejas
+- **✅ Error Handling**: 42% archivos con cobertura completa (+17% en v1.0.2)
+- **✅ Retry Logic**: Tests de manejo de errores y rate limiting
+- **✅ Operaciones Bulk**: Validación de procesamiento optimizado
+- **✅ API Jerárquica**: Tests de navegación workspace → database → table
+
+### 🆕 Error Handling Tests (v1.0.2)
+
+**Helpers Reutilizables**:
+
+- `tests/helpers/error-assertions.ts` - Funciones para validar errores tipados
+- `tests/fixtures/invalid-data.ts` - Datos inválidos para testing consistente
+
+**Servicios con Error Handling Completo**:
+
+- ✅ `admin-database.test.ts` - 8 tests de error (404, 400/422, validaciones)
+- ✅ `admin-table.test.ts` - 9 tests de error (404, validaciones, edge cases)
+- ✅ `admin-field-basic.test.ts` - 10 tests de error (validaciones por tipo)
+- ✅ `admin-field-advanced.test.ts` - 7 tests de error (campos complejos)
+
+**Códigos HTTP Validados**:
+
+- 404 (Not Found) - BaserowNotFoundError con contexto
+- 400/422 (Validation) - Nombres vacíos, longitud, parámetros inválidos
+- Comportamiento Baserow - Documentado lo que acepta vs rechaza
+
+### Categorías de Tests
+
+#### Tests de Campos por Tipo
+
+- `admin-field-basic.test.ts` - Campos básicos (text, number, boolean) + **10 error tests**
+- `admin-field-text.test.ts` - Campos de texto (url, email, phone)
+- `admin-field-numeric.test.ts` - Campos numéricos (number, rating)
+- `admin-field-datetime.test.ts` - Campos de fecha y auditoría
+- `admin-field-select.test.ts` - Campos de selección
+- `admin-field-relations.test.ts` - Campos relacionales con retry logic
+- `admin-field-advanced.test.ts` - Campos avanzados (file, autonumber, count, rollup, lookup) + **7 error tests**
+- `admin-field-audit.test.ts` - Campos de auditoría automática
+
+#### Tests CRUD Core
+
+- `admin-database.test.ts` - CRUD databases + **8 error tests**
+- `admin-table.test.ts` - CRUD tables + **9 error tests**
+- `admin-row.test.ts` - CRUD rows (próximo: error handling)
+- `admin-workspace.test.ts` - Gestión workspaces
+
+#### Tests del PrismaMapper
+
+- `prisma-mapper.test.ts` - **35+ tests** de transformaciones Prisma → Baserow
+
+### 📝 Variables de Entorno para Tests
+
+```env
+BASEROW_URL=https://baserow.example.com
+BASEROW_ADMIN_MAIL=admin@example.com
+BASEROW_ADMIN_PASSWORD=your_password
+BASEROW_DB_TOKEN=your_database_token
+```
+
+### 🔧 Configuración de Tests
+
+Los tests están configurados para:
+
+- **Cleanup automático**: Destrucción de recursos tras cada test
+- **Retry logic**: Manejo de campos que se crean de forma asíncrona
+- **Timeouts configurables**: Adaptados para diferentes entornos
+- **Mock y real API**: Soporte para tests unitarios e integración
+
+## 🔗 Compatibilidad y Versiones
+
+### Baserow v1.35.3 - Totalmente Compatible
+
+✅ **Sin Breaking Changes** - Upgrade seguro desde v1.35.0+
+
+**Mejoras Automáticas (sin código requerido):**
+
+- 🚀 **Búsquedas optimizadas** (v1.35.2) - Queries con `search` más rápidas
+- 🔍 **Filtros robustos** (v1.35.2) - Mejor confiabilidad en operadores complejos (`AND`, `OR`, `NOT`)
+- 🔐 **Permisos expandidos** (v1.35.3) - Exportaciones disponibles para roles visualizador
+- 🪝 **Webhooks retroactivos** (v1.35.2) - Compatible con webhooks para registros pasados
+
+**Funcionalidades Nuevas de Baserow:**
+
+- **Date Dependency** (v1.35.2) - Conexión automática entre fechas inicio/fin/duración
+  - ⚠️ Configuración via UI de Baserow (API no documentada públicamente aún)
+  - ✅ Nuestra librería puede leer/escribir campos relacionados normalmente
+- **PostgreSQL Sync bidireccional** (v1.35.0) - Feature de servidor
+  - Usar @gzl10/baserow para sincronizar datos post-sync
+
+**Análisis Completo:** Ver [docs/BASEROW_1.35.3_IMPACT_ANALYSIS.md](docs/BASEROW_1.35.3_IMPACT_ANALYSIS.md)
+
+---
+
+## 🔗 Enlaces
+
+- [Baserow API Documentation](https://baserow.io/docs)
+- [TypeScript Documentation](https://www.typescriptlang.org/docs)
+- [Express.js](https://expressjs.com)
+
+## ☕ Support
+
+<a href="https://www.buymeacoffee.com/gzl10g" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" ></a>
+
+## 📄 Licencia
+
+MIT License - Ver archivo [LICENSE](LICENSE)