@gzl10/baserow 1.2.0 → 1.2.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @gzl10/baserow
 
+## 1.2.1 (2025-01-03)
+
+### Patch Changes
+
+- README translated to English and simplified (848 → 275 lines)
+- Fixed npm compatibility: docs links now use absolute GitLab URLs
+- Added `funding` field to package.json (Buy Me A Coffee)
+- Updated `homepage` to www.gzl10.com
+- Changed license to MIT
+
+---
+
 ## 1.2.0 (2025-01-02)
 
 ### Minor Changes

package/README.md

@@ -1,93 +1,61 @@
 # @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**.
+Modern TypeScript client for Baserow API v1.35+ with **3-client architecture**, **PrismaBaserowMapper**, **21/22 field types**, and **automatic JWT refresh**.
 
-## ✨ Características Principales
+## Features
 
-- 🎯 **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
+- 🎯 **3-Client Architecture**: Token, Admin Global, and Admin Workspace
+- 🔐 **Auto-Refresh JWT**: Automatic access/refresh token management
+- 🗺️ **PrismaBaserowMapper**: Familiar Prisma-style query syntax (35+ tests)
+- 📋 **21/22 Field Types**: Complete coverage including file, autonumber, count, rollup, lookup
+- 🚀 **Optimized HTTP**: axios-retry + axios-rate-limit (36% less code)
+- 🔄 **Hierarchical API**: Intuitive workspace → database → table → fields/rows navigation
+- ⚡ **Bulk Operations**: Optimized batch processing with retry logic
 
-## 📚 Documentación
+## Installation
 
-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
+```bash
+pnpm add @gzl10/baserow
+```
 
-### Cliente Principal Unificado
+## Quick Start
 
 ```typescript
 import { BaserowClient } from '@gzl10/baserow'
 
-// 1. Cliente con Database Token (solo lectura de datos)
+// 1. Database Token (read-only)
 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({
+// 2. Admin Global (multi-workspace)
+const admin = 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({
+// 3. Admin Workspace (scoped)
+const adminWS = await BaserowClient.create({
   url: 'https://baserow.example.com',
   credentials: { email: 'admin@example.com', password: 'password' },
-  workspace: 'Mi Workspace'
+  workspace: 'My 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
+## Client Types
 
-```bash
-pnpm install @gzl10/baserow
-```
+| Client             | Auth           | Capabilities                         | Use Cases                    |
+| ------------------ | -------------- | ------------------------------------ | ---------------------------- |
+| **BaserowClient**  | Database Token | Data CRUD, bulk operations           | Apps, data integration, APIs |
+| **AdminGlobal**    | JWT Multi-WS   | Full workspace/database/table mgmt   | Admin scripts, DevOps tools  |
+| **AdminWorkspace** | JWT Scoped     | Operations within specific workspace | Enterprise apps, dashboards  |
 
-## 🔍 PrismaBaserowMapper - Sintaxis Familiar
+## PrismaBaserowMapper
 
-Sintaxis estilo Prisma.js para consultas Baserow con **35+ tests** de validación:
+Familiar Prisma-style syntax for Baserow queries:
 
 ```typescript
-import { BaserowClient } from '@gzl10/baserow'
-
-const client = await BaserowClient.create({ url, token })
-
-// Sintaxis Prisma familiar
 const employees = await client
   .database(123)
   .table(456)
@@ -97,95 +65,39 @@ const employees = await client
     },
     orderBy: [{ created_at: 'desc' }, { name: 'asc' }],
     take: 20,
-    skip: 40,
-    select: { id: true, name: true, email: true }
+    skip: 40
   })
 ```
 
-**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'
+**Supported operators:** `equals`, `not`, `contains`, `startsWith`, `endsWith`, `gt`, `gte`, `lt`, `lte`, `AND`, `OR`, `NOT`, `isEmpty`, `isNotEmpty`
 
-// Equivalencias:
-// - TokenConfig = BaserowTokenConfig
-// - CredentialsConfig = BaserowCredentialsConfig
-// - CredentialsWorkspaceConfig = BaserowCredentialsWorkspaceConfig
-```
+## Basic Usage
 
-### 1. Cliente con Database Token (Solo datos)
+### Data Operations (Token Client)
 
 ```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 }
-  )
+// Bulk operations
+const bulkRows = await client.database(123).table(456).rows.createBulk(items, { batchSize: 100 })
 ```
 
-### 2. Cliente Admin Global (Multi-workspace)
+### Admin Operations
 
 ```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
+// 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()
+const newWS = await admin.workspaces.create({ name: 'New Company' })
 
-// Creación jerárquica de recursos
+// Databases
 const database = await admin.workspace('Company').databases.create('CRM')
+
+// Tables
 const table = await admin
   .workspace('Company')
   .database('CRM')
@@ -199,649 +111,160 @@ const table = await admin
   })
 ```
 
-### 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'
-}
+## Field Types (21/22)
 
-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)
+### Text & Communication
 
 ```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')
+await table.field.createText('full_name')
+await table.field.createLongText('description')
+await table.field.createUrl('website')
+await table.field.createEmail('contact_email')
+await table.field.createPhoneNumber('phone')
 ```
 
-#### Numéricos y Lógicos (3 tipos)
+### Numeric & Boolean
 
 ```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
+await table.field.createNumber('price', 2) // 2 decimals
+await table.field.createBoolean('is_active')
+await table.field.createRating('rating', 5)
 ```
 
-#### Fecha y Auditoría (5 tipos)
+### Date & Audit
 
 ```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')
+await table.field.createDate('birthdate')
+await table.field.createLastModified('updated_at')
+await table.field.createCreatedOn('created_at')
 ```
 
-#### Selección y Opciones (2 tipos)
+### Selection
 
 ```typescript
-const statusField = await table.field.createSingleSelect('status', [
+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' }
-])
+await table.field.createMultipleSelect('tags', options)
 ```
 
-#### Relacionales (2 tipos)
+### Relational
 
 ```typescript
-const linkField = await table.field.createLinkRow('related_items', targetTableId)
-const formulaField = await table.field.createFormula('total_price', 'field("quantity") * field("price")')
+await table.field.createLinkRow('related_items', targetTableId)
+await table.field.createFormula('total', 'field("qty") * field("price")')
 ```
 
-#### 🆕 Campos Avanzados (5 tipos) - ¡Nuevos en v1.1.0+!
+### Advanced
 
 ```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)
+await table.field.createFile('documents')
+await table.field.createAutonumber('ticket_id')
+await table.field.createCount('items_count', targetTableId)
+await table.field.createRollup('total_amount', tableId, fieldId, 'sum')
+await table.field.createLookup('item_names', tableId, fieldId)
 ```
 
-### API Fluida Consistente
+## Configuration
 
-Todos los tipos de campos siguen el mismo patrón de API para máxima consistencia:
+### Performance Presets
 
 ```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)
+import { BaserowClient, PERFORMANCE_PRESETS } from '@gzl10/baserow'
 
-```typescript
-const adminClient = await BaserowClient.create({
+const client = await BaserowClient.create({
   url: 'https://baserow.example.com',
-  credentials: { email: 'admin@example.com', password: 'password' }
+  token: 'your_token',
+  performance: PERFORMANCE_PRESETS.production
 })
-
-// ✅ 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+)
+| Preset         | Timeout | Retries | Rate (req/s) |
+| -------------- | ------- | ------- | ------------ |
+| `production`   | 30s     | 3       | 10           |
+| `development`  | 60s     | 2       | 5            |
+| `testing`      | 45s     | 2       | 5            |
+| `aggressive`   | 15s     | 5       | 20           |
+| `conservative` | 60s     | 1       | 2            |
 
-⚠️ **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.
+### Keep-Alive (24/7 Backends)
 
 ```typescript
-// Backend de larga duración con keep-alive
-const backendClient = await BaserowClient.create({
+const client = 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)
+    intervalMinutes: 7200 // Re-login every 5 days
   }
 })
-
-// ✅ 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()`
+⚠️ **Baserow limitation**: Refresh token expires 7 days after login (fixed). Keep-alive performs automatic re-login to prevent expiration.
 
-### Performance con Presets Predefinidos
-
-La librería incluye **presets de performance optimizados** para diferentes entornos:
+## Express Utilities (Optional)
 
 ```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
-})
+import { BaserowClient, express as baserowExpress } from '@gzl10/baserow'
 
-// 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
-})
+app.use('/api', baserowExpress.baserowContext(client))
+app.use('/api', baserowExpress.requireAuth())
 
-// 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
+app.get('/api/rows', async (req, res) => {
+  const rows = await req.baserow!.database(123).table(456).rows.list()
+  res.json(baserowExpress.serializePaginated(rows))
 })
-```
-
-#### 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
+app.use(baserowExpress.errorHandler())
 ```
 
-### Performance Global
+## Error Handling
 
 ```typescript
-import { PerformanceManager } from '@gzl10/baserow'
-
-// Configurar defaults globales
-PerformanceManager.setGlobal({
-  timeout: 45000,
-  retries: 5,
-  maxRequestsPerSecond: 20,
-  enableRateLimiting: true
-})
+import {
+  BaserowError,
+  BaserowNotFoundError,
+  BaserowValidationError,
+  BaserowAuthTokenExpiredError
+} from '@gzl10/baserow'
 
-// 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
+try {
+  await client.database(999).table(456).rows.list()
+} catch (error) {
+  if (error instanceof BaserowNotFoundError) {
+    console.error('Resource not found:', error.message)
   }
-})
-```
-
-## 🗂️ 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
+## Testing
 
 ```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
+pnpm test           # All tests
+pnpm test:watch     # Watch mode
+pnpm test:smoke     # CI/CD smoke tests
 ```
 
-### 📊 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
+60+ tests including 35+ integration tests and 34 error handling tests.
 
-**Análisis Completo:** Ver [docs/BASEROW_1.35.3_IMPACT_ANALYSIS.md](docs/BASEROW_1.35.3_IMPACT_ANALYSIS.md)
+## Documentation
 
----
+- [Filters & Sorting](https://gitlab.gzl10.com/oss/baserow/-/blob/main/docs/FILTERS_AND_SORTING.md)
+- [API Reference](https://gitlab.gzl10.com/oss/baserow/-/blob/main/docs/BASEROW_API_REFERENCE.md)
+- [Keep-Alive Guide](https://gitlab.gzl10.com/oss/baserow/-/blob/main/docs/KEEP_ALIVE.md)
+- [Migration Guide](https://gitlab.gzl10.com/oss/baserow/-/blob/main/docs/MIGRATION.md)
+- [Testing Guide](https://gitlab.gzl10.com/oss/baserow/-/blob/main/docs/TESTING.md)
+- [Debugging](https://gitlab.gzl10.com/oss/baserow/-/blob/main/docs/DEBUGGING.md)
 
-## 🔗 Enlaces
+## Compatibility
 
-- [Baserow API Documentation](https://baserow.io/docs)
-- [TypeScript Documentation](https://www.typescriptlang.org/docs)
-- [Express.js](https://expressjs.com)
+✅ **Baserow v1.35.3** - Fully compatible, safe upgrade from v1.35.0+
 
-## ☕ Support
+## 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
+## License
 
-MIT License - Ver archivo [LICENSE](LICENSE)
+MIT License - See [LICENSE](LICENSE)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gzl10/baserow",
-  "version": "1.2.0",
-  "description": "Cliente TypeScript avanzado para Baserow API con arquitectura de 3 clientes, 21 tipos de campos soportados y operaciones bulk optimizadas",
+  "version": "1.2.1",
+  "description": "Modern TypeScript client for Baserow API with 3-client architecture, 21 field types, and optimized bulk operations",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",
@@ -43,16 +43,20 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git@ssh.gitlab.gzl10.com:oss/baserow.git"
+    "url": "https://gitlab.gzl10.com/oss/baserow.git"
   },
-  "homepage": "https://gitlab.gzl10.com/oss/baserow",
+  "homepage": "https://www.gzl10.com",
   "bugs": "https://gitlab.gzl10.com/oss/baserow/-/issues",
   "author": {
     "name": "Gonzalo Díez",
     "email": "gonzalo@gzl10.com",
     "url": "https://gitlab.gzl10.com/oss"
   },
-  "license": "UNLICENSED",
+  "license": "MIT",
+  "funding": {
+    "type": "buymeacoffee",
+    "url": "https://www.buymeacoffee.com/gzl10g"
+  },
   "devDependencies": {
     "@types/chance": "^1.1.7",
     "@types/node": "^20.19.5",