@gzl10/baserow 1.2.0

package/package.json

@@ -0,0 +1,91 @@
+{
+  "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",
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "baserow",
+    "typescript",
+    "api",
+    "crud",
+    "database",
+    "client",
+    "rest",
+    "sdk",
+    "admin",
+    "jwt",
+    "database-token",
+    "fields",
+    "bulk-operations",
+    "rate-limiting",
+    "retry-logic",
+    "hierarchical-api",
+    "workspace",
+    "table",
+    "row",
+    "field"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git@ssh.gitlab.gzl10.com:oss/baserow.git"
+  },
+  "homepage": "https://gitlab.gzl10.com/oss/baserow",
+  "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",
+  "devDependencies": {
+    "@types/chance": "^1.1.7",
+    "@types/node": "^20.19.5",
+    "@typescript-eslint/eslint-plugin": "^8.18.1",
+    "@typescript-eslint/parser": "^8.18.1",
+    "chance": "^1.1.13",
+    "dotenv": "^16.6.1",
+    "eslint": "^9.17.0",
+    "prettier": "^3.4.2",
+    "tsup": "^8.5.0",
+    "typescript": "^5.6.3",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=20.19.5"
+  },
+  "packageManager": "pnpm@8.15.1",
+  "dependencies": {
+    "axios": "^1.7.9",
+    "axios-rate-limit": "^1.4.0",
+    "axios-retry": "^4.5.0",
+    "zod": "^3.25.1"
+  },
+  "scripts": {
+    "build": "tsup",
+    "build:tsc": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:smoke": "vitest run --config vitest.config.smoke.ts",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --check .",
+    "format:fix": "prettier --write ."
+  }
+}

package/src/BaserowClient.ts

@@ -0,0 +1,501 @@
+/**
+ * Cliente unificado principal de Baserow API v1.35+ (2025)
+ *
+ * **Arquitectura de 3 clientes especializados con auto-detección inteligente**
+ *
+ * Detecta automáticamente el tipo de autenticación basado en la configuración
+ * y devuelve el cliente apropiado con tipos TypeScript perfectos.
+ *
+ * **Características principales v1.1.0+:**
+ * - 🎯 **Arquitectura de 3 Clientes**: Auto-detección Token/Admin Global/Admin Workspace
+ * - 🗺️ **PrismaBaserowMapper**: Sintaxis familiar Prisma con 35+ tests de transformaciones
+ * - 📋 **21/22 Tipos de Campos**: Cobertura prácticamente completa incluyendo campos avanzados
+ * - 🚀 **HTTP Optimizado**: 36% menos código con axios-retry + axios-rate-limit oficiales
+ * - ⚡ **Operaciones Bulk**: Procesamiento optimizado con retry logic y rate limiting
+ * - 🧪 **Testing Robusto**: 35+ tests de integración + tests comprehensivos del mapper
+ *
+ * **Un solo método: `BaserowClient.create()`**
+ * - Detecta automáticamente si usas token o credenciales
+ * - Infiere el tipo correcto de cliente
+ * - Sin necesidad de elegir entre múltiples clases
+ *
+ * @aiComparison
+ * ## 📊 Matriz de Selección de Cliente por Escenario
+ *
+ * | Escenario | Cliente Recomendado | Razón | Config Example |
+ * |-----------|-------------------|-------|----------------|
+ * | **Frontend/Mobile App** | `ClientWithToken` | Máxima seguridad, scope limitado a tablas específicas | `{ token: 'db_xxx' }` |
+ * | **Admin Dashboard Web** | `ClientWithCreds` (Global) | Gestión multi-workspace, crear/editar estructuras | `{ credentials: {...} }` |
+ * | **Backend API** | `ClientWithToken` | Performance óptimo, solo CRUD de datos | `{ token: 'db_xxx' }` |
+ * | **CLI Tool Admin** | `ClientWithCreds` (Global) | Operaciones admin en múltiples workspaces | `{ credentials: {...} }` |
+ * | **Microservicio Single-Tenant** | `ClientWithCredsWs` | API simplificada, workspace fijo | `{ credentials: {...}, workspace: 'X' }` |
+ * | **Background Job/Cron** | `ClientWithToken` | Sin riesgo de sesión expirada (token no expira) | `{ token: 'db_xxx' }` |
+ * | **Data Migration Script** | `ClientWithCreds` (Global) | Crear workspaces/databases/tablas completas | `{ credentials: {...} }` |
+ * | **Edge Functions** | `ClientWithToken` | Stateless, no maneja refresh tokens | `{ token: 'db_xxx' }` |
+ * | **Desktop App (Electron)** | `ClientWithCredsWs` | UX simplificada, workspace predefinido | `{ credentials: {...}, workspace: 'X' }` |
+ * | **Testing/E2E** | `ClientWithCreds` (Global) | Setup/teardown completo de fixtures | `{ credentials: {...} }` |
+ * | **Webhook Handler** | `ClientWithToken` | Read-only verification, performance crítico | `{ token: 'db_xxx' }` |
+ * | **Serverless Functions** | `ClientWithToken` | Cold start rápido, sin estado de sesión | `{ token: 'db_xxx' }` |
+ *
+ * @aiDecisionFactors
+ * ## 🔑 5 Factores Clave para Elegir Cliente
+ *
+ * **1. Operaciones Requeridas**
+ * - Solo CRUD de datos → `ClientWithToken`
+ * - Crear/modificar estructura (tablas, campos) → `ClientWithCreds*`
+ * - Gestión de workspaces → `ClientWithCreds` (Global)
+ *
+ * **2. Scope de Acceso**
+ * - Single workspace → `ClientWithCredsWs` o `ClientWithToken`
+ * - Multi-workspace → `ClientWithCreds` (Global)
+ * - Tablas específicas → `ClientWithToken` (mejor seguridad)
+ *
+ * **3. Ambiente de Ejecución**
+ * - Stateless (serverless, edge) → `ClientWithToken`
+ * - Stateful (backend server) → Cualquiera
+ * - Cliente (frontend, mobile) → `ClientWithToken`
+ *
+ * **4. Seguridad y Permisos**
+ * - Máxima seguridad (least privilege) → `ClientWithToken`
+ * - Admin operations trusted → `ClientWithCreds*`
+ * - Credenciales en código → ⚠️ Evitar (usar env vars)
+ *
+ * **5. Mantenimiento de Sesión**
+ * - Sin preocuparse de sesiones → `ClientWithToken` (no expira)
+ * - Manejo de refresh tokens OK → `ClientWithCreds*`
+ * - Background jobs largos → `ClientWithToken` (no requiere refresh)
+ *
+ * @aiComparison
+ * ## 🎯 Ejemplos de Decisión por Caso de Uso
+ *
+ * **Caso: Aplicación React de E-Commerce**
+ * ```typescript
+ * // ✅ CORRECTO - Token limitado a tablas de productos/carritos
+ * const client = await BaserowClient.create({
+ *   token: process.env.VITE_BASEROW_TOKEN
+ * })
+ * // Scope: Solo products + carts (configurado en Baserow)
+ * const products = await client.database(DB_ID).table(PRODUCTS_TABLE).rows.list()
+ * ```
+ *
+ * **Caso: Dashboard Admin Multi-Tenant**
+ * ```typescript
+ * // ✅ CORRECTO - Credenciales globales para gestión completa
+ * const admin = await BaserowClient.create({
+ *   credentials: {
+ *     email: process.env.ADMIN_EMAIL,
+ *     password: process.env.ADMIN_PASSWORD
+ *   }
+ * })
+ * // Puede crear/eliminar workspaces, databases, tables
+ * const workspace = await admin.workspaces.create({ name: 'Nuevo Cliente' })
+ * ```
+ *
+ * **Caso: Microservicio de Reportes para Empresa X**
+ * ```typescript
+ * // ✅ CORRECTO - Workspace-scoped para UX simplificada
+ * const reports = await BaserowClient.create({
+ *   credentials: {
+ *     email: process.env.SERVICE_EMAIL,
+ *     password: process.env.SERVICE_PASSWORD
+ *   },
+ *   workspace: 'Empresa X'
+ * })
+ * // API simplificada: admin.databases.list() en vez de admin.workspace('X').databases.list()
+ * const databases = await reports.databases.list()
+ * ```
+ *
+ * **Caso: Webhook Processor (Vercel Edge Function)**
+ * ```typescript
+ * // ✅ CORRECTO - Token para stateless execution
+ * export default async function handler(req: Request) {
+ *   const client = await BaserowClient.create({
+ *     token: process.env.BASEROW_TOKEN
+ *   })
+ *
+ *   // Verificar evento sin mantener sesión
+ *   const row = await client.database(DB_ID).table(TBL_ID).rows.get(rowId)
+ *   return Response.json({ verified: true })
+ * }
+ * ```
+ *
+ * **Caso: CLI Tool de Migración**
+ * ```typescript
+ * // ✅ CORRECTO - Credenciales globales para setup completo
+ * const migrator = await BaserowClient.create({
+ *   credentials: {
+ *     email: await promptEmail(),
+ *     password: await promptPassword()
+ *   }
+ * })
+ *
+ * // Crear estructura completa: workspace → database → tables → fields → data
+ * const ws = await migrator.workspaces.create({ name: 'Production' })
+ * const db = await migrator.workspace('Production').databases.create('Main DB')
+ * const table = await migrator.workspace('Production').database('Main DB').tables.create({ name: 'Users' })
+ * ```
+ *
+ * @aiWarning
+ * ## ⚠️ Errores Comunes de Selección
+ *
+ * **❌ Error 1: Usar Credentials en Frontend**
+ * ```typescript
+ * // ❌ PELIGROSO - Credenciales expuestas en bundle
+ * const client = await BaserowClient.create({
+ *   credentials: {
+ *     email: 'admin@company.com',  // ❌ Visible en DevTools
+ *     password: 'secret123'         // ❌ Comprometido
+ *   }
+ * })
+ * ```
+ * **✅ Solución: Usar Database Token**
+ * ```typescript
+ * const client = await BaserowClient.create({
+ *   token: import.meta.env.VITE_BASEROW_TOKEN  // ✅ Scope limitado
+ * })
+ * ```
+ *
+ * **❌ Error 2: Token para Operaciones Admin**
+ * ```typescript
+ * // ❌ IMPOSIBLE - Database Token no puede crear campos
+ * const client = await BaserowClient.create({ token: 'db_xxx' })
+ * await client.database(1).table(2).field.createText('name')  // ❌ 403 Forbidden
+ * ```
+ * **✅ Solución: Usar Credentials**
+ * ```typescript
+ * const admin = await BaserowClient.create({ credentials: {...} })
+ * await admin.workspace('X').database('Y').table('Z').field.createText('name')  // ✅
+ * ```
+ *
+ * **❌ Error 3: Global Credentials para Single Workspace**
+ * ```typescript
+ * // ❌ VERBOSE - API innecesariamente compleja
+ * const admin = await BaserowClient.create({ credentials: {...} })
+ * await admin.workspace('My Company').databases.list()
+ * await admin.workspace('My Company').database('DB').tables.list()
+ * // Repetir 'My Company' en cada llamada
+ * ```
+ * **✅ Solución: Usar Workspace-Scoped**
+ * ```typescript
+ * const admin = await BaserowClient.create({
+ *   credentials: {...},
+ *   workspace: 'My Company'  // ✅ Workspace automático
+ * })
+ * await admin.databases.list()          // ✅ Simplificado
+ * await admin.database('DB').tables.list()  // ✅ Sin prefijo workspace
+ * ```
+ *
+ * @example Uso básico con auto-detección
+ * ```typescript
+ * import { BaserowClient, PrismaBaserowMapper } from '@gzl10/baserow'
+ *
+ * // === ARQUITECTURA DE 3 CLIENTES ===
+ *
+ * // 🎯 Token-based (auto-detectado) - para operaciones de datos
+ * const client = await BaserowClient.create({
+ *   url: 'https://baserow.com',
+ *   token: 'db_token_123'
+ * })
+ * // Tipo inferido automáticamente: BaserowWithToken
+ * const rows = await client.database(123).table(456).rows.list()
+ *
+ * // 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 })
+ *
+ * // 🎯 Credentials global (auto-detectado) - para administración multi-workspace
+ * const admin = await BaserowClient.create({
+ *   url: 'https://baserow.com',
+ *   credentials: { email: 'admin@co.com', password: 'pass' }
+ * })
+ * // Tipo inferido automáticamente: BaserowWithCredentialsGlobal
+ * const workspaces = await admin.workspaces.list()
+ * const newWS = await admin.workspaces.create({ name: 'Nueva Empresa' })
+ * const updatedWS = await admin.workspace('My Workspace').update({ name: 'New Name' })
+ * const database = await admin.workspace('My Workspace').databases.create('CRM')
+ * await admin.workspace('Old Workspace').delete()
+ *
+ * // 🎯 Credentials workspace (auto-detectado) - para workspace específico
+ * const adminWS = await BaserowClient.create({
+ *   url: 'https://baserow.com',
+ *   credentials: { email: 'admin@co.com', password: 'pass' },
+ *   workspace: 'My Workspace'  // Esto activa modo workspace
+ * })
+ * // Tipo inferido automáticamente: BaserowWithCredentialsWorkspace
+ * const databases = await adminWS.databases.list()
+ * const table = await adminWS.database('My DB').tables.create({ name: 'Customers' })
+ *
+ * // === PRISMA MAPPER ===
+ * // Sintaxis familiar Prisma para consultas complejas
+ * const prismaQuery = {
+ *   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 }
+ * }
+ *
+ * const baserowOptions = PrismaBaserowMapper.transformPrismaToBaserow(prismaQuery)
+ * const filteredRows = await client.database(123).table(456).rows.list(baserowOptions)
+ *
+ * // === COBERTURA COMPLETA DE CAMPOS ===
+ * // 21/22 tipos de campos soportados incluyendo campos avanzados v1.1.0+
+ * const textField = await table.field.createText('full_name')
+ * const emailField = await table.field.createEmail('contact_email')
+ * const fileField = await table.field.createFile('documents')        // ¡Nuevo!
+ * const autoField = await table.field.createAutonumber('ticket_id')  // ¡Nuevo!
+ * const countField = await table.field.createCount('items_count', targetTableId) // ¡Nuevo!
+ * const rollupField = await table.field.createRollup('total_amount', tableId, fieldId, 'sum') // ¡Nuevo!
+ * const lookupField = await table.field.createLookup('item_names', tableId, fieldId) // ¡Nuevo!
+ * ```
+ *
+ * @example Uso con presets de performance
+ * ```typescript
+ * import { BaserowClient, PERFORMANCE_PRESETS } from '@gzl10/baserow'
+ *
+ * // Cliente con preset de producción (balanceado)
+ * const prodClient = await BaserowClient.create({
+ *   url: 'https://api.baserow.com',
+ *   token: process.env.BASEROW_TOKEN,
+ *   performance: PERFORMANCE_PRESETS.production
+ * })
+ *
+ * // Cliente para desarrollo (más relajado)
+ * const devClient = await BaserowClient.create({
+ *   url: 'http://localhost:3000',
+ *   credentials: { email: 'dev@example.com', password: 'dev123' },
+ *   performance: PERFORMANCE_PRESETS.development
+ * })
+ *
+ * // Cliente para tests (conservador)
+ * const testClient = await BaserowClient.create({
+ *   url: 'https://test.baserow.com',
+ *   token: process.env.TEST_TOKEN,
+ *   performance: PERFORMANCE_PRESETS.testing
+ * })
+ * ```
+ *
+ */
+
+import { ClientWithToken } from './ClientWithToken'
+import { ClientWithCreds } from './ClientWithCreds'
+import { ClientWithCredsWs } from './ClientWithCredsWs'
+import { PerformanceManager } from './utils/performance'
+import { verifyLogin, verifyBaserowHealth } from './utils/auth'
+import {
+  BaserowTokenConfig,
+  BaserowCredentialsConfig,
+  BaserowCredentialsWorkspaceConfig,
+  BaserowUnifiedConfig,
+  BaserowCredentials
+} from './types'
+
+// Conditional types para inferencia automática de tipos
+type InferClientType<T> = T extends { token: string }
+  ? ClientWithToken
+  : T extends { workspace: string }
+    ? ClientWithCredsWs
+    : T extends { credentials: any }
+      ? ClientWithCreds
+      : never
+
+export class BaserowClient {
+  /**
+   * Crea un cliente con Database Token para operaciones de datos
+   * @internal
+   */
+  private static withToken(config: BaserowTokenConfig): ClientWithToken {
+    return new ClientWithToken(config)
+  }
+
+  /**
+   * Crea un cliente admin con credenciales
+   * @internal
+   */
+  private static async withCredentials(config: BaserowCredentialsConfig): Promise<ClientWithCreds>
+  private static async withCredentials(config: BaserowCredentialsWorkspaceConfig): Promise<ClientWithCredsWs>
+  private static async withCredentials(
+    config: BaserowCredentialsConfig | BaserowCredentialsWorkspaceConfig
+  ): Promise<ClientWithCreds | ClientWithCredsWs> {
+    // Si tiene workspace, crear cliente de workspace específico
+    if ('workspace' in config && config.workspace) {
+      return await ClientWithCredsWs.create({
+        url: config.url,
+        credentials: config.credentials,
+        workspace: config.workspace,
+        logger: config.logger,
+        performance: config.performance
+      })
+    }
+
+    // Si no, crear cliente global
+    return await ClientWithCreds.create({
+      url: config.url,
+      credentials: config.credentials,
+      logger: config.logger,
+      performance: config.performance
+    })
+  }
+
+  /**
+   * Auto-detecta el tipo de configuración y crea el cliente apropiado (overload para token)
+   */
+  static create(config: BaserowTokenConfig): Promise<ClientWithToken>
+
+  /**
+   * Auto-detecta el tipo de configuración y crea el cliente apropiado (overload para credentials)
+   */
+  static create(config: BaserowCredentialsConfig): Promise<ClientWithCreds>
+
+  /**
+   * Auto-detecta el tipo de configuración y crea el cliente apropiado (overload para credentials + workspace)
+   */
+  static create(config: BaserowCredentialsWorkspaceConfig): Promise<ClientWithCredsWs>
+
+  /**
+   * Auto-detecta el tipo de configuración y crea el cliente apropiado (generic)
+   */
+  static create<T extends BaserowUnifiedConfig>(config: T): Promise<InferClientType<T>>
+
+  /**
+   * Implementación de create con auto-detección
+   */
+  static async create(config: BaserowUnifiedConfig): Promise<ClientWithToken | ClientWithCreds | ClientWithCredsWs> {
+    // Detectar tipo basado en propiedades
+    if ('token' in config) {
+      // Es configuración de token
+      return this.withToken(config as BaserowTokenConfig)
+    }
+
+    if ('credentials' in config) {
+      // Es configuración de credenciales
+      if ('workspace' in config && config.workspace) {
+        // Con workspace específico
+        return await this.withCredentials(config as BaserowCredentialsWorkspaceConfig)
+      } else {
+        // Sin workspace (global)
+        return await this.withCredentials(config as BaserowCredentialsConfig)
+      }
+    }
+
+    throw new Error('Invalid configuration: must provide either "token" or "credentials"')
+  }
+
+  /**
+   * Establece configuración global de rendimiento para todos los tipos de clientes
+   *
+   * @param defaults - Configuración parcial de performance para sobrescribir defaults
+   *
+   * @example
+   * ```typescript
+   * // Configurar defaults más agresivos para toda la aplicación
+   * BaserowClient.setGlobalPerformanceDefaults({
+   *   timeout: 45000,
+   *   retries: 5,
+   *   maxRequestsPerSecond: 20
+   * })
+   * ```
+   */
+  static setGlobalPerformanceDefaults(defaults: Partial<import('./types.js').BaserowPerformanceOptions>): void {
+    PerformanceManager.setGlobal(defaults)
+  }
+
+  /**
+   * Obtiene la configuración global actual de rendimiento
+   *
+   * @returns Configuración global actual de performance
+   *
+   * @example
+   * ```typescript
+   * const currentDefaults = BaserowClient.getGlobalPerformanceDefaults()
+   * console.log('Timeout global:', currentDefaults.timeout)
+   * ```
+   */
+  static getGlobalPerformanceDefaults(): import('./types.js').BaserowPerformanceOptions {
+    return PerformanceManager.getGlobal()
+  }
+
+  /**
+   * 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.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
+   * // Verificar credenciales antes de crear cliente
+   * const isValid = await BaserowClient.verifyLogin('https://baserow.com', {
+   *   email: 'user@example.com',
+   *   password: 'password123'
+   * })
+   *
+   * if (isValid) {
+   *   // Proceder a crear cliente admin
+   *   const admin = await BaserowClient.create({
+   *     url: 'https://baserow.com',
+   *     credentials: { email: 'user@example.com', password: 'password123' }
+   *   })
+   * } else {
+   *   console.error('Credenciales inválidas')
+   * }
+   * ```
+   */
+  static async verifyLogin(
+    url: string,
+    credentials: BaserowCredentials,
+    options?: import('./utils/auth.js').VerifyLoginOptions
+  ): Promise<boolean> {
+    return verifyLogin(url, credentials, options)
+  }
+
+  /**
+   * Verificar si una URL de Baserow es accesible (health check básico)
+   *
+   * Útil para verificar conectividad del servidor antes de realizar operaciones.
+   * No requiere autenticación.
+   *
+   * @param url URL base de Baserow (ej: 'https://baserow.com')
+   * @param options Opciones de verificación (timeout, logger)
+   * @returns Promise<boolean> - true si el servidor es accesible
+   *
+   * @example
+   * ```typescript
+   * // Verificar si Baserow está disponible
+   * const isHealthy = await BaserowClient.health('https://baserow.com')
+   *
+   * if (!isHealthy) {
+   *   console.log('Servidor Baserow no disponible')
+   *   return
+   * }
+   *
+   * // Proceder con operaciones normales
+   * const client = await BaserowClient.create({ ... })
+   * ```
+   */
+  static async health(
+    url: string,
+    options?: Pick<import('./utils/auth.js').VerifyLoginOptions, 'timeout' | 'logger'>
+  ): Promise<boolean> {
+    return verifyBaserowHealth(url, options)
+  }
+}
+
+// Re-export de las clases internas para uso avanzado (pero marcadas como internas)
+export { ClientWithToken } from './ClientWithToken'
+export { ClientWithCreds } from './ClientWithCreds'
+export { ClientWithCredsWs } from './ClientWithCredsWs'